API Reference - Genesis Computing

Blueprint versioning and access

These endpoints are mounted under /api/blueprints/... and cover Blueprint Library inventory, versioning, and role-based access management for blueprint workspaces. Blueprint versioning follows the same edit and promotion model used by Genesis Apps: a blueprint can stay in standard mode or opt into versioned mode with immutable saved versions, a production assignment, and a mutable working copy. When authentication is enabled, Genesis resolves blueprint ownership from blueprint_manifest.yaml using the top-level created_by field, with fallback to legacy blueprint.created_by metadata and, when needed, origin.created_by_user_id. The owner automatically satisfies Blueprint RBAC checks on these routes, and newly created or copied blueprints are owner-only by default until you add role grants. When a caller imports a blueprint ZIP as a new local install or separate copy, Genesis sets created_by to the importing user so they can access the installed copy immediately; archive creator metadata is preserved in origin when the ZIP does not already include that block.

When authentication is disabled, Blueprint RBAC checks do not block requests on these routes.

HTTP authentication refusal responses

When an HTTP request is refused by the authentication middleware, Genesis returns the same JSON error envelope used by the rest of the API rather than a bare response string:

{
  "success": false,
  "error": "<human-readable refusal detail>",
  "error_type": "authentication",
  "request_id": "<correlation id>"
}

The error_type identifies the refusal category: authentication for 401, forbidden for 403, and service_unavailable for 503. Other server-side refusals use the shared internal category when no more specific status mapping exists. HTTP 410 Gone uses error_type: "gone"; for example, a dataset snapshot that is no longer available after a restart cannot be retried as-is and the dataset must be refreshed. Genesis also returns the same value in the X-Request-Id response header. Clients can use request_id or that header to correlate the refusal with server logs, including when HTTP request logging is disabled. Features unavailable in a deployment can return HTTP 501 with error_type: "not_available_here"; the error field gives the reason and available alternative. Browser-dependent features also use this response in a Databricks App deployment when Chromium is not included. Databricks App SCIM endpoints use this response for admin routes; the /scim/v2 routes return the corresponding SCIM error shape. For a missing or invalid credential, the error detail names the configured authentication provider and explains the accepted forms: an Authorization: Bearer <access token> issued by that provider or a Genesis service credential in the X-Genesis-Service-Token header. The detail also distinguishes authentication failure from a separate 403 permission refusal. API clients should preserve and display the full 403 refusal detail on affected routes: it includes actionable administrator guidance, not just a permission ID. See the RBAC Practical Guide for the permission labels. For the credentials most commonly used by API clients, the refusal identifies which credential was rejected: a Genesis personal access token uses Authorization: Bearer gp_... and points to POST /api/auth/pats to mint a new one; a sandbox thread token uses Authorization: Bearer gsk_... and expires with its sandbox run. These credentials are not interchangeable. Internal endpoints that explicitly require X-Genesis-Internal-Token report whether that header was absent or present but unrecognised and do not accept an Authorization: Bearer token or a session cookie as a substitute. Some refusals preserve a machine-readable error code and add existing response fields alongside the envelope. For example, a demo access denial continues to use error: "demo_access_denied" and may include reason, detail, and redirect_to. When the demo gate denies an identity, an HTML browser request is redirected with HTTP 303 to the refusal page; non-HTML requests receive HTTP 403 rather than a missing-credential 401. The hosted /mcp/ transport also returns 403 for this denial. GET /api/desktop/auth/login returns HTTP 400 with error_type: "bad_request" when the Genesis backend listens on a port that Genesis Desktop does not register for sign-in callbacks. The response’s payload.reason is sign_in_port_not_registered, and payload.sign_in_ports lists the supported ports (47080–47083). An invalid desktop.callback_relay_url remains a 400 validation error. GET /api/desktop/auth/login returns data.authorize_url and data.state. Open the authorization URL in the system browser, then use the state to follow the sign-in while the Desktop dialog waits:

Endpoint	Contract
`GET /api/desktop/auth/attempt?state={state}`	Returns `data.status` as `waiting`, `finishing`, `succeeded`, `failed`, or `unknown`. `waiting` means the browser has not returned; `finishing` means Genesis is completing the callback. `message` is `null` except when the attempt failed, when it contains the failure reason shown in the browser tab. The attempt is held in memory; `unknown` means it expired, was cancelled, or Genesis restarted.
`POST /api/desktop/auth/cancel`	Send `{"state":"..."}` to abandon a waiting sign-in. Returns HTTP `204`; the browser tab can no longer complete that sign-in.

The state query parameter and cancel-request field must contain 1–128 characters. A completed attempt reports succeeded or failed through the status endpoint. Before returning Desktop state or checking in an activated device, the service compares the saved sign-in target with the configured provisioner URL and identity-provider issuer. If either changed, it clears the prior sign-in and device activation and asks the person to sign in again; the install and its chats and data remain. Older installs without a saved target are treated as a different target when they have activation state. The current Desktop defaults are listed in Genesis Desktop sign-in targets. If Desktop cannot remove the Genesis AI key from the previous sign-in, the sign-in callback returns HTTP 503 with Genesis could not remove the AI key from your previous sign-in. Try again in a moment. It does not record the new sign-in target until removal succeeds, so the person can retry sign-in later. After a successful sign-in, the callback page confirms the signed-in identity and attempts to open Genesis Desktop through genesis-desktop://signed-in 300 ms after loading. The page also offers Return to Genesis Desktop as a link to open the app. The browser may ask permission to open it; if Genesis does not open, switch back to the Genesis window. When the provisioner refuses activation because the account’s email domain is not allowed, the activation result uses status: "not_allowed" and its message says Genesis Desktop isn't available for this account yet. Use a different account, or contact [email protected]. This is distinct from email_unverified, which remains the status for an account that needs email verification.

Genesis Desktop returning activation

The data.activation.llm.returning, data.activation.llm.plan_mode, and data.activation.llm.remaining_usd fields are returned by GET /api/desktop/status and the responses to POST /api/desktop/activate, POST /api/desktop/check-in, and POST /api/desktop/sign-out when an LLM activation is present. returning is true when the provisioner indicates an activation before this one; otherwise it is false. When a returning activation has no saved AI choice and no other AI provider is active, Genesis Desktop restores Genesis AI as the person’s choice instead of asking them to choose again. If another provider is active, Desktop does not replace it during this step and may read the person’s remaining Genesis AI credit from the provisioner.

Field	Type	Description
`returning`	boolean	Whether the person activated Genesis Desktop before on any computer. Defaults to `false` if the provisioner does not say.
`plan_mode`	`one_time` or `monthly`	The Genesis AI plan reported by the provisioner. Defaults to `one_time` when it does not report a plan.
`remaining_usd`	number or `null`	Remaining Genesis AI credit in USD, calculated as the maximum budget minus spend, floored at zero. It is `null` unless the returning person’s credit was read and a maximum budget was available.

Genesis Desktop Genesis AI-only mode

DesktopStatusData exposes these fields; both default to false:

Field	Type	Default	Description
`genesis_ai_only`	boolean	`false`	Whether Genesis AI is the only provider that can be configured or selected in Genesis Desktop.
`genesis_ai_only_notice_due`	boolean	`false`	Whether to show the one-time notice that Genesis AI now handles all AI requests because it replaced the person’s own provider during an upgrade.

After showing the notice, acknowledge it with POST /api/desktop/genesis-ai-only-notice/seen. It takes no request body and returns BaseResponse; the notice is not due again after acknowledgment. This laptop-mode route returns 409 when Genesis Desktop mode is unavailable. Genesis Desktop also enforces this restriction on the server: attempts to configure or test another provider, change its chat or embedding assignments, or choose AI supplied by a saved connection are refused with HTTP 403. POST /api/desktop/llm-choice refuses the own choice with 403, and POST /api/desktop/credit/switch refuses a switch away from Genesis AI with 403.

Genesis Desktop saved credential notice

GET /api/desktop/status returns data.saved_credentials_unreadable, an integer that defaults to 0. When it is greater than 0, Genesis Desktop shows a notice asking the person to reconnect saved connections whose credentials this install’s encryption key cannot open. After the notice is dismissed, Desktop acknowledges it with POST /api/desktop/credentials-notice/seen; the request has no body and returns BaseResponse. The notice is not due again after acknowledgment. This laptop-mode route returns 409 when Genesis Desktop mode is unavailable. See Master encryption key for how Desktop stores and recovers its key.

Genesis Desktop Genesis AI allowance

GET /api/desktop/credit returns the current Genesis AI reading when Genesis AI is active. With fresh=false (the default), a cached reading can be about three minutes old. With fresh=true, or while a monthly refusal is recorded, readings older than about 15 seconds are refreshed. Desktop reads the provisioner’s allowance with the sign-in token while it is valid, then uses this install’s device credential after the token expires. This keeps the reading refreshable without another sign-in when the provisioner accepts device-credential entitlement reads. If the provisioner refuses that credential, the reading is unavailable and Desktop waits 180 seconds before retrying; a new sign-in resumes sign-in-token reads immediately. A successful reading also updates the stored activation’s plan when it differs from the provisioner’s reported plan.

Field	Type	Description
`plan_mode`	`one_time` or `monthly`	The plan reported by the provisioner; defaults to `one_time` when no reading is available.
`percent_used`	integer or `null`	Percentage of the plan used, from 0 to 100; `100` while calls are refused.
`resets_at`	string or `null`	Monthly allowance reset instant as ISO 8601, at 00:00 UTC on the reset day; `null` for a one-time credit or when unavailable.
`remaining_usd`	number or `null`	Remaining amount in USD when the provisioner reports it.

The Desktop allowance display uses percent_used and resets_at on the monthly plan without showing dollar amounts. The one_time plan keeps the existing dollar-based credit display. The response also includes the existing available, model, max_budget_usd, spend_usd, used_fraction, exhausted, heads_up_due, and alternatives fields. If Genesis AI is not active or a reading is unavailable, available is false; plan usage and reset fields are null when there is no reading.

Genesis Desktop trial status

The data.trial field in GET /api/desktop/status and the responses to POST /api/desktop/activate, POST /api/desktop/check-in, and POST /api/desktop/sign-out is present when the provisioner marks a trial for display; otherwise it is null. It reports the provisioner’s latest trial answer:

Field	Type	Description
`expires_at`	datetime or `null`	When the trial ends; `null` means it has no end date.
`days_left`	integer or `null`	Whole days remaining, rounded up; `0` once the trial has ended.
`expired`	boolean	Whether the provisioner says the trial has ended.
`days_since_end`	integer or `null`	Whole days since the trial ended; `null` while it is running.
`contact_url`	string	Destination for Contact Genesis, as an `https` or `mailto` URL. Defaults to `mailto:[email protected]?subject=Genesis%20Desktop%20access`.

For how trial status affects Genesis Desktop locking and display, see Genesis Desktop lock and origin controls.

Genesis Desktop version policy

The provisioner can include an app_version_policy object in activation, check-in, or entitlement answers to set a minimum or recommended Desktop version. The running app reports the resulting notice in GET /api/desktop/status; data.update_required and data.update_available are null when there is no applicable update:

Field	Type	Description
`data.update_required`	object or `null`	Present when the running version is below `min_version`, or when the provisioner refuses it outright with HTTP `426`. Contains `min_version`, `current_version`, `message`, and `download_url`, each of which may be `null`.
`data.update_available`	object or `null`	Present when the running version is below `recommended_version` but does not require an update. Contains `recommended_version`, `current_version`, and `download_url`; `recommended_version` is required.

In these notices, min_version, recommended_version, and current_version use the display name for named Genesis Desktop builds: for example, 1.19.98-3 is returned as 1.19.98d3. Other version strings are returned unchanged. The provisioner policy fields are min_version, recommended_version, message, and download_url. The version fields are optional release-version strings such as 0.2.28; message is optional text, and download_url is an optional HTTPS URL. A required notice locks Desktop until it updates; a recommended-only notice does not lock it. A 426 refusal uses status: "update_required" and may include app_version_policy beside detail. It locks the app even if the response omits a minimum version. The app retains the latest policy in memory and checks again at the normal check-in cadence, so it can unlock when the provisioner lowers its minimum. For lock enforcement and in-progress agent turns, see Genesis Desktop lock and origin controls.

Genesis Desktop release-channel updates

The Desktop updater checks its install’s release channel with GET /api/desktop/update/{target}/{arch}/{current_version}. target and arch must each match [a-z0-9_]{1,32}; current_version must match [0-9A-Za-z.+_-]{1,64}. The provisioner selects the channel (dev, internal, or public) from the install’s device credential, and the endpoint returns that channel’s Tauri latest.json manifest as published. The route returns 204 when no newer version is available, 404 when Desktop laptop mode is unavailable, 409 when the install is not activated, and 503 when the provisioner update check fails. On 409 or 503, Desktop checks the stable feed instead. The release-channel check is also available from the Update now action on the Update required lock screen.

Genesis Desktop diagnostics

The Genesis Desktop trial build sends redacted diagnostic logs to its provisioner. Secrets are removed before upload. This behavior is limited to Genesis Desktop; hosted and self-hosted deployments do not send these diagnostics. The provisioner must advertise diagnostics in its latest check-in response’s accepts list for automatic uploads to run. At each start, after this process’s first successful check-in, the Desktop check-in job uploads new redacted log content since the previous accepted upload. This includes the previous session’s remaining logs and the current start’s first lines. If Desktop starts offline, this upload runs on a check-in tick after the first successful check-in. After that startup attempt, the job attempts another automatic upload at most once an hour, measured from the previous attempt. Each attempt sends at most four chunks; any remaining log content is sent on a later hourly attempt. Failed chunks are retried on that schedule, not on every check-in tick. Both automatic uploads require an activated device credential and a provisioner that advertises diagnostics in its latest check-in response. Each chunk contains up to 1,500,000 log bytes by default. If the provisioner’s latest check-in response also advertises diagnostics_gzip, Desktop sends gzipped chunks of up to 4,000,000 log bytes instead; Send diagnostics uses gzip under the same condition. If a provisioner responds with HTTP 413, Desktop halves the automatic chunk size and retries, down to 64,000 bytes, then retains that size for the rest of the process. The job also includes redacted log excerpts around recent failures in a check-in when the provisioner accepts diagnostics. A failure excerpt is generated for an error or crash, or a failed tool or query event. Genesis Desktop can also show a preview before a person chooses Send diagnostics. These laptop-mode routes return HTTP 404 when laptop mode is unavailable:

Method	Path	Description
`GET`	`/api/desktop/diagnostics/preview?reason=manual`	Preview the redacted recent log files for a manual send. `reason` is required and may be `manual` or `error_card`.
`POST`	`/api/desktop/diagnostics/send`	Upload the exact preview identified by `bundle_id`; the preview can be sent once, within 15 minutes.

Successful responses use { "success": true, "data": ... }. The preview’s data contains:

Field	Type	Description
`bundle_id`	string	Identifier to submit to the send route.
`reason`	`"manual"` or `"error_card"`	Reason selected when the preview was created.
`files`	array	Redacted log files, each with `name`, `text`, and `bytes` (UTF-8 byte count).
`total_bytes`	integer	Total UTF-8 bytes across the files.

Send the preview identifier in the request body:

{ "bundle_id": "0123456789abcdef0123456789abcdef" }

The send response’s data contains the provisioner’s receipt id, and optional received_at and expires_at timestamps. The send route returns HTTP 404 if the preview expired, was already sent, or laptop mode is unavailable; 409 if the device is not activated; and 503 if the provisioner cannot accept the upload.

Genesis Desktop browser tools

These routes manage the browser driver and Chromium downloaded by Genesis Desktop. They are available only when the server runs in laptop mode; otherwise they return HTTP 403. The install and remove operations apply to the computer running Genesis, not to a remote browser client.

Method and path	Behavior
`GET /api/desktop/browser-tools`	Return the current browser-tools status.
`POST /api/desktop/browser-tools/install`	Start the download or return the status of an install already in progress. The request returns without waiting for the download; poll the GET route for progress.
`POST /api/desktop/browser-tools/remove`	Remove the downloaded driver and browser. Returns HTTP `409` while an install is running.

Successful responses use { "success": true, "data": ... }. The data object contains:

Field	Type	Description
`state`	string	One of `not_managed` (this server does not use downloadable browser tools), `unavailable` (the tools cannot be installed here), `not_installed`, `outdated` (installed for another Playwright version), `installing`, `installed`, or `failed` (the last install attempt failed).
`download_mb`	integer	Download size in MB for the pinned browser tools; `0` when this Genesis does not manage a download.
`playwright_version`	string	Playwright version required by this Genesis build, or an empty string when unmanaged.
`phase`	`"driver"`, `"browser"`, or `null`	Current install phase; non-null while an install is running.
`percent`	integer or `null`	Progress percentage while an install is running.
`error`	string or `null`	Failure detail when `state` is `failed`, or the reason browser tools are unavailable.

The install and remove routes return HTTP 501 when this Genesis does not manage downloadable browser tools. The Settings controls and first-use browser behavior are described in Advanced Settings — Browser tools and Browser Tools.

Genesis Desktop MCP clients

These laptop-mode routes inspect and connect MCP clients on the computer running Genesis. The client list is available only in laptop mode; otherwise it returns HTTP 403.

Method and path	Behavior
`GET /api/desktop/mcp/clients`	Return detected clients in `data.clients[]`, including whether each client is installed and its registration status.

Each client includes connectable (boolean). false means Connect cannot work for that client; connect_action gives the reason.

Desktop CLI connections

These routes detect and import connections configured in local CLIs and Git on the computer running Genesis. They are available only in laptop mode; otherwise they return HTTP 403. Detection never returns credential values. If gh has no github.com account, detection also checks Git’s credential helper and, when that check finds no sign-in, may run an SSH authentication check against github.com. That check can make one network round trip.

Method and path	Behavior
`GET /api/desktop/cli-connections`	Detect local CLI profiles and return `{ "success": true, "data": { "candidates": [...], "files_read": [...], "problems": [...] } }`. GitHub candidates can have `auth_kind` / `origin` of `git_credential` or `ssh`. A helper-backed candidate can be imported as a GitHub PAT connection with consent to copy its token; an SSH-only candidate is not importable because SSH does not provide a GitHub API token. A previously declined candidate has `declined: true` and `preselected: false`; see Connections — Desktop CLI profile import for the user-facing selection behavior.
`POST /api/desktop/cli-connections/import`	Import the candidate named by `candidate_id`; for a Git credential candidate, set `consent_to_copy_secret: true` to copy its token into Genesis secrets. Connection details are re-read locally rather than accepted from the request.
`POST /api/desktop/cli-connections/declined`	Remember candidate IDs the person chose not to add.

The decline request accepts one to 100 candidate IDs, for example:

{ "candidate_ids": ["git:github.com"] }

It returns { "success": true }. A successful import clears that candidate’s declined state.

Hosted identity lifecycle

Hosted deployments use auth.provider: hosted to verify signed assertions against the configured issuer, audience, JWKS URL, tenant, and installation. Verification alone does not authorize application access: the assertion subject must resolve to an active explicit identity link for that tenant and installation. Hosted lifecycle responses contain only the selected binding_id and its state; assertion claims and audit details are not returned. For the role-ownership rule that keeps hosted roles tied to active identity links during startup and revocation, see Hosted identity links.

`POST /api/hosted-identities/initial-admin`

Creates the sole initial administrator binding. This route requires a verified hosted management assertion with the hosted.identity.bootstrap scope.

`POST /api/hosted-identities/invitations`

Creates one ordinary hosted-user binding. The authenticated hosted user must have the manage_users permission.

`POST /api/hosted-identities/{binding_id}/revoke`

Revokes one exact binding selected by the path parameter. A hosted user needs manage_users; a management assertion needs the hosted.identity.emergency_revoke scope. The request body for the initial-admin and invitation routes is:

Field	Type	Required	Description
`operation_id`	string	Yes	Bounded operation identity. Maximum 128 characters; allowed characters are letters, numbers, `.`, `_`, `:`, and `-`.
`binding_id`	string	Yes	Exact binding identity. Maximum 128 characters; allowed characters are letters, numbers, `.`, `_`, `:`, and `-`.
`provider`	`"hosted"`	Yes	Hosted provider discriminator.
`subject`	string	Yes	Canonical hosted subject to bind. Maximum 255 characters.
`display_name`	string	Yes	Display name for the Genesis user. Maximum 255 characters.

The revocation body contains only operation_id with the same bounded string rules. Successful responses have the form:

{"binding_id":"customer-123","state":"active"}

Hosted WebSocket admission

In hosted mode, the estate-live, log, unified, sandbox-terminal, and CLI-terminal WebSockets require the same verified hosted assertion and active identity link before accepting the socket. Sandbox and CLI terminal access are then checked against the admitted user’s existing permissions and ownership rules. Hosted sockets are rechecked while connected; an expired or revoked identity closes the socket instead of leaving the session usable.

Blueprint library inventory endpoint

GET /api/blueprints/ returns the Blueprint Library inventory used by the web client. The inventory and agent capability catalog/search omit built-in blueprints marked hidden: true; those blueprints remain startable by name. See Hidden built-in blueprints for the affected blueprints and supported start routes. Malformed manifest fields do not remove the rest of the library from the index; see Library index resilience for the handling of the skipped entry. When authentication is enabled, Genesis filters out blueprints the caller cannot view. The same ownership resolution applies here, so owners continue to see their own blueprints without separate role grants. Callers also pass when their role includes view_all_blueprints or manage_all_blueprints.

`GET /api/blueprints/`

Field	In	Type	Default	Required	Description
`category`	query	string or null	`null`	No	Optional exact-match category filter.
`repo_id`	query	string or null	`null`	No	Optional filter for `source_repo_id`.
`source_type`	query	string or null	`null`	No	Optional filter for source type. Allowed values: `default`, `local`, `remote`.
`group_by_repo`	query	boolean	`false`	No	When `true`, also return `grouped_by_repo` keyed by `repository_group_key`.

Blueprint library response fields

Field	Type	Description
`success`	boolean	Whether the inventory request completed successfully.
`default_blueprints`	object[]	Default blueprints visible to the caller after filtering.
`custom_blueprints`	object[]	Custom blueprints visible to the caller after filtering.
`grouped_by_repo`	`object<string, object[]>` or absent	Present only when `group_by_repo=true`. Groups returned blueprints by `repository_group_key`, with `unassigned` used when no repository group is available.

Key per-blueprint inventory fields

Field	Type	When present	Description
`name`	string	Always	Blueprint identifier shown in the library.
`blueprint_id`	string	Always	Stable identity returned for the listed blueprint. Send this value back on Blueprint routes that support duplicate-name resolution so follow-up requests stay pinned to the same source-backed blueprint.
`short_description`	string	Always; may be empty string	Concise manifest-backed summary intended for tile/card display. Maps to `blueprint.short_description`; clients can fall back to `description` when blank.
`author`	string or absent	When the manifest records a free-text author	Manifest `author` field. Absent on Genesis-shipped list entries.
`author_display`	string	Always on index entries	Readable author label for library display. Genesis-shipped blueprints return `Genesis Team`. Custom blueprints return the RBAC creator’s display name or email resolved from `owner_identity`; when resolution fails, Genesis falls back to the manifest `author` when present, otherwise `Unknown`.
`source_type`	string	Always	Source classification used by filtering. Allowed values are `default`, `local`, and `remote`.
`source_repo_id`	string or null	When the blueprint is tied to a repository source	Repository identifier used by the `repo_id` filter.
`owner_identity`	string or null	On custom blueprints when the manifest records an owner	RBAC creator user id resolved from `created_by` metadata, with fallback to `origin.created_by_user_id` when needed. Used for ownership checks and to build `author_display`. Not set on Genesis-shipped blueprints.
`origin`	object or null	When custom or imported blueprint provenance is available	Provenance block extracted from `blueprint_manifest.yaml`. See Blueprint origin fields.
`user_can_manage`	boolean	Auth-enabled listings	Whether the caller can manage Blueprint access or versioning.
`user_can_edit`	boolean	Auth-enabled listings	Whether the caller can edit the Blueprint.
`user_can_execute`	boolean	Auth-enabled listings	Whether the caller can execute the Blueprint.
`user_can_delete`	boolean	Auth-enabled listings	Whether the caller can delete this Blueprint. When durable blueprint history is enabled, this requires `manage`; otherwise the delete route does not add an access check.

Blueprint authoring short-description field

The Blueprint editor also sends short_description on create and update requests. This field writes to blueprint.short_description in blueprint_manifest.yaml.

Field	Used by	Type	Default	Description
`short_description`	`POST /api/blueprints/`	string	`""`	Short description for tile/card display. Maximum length `200`; about `116` characters is recommended.
`short_description`	`PUT /api/blueprints/{blueprint_name}`	string or null	`null`	Optional replacement for the existing tile/card summary. Send an empty string to clear it. Maximum length `200`; about `116` characters is recommended.

Create requests also accept default_mode, which writes blueprint.default_mode:

Field	Used by	Type	Default	Description
`default_mode`	`POST /api/blueprints/`	string	`"goal"`	The mode a Mission of this blueprint starts in when the start names none: `goal`, `manual`, or the legacy `continuous`, still accepted. Omitted or empty, a new blueprint defaults to `goal`.
`default_mode`	`PUT /api/blueprints/{blueprint_name}`	string or null	`null`	Optional replacement for the saved default mode; `null` leaves it unchanged.

Blueprint recommendation wizard endpoint

POST /api/blueprints/wizard powers the guided mission-creation flow. Genesis matches the caller’s free-text goal against the Blueprint Library and only considers blueprints the caller can execute. Depending on how specific the request is, the route returns either up to two clarifying questions or up to three ranked blueprint recommendations. When the caller has visible saved connections, Genesis may also use a compact RBAC-filtered connection summary as a soft signal about likely platforms. Missing or mismatched connections do not make a blueprint ineligible. After a client submits answers, Genesis does not start another follow-up round and instead returns type: recommendations. Follow-up calls can also include answer_context so Genesis receives the original question text alongside each answer instead of only question IDs.

`POST /api/blueprints/wizard`

Field	In	Type	Default	Required	Description
`query`	body	string	none	Yes	User’s free-text description of their data goal. Minimum length `1`, maximum length `2000`.
`answers`	body	object<string, string> or null	`null`	No	Answers to follow-up questions keyed by question `id`.
`answer_context`	body	object[] or null	`null`	No	Optional structured follow-up context. Each item includes `id`, `question`, and `answer` so Genesis can use the original question text when generating recommendations.
`session_id`	body	string or null	`null`	No	Correlates multi-turn wizard interactions. Maximum length `64`.

Blueprint wizard answer-context item fields

Field	Type	Required	Description
`id`	string	Yes	Original question identifier. Maximum length `200`.
`question`	string	Yes	Original question text shown to the user. Maximum length `500`.
`answer`	string	Yes	User-provided answer for the question. Maximum length `2000`.

Blueprint wizard response fields

Field	Type	Description
`type`	string	Either `questions` or `recommendations`.
`questions`	object[] or null	Present when `type` is `questions`. Up to 2 entries.
`recommendations`	object[] or null	Present when `type` is `recommendations`. Up to 3 entries.
`session_id`	string	Session identifier to send back on follow-up calls.

When the advisor LLM omits type but returns exactly one non-empty, shape-valid array — questions (each item has id and text) or recommendations (each item has blueprint_name, numeric confidence, and rationale) — Genesis infers type server-side before returning the response. An absent or empty array, malformed items, an explicit but invalid type, or both arrays present without type still fail validation. Some Claude endpoints return the complete recommendation object as a JSON string in the top-level recommendations field. Genesis accepts this form only when the outer object contains exactly that field and its decoded object contains exactly type: "recommendations" and a non-empty recommendations array of valid items. Recommendation confidence must be numeric (not a boolean) and between 0.0 and 1.0, inclusive; out-of-range values fail validation.

Blueprint wizard question fields

Field	Type	Description
`id`	string	Stable question identifier.
`text`	string	The question to display.
`options`	string[]	Suggested clickable answers.
`allow_free_text`	boolean	Whether a free-text fallback is allowed. Default `true`.

Blueprint wizard recommendation fields

Field	Type	Description
`blueprint_name`	string	Blueprint identifier.
`confidence`	float	Fit score from `0.0` to `1.0`.
`rationale`	string	Why the blueprint fits.
`description`	string	Blueprint description copied from catalog metadata.
`category`	string	Blueprint category copied from catalog metadata.
`tags`	string[]	Blueprint tags copied from catalog metadata.
`estimated_duration`	string	Blueprint duration copied from catalog metadata.
`use_cases`	string[]	Blueprint use cases copied from catalog metadata.

Blueprint wizard error responses

POST /api/blueprints/wizard returns a classified LLM error when the advisor cannot produce a usable result; clients should not treat it as an empty recommendation list. The response uses error_type: "llm_error", a safe top-level error message, request_id, and payload.llm_failure. The llm_failure object contains kind, message, action, and error_id; it does not include the provider’s raw error text. The response also includes the request ID in the X-Request-Id header.

Status	`payload.llm_failure.kind`	When returned
`424`	`connection_required`, `authentication`, `access_denied`, `not_configured`, `quota_exhausted`	The provider connection, credentials, model access, configuration, or available quota needs attention.
`429`	`rate_limit`	The provider’s request limit was reached.
`504`	`timeout`	The model did not respond in time.
`503`	`unavailable`	The model service is unavailable.
`502`	`invalid_response`	The model response could not be processed, including an unusable wizard response.
`422`	`context_limit`, `invalid_request`	The request exceeds the model context limit or the provider could not accept the request.
`500`	`unknown`	The failure could not be classified.

For the same structured failure metadata on chat messages and stream events, see Chat endpoints — working with threads.

Blueprint path parameter

Field	Type	Required	Description
`blueprint_name`	string	Yes	Blueprint identifier used in the Blueprint API routes.

Optional blueprint identity query parameter

Field	In	Type	Default	Required	Description
`blueprint_id`	query	string or null	`null`	No	Stable identity previously returned by the Blueprint Library or detail routes. Use it on Blueprint routes that support duplicate-name resolution, including export, versioning, access, history, mission list, mission start, update, rename, revert, delete, and dev-session routes, so the request stays pinned to the same source-backed blueprint when names overlap across sources.

Blueprint export endpoint

GET /api/blueprints/{blueprint_name}/export streams a ZIP of a custom (non-default) blueprint working copy. When the blueprint is versioned, Genesis also bundles saved version snapshots and embeds a blueprint_export_manifest.yaml sidecar.

`GET /api/blueprints/{blueprint_name}/export`

Field	In	Type	Default	Required	Description
`blueprint_id`	query	string or null	`null`	No	Stable identity previously returned by the Blueprint Library or detail routes. Use it when names overlap across sources so the export stays pinned to the same Blueprint.

Current Genesis exports use manifest_version: 2 in the sidecar. In addition to blueprint_name, the manifest records blueprint_id, source_identity (source_type, source_id, repo_id, path), and working_copy_fingerprint so destination imports can match identity across environments. When the blueprint is versioned, the manifest also includes a versioning block with production and working-copy metadata plus per-version snapshot roots. Legacy exports without blueprint_id remain importable; the import preview marks them as legacy_export: true and requires explicit confirmation before Add as a new version can target an exact name match. If a saved version’s files are no longer available, Genesis completes the working-copy export but omits that version from the archive. The manifest lists omissions in versioning.versions_not_included and sets versioning.includes_all_saved_versions to false; if the omitted version was production, its reason warns that an imported archive will have no production pin for it.

Blueprint ZIP import endpoints

Blueprint ZIP uploads are limited to 64 MiB. Archives with more than 2048 members, oversized members, or unsafe compression ratios are rejected during validation. POST /api/blueprints/import/preview accepts multipart form field file and optional confirm_legacy_name_match (boolean, default false). The route validates a ZIP without changing files, registrations, or version history. The response identifies the incoming blueprint_name, optional blueprint_id, manifest_version, legacy_export, matching local target, allowed collision strategies, and recommended_strategy. When valid is false, message carries the validation error. Preview responses can also include:

Field	Type	Description
`collision`	boolean	Whether any same-name blueprint candidates were found.
`allowed_strategies`	string[]	Strategies currently allowed without extra confirmation (`create_copy`, `create_version`, `replace`).
`strategies`	object	Per-strategy availability with `allowed`, optional `reason_code`, `message`, and `requires_confirmation`.
`requires_legacy_name_confirmation`	boolean	When `true`, legacy exports need `confirm_legacy_name_match=true` before Add as a new version.
`recommended_strategy`	string	Strategy Genesis recommends in the import UI (`create_version` when allowed, otherwise `create_copy`).

Older exports can be previewed without confirmation; the response marks create_version as requiring a legacy name-match confirmation when the export lacks blueprint_id. POST /api/blueprints/import accepts multipart form field file plus:

collision_strategy: create_copy (default), create_version, or replace.
promote_imported_version: optionally promote a newly created destination version when collision_strategy=create_version. Ignored for copy and replace operations. Requires Blueprint manage access on the destination.
confirm_legacy_name_match: required before a pre-v2 export can update an existing blueprint by exact name with collision_strategy=create_version.
override: backward-compatible boolean alias for collision_strategy=replace.

create_copy keeps the existing object and suffixes the imported name on collision. create_version requires one matching editable local blueprint_id, preserves destination-owned history and production, and appends one local version; identical content returns no_change=true. When the backing Git repository already exists, Genesis stages and commits the imported working copy with message Import blueprint version: {blueprint_name} so the import is visible through GET /api/blueprints/{blueprint_name}/history. replace changes only the working copy and preserves existing destination history. Default, WIP, ambiguous, and managed-repository targets reject version import with HTTP 409 and structured detail fields such as error_code, blueprint_name, and blueprint_id (for example BLUEPRINT_IDENTITY_MISMATCH, BLUEPRINT_VERSION_TARGET_NOT_UNIQUE, LEGACY_BLUEPRINT_CONFIRMATION_REQUIRED). Successful import responses include import_action, blueprint_name, blueprint_id, created_version_number, created_version_id, promoted, no_change, overrode_existing, and a human-readable message. For new installs and create_copy imports, Genesis assigns the importing user as manifest created_by so RBAC grants immediate view, edit, and manage access to the installed copy. When the archive lacks an explicit origin block, Genesis records the archive creator there (including legacy manifests that only stored created_by) before replacing the local owner. create_version and replace preserve the destination blueprint’s existing created_by and origin.

Blueprint detail endpoint

GET /api/blueprints/{blueprint_name} returns the resolved Blueprint manifest, phase payloads, source-selection metadata, and caller access flags used by the Blueprint detail page.

`GET /api/blueprints/{blueprint_name}`

Field	In	Type	Default	Required	Description
`blueprint_id`	query	string or null	`null`	No	Stable identity previously returned by the Blueprint Library or detail routes. Use it when names overlap across sources so the detail request stays pinned to the same Blueprint.
`at_timestamp`	query	string or null	`null`	No	Optional ISO timestamp used to retrieve the historical manifest and phase files nearest that time.
`mission_id`	query	string or null	`null`	No	Mission this read renders. If the blueprint name is ambiguous and `blueprint_id` is omitted, resolves to the Blueprint the mission recorded or ran. This resolution reads the mission record when the name is ambiguous.
`source`	query	string or null	`null`	No	Blueprint source mode. Use `working_copy` for the editable draft, `production` for the pinned production snapshot, or `default_release` for the remote release checkout. Legacy aliases `wip` and `default` still normalize to `working_copy` and `default_release`.

Key Blueprint detail response fields

Field	Type	Description
`success`	boolean	Whether the detail request completed successfully.
`blueprint`	object	Resolved Blueprint payload used by the detail page.
`blueprint.user_can_view`	boolean	Whether the caller can view this Blueprint.
`blueprint.user_can_manage`	boolean	Whether the caller can manage Blueprint versioning or access.
`blueprint.user_can_edit`	boolean	Whether the caller can edit the Blueprint working copy.
`blueprint.user_can_execute`	boolean	Whether the caller can start missions from this Blueprint.
`blueprint.user_can_delete`	boolean	Whether the delete route permits the caller to delete this Blueprint.
`blueprint._historical_version`	object or absent	Present when `at_timestamp` is supplied. Includes `commit_hash`, `commit_date`, and `is_fallback`.
`blueprint.author`	string	Manifest author, or `Genesis Team` for a shipped Blueprint without an author, or `Unknown` for a custom Blueprint without one.
`blueprint.author_display`	string	Readable author label for the detail page. Custom Blueprints use the RBAC creator’s display name or email when resolved, then the manifest author, otherwise `Unknown`; shipped Blueprints use `Genesis Team`.
`blueprint.origin`	object or null	Provenance block for custom or imported blueprints. See Blueprint origin fields.
`blueprint.source_view`	object	Source-selection metadata for source-aware Blueprint detail views.
`blueprint.inputs`	object or absent	Structured input contract with `required` and `optional` arrays (each entry has `name`, `type`, `description`, and optional `default`).
`blueprint.outputs`	array or absent	Declared output artifacts downstream handoffs can consume (each entry has `name`, `type`, `description`, and optional `path`).

Blueprint file endpoint

GET /api/blueprints/{blueprint_name}/files/{file_path} serves a resource file from a Blueprint package. Use mission_id for a file read rendered in a mission when duplicate Blueprint names need to resolve to the Blueprint that mission recorded or ran.

Field	In	Type	Default	Required	Description
`file_path`	path	string	none	Yes	Relative file path within the Blueprint package.
`download`	query	boolean	`false`	No	Force download instead of inline display.
`blueprint_id`	query	string or null	`null`	No	Stable Blueprint identity for duplicate-name resolution.
`at_timestamp`	query	string or null	`null`	No	Optional ISO timestamp to retrieve the file as it was at that time.
`repo_id`	query	string or null	`null`	No	Optional repository id for loading a file from another repository.
`mission_id`	query	string or null	`null`	No	Mission this read renders. When the Blueprint name is ambiguous and `blueprint_id` is omitted, resolves to the Blueprint the mission recorded or ran. Resolving an ambiguous name reads the mission record.

Blueprint origin fields

The same origin schema is used by the inventory origin field and the detail payload blueprint.origin.

Field	Type	Description
`created_by_user_id`	string or null	Original creator or first importer recorded in provenance. After a ZIP import into a new local copy, this may differ from top-level `created_by`, which identifies the local RBAC owner.
`created_by_agent`	string or null	Agent name recorded when Genesis created the blueprint automatically.
`created_by_thread_id`	string or null	Thread that created the blueprint when Genesis captured that provenance.
`created_at`	string or null	ISO timestamp for the provenance record.
`source`	string or null	Origin source such as `create_blueprint`, `copy`, `import`, or `legacy`.
`source_thread_ids`	string[]	Source conversation thread IDs used to build the blueprint, when applicable.
`import_events`	object[]	Ordered import history entries. Each item can include `imported_by_user_id`, `imported_at`, `import_source`, and `imported_via`.

`blueprint.source_view` fields

Field	Type	Description
`active_source`	string	Current resolved source: `working_copy`, `production`, or `default_release`.
`active_source_read_only`	boolean	Whether the selected source is read-only.
`available_sources`	object[]	Switchable source options. Each item includes `mode`, `read_only`, and optional `version_number`.
`can_switch`	boolean	Whether the caller can switch between available sources.
`working_copy_dirty`	boolean	Whether the working copy differs from its saved baseline.
`working_copy_baseline_version_number`	integer or null	Saved version number used as the working-copy baseline when versioning is enabled.
`working_copy_matches_production`	boolean	Whether the working-copy fingerprint matches the current production fingerprint.
`production_version_number`	integer or null	Current production version number when the Blueprint has a pinned production snapshot.

Blueprint rename endpoint

POST /api/blueprints/{blueprint_name}/rename renames an existing local or remote-backed blueprint. The route rejects default blueprints, active WIP sessions, and blueprints that still have in-flight missions. Local renames take effect immediately. Remote-backed renames open a pull request and become effective after that pull request is merged and the next source sync applies the rename. Genesis also migrates completed mission references, saved versioning state, and Blueprint access grants to the new name. Requires Blueprint manage access and the system-level manage_git permission.

`POST /api/blueprints/{blueprint_name}/rename`

Field	In	Type	Default	Required	Description
`blueprint_id`	query	string or null	`null`	No	Stable identity previously returned by the Blueprint Library or detail routes. Use it when names overlap across sources so the rename request stays pinned to the same Blueprint.
`new_name`	body	string	none	Yes	New blueprint name. Minimum length `1`, maximum length `100`, pattern `^[a-z0-9_-]+$`.

Blueprint rename response fields

Field	Type	Description
`success`	boolean	Whether the rename request succeeded.
`rename_type`	string	Rename mode: `local` or `remote`.
`old_name`	string	Blueprint name before the rename.
`new_name`	string	Blueprint name after the rename.
`old_blueprint_id`	string or null	Stable identity before the rename when Genesis can resolve it.
`new_blueprint_id`	string or null	Stable identity after the rename when Genesis can resolve it.
`message`	string	Human-readable rename result.
`pull_request_url`	string or null	Present for remote-backed renames when Genesis opens a pull request.
`branch_name`	string or null	Present for remote-backed renames when Genesis creates a rename branch.
`tombstone_path`	string or null	Present for remote-backed renames. Points to the repository-relative rename tombstone path Genesis uses during sync.

Blueprint rename status behavior

Status	Meaning
`200`	Local rename completed, or remote-backed rename pull request opened successfully.
`400`	The request used the current name again, targeted an active WIP session, or another rename precondition failed.
`403`	The caller lacks Blueprint `manage` access or `manage_git`, or the target Blueprint is default and cannot be renamed.
`409`	The new name already exists, or the Blueprint still has in-flight missions. In-flight responses include `error_code` `BLUEPRINT_HAS_INFLIGHT_MISSIONS`.
`422`	`new_name` failed request validation.

Blueprint RBAC actions

The access-management endpoints accept these Blueprint action names:

Action	Allows
`view`	Read the versioning summary and list saved versions.
`edit`	Create saved versions and restore the working copy from a saved version.
`manage`	Enable versioning, promote versions to production, rename custom or remote-backed blueprints, and manage access grants.
`execute`	Run the blueprint where execution access is enforced elsewhere in Genesis.

Blueprint-wide role permissions

Genesis checks Blueprint access in two layers. First, it evaluates the per-blueprint policy: admin bypass, ownership, or an explicit blueprint:<name> grant for the requested action. If that does not allow access, Genesis falls back to role-level blueprint-wide permissions:

Permission	Effective Blueprint actions
`view_all_blueprints`	`view`, `execute`
`manage_all_blueprints`	`view`, `edit`, `manage`, `execute`

Grant these on a custom role in Config → Users (or via RBAC role updates) to give members every existing and future blueprint without individual /api/blueprints/{blueprint_name}/access/grant calls. The built-in admin role includes both permissions by default.

Blueprint delete endpoint

DELETE /api/blueprints/{blueprint_name} permanently deletes a custom Blueprint without missions. If it has associated missions, Genesis hides it instead. When durable blueprint history is enabled (durable SQLite or git durability for the Apps repository), hard deletion also removes its saved versions, release mode, promotion history, and production assignment, and the caller must have manage access. The optional blueprint_id query parameter pins the request to a stable Blueprint identity; see Optional blueprint identity query parameter.

Status	Meaning
`403`	The caller lacks `manage` access when history is durable, or the target is a default Blueprint.
`404`	The custom Blueprint does not exist.
`409`	Git durability refuses the Apps repository for history cleanup.
`503`	Versioning is unavailable or the Apps repository is still restoring; retry the delete. The Blueprint remains registered if history cleanup was not completed.

Versioning endpoints

Method	Path	Description	Required action
`GET`	`/api/blueprints/{blueprint_name}/versioning/summary`	Get release-mode, production, working-copy, and saved-version summary data.	`view`
`POST`	`/api/blueprints/{blueprint_name}/versioning/enable`	Enable versioning, create `v1`, and set it as production.	`manage`
`GET`	`/api/blueprints/{blueprint_name}/versioning/versions`	List all saved versions for the blueprint.	`view`
`POST`	`/api/blueprints/{blueprint_name}/versioning/versions`	Create a new saved version snapshot from the current working copy.	`edit`
`POST`	`/api/blueprints/{blueprint_name}/versioning/promote`	Promote a saved version to production.	`manage`
`POST`	`/api/blueprints/{blueprint_name}/versioning/restore`	Restore the working copy from a saved version.	`edit`

A blueprint must already be in versioned mode before you can create, promote, or restore saved versions. When an operation needs saved-version files from an Apps repository still being restored after a restart, it can return 503 and be retried. A missing production assignment or unavailable production snapshot returns 404; conflicting or unsafe Apps-repository state returns 409.

Versioning summary fields

GET /api/blueprints/{blueprint_name}/versioning/summary returns these top-level fields:

Field	Type	Description
`blueprint_release_mode`	string	Current mode: `standard` or `versioned`.
`is_versioned`	boolean	Whether the blueprint is in versioned mode.
`production`	object or null	Current production assignment, including the promoted version payload when available.
`production_version_id`	string or null	Saved version currently assigned to production.
`production_version_number`	integer or null	Numeric version currently assigned to production.
`production_promoted_at`	string or null	ISO timestamp for the current production promotion.
`manual_promotion`	boolean	Whether the managed source is configured to hold synced blueprint changes for an administrator to promote.
`working_copy_dirty`	boolean	Whether the working copy differs from its baseline version.
`working_copy_baseline_version_id`	string or null	Baseline saved version for the current working copy.
`working_copy_baseline_version_number`	integer or null	Numeric baseline version for the current working copy.
`working_copy_matches_production`	boolean	Whether the working copy fingerprint matches the production version fingerprint.
`latest_version_number`	integer or null	Highest saved version number for this blueprint.
`latest_version_id`	string or null	Identifier of the highest-numbered saved version.
`previous_production_version_id`	string or null	Identifier of the most recently promoted version other than the current production version, when available.
`previous_production_version_number`	integer or null	Version number of the most recently promoted version other than the current production version, when available.
`available_version_count`	integer	Total number of saved versions.
`user_can_open_saved_versions`	boolean	Whether the current user can open saved versions in the UI.

Versioning request bodies

`POST /api/blueprints/{blueprint_name}/versioning/enable`

This endpoint does not document any request body fields.

`POST /api/blueprints/{blueprint_name}/versioning/versions`

Field	Type	Default	Required	Description
`note`	string or null	`null`	No	Optional note stored with the new saved version.

`POST /api/blueprints/{blueprint_name}/versioning/promote`

Field	Type	Default	Required	Description
`version_id`	string	none	Yes	Saved version identifier to promote.
`note`	string or null	`null`	No	Optional promotion note recorded with the action.

`POST /api/blueprints/{blueprint_name}/versioning/restore`

Field	Type	Default	Required	Description
`version_id`	string	none	Yes	Saved version identifier to restore into the working copy.
`force`	boolean	`false`	No	Optional restore flag accepted by the API.

Access-control endpoints

Method	Path	Description	Required action
`GET`	`/api/blueprints/{blueprint_name}/access`	Return configured RBAC role names and the current role grants for the blueprint.	`manage`
`POST`	`/api/blueprints/{blueprint_name}/access/grant`	Grant Blueprint RBAC actions to one role.	`manage`
`POST`	`/api/blueprints/{blueprint_name}/access/revoke`	Revoke Blueprint RBAC actions from one role.	`manage`

`GET /api/blueprints/{blueprint_name}/access`

Field	In	Type	Default	Required	Description
`blueprint_id`	query	string or null	`null`	No	Stable identity previously returned by the Blueprint Library or detail routes. Use it when duplicate blueprint names exist across sources.

Response fields:

Field	Type	Description
`blueprint_name`	string	Blueprint name for the access policies.
`blueprint_id`	string or null	Echoed when the request included `blueprint_id`.
`available_roles`	string[]	Configured RBAC role names (built-in and custom) that are valid targets for grant requests. Returned alongside current grants so callers with Blueprint `manage` access can share a blueprint without `manage_users`.
`roles`	object[]	Current role grants for this blueprint. Each item has `role_name` (string) and `actions` (string[] of `view`, `edit`, `manage`, `execute`).

`POST /api/blueprints/{blueprint_name}/access/grant`

Field	Type	Default	Required	Description
`role_name`	string	none	Yes	Configured RBAC role to update. Must match a built-in or custom role name (leading and trailing whitespace is trimmed).
`actions`	string[]	`[]`	Yes	One or more action names: `view`, `edit`, `manage`, `execute`.

Grant requests reject unknown role_name values with 400 Bad Request, for example: Unknown role 'analyst'. Choose one of the configured roles. Empty or whitespace-only role_name values return 400 with role_name is required.

`POST /api/blueprints/{blueprint_name}/access/revoke`

Field	Type	Default	Required	Description
`role_name`	string	none	Yes	Role to update.
`actions`	string[]	`[]`	Yes	One or more action names: `view`, `edit`, `manage`, `execute`.

Action Review endpoints

These routes provide one generic lifecycle for governed actions: propose, inspect, decide, execute, and reconcile. Proposal creation and reconciliation require APPROVE_AGENT_ACTION. Inbox listing accepts either APPROVE_AGENT_ACTION or view_connections: a signed-in caller without APPROVE_AGENT_ACTION sees Prover requests only, while a caller with it continues to see every authorized action family. Reading or acting on one proposal also requires APPROVE_AGENT_ACTION, except registered Prover requests, for which view_connections is sufficient. Approve and reject remain person-only. For Prover requests, any signed-in person with view_connections may decide only when they can also read the subject the request decides on: its comparison, finding, or view test cases. A request whose subject is hidden is answered as an unknown proposal (404), including for a caller who holds APPROVE_AGENT_ACTION. The person’s own PAT is accepted and attributed to its owner, while an agent’s own call, the system identity, and an app-only token are refused. Execute and reconcile also enforce the authenticated caller and deployment tenant boundary. The registry admits crm.merge.v1, the first Action Review action, and the Prover evidence-request action prover.request_finding_evidence.v1. The CRM action’s shipped default posture is require_review, so proposals for it enter the review lifecycle before execution; there is no configuration key that enables its action type. Salesforce and HubSpot CRM merge routes and connector tools now submit crm.merge.v1 proposals through this lifecycle while retaining their compatibility facades and legacy response shapes. The Prover action type is used by the request_evidence tool; its approval flow and result are documented there. Reviewer reads are scoped to the authenticated human and the deployment tenant. Rows for action scopes the caller cannot access are omitted, and detail, status, approval, rejection, execution, and reconciliation requests do not grant access just because the caller knows a proposal ID. Prover requests are also filtered by whether the caller can see the comparison or finding the request decides on, using the same visibility rule as the corresponding Prover read. Hidden requests are omitted from the inbox and total_count; requests beyond the visibility probe budget are withheld and reported as incomplete with incomplete_reason=probe_budget.

Action Review route summary

Method	Path	Description
`POST`	`/api/action-review/proposals`	Derive, admit, and persist one proposal from a typed intent.
`GET`	`/api/action-review/proposals`	List bounded caller-visible inbox rows, newest first.
`GET`	`/api/action-review/proposals/{proposal_id}`	Return the reviewer-scoped record, parsed payloads, and optionally its event trail.
`GET`	`/api/action-review/proposals/{proposal_id}/status`	Return the bounded status view for polling.
`POST`	`/api/action-review/proposals/{proposal_id}/approve`	Record one authenticated human approval.
`POST`	`/api/action-review/proposals/{proposal_id}/approve-and-execute`	Record the authenticated human approval and immediately attempt the action once.
`POST`	`/api/action-review/proposals/{proposal_id}/reject`	Record one authenticated human rejection.
`POST`	`/api/action-review/proposals/{proposal_id}/execute`	Claim the single-use grant and attempt the action once.
`POST`	`/api/action-review/proposals/{proposal_id}/reconcile`	Run a read-only postcondition check without re-executing the action.

`POST /api/action-review/proposals` request fields

Field	Type	Default	Required	Description
`action_type`	string	none	Yes	Registered, versioned semantic action type. Length is 1–128 characters.
`intent`	object	none	Yes	Handler-defined intent. The server-side handler re-derives the candidate, evidence, and scope from authoritative state; this object is not authoritative by itself.
`supersedes_proposal_id`	string or null	`null`	No	Proposal identifier superseded by this proposal. Maximum length is 64 characters.

`GET /api/action-review/proposals` query fields

Field	Type	Default	Description
`status`	string, array of strings, or null	`null`	Optional lifecycle-status filter. Repeat the query parameter for multiple statuses. Unknown status values return `400 Bad Request`.
`action_type`	string or null	`null`	Optional action-type filter. Maximum length is 128 characters.
`thread_id`	string or null	`null`	Optional thread identifier filter. Maximum length is 255 characters.
`dossier_scope`	`none`, `headline`, or `full`	`none`	How much stored review payload each row carries. Applied after reviewer scoping and paging, so it costs one stored-JSON parse per returned row per payload selected, not per row scanned. `headline` returns the dossier’s title and first record only; `full` returns the whole dossier and the expected effect. An unrecognised value is rejected.
`include_dossier`	boolean	`false`	Deprecated alias for `dossier_scope=full`, kept for clients written before `dossier_scope`. An explicit `dossier_scope` wins over it.
`visible_threads_only`	boolean	`false`	Keep only proposals raised on a thread the caller may open. Proposals without a thread are omitted. Each distinct thread costs one ownership read, up to 100 threads per request; rows beyond that probe budget are withheld and reported through `truncated=true` and `incomplete_reason=probe_budget`.
`include_statement`	boolean	`false`	Add `requested_statement` to each returned row when the governed action runs a statement. The value is the exact stored statement, without trimming; the option costs one in-memory read per returned row.
`offset`	integer	`0`	Number of visible rows to skip after reviewer-scope filtering. Must be 0 or greater.
`limit`	integer	`100`	Maximum number of rows to return, from 1 through 500.

For inbox listing, the service checks APPROVE_AGENT_ACTION once per request to choose whether to apply the Prover-only family filter; the RBAC lookup is served from memory once RBAC is warm. A caller without that permission sees Prover requests only, with the family filter applied in the ledger query before the bounded scan. Other action families therefore neither consume that caller’s scan ceiling nor make the Prover-only result incomplete. In either case, a Prover request is listed and counted only when the caller can read the subject it decides on. Prover subject visibility is checked independently of visible_threads_only. When the scan reaches a Prover request, it makes one indexed read per distinct finding or view boundary, up to 100 subjects. For a view boundary with snapshots, visibility requires access to every snapshot. For a boundary with no snapshots, as with a pair prepared by prepare_migration_prover, visibility requires access to every connection sealed in the request (source, target, and any warehouse connection). A request that sealed no connections uses the pair recorded for its boundary instead; an unreadable or missing pair is visible only to a caller with manage_all_connections. The same visibility rule applies when retrieving or deciding a Prover request. Requests beyond the subject budget are withheld; the response sets truncated=true and incomplete_reason=probe_budget. Submitting a Prover request also requires the caller to see its comparison, finding, or view boundary; an unseeable subject is refused as unknown before the request is stored. Reconciling an uncertain Prover request applies the same subject check before the handler reads it. The list is bounded: reviewer-scope checks are performed before offset paging, and the response can be incomplete when Genesis cannot examine every candidate or must omit a candidate. Use truncated and incomplete_reason to distinguish an incomplete view from an empty inbox. The wire values for incomplete_reason are probe_failure, probe_budget, handler_unavailable, row_unreadable, and scan_ceiling. Only one value is returned, using this precedence order: probe_failure > probe_budget > handler_unavailable > row_unreadable > scan_ceiling. The page limit is not an incomplete reason; compare total_count with the number of returned proposals to detect it. The detail route accepts include_events as a boolean query parameter, default true, and view as full or summary, default full. Set include_events=false when the caller needs the reviewer dossier without the durable event trail. view=full parses and returns the stored review payloads; view=summary returns the status view, linked record, expected_effect, requester_kind, bot_id, decided_by, decided_by_label, and decision_reason. It provides the request’s state, approval lifetime, and decision context without producing the omitted review payloads. When include_events=false, events is absent; when it is true, events is an array that can be empty. For a Prover disposition-package approval request, set include_package_signability=true to include viewer_can_sign, viewer_can_apply, and viewer_cannot_sign_reason for this caller. The server performs one package-state fold to produce these fields, so the option is opt-in; the package read already carries the same verdict when that page is available. For a Prover package request withdrawn because an agent’s bundle adopted it, the detail response also includes bundle_supersession with bundle_id, outcome, superseded_by_proposal_id, and superseded_by_url. The outcome is superseded when the bundle request was created, or bundle_request_not_created when it was not; in the latter case the package can be requested again. These fields are null until the supersession event is sealed. If include_events=false, this field costs one ledger event read for an adopted package request; other requests do not incur that read. When a bundle request holds the adopted package, detail also returns can_renew: false, ownership_reason (bundle_request_live, bundle_declined, or bundle_policy_denied), and holding_bundle_request with the owning request’s identity and decision details. Checking this ownership reads the package owner; in view=summary, when the response has no intent, it also reads the proposal to locate the package coordinates.

`POST /api/action-review/proposals/{proposal_id}/approve` and `/reject`

Both decision routes accept the same body:

Field	Type	Default	Required	Description
`reason`	string or null	`null`	No	Optional human decision reason. Maximum length is 2000 characters.

Approval and rejection are separate operations by default. For a proposal that the current human is allowed to execute, POST /api/action-review/proposals/{proposal_id}/approve-and-execute combines the approval and the single execution attempt. Its body uses the same optional reason field. The response reports success, decided, claimed, final_status, execution_refusal_reason, and the optional execution_refusal_detail and execution_error_detail. success is true only when final_status is executed; a refusal is returned with HTTP 200 and success: false. When a handler or provider proves that it refused before any write was applied, final_status is not_applied, and the handler’s reason and detail are returned in execution_refusal_reason and execution_refusal_detail. When the effect may have applied, final_status is reconciliation_required; do not retry the action, and use execution_error_detail for the provider’s error when the handler captured it. Approval refusal issues no grant, while refusal before claiming leaves the grant unspent. A decision can be refused with 409 Conflict when the proposal or current policy no longer matches the decision context. Some actions have no separate apply step: approving them is the whole action. Every proposal read (status, list rows and detail) carries approving_is_the_action, and it is true for those actions, currently Prover test-case approval (prover.approve_view_test_cases.v1) and learning adoption (learning.adopt.v1) and local command runs (local_cli.run.v1; see run_local_command). For such a proposal, POST .../approve also applies it in the same request, exactly as approve-and-execute does, and its response adds the same claimed, final_status, execution_refusal_reason, execution_refusal_detail and execution_error_detail fields; success is then true only when the change was applied. The proposal stays authorized only when the apply could not start (the policy could not be reloaded, or the executor was refused before the claim); claimed is then false and execution_refusal_reason says why. execution_refusal_reason: "claim_lost" means another executor holds or has already spent the grant. claimed: true with no final_status (outcome_not_recorded) means the attempt ran but its outcome was not stored; do not retry it. For every other proposal, approve answers success, decided, refusal_reason and proposal only.

Decision hand-back to the agent

After a human approval or rejection is committed, Genesis sends the decision and optional reason to the registered agent conversation that raised the proposal. This applies whether the person decides in the Action Review page or through these API routes. A tool call made outside a Genesis conversation (over MCP or /api/tool_call) does not receive this hand-back; its caller must poll action_review_request_status for the request it opened. A delivery failure does not undo the decision; the default-on Action Review cleanup sweep retries a hand-back that was not delivered durably. The sweep cadence is controlled by action_review.sweep_interval_seconds (default 600 seconds; see Action Review settings). The Prover disposition-package action type is prover.approve_disposition_package.v1. Its handler compares the package’s approval projection digest before writing and applies every staged item in one strict transaction or none. The Action Review proposal’s expected_effect identifies each finding’s disposition and durability; the package’s overall durability is the furthest-reaching item level. A successful execution returns an execution receipt that links the Action Review proposal and digest to the Prover decision event; a drift, unavailable promotion, or lock conflict is reported as not applied rather than as a partial package approval. The composite Prover bundle action type is prover.approve_composite_bundle.v1. It is created when a review bundle carries one or more disposition packages, and its sealed projection includes the bundle’s rules, packages, and evidence-gap decisions. Execution applies every carried member in one transaction or none. The native bundle /approve endpoint does not accept this grant; approve the linked Action Review proposal instead. The improvement-docket action type is prover.decide_improvement_docket_entry.v1, one request per finding. Its sealed projection names each open element, the finding’s disposition, and the licence approving installs. Execution accepts every element in one transaction or none. Declining leaves the elements open. The native docket /accept endpoint refuses an agent-filed entry; approve its Action Review request instead. Generic HTTP execution does not carry a trusted tool or Blueprint runtime origin. When an authorized proposal is bound to a non-empty origin, the execute route refuses it with claimed=false and refusal_reason=execution_origin_required before claiming the single-use grant, so the human approval remains available for execution from its originating runtime.

Action Review response fields

Status responses contain success and a proposal object with these fields:

Field	Type	Description
`proposal_id`	string	Proposal identifier.
`supersedes_proposal_id`	string or null	Identifier of the proposal this one supersedes, when present.
`action_type`	string	Registered action type.
`status`	string	Effective lifecycle status.
`admission_outcome`	string	Admission result recorded for the proposal.
`admission_explanation`	string	Explanation of the admission result.
`authorization_basis`	string or null	Authorization basis used for admission, when present.
`proposal_digest`	string	Digest of the proposal.
`title`	string	Short reviewer-facing title.
`summary`	string	Reviewer-facing summary.
`created_at`, `expires_at`, `decided_at`, `completed_at`	timestamp or null	Lifecycle timestamps.

The list response returns success, proposals, total_count, offset, limit, truncated, and incomplete_reason. Each row includes effective_status, requester identity, tenant, optional bot and thread identifiers, decision metadata, and the review payload selected by dossier_scope: headline adds a dossier holding only its title and first record, and full adds the whole dossier plus expected_effect. When include_statement=true, a row also includes requested_statement for an action that runs a statement; otherwise that field is null. The list response also includes visible_threads_only, which is true when the caller requested thread-visibility narrowing. The detail response additionally returns parsed stored payloads, including execution_receipt once an execution has produced one, and carries the effective status in status rather than in a separate effective_status field. Execute responses report success, claimed, final_status, an optional refusal_reason, an optional refusal_detail, an optional error_detail, and execution_result when available. success is true only when final_status is executed; not_applied means the handler or provider proved that no write was applied, while reconciliation_required means the effect may have applied and must not be retried. When available, error_detail is the provider’s own error text. Reconcile responses report resolved, final_status, and an optional refusal_reason. If Action Review storage fails with a database error, the endpoint returns 503 Service Unavailable with a generic message directing operators to the server log; raw driver error text is not included in the response. This is separate from error_detail, which describes an action handler or provider execution result when available. For governed Linear writes (ticket.write.v1), the default-on cleanup sweep can settle a reconciliation_required item without retrying the write when the item recorded a shared linear connection that has personal_credentials set to disabled, does not use User OAuth, and does not require double-key access. The sweep reads through that recorded connection’s service credential rather than a default connection, then verifies the Linear organization and authenticated user against the original attempt. If any check fails, the item remains unresolved. When a stored by-reference literal cannot be rejoined, reviewer reads and authority-bearing operations return 409 Conflict with code: "proposal_text_unavailable"; the proposal cannot be shown, approved, or executed, but it can still be rejected or revoked. If a proposal is too large to store, Genesis refuses it before writing and returns 413 Payload Too Large. Action Review also runs a default-on cleanup sweep in the background. Each pass materializes expired proposals and reconciles claims that have remained claimed past their stale threshold; expiry is still enforced when decisions and claims are evaluated, so the sweep makes the resulting state visible rather than providing the enforcement itself. Configure its cadence and stale-claim age in Advanced Settings.

Blueprint history endpoint

This route returns commit history from the backing Git repository. When authentication is enabled, it requires the system-level view_git permission rather than a Blueprint action grant.

Method	Path	Description	Required permission
`GET`	`/api/blueprints/{blueprint_name}/history`	Return Git commit history for a blueprint.	`view_git`

`GET /api/blueprints/{blueprint_name}/history`

Field	In	Type	Default	Required	Description
`source`	query	string or null	`null`	No	History source mode. Use `working_copy` for editable history, `production` for the pinned production snapshot, or `default_release` for the remote release checkout. Legacy aliases `wip` and `default` still normalize to `working_copy` and `default_release`.

In a Databricks App, these routes follow the repository’s Git safety policy. See the Git policy.

Blueprint import endpoint

The canonical preview, request fields, collision strategies, compatibility behavior, and response contract are documented in Blueprint ZIP import endpoints. The legacy override=true form field remains supported as an alias for collision_strategy=replace; new clients should send the explicit strategy.

Blueprint repository sync and dev-session remediation

POST /api/blueprints/repositories/{source_id}/sync and POST /api/blueprints/{blueprint_name}/dev-session can return a structured remediation payload when the requested refresh or workspace setup fails for an actionable reason, such as an expired saved Git OAuth grant. For these routes, Genesis returns HTTP 409 when error_code is OAUTH_RENEWAL_REQUIRED. The structured payload is returned in the FastAPI error detail body so clients can render a recovery CTA instead of treating the response as a session-auth failure.

Blueprint sync remediation payload fields

Field	Type	Description
`success`	boolean	Always `false` for these error payloads.
`error_code`	string	Structured failure code such as `OAUTH_RENEWAL_REQUIRED`.
`error`	string	Human-readable error message.
`connection_type`	string or absent	Provider type tied to the failing connection, such as `github` or `gitlab`.
`connection_name`	string or absent	Saved connection name that needs user action.
`action`	object or absent	Structured remediation action. See Blueprint sync remediation action fields.

Blueprint sync remediation action fields

Field	Type	Description
`type`	string	Currently `oauth_reauthorize`.
`label`	string	CTA label returned by Genesis for the client to display.
`initiate_endpoint`	string	API path the client `POST`s to start the reauthorization flow.

Blueprint mission-start sync warning fields

POST /api/blueprints/{blueprint_name}/start keeps remote release refresh best-effort. If Genesis cannot refresh the remote release before execution, the mission can still be created from the previously synced release and the success payload can include these warning fields:

Field	Type	Description
`warning`	string	User-facing warning message describing the previously synced commit or version Genesis will run, including a relative last-sync age when available.
`warning_code`	string or absent	Structured warning code such as `OAUTH_RENEWAL_REQUIRED` when the cause is actionable.
`warning_action`	object or absent	Structured remediation action matching the fields in Blueprint sync remediation action fields.

Blueprint mission-start request fields

POST /api/blueprints/{blueprint_name}/start accepts the following model fields in the JSON body (alongside mission_name, description, kickoff_notes, agent_id, mode, source_context, repo_id, and optional blueprint_id):

Field	In	Type	Default	Required	Description
`mode`	body	string	Blueprint’s `default_mode`	No	Execution mode: `goal` (the default of most shipped blueprints and of new ones), `manual`, or the legacy `continuous`, still accepted. Omitting `mode` for a blueprint without a valid `default_mode` returns HTTP `400` (`mode is required`).
`goal_statement`	body	string or null	`null`	No	Optional custom goal text. Used only in `goal` mode; omitted, null, or blank text uses the blueprint-naming default. A non-string value returns HTTP `400` in `goal` mode.
`llm_provider`	body	string or null	agent default	No	Mission kickoff LLM provider. Alias: `model_provider`.
`llm_tier`	body	`"frontier" \| "main" \| "fast"`	agent default	No	Mission kickoff chat tier. Alias: `model_tier`. Invalid values return HTTP `400`.
`demo_scope`	body	string or null	`null`	Conditional	Required with `presenter_session_id` for disposable starts except `client_file_onboarding` starts that omit this field. Canonical presenter scope: 1–32 characters, pattern `^[a-z0-9]+(?:-[a-z0-9]+)*$`. Genesis derives the scope from the authenticated user and `presenter_session_id` for the automatic onboarding path; otherwise the submitted value must match that binding. Genesis persists `demo_scope` and a collision-resistant `demo_resource_scope` on the Mission and appends the scope to the displayed mission name. Omit both fields for non-disposable blueprints.
`presenter_session_id`	body	string or null	`null`	Conditional	Required for disposable starts. For `client_file_onboarding`, the web client may generate a browser-tab session id and submit it without `demo_scope`; Genesis then derives the scope and requires an authenticated user. Otherwise, submit it with `demo_scope` for Presenter Controls starts. Pattern `^presenter-[a-z0-9]{1,20}$` (11–30 characters). Requires `features.presenter_controls_enabled` and Genesis Staff for Presenter Controls starts.
`inputs`	body	object or null	`null`	No	Structured blueprint inputs keyed by manifest input names. Unknown names return HTTP `400`. Maximum serialized size 50 KB. Omit or pass `{}` when the blueprint declares no input contract.
`local_file_uploads`	body	object or null	`null`	Conditional	Launchpad pre-start files for `client_file_onboarding` when `inputs.source_mode` is `local_files`. Requires `session_id` and one or more unique `file_ids`; the server validates ownership and materializes the exact files into the Mission repository before phase entry.
`journey_context`	body	object or null	`null`	No	Journey recipe context when starting from a guided flow. Requires `definition_id` (string), `variant` (string), and optional `plan_only` (boolean, default `false`). Genesis validates that the journey’s `entry_blueprint` matches `{blueprint_name}`.
`working_context`	body	object or null	`null`	No	Optional repository, folder, and connection selections for the mission thread. The object contains `repo_id` (string or null), `folder` (string), and `connections` (string array). Genesis validates the selections before creating the Mission; when `repo_id` is null and the mission resolves a repository, that repository fills the working context.

When llm_provider or llm_tier is omitted, Genesis resolves the value from the selected agent_id before persisting mission kickoff defaults on the thread. Phase context_defaults.model_tier overrides the mission kickoff tier while that phase is active. See Model tier during blueprint missions. When inputs is present, Genesis validates each key against the blueprint manifest inputs.required and inputs.optional names, stores the normalized object on the mission thread as blueprint_inputs, and includes it in the initial kickoff message. When journey_context is present, Genesis stores blueprint_journey_context on the thread and inherits it across blueprint_chain handoffs. For the system_test blueprint’s release and sandbox-trial inputs, including their model-selection behavior, see System Test mission guidance. For local_file_uploads, use the session_id supplied by the Launchpad upload flow and pass the returned file_ids unchanged. The session id is an opaque presenter- value; uploads are authenticated to the caller and are consumed after the Mission’s immutable client_files/manifest.json snapshot is created. Invalid, incomplete, duplicate, or unauthorized file references reject the start without leaving a partially created Mission.

Blueprint journey definitions

Resolve one declarative journey variant (for example the database-migration recipe’s snowflake or databricks platform variant).

Method	Path	Description
`GET`	`/api/blueprints/journey-definitions/{journey_id}`	Return the resolved journey recipe for one variant.

`GET /api/blueprints/journey-definitions/{journey_id}`

Field	In	Type	Default	Required	Description
`journey_id`	path	string	none	Yes	Journey id (lowercase letters, numbers, hyphens; must match the YAML file name).
`variant`	query	string	none	Yes	Platform or flavor variant within the journey (for example `snowflake` or `databricks`). Minimum length `1`, maximum length `100`.

Response data (BlueprintJourneyDefinition):

Field	Type	Description
`journey_id`	string	Normalized journey id.
`version`	integer	Journey recipe version from YAML.
`variant`	string	Normalized variant id.
`label`	string	Human-readable journey title.
`description`	string	Journey summary.
`variant_label`	string	Human-readable variant title.
`entry_blueprint`	string	Blueprint name for the first stage (must match `stages[0].blueprint_name`).
`input_bindings`	object	Maps blueprint input names to Launchpad step bindings (`step_id`, `value_type`, optional `omit_values`).
`stages`	array	Ordered stages (`id`, `blueprint_name`, `label`, `description`, `optional`, `requires_target`).
`edges`	array	Conditional transitions (`from`, `to`, `conditions[]`).

Blueprint mission-start execute access

With authentication enabled, POST /api/blueprints/{blueprint_name}/start and POST /api/blueprints/{blueprint_name}/runs require the caller to have execute access to the resolved Blueprint. A caller who can view a Blueprint may still receive HTTP 403 when no applicable owner, administrator, or role permission allows execution. This denial is distinct from the agent-access 403; its response includes these top-level fields:

Field	Type	Description
`code`	string	`blueprint_execute_denied` for a missing Blueprint execute grant.
`blueprint_name`	string	Blueprint name associated with the refused start.

The execute action and role-wide permissions are described in Blueprint RBAC actions.

Blueprint mission-start tool policy preflight

POST /api/blueprints/{blueprint_name}/start and POST /api/blueprints/{blueprint_name}/runs run the same high-risk tool policy preflight before Genesis creates a mission project or thread. When the selected blueprint requires tools that are globally blocked under High-Risk Tool Controls, Genesis returns HTTP 409 with error_type policy_blocked. The ErrorResponse.payload object includes:

Field	Type	Description
`code`	string	`blueprint_tool_policy_blocked`
`policy_blocked`	boolean	Always `true` for this failure.
`blocked_policy`	string	`high_risk_tools_disabled` when the workspace toggle blocks the high-risk tool family.
`blocked_tools`	object[]	Each item includes `name`, `display_name`, and `description` for a blocked tool.
`blueprint_name`	string	Blueprint identifier from the route.
`bot_id`	string or null	Agent id from the request body when supplied.
`admin_location`	string	UI hint for where an admin enables high-risk tools (`Config > Users > High-Risk Tools`).
`admin_path`	string	Config path hint (`/config/users`).
`message`	string	Same human-readable explanation as the top-level `error` field.

Preflight inspects phase context_defaults tool groups (for example code_executor_tools or dbt_action) and phase text that references dbt_action, execute_python_code, or _run_sqlite_cli_commands. Model tier selection (llm_tier / llm_provider on mission start and context_defaults.model_tier per phase) is unrelated to this preflight.

Programmatic BlueprintRun endpoints

These routes let a host application start and supervise a blueprint mission without holding the mission chat UI. Full integration guidance, gate contracts, and the Atlas reference app are in Programmatic BlueprintRun.

Method	Path	Description
`POST`	`/api/blueprints/{blueprint_name}/runs`	Start a programmatic run (`BlueprintRunCreateRequest`). Returns `202` after the run is linked to its mission project and thread and the entry phase is pre-entered, `200` when replaying a terminal run, or `409` when the same `run_id` is already active or when tool policy preflight blocks required high-risk tools. The first agent kickoff includes the pre-entered phase’s public briefing and injected documents; see Programmatic BlueprintRun for size limits and re-read behavior.
`GET`	`/api/runs/{run_id}`	Aggregate run state (`BlueprintRunStateResponse`), including `pending_inputs`, `current_phase`, `thread_id`, and `project_id`.
`GET`	`/api/runs/{run_id}/events`	Poll events since `since` (event sequence). Response includes `next_since`.
`POST`	`/api/runs/{run_id}/input/{input_id}`	Submit external gate input (`BlueprintRunInputRequest`: `intent` `commit` or `details`, `purpose`, `response`, `details`).
`POST`	`/api/runs/{run_id}/input`	Compat path when exactly one gate is open; otherwise `400` with `ambiguous_pending_input`.
`POST`	`/api/runs/{run_id}/external-inputs`	Register a dynamic external gate (`BlueprintRunRegisterExternalInputRequest`; requires manifest `allow_dynamic_external_inputs`).
`POST`	`/api/runs/{run_id}/required-checks/{check_name}/waive`	Record an exact required-check waiver from an authenticated human approver. Requires `approve_agent_action`; internal service tokens and unauthenticated callers are rejected.
`POST`	`/api/runs/{run_id}/cancel`	Cancel the run.
`GET`	`/api/runs/{run_id}/deliveries`	List webhook delivery rows.
`GET`	`/api/runs/{run_id}/capabilities`	Git capability hints (`can_view_git`, `can_manage_git`) for host UIs.
`GET`	`/api/runs/{run_id}/repos`	Mission repositories for the run’s project.
`GET`	`/api/runs/{run_id}/repos/{repo_id}/tree`	List or fetch a file under a mission repo (same semantics as project git tree).
`GET`	`/api/runs/{run_id}/repos/{repo_id}/bundle`	Download a mission repository bundle; optional `since` query for incremental bundles.

The caller needs system view_git permission, access to the run’s agent and mission project, and the repository must be associated with that project. Unlike direct Git repository routes, this run-scoped route does not perform the repository view check described under Git permissions. In a Databricks App, the repository-bundle route applies the same Git safety policy as other agent-writable repositories; see Git Action Tools. POST commit routes accept optional Idempotency-Key (max 120 characters). Replay with the same key and body returns 204; a different body returns 409 (idempotency_key_mismatch). Genesis carries the authenticated request’s user context into the kickoff and turns created by gate submissions, so Prover permission checks in those turns use the API caller. The optional actor field is audit metadata and does not supply that identity; see Programmatic BlueprintRun. Project detail payloads can include blueprint_run_id when the mission thread is linked to a programmatic run.

Required-check waiver

Call the waiver route only after reviewing why the server-owned check cannot be run or pass. The request body contains a human-authored reason string from 1 to 2,000 characters:

POST /api/runs/{run_id}/required-checks/{check_name}/waive
Content-Type: application/json

{"reason":"The approved dependency is unavailable in this deployment."}

The response identifies the exact pinned check and includes blueprint_name, phase_id, script_sha256, waived: true, and idempotent. Repeating the same waiver for the same phase-entry snapshot is safe and returns idempotent: true. A waiver is recorded as platform provenance and clears the required-check gate only when all checks in the active phase are satisfied or waived.

`BlueprintRunCreateRequest` fields

Field	Type	Default	Description
`run_id`	string	required	Caller-owned durable id (4–128 chars; UUID recommended).
`bot_id`	string	`"Eve"`	Agent that owns the mission thread.
`mission_name`	string or null	`null`	Mission name shown in Genesis (max 255).
`description`	string or null	`null`	Mission description (max 5000).
`kickoff_notes`	string or null	`null`	Host text included in the first mission kickoff message (max 5000).
`mode`	string	`"continuous"`	`manual` or `continuous`.
`source_context`	string or null	`null`	Blueprint source: `default` or `wip`.
`demo_scope`	string or null	`null`	Required with `presenter_session_id` when the blueprint carries `demo:disposable`. Canonical presenter scope: max 32 characters, pattern `^[a-z0-9]+(?:-[a-z0-9]+)*$`. Must match the scope bound to the caller’s `presenter_session_id`.
`presenter_session_id`	string or null	`null`	Required with `demo_scope` for presenter-bound disposable demo starts. Pattern `^presenter-[a-z0-9]{1,20}$`.
`inputs`	object	`{}`	Opaque host inputs persisted on the run (for example `catalog_repo_id`).
`webhooks`	array	`[]`	Webhook subscriptions (`url`, optional `events`, optional `bearer_token`).
`hmac_secret`	string or null	`null`	Shared secret for `X-Genesis-Signature` on webhook bodies.
`use_fixture_timeline`	boolean	`false`	Deterministic no-LLM timeline for harness tests.
`actor`	object or null	`null`	Optional identity block echoed on events; `type` must be `user`, `service`, `cron`, or `agent` when set.

`BlueprintRunInputRequest` fields

Field	Type	Default	Description
`intent`	string	`"commit"`	`commit` satisfies the gate; `details` is a non-ungating clarification round.
`purpose`	string	required	Must match the pending gate’s `purpose` for this `input_id`.
`response`	object	`{}`	Commit payload (validated against the gate response schema).
`details`	object	`{}`	Details payload when `intent` is `details`.

Mission and project list endpoints

Genesis missions are backed by projects. The Mission Center UI loads its mission list from GET /api/projects.

Method	Path	Description
`GET`	`/api/projects`	List missions/projects visible to the caller, with optional search, status, blueprint, pagination, and sort filters.
`GET`	`/api/projects/awaiting-input`	List visible missions waiting on a person, with unanswered task questions when available.
`GET`	`/api/projects/{project_id}`	Return detailed information for one project.
`PUT`	`/api/projects/{project_id}/status`	Change a mission status. Set `new_status` to `RETIRED` with a required non-empty `reason` to permanently stop the mission.
`GET`	`/api/projects/{project_id}/blueprint-chain`	Return the visible blueprint handoff chain for a mission, including journey-planned stages when `blueprint_journey_context` is set on the root thread.

`PUT /api/projects/{project_id}/status`

Request body:

Field	Type	Required	Description
`new_status`	string	Yes	Target mission status. `RETIRED` is terminal and requires `reason`.
`reason`	string or null	Required for `RETIRED`	Why the mission is being retired. Must contain at least one character when supplied.

The response includes the persisted result of the change:

Field	Type	Description
`success`	boolean	Whether the status change succeeded.
`message`	string	Human-readable result summary.
`current_status`	string or null	Status the mission holds after the change.
`discharge_pending`	boolean or null	For retirement, `true` when Blueprint thread state still needs discharging and the retirement should be reissued; `false` when that cleanup completed. `null` when the change was not a retirement.

Read-only project record endpoints

These endpoints provide the Goals page’s read-only view of typed project records. They are separate from Mission projects and organizational Projects. Records are created and updated through the project tools.

Method	Path	Description
`GET`	`/api/project-records`	List the authenticated caller’s own records, newest first. Administrators also see only their own records.
`GET`	`/api/project-records/{project_id}`	Return one record with its goals, notes, and assets, using the owner/administrator access rule documented for `project_read`.

The list endpoint accepts these optional query parameters:

Parameter	Type	Default	Description
`thread_id`	string, 1–255 characters	—	Limit results to the caller’s own project records opened in this chat thread or resumed in it by planning. This filter cannot expose another person’s records; a thread with no matching project returns an empty list.
`include_people`	boolean	`true`	Include person display names in `people`. Set to `false` when names are not needed; the response’s `people` map is empty and Genesis skips the user reads used to resolve names.

Both endpoints require authentication and return { "success": true, "data": ... }. The list keeps at most the 100 newest records. truncated is true when more records exist than the response contains. A different person’s record returns the same 404 as an unknown project_id. List errors include 401 and 500; detail errors include 401, 404, and 500. Without these filters, listing projects uses three database reads plus a user read per distinct person named in the records. A thread_id with no matching project uses one database read and no user reads; setting include_people=false skips the person-name reads for matching records as well. The list data contains items, people, truncated, and generated_at. Each item includes id, name, project_type, principal, opened_by, thread_id, created_at, closed_at, goal_total, status_counts, last_note, plan_incomplete, and planned. thread_id, created_at, closed_at, and last_note may be null; closed_at is set when the project is retired. plan_incomplete is true when the plan the project came from has gaps. planned maps each constrained goal to {"total": <expected assets>, "done": <assets with a passing check at their current version>}. people maps person IDs to display names or email addresses, or null when no name is available. A non-null last_note contains goal, at, actor, principal, kind, verification, status, and person_turn. The detail data includes id, name, project_type, parameters, principal, opened_by, thread_id, created_at, note_sequence, goals, notes, assets, and people. Goal ordering follows the project_read contract; notes are oldest first in server sequence. Each goal includes its id, name, status, acceptance_criterion, skill_ref, preconditions, asset_refs, and input_versions. For a met goal, input_versions records the versions its proof is based on: the last met note’s versions when the goal declares asset_refs, or the latest passing version of each asset cited by its checked evidence otherwise. These are assets registered to that goal, except that a goal met before assets belonged to goals may include an asset registered to another goal. It is empty unless the stored goal status is met. A note includes id, sequence, goal, actor, principal, at, evidence, asset, finding, waive_reason, person_turn, verification, verification_reason, server_check_result, previous_status, status, and input_versions. The detail read does not re-check evidence; verification describes the check when the note was recorded. Goals may also include status_qualifier (planned_scope when a met status applies only to the plan’s constrained scope) and planned with total expected assets and done passing at their current versions. Each goal includes server_records, newest first, for work the server filed under that project and goal whether or not it has been cited. A record includes kind (foundry_copy_receipt, notebook_publish, notebook_overwritten, or databricks_run), evidence_id (a Foundry copy receipt, published notebook version, overwrite mark, or Databricks run id), asset_id (the dataset or pipeline), target_table (the copy target or notebook path), state, reason, attempts, created_at, and updated_at; kind, target_table, reason, attempts, and timestamps may be null. Foundry copy states include copy_running, copied, copied_no_receipt, and copy_failed; notebook publishing and run submission use published and run_submitted. Recording outcomes include recorded_passed, recorded_failed, registered, replaced, not_readable, not_checkable, and project_retired; future states may be returned as well. attempts is how many times the server has checked the work; an open record with at least one attempt and a reason is waiting for another check. The detail read also selects every row in the project’s evidence queue, which is unbounded and grows with the copies filed under that project. Reading this data does not re-check the cited copies against their tables. The detail also includes parameter_words, the parameters the server can render as text, and scope, which is null for projects opened without a plan or otherwise contains the plan’s gaps (the expected and covered asset lists are not returned). plan_incomplete and plan_banner describe a plan with gaps; closed_at and closed_reason describe retirement. For the project’s own person, a retired record may include live_successor (id and name) when another live project for the same source exists. live_successor_undetermined is true when there are too many live projects to determine one; live_successor_looked_up indicates whether Genesis checked. For administrators reading another person’s record, successor lookup is not performed and these fields do not imply that no successor exists. Reading a retired project as its owner adds one lookup for a live project for the same source; an administrator reading another person’s record does not trigger that lookup.

Organizational Project endpoints

Organizational Projects group related Apps, Flows, Missions, and chat threads. They are separate from the execution project used internally by a Mission. Project identifiers use the wprj_ prefix followed by 32 lowercase hexadecimal characters.

Method	Path	Description
`GET`	`/api/workspace-projects`	List organizational Projects. `include_archived` is an optional boolean query parameter and defaults to `false`.
`POST`	`/api/workspace-projects`	Create a Project with `name` (1–255 characters) and optional `description` (up to 5,000 characters).
`GET`	`/api/workspace-projects/{workspace_project_id}`	Return one Project, including archived Projects.
`PATCH`	`/api/workspace-projects/{workspace_project_id}`	Update the Project `name` and/or `description`. The creator or an instance admin may edit it.
`POST`	`/api/workspace-projects/{workspace_project_id}/archive`	Archive a Project without removing existing assignments.
`POST`	`/api/workspace-projects/{workspace_project_id}/unarchive`	Restore an archived Project.
`GET`	`/api/missions/{project_id}/workspace-project`	Return the organizational Project assigned to a Mission, or `null` when unassigned.
`PUT`	`/api/missions/{project_id}/workspace-project`	Assign or clear a Mission’s organizational Project with `{ "workspace_project_id": "wprj_..." }` or `null`.
`PATCH`	`/api/apps/{app_id}/project`	Assign or clear an App’s organizational Project with `{ "project_id": "wprj_..." }` or `null`. Requires App `manage` permission.
`PATCH`	`/api/flows/{flow_id}/project`	Assign or clear a Flow’s organizational Project with `{ "project_id": "wprj_..." }` or `null`. Requires Flow edit permission.
`POST`	`/api/bots/{bot_id}/threads`	Create a chat thread with optional `project_id` in the request body.
`PUT`	`/api/bots/{bot_id}/threads/{thread_id}/project`	Assign or clear an existing chat thread with `{ "project_id": "wprj_..." }` or `null`.

Workspace Project list and single-object responses use { "success": true, "data": ... }. The data object contains id, name, description, created_by, created_at, updated_at, and archived_at. Assignment responses return the assigned Project ID and, where applicable, its summary; clearing an assignment returns a null Project ID.

`GET /api/projects/{project_id}/blueprint-chain`

Requires project access (same gate as GET /api/projects/{project_id}). When the mission has no root thread, Genesis returns success: true with an empty chain (project_id only). Response data (ProjectBlueprintChain):

Field	Type	Description
`project_id`	string	Mission id.
`root_thread_id`	string or null	Visible chain root after walking `blueprint_chain` handoff ancestors.
`nodes`	array	Spawned blueprint threads (`thread_id`, `thread_title`, `bot_id`, `project_id`, `blueprint_name`, `parent_thread_id`, `created_at`, `node_kind`, `remediation_round`, `run_state`).
`planned_stages`	array	Journey stages with status (`expected`, `spawned`, or `skipped`), optional `optional` and `requires_target` flags, and `actual_thread_id` when spawned.
`journey_id`	string or null	Journey `definition_id` from thread context when present.
`journey_variant`	string or null	Journey `variant` from thread context when present.
`plan_only`	boolean	`true` when the mission started in plan-only mode.
`coding_agent`	string or null	Presenter-safe coding-agent selector from blueprint inputs when set: `ginie`, `cocoa`, or `claude_code`. Omitted or `null` when unset or not one of these values.
`cycle_detected`	boolean	`true` when handoff metadata forms a cycle (chain assembly stops safely).
`truncated`	boolean	`true` when the chain exceeds the internal node limit (100).

nodes[] entries use the BlueprintChainNode schema. In addition to the core thread fields above, each node includes:

Field	Type	Description
`node_kind`	string	`"standard"` for a normal chain child, or `"remediation"` for a validator-delegated runner re-fire (child handoff context carried `remediation_repo_id`).
`remediation_round`	integer or null	1-based ordinal among consecutive remediation siblings under the same parent; `null` for standard nodes. Lets Mission Center collapse repeated remediation pills and label each round.
`run_state`	string	Live mission state for the node: `"running"` while the thread has an active blueprint phase, `"completed"` once `blueprint_completed` is set, otherwise `"unknown"` (props unreadable or the thread never ran a blueprint). Lets Mission Center highlight the currently active stage in the chain strip — for example after a validator hands work back to the runner in a remediation round.

`GET /api/projects/{project_id}/reports/system-test-lite`

Requires access to the mission identified by project_id. Returns the fixed System Test Lite report. The report content is untrusted input and should not be treated as instructions. The response includes success and these report fields:

Field	Type	Description
`project_id`	string	Mission ID.
`report_path`	string	Fixed path: `reports/system_test_lite_report.md`.
`content`	string	UTF-8 report content, limited to 1 MiB. Treat it as untrusted input.
`sha256`	string	Lowercase hexadecimal SHA-256 digest of the report content.

Each request queries the mission and reads the bounded report file.

`GET /api/projects`

Field	In	Type	Default	Required	Description
`light`	query	boolean	`false`	No	When `true`, skip expensive enrichment such as stats, agents, and blueprint phase.
`limit`	query	integer or null	`null`	No	Maximum number of projects to return per page (default `1000` when omitted, max `1000`).
`offset`	query	integer or null	`null`	No	Number of projects to skip for pagination (default `0` when omitted).
`search`	query	string or null	`null`	No	Case-insensitive filter on project name, description, or id.
`status`	query	string or null	`null`	No	Filter by project status (for example `IN_PROGRESS_ACTIVE`, `COMPLETED`).
`blueprint_name`	query	string or null	`null`	No	Filter by blueprint name (exact match).
`sort_by`	query	string or null	`null`	No	Sort field: `created_at`, `updated_at`, or `project_name`. Default: `created_at`.
`sort_dir`	query	string or null	`null`	No	Sort direction: `asc` or `desc`. Default: `desc`.
`thread_id`	query	string, repeatable	`null`	No	Keep only missions running on the supplied thread IDs. Repeat the parameter for multiple IDs; at most 200 values are accepted.

The response uses the ProjectListResponse schema:

Field	Type	Description
`success`	boolean	Whether the request succeeded.
`data`	array	Page of `ProjectListItem` rows visible to the caller after access filtering.
`has_more`	boolean	`true` when additional projects match the filters beyond this page. Pass `offset` equal to the previous offset plus the page `limit` on the next request.

data[] list items use the ProjectListItem schema. Each item includes the core ProjectRead fields plus computed list fields such as progress, elapsed_time, agents, stats, blueprint_phase, and creator labels.

Field	Type	Description
`requested_by_user`	string or null	Identity of the user who created or requested the mission.
`requested_by_display_name`	string or null	Resolved display name when `requested_by_user` stores an internal user id. Omitted or `null` when unavailable.
`requested_by_email`	string or null	Resolved creator email when available. Omitted or `null` when unavailable.

Genesis resolves requested_by_display_name and requested_by_email on this route from the user directory. Identities that are already emails are returned as requested_by_email without a separate directory lookup. The built-in system_default_user identity is not resolved to a display name or email; UIs show it as System User.

`GET /api/projects/awaiting-input`

This route has no query parameters. It returns missions in IN_PROGRESS_NEEDING_INPUT or STUCK status that the caller may open, newest mission update first. Each request reads task details and recent thread messages for up to 50 visible missions, so this endpoint does more work than the light mission-list request. The candidate read checks up to 500 rows for each waiting status; truncated is true if a status read reports or reaches that limit, or more than 50 visible missions need describing. The response contains success, items, and truncated. Each items[] entry represents one waiting task, or the mission itself when no task describes the wait:

Field	Type	Description
`project_id`	string	Mission ID.
`project_name`	string	Mission name.
`bot_id`	string	Mission’s agent ID.
`thread_id`	string or null	Mission thread, when available.
`mission_status`	string	Mission status (`IN_PROGRESS_NEEDING_INPUT` or `STUCK`).
`todo_id`	string or null	Waiting task ID; null when no task describes the wait.
`phase`	string or null	Blueprint phase ID for the waiting task.
`phase_name`	string or null	Blueprint phase name, when available.
`asked_at`	string or null	Time of the unanswered question, falling back to the mission’s last update when the question has no timestamp.
`questions`	array	Unanswered question data; empty when no readable question is available.
`question_set_id`	string or null	ID of the question set, when present on a question.

Each question includes phase, priority, category, and content, with optional expected_response_type, options, question_id, and question_set_id fields. It can also include recommended (string or null), the option text the agent recommends for a choice or multiple question. A mission whose tasks or thread questions cannot be read can still appear without question data.

GET /api/projects/awaiting-input

{
  "success": true,
  "items": [
    {
      "project_id": "proj_123",
      "project_name": "Quarterly analysis",
      "bot_id": "Eve",
      "thread_id": "chat_123",
      "mission_status": "IN_PROGRESS_NEEDING_INPUT",
      "todo_id": "todo_456",
      "phase": "1",
      "phase_name": "Confirm scope",
      "asked_at": "2026-09-30T10:00:00Z",
      "questions": [
        {
          "phase": "1",
          "priority": "medium",
          "category": "clarification",
          "expected_response_type": "text",
          "content": "Which reporting period should I use?",
          "options": null,
          "question_id": "question_1",
          "question_set_id": "question_set_1"
        }
      ],
      "question_set_id": "question_set_1"
    }
  ],
  "truncated": false
}

Managed artifact repositories and dependencies

Skills, Flows, Apps, agent definitions, and document indexes (Knowledge Base feeds) can each register Git-backed managed sources and edit artifacts in per-user workspaces. Dependency binding is shared across artifact types. Operator workflows are documented in Multi-Instance Skill, Flow & App Sync and Document Indexes.

Repository sync and workspace routes can return the same structured OAUTH_RENEWAL_REQUIRED remediation payload described for Blueprints when a saved Git OAuth grant has lapsed.

Managed source permissions

Permission	Allows
`manage_repos`	`/api/managed-sources/*` (unified admin for multi-type Git-backed sources)
`manage_agents`	Required in addition to `manage_repos` when a source enables the `agents` scan type (create, update, delete, sync, list/enable agent artifacts, and apply agent changes from Git)
`manage_skills`	`/api/skills` catalog writes and `DELETE /api/skills/{skill_name}`; `/api/skills/repositories` and `/api/skills/{skill_name}/workspace/*`
`manage_flows`	`/api/flows/repositories`, `/api/flows/{flow_name}/workspace/*`, and `/api/flows/{flow_name}/bindings`
`manage_apps`	`/api/apps/repositories` and `/api/apps/{app_id}/workspace/*`
`manage_git`	`/api/managed-artifacts/` dependency and binding APIs; `/api/apps/{app_id}/export-to-managed/` (plus app-level `manage` on the target app)

Per-type repository POST, PATCH, and DELETE routes also accept manage_repos via require_any_permission alongside the legacy permission for that artifact type. POST on those legacy create routes sets the response header Deprecation: true; prefer /api/managed-sources when registering a repository that should scan more than one artifact type. Deleting a source through a per-type route when scan_types_enabled contains more than one type returns HTTP 409 with error_code SOURCE_HAS_MULTIPLE_TYPES and admin_url /api/managed-sources/{source_id}. Use DELETE /api/managed-sources/{source_id} instead.

Unified managed sources (`/api/managed-sources`)

Requires manage_repos. Creating or updating a source that includes roles, or applying a role preview, also requires manage_users (HTTP 403 when absent). When scan_types_enabled includes agents, routes that touch agent discovery, sync, or per-artifact enablement also require manage_agents (HTTP 403 when absent). Use this surface when one Git repository should discover Skills, Flows, Apps, Blueprints, agent definitions, document indexes (Knowledge Base feeds), and (when enabled) Missions from a single repo_id checkout. The dashboard page is Config → Managed Sources (also requires access_config_panel). The Document Indexes page exposes the same panel through Sync from Git.

Method	Path	Description
`GET`	`/api/managed-sources`	List managed sources. Optional query `scan_type` (`skills`, `flows`, `apps`, `blueprints`, `documents`, `agents`, `roles`, or `missions`) filters to sources whose `scan_types_enabled` includes that value. Each row includes `artifact_counts`, `dependency_summary`, `flows_waiting_for_promotion` (the number of held Flow changes, or `null` when the count cannot be read and no recorded count is available), and (for document feeds) `document_feed_summary` with per-index pending counts, proposers, open PR/MR metadata, and document totals (`count` / `total_count` for repo-managed docs only; `index_doc_count` per index and `total_index_doc_count` for the full live index including index-only documents). If enrichment fails for one source, that row is returned in degraded form with `error`, an empty `dependency_summary`, and no `document_feed_summary`; other rows are still returned.
`POST`	`/api/managed-sources`	Create a source (HTTP `201`). Body requires `repo_id` and `scan_types_enabled` (non-empty list). Each enabled scan type needs its matching root field (`skills_root`, `flows_root`, `apps_root`, `blueprint_root`, `missions_root`, `documents_root`, `agents_root`, or `roles_root`). A source that includes `roles` requires `manage_users`. When `documents` is enabled, `remote_url` is required. When `agents` is enabled, `agents_root` must point at a directory tree where each agent subdirectory contains `agent.yaml` or `agent.yml`. Optional fields include `remote_url`, `connection`, `release_ref` (default `main`), `documents_target_index`, `include`, `exclude`, `checkout_exclude` (default `[]`), `enabled` (default `true`), `fallback_to_default_branch`, `auto_promote_on_sync` (boolean or null; omitted by default; only explicit `false` holds synced Blueprints and Flows until an admin promotes them, and prevents scheduled sync from applying agent or role changes unattended), `auto_sync` (boolean, default `false`; opt this source into scheduled sync), `overwrite_indexes`, and `sync_now` (alias `sync_on_create`, default `false`). Returns `ManagedSourceUpsertResponse` (`success`, `source`, `sync`, optional `warning` / `warning_action`).
`GET`	`/api/managed-sources/{source_id}`	Get one source with `artifact_counts`, `flows_waiting_for_promotion` (the number of held Flow changes, or `null` when the count cannot be read and no recorded count is available), `dependency_summary`, and `document_feed_summary` when applicable (same `count` vs `index_doc_count` semantics as the list route). If enrichment fails, the source is returned in degraded form with `error`, an empty `dependency_summary`, and no `document_feed_summary`.
`GET`	`/api/managed-sources/{source_id}/skill-release-tags`	List release tags from the managed skill source’s last sync. Returns `SkillReleaseTagsResponse`: `tags` (`name`, `commit_sha`, `tagged_at`, `in_effect`), `total_count`, and `limit` (`500`). Newest first; the tag in effect is included even if older than the newest 500. Requires `manage_repos` and skill revision tracking.
`POST`	`/api/managed-sources/remote-skill-release-tags`	List a remote’s tags before a skill source has a checkout. Body: required `remote_url`, optional `connection`. Returns `SkillReleaseTagsResponse`; `tagged_at` is `null`, and tags are ordered by version where possible. Makes one network round trip to the remote Git host. Requires `manage_repos`.
`GET`	`/api/managed-sources/{source_id}/skill-release-diff?target={tag}`	Compare the release in effect with the required non-empty target tag, which must be among tags from the source’s last sync. Returns base and target (`tag`, `commit_sha`), skill changes (`name`, `status`, `files_changed`, `lines_added`, `lines_removed`), `unchanged_count`, and commit history (`sha`, `committed_at`, `author`, `subject`) when available. Added/removed skills have null line totals. At most 100 commits are returned, newest first, with `commits_truncated` and `commits_unavailable_reason`; `commits` is null when history is unavailable. `direction` is `upgrade`, `rollback`, or `null` when ancestry does not prove a direction. A shallow checkout may trigger one network fetch to the source remote; the skill comparison remains available when commit history cannot be established. Requires `manage_repos` and skill revision tracking.
`PATCH`	`/api/managed-sources/{source_id}`	Update a source. `repo_id` is not accepted on PATCH. When the merged source would enable `documents` without a non-blank `remote_url`, the response has `success: false`, `error_code` `DOCUMENTS_REMOTE_URL_REQUIRED`, the current and attempted values, and remediation to set `remote_url` or delete and recreate the source without `documents`. Adding `roles` to the source requires `manage_users`. Removing entries from `scan_types_enabled` is rejected (`error_code` `SCAN_TYPE_REMOVAL_NOT_SUPPORTED`); delete the source and recreate to drop a scan type. Supports the same optional fields as create plus `sync_now` / `sync_on_create`, `overwrite_indexes`, and `sync_in_background` (boolean, default `false`). Set `auto_promote_on_sync` to `false` to require manual promotion of synced Blueprints and Flows and prevent unattended agent or role apply during scheduled sync (omitted or `null` retains auto-promotion); set `auto_sync` to opt this source into or out of scheduled sync. `sync_in_background` applies only with `sync_now` for a governed skill release or policy change; see the background release sync note below. Returns `ManagedSourceUpsertResponse`.
`DELETE`	`/api/managed-sources/{source_id}`	Delete the source and discovered artifacts for all enabled scan types. Required for multi-type sources. Genesis first stages the source and its artifact-ownership records, retires dependent runtime artifacts and managed workspaces, and removes the registry records only after cleanup succeeds. On cleanup failure, returns HTTP `500` with `error_code` `SOURCE_DELETE_CLEANUP_PENDING`, `cleanup_warnings`, and cleanup status fields; the source remains marked for deletion so retrying this route can finish cleanup without re-registering a deleted legacy source. If registry persistence is unavailable, returns HTTP `500` with `error_code` `SOURCE_DELETE_PERSISTENCE_FAILED`.
`GET`	`/api/managed-sources/{source_id}/artifacts`	List discovered artifacts for a source. Optional query `artifact_type` (for example `blueprint` or `agent`) filters by type. Returns `ManagedArtifactResponse[]` (`artifact_type`, `artifact_id`, `source_id`, `path`, `enabled_in_genesis`, `artifact_state`, optional `apply_status`, `apply_error`, `last_seen_commit`, `last_applied_commit`). Listing agent rows requires `manage_agents` when the source enables `agents`; an explicit non-agent filter such as `blueprint` requires `manage_repos` only.
`PATCH`	`/api/managed-sources/{source_id}/artifacts/{artifact_type}/{artifact_id}`	Set per-artifact enablement in Genesis. Body: `{"enabled": <boolean>}`. Supports `artifact_type` `agent` and `blueprint`. Returns `ManagedArtifactEnablementResponse` (`artifact`, `apply`). Blueprint enablement requires `manage_repos` and writes the instance-local override immediately; it has no agent apply or preview stage. Agent enablement additionally requires `manage_agents` and follows the agent preview/apply flow.
`POST`	`/api/managed-sources/{source_id}/sync`	Sync the source from its remote synchronously. Optional body: `{"overwrite_indexes": ["index_name", ...], "apply_agent_changes": false, "expected_agent_commit": null, "expected_agent_plan_hash": null, "apply_role_changes": false, "expected_role_commit": null, "expected_role_plan_hash": null}`. When `agents` is enabled, a preview-only sync (`apply_agent_changes` default `false`) returns `agent_preview` and `requires_agent_apply_confirmation`; apply with the preview’s `commit_sha` and `plan_hash`. For a source with `roles`, preview-only sync returns `role_preview` and `requires_role_apply_confirmation` when an action needs review. Applying requires `manage_users` and `apply_role_changes: true` with `expected_role_commit` and `expected_role_plan_hash` copied from that preview. Missing pins return `ROLE_PREVIEW_REQUIRED`; changed commits or plans return `ROLE_PREVIEW_STALE`. Definitions granting access to an admin agent are rejected; see Users and Roles for other role-file restrictions. Returns `ManagedSourceSyncResponse`. Large repositories can exceed gateway timeouts; prefer `sync-async` + `sync-status` for long-running syncs.
`POST`	`/api/managed-sources/{source_id}/sync-async`	Start an async sync job. Optional body uses the same fields as synchronous sync (`overwrite_indexes`, `apply_agent_changes`, `expected_agent_commit`, `expected_agent_plan_hash`, `apply_role_changes`, `expected_role_commit`, `expected_role_plan_hash`). Applying a role preview requires `manage_users`. Returns `ManagedSourceSyncJobResponse` (`job_id`, `status`). When a sync for the same source is already `running` with the same `overwrite_indexes`, apply flags, and preview pins, returns the existing job id instead of starting a duplicate. Config → Managed Sources and per-library Manage Sources modals use this route.
`GET`	`/api/managed-sources/{source_id}/sync-status/{job_id}`	Poll an async sync job. Returns `ManagedSourceSyncStatusResponse` (`job_id`, `status`, optional `error`, optional `result`). `status` is `running`, `complete`, or `error`. When `complete`, `result` carries the same operational fields as `ManagedSourceSyncResponse`. When `error`, `result` may include structured failure fields such as `error_code` and `warning_action` (for example reauthorize CTAs). Returns HTTP `404` when the job id is unknown (for example after a server restart).
`POST`	`/api/managed-sources/{source_id}/reset-checkout`	Reset the local checkout and re-sync. Returns `ManagedSourceSyncResponse`.
`POST`	`/api/managed-sources/preview-documents`	Preview how markdown folders under `documents_root` would adopt into document indexes before creating or syncing a source. Body: `remote_url`, `documents_root`, optional `source_id`, `connection`, `release_ref` (default `main`), `include`, `exclude`. Returns folder classifications (`net_new`, `index_only`, `name_conflicts`) per target index.
`POST`	`/api/managed-sources/{source_id}/documents/export`	Export a standalone document index into the managed repo as staged markdown proposals. Body: `index_name`, optional `target_folder`. Returns `exported`, skip lists, and `pending_count`.
`GET`	`/api/managed-sources/{source_id}/workspace`	Workspace status for a document feed. Optional query `target_index`, `refresh_remote`. Returns `branch`, `worktree_path`, `changed_files`, `pending_count`, `proposer`, and `pr` (`url`, `state`, `number`, `provider`).
`POST`	`/api/managed-sources/{source_id}/workspace/propose`	Stage a supported KB text or metadata file (`.md`, `.yml`, `.yaml`, `.json`, `.txt`, or `.csv`) under a first-level folder in `documents_root`. Body: `relative_path`, and either `content` (full replacement) or `search` + optional `replace`, plus optional `note`. Returns `branch`, `relative_path`, `pending_count`, and refreshed `status`.
`POST`	`/api/managed-sources/{source_id}/workspace/pr`	Commit staged document changes (when needed) and open or update a PR/MR. Body: optional `target_index`, `title`, `body`, `commit_message`. Returns `pr_url`, `pr_number`, `pr_state`, `provider`, `branch`, `target_index`, and `changed_files`. `changed_files` is the authoritative list of PR contents; each entry includes the repository-relative `path` and status `A`, `M`, `D`, or `R`.
`POST`	`/api/managed-sources/{source_id}/workspace/discard`	Discard staged workspace changes. Optional query `target_index`. Returns `closed_pr` when an open review PR/MR was closed.

Flow pending-promotion endpoints

These endpoints manage Flow definitions held after a managed-source sync when auto_promote_on_sync is false. They require manage_flows.

Method	Path	Description
`GET`	`/api/flows/pending-promotions`	List waiting Flow changes. Optional `source_id` query parameter filters by managed source. Returns `pending` summaries with `pending_id`, `source_id`, `artifact_id`, optional `flow_id`, `kind` (`change`, `new`, or `removal`), and `state`.
`GET`	`/api/flows/pending-promotions/{pending_id}`	Read-only preview of one waiting change, including `before`, `after`, dependency status, and fingerprints in `preview`. Use these fingerprints unchanged when promoting. Returns `404` if the pending id is not found.
`POST`	`/api/flows/pending-promotions/{pending_id}/promote`	Promote the previewed change. Body: `pending_fingerprint`, `live_fingerprint`, and optional `enable` (boolean, default `false`; applies only to a Flow new to this install). Returns `pending_id`, `kind`, optional `flow_id` and `applied_version`, and state (`applied` or `applied_finishing`). A stale preview or unresolved dependencies returns `409`; if the response is `applied_finishing`, call this endpoint again for the same `pending_id` to complete its owed step.

The promotion request also returns 401 when the acting user is missing, 403 without manage_flows, 404 when the pending change or source is gone, and 400 for other promotion validation failures.

When a managed-source sync or preview cannot resolve release_ref, its error identifies the requested ref and reports available release tags, branch refs tried, local branches, and whether a remote is configured (or that remote state could not be read).

Managed-source responses include release_poll on each source object from list, detail, create, and update operations. It is null when skill revision tracking is disabled or the source does not scan skills. Otherwise it reports the scheduled check state: checked_at, skipped_at, and error; new_release (tag, commit_sha); moved_tag (tag, anchored_commit_sha, nullable remote_commit_sha, detected_at); and upgrade_refusal (tag, error_code, message, at). A null remote_commit_sha means the pinned tag was deleted remotely. Findings describe conditions that still hold; a failed check sets error and retains the findings from the previous check. Each source response also includes auto_sync (default false) and auto_sync_state. The state reports whether the scheduled job is running, whether the source is currently eligible and any ineligible_reason, the last recorded outcome, checked_at, skipped_at, optional counts in waiting, and sanitized failures. Outcomes are up_to_date, updated, updated_awaiting_promotion, updated_with_errors, failed, or not_eligible. checked_at changes when the outcome changes, not on every unchanged pass; the first unchanged pass after an update records up_to_date. skipped_at records when the latest pass left a source alone because it was syncing. waiting counts items needing administrator action by kind: blueprint_versions, agent_changes, document_indexes, flow_changes, and role_changes. For role changes, it also reports counts by reason: roles_edited_locally, roles_owned_elsewhere, roles_rejected, roles_removed_from_source, roles_granting_unmanaged_agents, roles_changed_during_sync, roles_waiting_for_review (when auto-promote is off), and role_errors. auto_sync_state.role_notes lists rejected roles to fix in Git and removed roles to delete manually in Admin → Roles; these notes are not waiting work. Their reasons are visible only to callers with manage_users. For agent changes, waiting also reports counts by reason: agents_edited_locally, agents_switched_off_locally, agents_without_applied_record, agents_changed_during_sync, agent_conflicts, and agent_errors. failures contains by_type counts, degraded, fixed-name exceptions, and an optional error_code. If sync resolves release_ref to a tag that now names a different remote commit, it fails with error_code: RELEASE_TAG_CHANGED_ON_REMOTE rather than using the stale local tag. Reset the checkout and sync again, or re-pin the release tag for a governed skill source.

Managed-source deletion is retryable. A source remains marked as pending deletion until dependent cleanup succeeds, so a failed delete does not lose the ownership records needed for a retry or allow a deleted legacy source to reappear after reload. While cleanup is pending, sync returns HTTP 500 with error_code SOURCE_DELETE_CLEANUP_PENDING; resolve the reported cleanup_warnings and retry DELETE /api/managed-sources/{source_id}.

Async managed-source sync. POST .../sync-async returns immediately with a job_id. Poll GET .../sync-status/{job_id} until status is complete or error. The dashboard polls every 2 seconds for up to 15 minutes. Job status is held in memory (up to 200 terminal jobs); restarting the server drops in-flight and completed job records, so polling after restart returns HTTP 404. A second sync-async for the same source with a different overwrite_indexes, apply_agent_changes, expected_agent_commit, expected_agent_plan_hash, apply_role_changes, expected_role_commit, or expected_role_plan_hash starts a new job (serialized behind the first); matching values on all seven fields reuse the in-flight job.

Background governed skill release changes. On PATCH /api/managed-sources/{source_id}, send both sync_now: true and sync_in_background: true to save and audit a governed skill release or policy change, then run its sync as a background job. The response has sync_job (job_id, status, expected_release_commit) instead of sync; poll GET /api/managed-sources/{source_id}/sync-status/{job_id} until complete or error. The job is complete only when both the sync result and current source name the expected commit and the source is no longer pending. Otherwise it ends with error_code SKILL_RELEASE_CHANGED_DURING_SYNC or SKILL_RELEASE_STILL_PENDING. If no job starts after the change is saved, the response has warning code SKILL_RELEASE_SYNC_NOT_STARTED and no sync_job. Another release change is refused with HTTP 409 and error_code MANAGED_SOURCE_SYNC_IN_PROGRESS while a sync or release change is in progress. For other saves with sync_now: true, sync_in_background is ignored and sync completes before the response. Job records are process-local and are lost when the server restarts.

Managed agent sync and apply. Agent sources discover one subdirectory per agent under agents_root, each with an agent.yaml or agent.yml manifest (schema_version, agent_id, name, instructions, optional description, llm_provider, default tool/skill groups, and tool/skill access modes). Sync without apply_agent_changes only checks out Git content and returns agent_preview (summary, changes, commit_sha, plan_hash) plus requires_agent_apply_confirmation when any change is not noop. To apply, call sync again with apply_agent_changes: true, expected_agent_commit set to the preview’s commit_sha, and expected_agent_plan_hash set to the preview’s plan_hash. Missing preview pins return error_code AGENT_PREVIEW_REQUIRED; commit or plan drift after preview returns AGENT_PREVIEW_STALE. Managed agents are non-editable in the UI (is_editable: false); disable them per artifact or by removing the source (owned agents are deactivated, not hard-deleted).Scheduled sync agent apply. When scheduled sync runs for an agent source whose auto_promote_on_sync is not false, Genesis applies the discovered agent changes without a separate confirmation. The sync result includes agent_auto_apply with applied and waiting; changes it cannot safely apply remain for an administrator, and set requires_agent_apply_confirmation: true. See auto_sync_state.waiting above for the waiting counts and reasons. With auto_promote_on_sync: false, scheduled sync previews the agent changes but does not apply them unattended.Managed role sync and apply. A source with roles scans roles/<role_name>/role.yaml (or role.yml) role definitions. Manual sync returns role_preview with summary, changes, commit_sha, and plan_hash, and sets requires_role_apply_confirmation when applicable; an administrator with manage_users confirms the preview using its commit and plan hash. Preview details and reasons are visible only to callers with manage_users; secret grant names also require manage_secrets. When scheduled sync is active for the source (auto_sync: true) and auto_promote_on_sync is omitted or not false, Genesis applies safe role creates and updates automatically only when every agent granted by the role is managed by that same source. Other applicable changes wait for review; rejected definitions must be fixed in Git, and roles removed from Git remain on the instance until deleted in Admin → Roles. With auto_promote_on_sync: false, scheduled sync records a preview but does not apply roles unattended. The next scheduled pass checks the source (300 seconds by default; see Managed source automatic sync). Role definitions cannot grant admin-level access; see Users and Roles for the definition restrictions.

ManagedSourceUpsertResponse and sync outcomes. POST and PATCH return the full upsert envelope at the top level (success, source, sync, optional sync_job, warning / warning_code / warning_action). When sync_now runs, inspect sync for partial_success, degraded_artifact_count, hydrate_errors, and per-type entries under sync.hydrate (for example skills.degraded_artifacts with artifact_id and reason). A completed sync with lenient-recovered SKILL.md or flow YAML frontmatter still sets sync.partial_success to true and lists the artifact under the matching hydrate.*.degraded_artifacts entry. Config → Managed Sources surfaces these as warning toasts rather than plain success.

SCAN_TYPE_REMOVAL_NOT_SUPPORTED on PATCH. When scan_types_enabled would remove one or more existing types, the route returns success: false with error_code, error, current_scan_types, attempted_scan_types, removed_scan_types, recovery (delete_and_recreate), and remediation (delete the source and recreate with the desired scan_types_enabled).

document_feed_summary document counts. Each entry in indexes includes count (markdown files under Git management in that index) and index_doc_count (count plus index_only_doc_count — documents present in the live index but not yet in the repo). total_count sums managed count values only; total_index_doc_count sums index_doc_count across every index and is the accurate total for UI chips such as Config → Managed Sources “N documents” rows. Per-index fields also include index_only_doc_count, pending_change_count, proposer, pr, adopted, name_conflict_count, and requires_overwrite_ack.

checkout_exclude (managed checkout pruning). checkout_exclude is an ordered string[] on create, update, and ManagedSourceResponse that controls which repository paths Genesis omits from the managed base checkout using Git sparse checkout. It is separate from include / exclude, which only govern artifact discovery and enablement — those selectors do not change what is present on disk. Each rule must not contain NUL or embedded newline characters. Blank lines and lines starting with # are ignored. Other lines use gitignore-style path patterns; prefix a line with ! to re-include a path inside a broader exclusion. When checkout_exclude is absent or empty ([]), Genesis performs a full checkout (same as before this field existed). On PATCH, omitting checkout_exclude preserves the stored rules; sending checkout_exclude: [] disables sparse checkout on the next sync. Non-empty rules require Git 2.25 or newer — otherwise sync returns error_code SPARSE_CHECKOUT_UNSUPPORTED. Failed sparse apply attempts return SPARSE_CHECKOUT_APPLY_FAILED or MANAGED_CHECKOUT_DEGRADED when rollback also fails. Paths pruned from the base checkout are not present in the Git Browser tree or other filesystem enumeration of that checkout. Per-user managed worktrees (skills, flows, apps, agents, and document workspaces) stay on a full checkout even when the base checkout is sparse.

Runtime skill catalog routes

Method	Path	Description	Required permission
`POST`	`/api/skills`	Create or replace one skill version. The body requires `skill_name`, `version`, `title`, and `summary`; `created_by`, `created_at`, and `updated_at` are optional and client values are ignored. Genesis records the authenticated caller and sets timestamps for new versions; replacing a version preserves its original creator and creation time and advances `updated_at`. Returns the saved skill spec.	`manage_skills`
`POST`	`/api/skills/executions`	Execute a skill. Body fields: required `bot_id` and `skill_name`; optional `version` (`null`), `payload` (`{}`), and `dry_run` (`false`). Returns the execution record.	`manage_skills`
`GET`	`/api/skills/executions`	List skill execution records. Optional query fields: `bot_id`, `skill_name`, and `limit` (default `100`, range `1`–`500`).	—
`DELETE`	`/api/skills/{skill_name}`	Hard-delete a skill (all versions) and every assignment referencing it. Unlike `POST /api/skills/catalog/{skill_name}/versions/{version}/deprecate`, which retires one version but leaves the catalog row, this removes the skill entirely so a broken or mistaken registry entry can be cleaned up. Returns `{"success": true, "data": {"skill_name": "<name>", "deleted": true}}`.	`manage_skills`

The execution response’s data contains execution_id, bot_id, skill_name, version, status, started_at, finished_at, duration_ms, invoked_by, input_payload, evidence, and error. A caller without manage_skills cannot execute a skill; the POST route returns 403. For shell-step payload substitution and its security boundary, see Skill Runtime Tools.

Status	Meaning
`200`	The skill was deleted from the runtime catalog.
`404`	No skill with that name exists in the runtime catalog.

DELETE /api/skills/{skill_name} operates on the runtime skill registry (SkillService). To remove an imported AgentSkills package and its on-disk files, use DELETE /api/agent-skills/{skill_name} instead.

Skill repository and workspace routes

Method	Path	Description
`GET`	`/api/skills/repositories`	List managed Skill sources.
`POST`	`/api/skills/repositories`	Create a source (`repo_id`, `remote_url`, `connection`, `release_ref?`, `skills_root?`, `include?`, `exclude?`, `checkout_exclude?`, `sync_on_create?`).
`PATCH`	`/api/skills/repositories/{source_id}`	Update a source; pass `sync_now: true` to refresh.
`DELETE`	`/api/skills/repositories/{source_id}`	Remove a source.
`GET`	`/api/skills/{skill_name}/workspace/status`	Workspace dirty/PR state for a managed skill.
`POST`	`/api/skills/{skill_name}/workspace/start`	Open or resume the edit workspace.
`POST`	`/api/skills/{skill_name}/workspace/discard`	Drop the workspace without pushing.
`GET`	`/api/skills/{skill_name}/workspace/files`	List files in the workspace.
`GET`	`/api/skills/{skill_name}/workspace/files/{relative_path}`	Read a workspace file.
`POST`	`/api/skills/{skill_name}/workspace/files/{relative_path}`	Write a workspace file.
`POST`	`/api/skills/{skill_name}/workspace/pr`	Commit workspace changes (when needed) and open an MR/PR.

App repository and workspace routes

Method	Path	Description
`GET`	`/api/apps/repositories`	List managed App sources. Each repository includes `artifact_counts` (per artifact type) and `dependency_summary`.
`POST`	`/api/apps/repositories`	Create a source (`repo_id`, `remote_url`, `connection`, `release_ref?`, `apps_root?`, `include?`, `exclude?`, `checkout_exclude?`, `sync_on_create?`).
`PATCH`	`/api/apps/repositories/{source_id}`	Update a source; pass `sync_now: true` to refresh.
`DELETE`	`/api/apps/repositories/{source_id}`	Remove a source.
`GET`	`/api/apps/{app_id}/workspace/status`	Workspace dirty/PR state for a managed app.
`POST`	`/api/apps/{app_id}/workspace/start`	Open or resume the edit workspace.
`POST`	`/api/apps/{app_id}/workspace/discard`	Drop the workspace without pushing.
`GET`	`/api/apps/{app_id}/workspace/files`	List files in the workspace.
`GET`	`/api/apps/{app_id}/workspace/files/{relative_path}`	Read a workspace file.
`POST`	`/api/apps/{app_id}/workspace/files/{relative_path}`	Write a workspace file.
`POST`	`/api/apps/{app_id}/workspace/pr`	Commit workspace changes (when needed) and open an MR/PR.
`POST`	`/api/apps/{app_id}/export-to-managed/preview`	Preview the standalone app bundle files that would be copied into a managed Apps source. Requires `manage_git` and app-level `manage`.
`POST`	`/api/apps/{app_id}/export-to-managed/commit`	Export a standalone app into a managed repo and open an MR/PR. Body: `source_id` or `repo_id` (one required), optional `title`, `body`, `commit_message`. Requires `manage_git` and app-level `manage`.

On GET /api/apps/repositories, artifact_counts includes only apps whose microapps record was created by managed sync (created_by starts with managed_sync:). Standalone apps whose workspace_path was mis-pathed into a managed clone after a failed export are excluded so Managed Sources counts stay accurate. Artifacts with no microapps record yet are still counted; if the microapps service is unavailable, Genesis falls back to counting all registry artifacts for that source.

Flow routes mirror the Skill pattern under /api/flows/... with flows_root on create and optional auto_promote_on_sync. Flow create and update validation also applies the bulk_copy contract before saving; see Flows — Move a table between registered connections for the accepted fields and target-specific rules. In a flow definition, steps[*].run_concurrently is a boolean that defaults to false; consecutive steps marked true run as one batch, with at most 8 steps at once.

Managed artifact dependency routes

Method	Path	Description
`GET`	`/api/managed-artifacts/dependencies`	List dependency rows (`source_id?`, `artifact_type?`, `artifact_id?`, `unresolved_only?`).
`GET`	`/api/managed-artifacts/dependency-targets`	List local bind candidates (`kind`, `query?`, `provider?`).
`POST`	`/api/managed-artifacts/bindings`	Upsert a binding (`scope`, `source_id`, `kind`, `target`, plus artifact fields when `scope` is `artifact`). Accepts `slot_id`, `slot_id_or_role`, or `role`.
`DELETE`	`/api/managed-artifacts/bindings/{binding_id}`	Remove a saved binding.
`POST`	`/api/managed-artifacts/dependencies/recheck`	Re-evaluate dependency satisfaction (`source_id?`).

Blueprint example requests

curl -X POST http://<genesis-host>/api/blueprints/customer-onboarding/versioning/enable

curl -X GET http://<genesis-host>/api/blueprints/customer-onboarding/versioning/summary

curl -G http://<genesis-host>/api/blueprints/customer-onboarding/versioning/summary \
  --data-urlencode "blueprint_id=<blueprint_id_from_inventory>"

curl -X POST http://<genesis-host>/api/blueprints/customer-onboarding/versioning/versions \
  -H "Content-Type: application/json" \
  -d '{
    "note": "Captured onboarding workflow edits"
  }'

curl -X POST http://<genesis-host>/api/blueprints/customer-onboarding/versioning/promote \
  -H "Content-Type: application/json" \
  -d '{
    "version_id": "2d3b4c5e-0000-1111-2222-333344445555",
    "note": "Approved for production"
  }'

curl -X GET http://<genesis-host>/api/blueprints/customer-onboarding/access

curl -X POST http://<genesis-host>/api/blueprints/customer-onboarding/access/grant \
  -H "Content-Type: application/json" \
  -d '{
    "role_name": "analysts",
    "actions": ["view", "execute"]
  }'

curl -X POST http://<genesis-host>/api/blueprints/wizard \
  -H "Content-Type: application/json" \
  -d '{
    "query": "I need to sync transformed warehouse data back into Salesforce"
  }'

curl -X POST http://<genesis-host>/api/blueprints/wizard \
  -H "Content-Type: application/json" \
  -d '{
    "query": "I need to sync transformed warehouse data back into Salesforce",
    "answers": {
      "q1": "Salesforce",
      "q2": "Near real time"
    },
    "answer_context": [
      {
        "id": "q1",
        "question": "Which destination system should receive the transformed data?",
        "answer": "Salesforce"
      },
      {
        "id": "q2",
        "question": "How frequently should the sync run?",
        "answer": "Near real time"
      }
    ],
    "session_id": "abcd1234efgh5678"
  }'

Team Wiki endpoints

These endpoints are mounted under /api/wiki/v1/... and provide Team Wiki browsing plus per-page commentary for the dashboard. Read responses cover both graph-backed entity pages and generated wiki://... subgraph documents. Graph-backed page responses are rendered dynamically from the Context Graph and can include graph-backed properties, lineage, ancestry, child-navigation metadata, related subgraph-document references, and a learning count for the requested node. Commentary routes let callers list, post, and soft-delete Markdown comments on any wiki page; only the comment author can delete a live comment, and soft-deleted comments return an empty body_markdown in list responses. The same page payload also backs the Digital Twin node detail panel and graph-backed entity pages in the standalone Wiki workspace when the frontend wiki feature flag is enabled. The page endpoint is optimized for the web UI: graph-native pages return the main rendered markdown without waiting for the ## Children rollup, and clients can load children separately from /api/wiki/v1/tree?parent=<qualified_name> when needed.

When authentication is enabled, all Team Wiki routes in this section require the system-level view_git permission, including commentary list, create, and delete.

Endpoint summary

Method	Path	Description	Required permission
`GET`	`/api/wiki/v1/tree`	List the immediate child nodes under an optional parent qualified name.	`view_git`
`GET`	`/api/wiki/v1/subgraphs`	List every generated `wiki://...` subgraph document available in the standalone Wiki discovery pane.	`view_git`
`GET`	`/api/wiki/v1/pages/{qualified_name:path}`	Read one Team Wiki page by qualified name, including a learnings-only page for an active anchor absent from the graph.	`view_git`
`GET`	`/api/wiki/v1/subgraph/{qualified_name_tail:path}`	Read one generated subgraph document by its `wiki://...` qualified-name tail.	`view_git`
`GET`	`/api/wiki/v1/pages/{qualified_name:path}/commentary`	List commentary on the requested wiki page.	`view_git`
`POST`	`/api/wiki/v1/pages/{qualified_name:path}/commentary`	Post one Markdown comment on the requested wiki page.	`view_git`
`DELETE`	`/api/wiki/v1/pages/{qualified_name:path}/commentary/{comment_id}`	Soft-delete one commentary row when the caller is the author.	`view_git`

`GET /api/wiki/v1/tree`

Field	In	Type	Default	Required	Description
`parent`	query	string or null	`null`	No	Optional qualified-name parent. When omitted, Genesis lists top-level source systems.

Team Wiki tree response fields

Field	Type	Description
`success`	boolean	Whether the request completed successfully.
`parent`	string or null	Echoes the requested parent qualified name. `null` means the root listing.
`nodes`	object[]	Immediate child nodes under the requested parent. Includes synthesized branches for active authored learning anchors that are absent from the graph.
`total`	integer	Total number of nodes returned.

Team Wiki tree node fields

Field	Type	Description
`id`	string	Node qualified name.
`name`	string	Display label for the node.
`path`	string	Node qualified name.
`display_name`	string	Human-friendly node label.
`node_type`	string	Node type for the returned graph item or intermediate hierarchy node.
`is_directory`	boolean	`true` when the node can be expanded with another tree request, including a synthesized learning-anchor branch.
`children`	object[]	Always returned as an empty array in this response shape; expand child nodes by calling the tree endpoint again with `parent`.

`GET /api/wiki/v1/subgraphs`

This route has no request parameters. It returns the generated wiki://... document refs used to populate the standalone Wiki discovery pane. When Twin cannot enumerate those documents, the route returns 503 instead of an empty success response. An empty subgraph_documents list therefore means Twin was reachable and no generated documents were found.

Team Wiki subgraph list response fields

Field	Type	Description
`success`	boolean	Whether the request completed successfully.
`subgraph_documents`	object[]	Generated `wiki://...` subgraph document refs available for discovery.
`total`	integer	Total number of subgraph document refs returned.

Team Wiki subgraph list error responses

Status	When returned
`403`	The caller lacks the `view_git` permission.
`500`	Twin returned a response that could not be read, or the wiki read failed.
`503`	Twin could not be reached or its request budget was unavailable.

`GET /api/wiki/v1/pages/{qualified_name:path}`

Field	In	Type	Default	Required	Description
`qualified_name`	path	string	none	Yes	Fully qualified graph node or Team Wiki learning-anchor name to read, such as `snowflake://ANALYTICS/FINANCE/REVENUE`.

Team Wiki page response fields

Field	Type	Description
`success`	boolean	Whether the page request completed successfully.
`qualified_name`	string	Canonical qualified name for the requested graph node.
`display_name`	string	Human-friendly node label.
`node_type`	string	Graph node type such as `table`, `view`, `dashboard`, or `file`.
`source_system`	string	Source-system identifier derived from the graph node.
`properties`	object	Structured graph-backed metadata for the node.
`upstream`	object[]	Upstream lineage links included in the page response.
`downstream`	object[]	Downstream lineage links included in the page response.
`upstream_total`	integer	Total upstream link count for the node before any response capping.
`downstream_total`	integer	Total downstream link count for the node before any response capping.
`children`	object[]	Direct child wiki-page links for synthesized hierarchy pages. For graph-native pages returned by this UI endpoint, Genesis skips the synchronous children rollup and typically returns an empty array; clients can call `/api/wiki/v1/tree?parent=<qualified_name>` to load children progressively.
`children_total`	integer	Total direct child link count returned with `children`. Graph-native UI responses typically return `0` here because the children list is fetched separately.
`is_synthesized`	boolean	`true` for synthesized or virtual hierarchy pages whose `rendered_body` already contains a rendered `## Children` section. `false` for graph-native pages that should load children separately if needed.
`is_ungrounded`	boolean	Present as `true` only when no Twin graph node exists for the qualified name and the page was synthesized from authored learnings anchored at or beneath it. Omitted for graph-grounded pages.
`ancestors`	object[]	Ordered ancestor chain for the node.
`rendered_body`	string	Markdown body rendered dynamically from graph metadata and lineage for the standalone Wiki workspace or the Digital Twin node detail panel. For graph-native pages, this UI response omits the rendered `## Children` rollup so the main body can render immediately; synthesized pages still include that section inline.
`subgraph_documents`	object[]	Generated `wiki://...` subgraph document refs associated with this entity. Graph-backed pages can return these refs so clients can link to document-level writeups; synthesized hierarchy pages return an empty array.
`subgraph_documents_unavailable`	boolean	Present as `true` when the graph-backed page was read successfully but its covering-document lookup could not be completed. When omitted, the lookup succeeded; an empty `subgraph_documents` list then means no covering documents were found.
`learnings_total`	integer	Number of learning statements currently associated with the requested qualified name.

Team Wiki page error responses

Status	When returned
`400`	The qualified name is invalid.
`403`	The caller lacks the `view_git` permission.
`404`	The requested page does not exist.
`500`	Twin returned a response that could not be read, or the wiki read failed.
`503`	The wiki storage backend or Twin service is unavailable.

Subgraph document reference fields

Field	Type	Used by	Description
`qualified_name`	string	`subgraph_documents`, `GET /api/wiki/v1/subgraphs`	Canonical subgraph-document qualified name, such as `wiki://finance/order-to-cash`.
`title`	string	`subgraph_documents`, `GET /api/wiki/v1/subgraphs`	Human-friendly title for the generated subgraph document.

Team Wiki link fields

Field	Type	Used by	Description
`qualified_name`	string	`upstream`, `downstream`, `children`, `ancestors`	Qualified name of the related graph node.
`display_name`	string	`upstream`, `downstream`, `children`, `ancestors`	Human-friendly label for the related graph node.
`node_type`	string	`upstream`, `downstream`, `children`	Graph node type for lineage or direct-child links.

`GET /api/wiki/v1/subgraph/{qualified_name_tail:path}`

Field	In	Type	Default	Required	Description
`qualified_name_tail`	path	string	none	Yes	Subgraph-document qualified-name tail without the leading `wiki://` scheme. Encode each path segment separately; Genesis reconstructs the full `wiki://...` qualified name on the server.

Team Wiki subgraph document response fields

Field	Type	Description
`qualified_name`	string	Canonical `wiki://...` qualified name for the returned subgraph document.
`title`	string	Human-friendly title for the generated subgraph document.
`body_markdown`	string	Markdown body for the generated subgraph document. Wikilinks inside the body can reference graph-backed entity pages or other `wiki://...` subgraph documents.
`updated_at`	string or null	Last-updated timestamp when available.
`template`	string[] or null	For `wiki://estate` only: ordered list of visible section block types in the rendered page (for example `["overview", "areas", "systems"]`). `null` for other subgraph documents.
`available_block_types`	string[] or null	For `wiki://estate` only: all valid section block types that can appear in the estate template (`overview`, `areas`, `systems`). `null` for other subgraph documents.

Team Wiki subgraph document error responses

Status	When returned
`403`	The caller lacks the `view_git` permission.
`404`	The requested subgraph document does not exist.
`500`	Twin returned a response that could not be read, or the wiki read failed.
`503`	Twin could not be reached or its request budget was unavailable.

`GET /api/wiki/v1/pages/{qualified_name:path}/commentary`

Field	In	Type	Default	Required	Description
`qualified_name`	path	string	none	Yes	Fully qualified graph node name or `wiki://...` page whose commentary to list.

Team Wiki commentary list response fields

Field	Type	Description
`comments`	object[]	Commentary rows for the requested page, ordered for display.

Team Wiki commentary row fields

Field	Type	Description
`id`	integer	Commentary row identifier.
`qn`	string	Qualified name of the wiki page this comment belongs to.
`author_identity`	string	Display identity for the author (email when available, otherwise user id).
`body_markdown`	string	Markdown body for live comments. Soft-deleted comments return an empty string so deleted content is not exposed in API responses.
`created_at`	string	Creation timestamp for the comment.
`deleted_at`	string or null	Soft-delete timestamp when the comment was removed; `null` for live comments.
`deleted_by`	string or null	Identity recorded when the comment was soft-deleted; `null` for live comments.
`can_delete`	boolean	`true` when the authenticated caller authored the comment and it is not already soft-deleted.

`POST /api/wiki/v1/pages/{qualified_name:path}/commentary`

Create one Markdown comment on the requested wiki page. Genesis attributes the comment to the authenticated caller and returns 201 Created on success.

Field	In	Type	Default	Required	Description
`qualified_name`	path	string	none	Yes	Fully qualified graph node name or `wiki://...` page to attach the comment to.
`body_markdown`	body	string	none	Yes	Comment body to persist. Genesis strips surrounding whitespace before validation; empty or whitespace-only values are rejected, and the maximum length is 5000 characters.

Team Wiki commentary create response fields

Field	Type	Description
`success`	boolean	Whether the commentary write completed successfully.
`comment_id`	integer	Storage-assigned identifier for the new comment.

Team Wiki commentary create error responses

Status	When returned
`400`	Invalid request payload (for example empty `body_markdown` after whitespace strip).
`403`	The caller lacks the `view_git` permission.
`503`	The Team Wiki storage backend is unavailable.

`DELETE /api/wiki/v1/pages/{qualified_name:path}/commentary/{comment_id}`

Soft-delete one commentary row. Genesis verifies that the comment belongs to the path qualified name and that the authenticated caller is the author.

Field	In	Type	Default	Required	Description
`qualified_name`	path	string	none	Yes	Qualified name of the wiki page that should own the comment.
`comment_id`	path	integer	none	Yes	Commentary row identifier to soft-delete.

Team Wiki commentary delete response fields

Field	Type	Description
`success`	boolean	`true` when the soft-delete completed successfully.

Team Wiki commentary delete error responses

Status	When returned
`403`	The caller lacks the `view_git` permission, the comment is not on the requested page, or the caller is not the author.
`503`	The Team Wiki storage backend is unavailable.

Configuration and secrets permissions

These endpoints back the Genesis Config UI and related administrative flows. They are mounted under /api/config/..., /api/secrets/..., /api/push-metrics/..., and selected /api/genesis-enhancements/... routes.

When authentication is disabled, RBAC permission checks do not block requests on these routes.

Routes in the groups below either enforce the listed system-level permission or, when marked Public, do not require an RBAC permission. Protected routes return 403 Permission denied when the caller lacks access.

Configuration permissions

Permission	Allows
`access_config_panel`	Read and manage configuration and related admin APIs used for advanced settings, profiles, templates, provider setup, model assignments, connection tests, enhancement-admin workflows, push-metrics administration, warehouse settings, admin audit log reads, and related integrations.
`access_pulse_panel`	Read Pulse monitoring surfaces and agent-review scorecard, backfill, run-history, learning-candidate, adoption-ledger, and learning-delta APIs. Does not gate expectation-met message feedback on chat threads.
`manage_agent_learning`	Accept or dismiss the lessons proposed for agents. Reading the Pulse learning queue, adoption ledger, and improvement report only needs `access_pulse_panel`.
`manage_secrets`	Manage secret records, encryption-key setup APIs, and embedded Tailscale auth-key setup APIs (Native App). Also required for the LLM provider debug endpoint because it can expose secret-related runtime details.

Protected configuration and secrets endpoints

Configuration request bodies on these routes reject undeclared JSON fields with HTTP 422 Unprocessable Entity; fields are no longer silently ignored. Send only the fields listed for the endpoint, including for partial updates and connection tests. This applies to the request models used by the configuration, provider, automation, profile, secret, branding, SCIM, and custom-endpoint routes below.

Route family	Example paths	Required permission
Advanced settings	`/api/config/advanced/schema`, `/api/config/advanced`, `/api/config/advanced/{section_name}`, `/api/config/advanced/value`, `/api/config/advanced/values`, `/api/config/advanced/reset`, `/api/config/advanced/archive/threads/run`	`access_config_panel`
Admin audit log (read)	`/api/admin/audit-log`, `/api/admin/audit-log/{audit_id}`	`access_config_panel`
Agent slots (full)	`/api/admin/slots`	`access_config_panel`
Agent review (scorecard, backfill, and learning reads)	`/api/agent-review/backfill/estimate`, `/api/agent-review/backfill/{run_id}/start`, `/api/agent-review/runs`, `/api/agent-review/scorecard/filter-options`, `/api/agent-review/scorecard/data`, `/api/agent-review/learning-candidates`, `/api/agent-review/learning-deltas`, `/api/agent-review/adoptions`	`access_pulse_panel`
Agent learning decisions	`/api/agent-review/learning-candidates/{candidate_id}/accept`, `/api/agent-review/learning-candidates/{candidate_id}/dismiss`	`manage_agent_learning`
Mission Value report	`/api/mission-value`	`access_pulse_panel` and `view_all_missions`
Mission Value baseline replacement	`/api/mission-value/baselines`	`access_config_panel`
Config profiles	`/api/config/profiles`, `/api/config/profiles/current`, `/api/config/profiles/current/drift`, `/api/config/profiles/{name}`, `/api/config/profiles/{name}/diff`, `/api/config/profiles/example/download`	`access_config_panel`
Config setup utilities	`/api/config/setup/validate`, `/api/config/setup/validate-file`, `/api/config/setup/apply`, `/api/config/setup/apply-partial`, `/api/config/setup/apply-file`, `/api/config/setup/export`, `/api/config/setup/export-file`, `/api/config/setup/templates`, `/api/config/setup/templates/{template_name}`, `/api/config/setup/templates/{template_name}/download`, `/api/config/setup/templates/{template_name}/apply`, `/api/config/setup/status`, `/api/config/setup/required-secrets`, `/api/config/setup/sources`	`access_config_panel`
Bitbucket config	`/api/config/bitbucket`, `/api/config/bitbucket/test`	`access_config_panel`
Jira config, automation, service worker, and Jira EAI	`/api/config/jira`, `/api/config/jira/test`, `/api/config/jira/automation`, `/api/config/jira/automation/options`, `/api/config/jira/automation/poll-now`, `/api/config/jira/service-worker`, `/api/config/jira/service-worker/validate`, `/api/config/jira/service-worker/provision`, `/api/config/jira/eai/assigned`, `/api/config/jira/eai/assign`	`access_config_panel` for base Jira config and Jira EAI; shared automation and service-worker routes also require Jira automation rollout to be enabled and then accept either `access_config_panel` or `manage_all_connections`
ServiceNow automation	`/api/config/servicenow/automation`, `/api/config/servicenow/automation/options`, `/api/config/servicenow/automation/poll-now`	`access_config_panel` or `manage_all_connections`
Linear automation	`/api/config/linear/automation`, `/api/config/linear/automation/options`, `/api/config/linear/automation/poll-now`	`access_config_panel` or `manage_all_connections`
Azure DevOps automation	`/api/config/azure-devops/automation`, `/api/config/azure-devops/automation/poll-now`	`access_config_panel` or `manage_all_connections`
Ticket automation (Requests read API)	`/api/ticket-automation/activity`, `/api/ticket-automation/activity/{work_item_id}`, `/api/ticket-automation/health`	`access_config_panel` or `manage_all_connections`
ServiceNow webhook (public)	`POST /api/servicenow/webhook`	No auth; HMAC signature required when `webhook_secret` is configured
Email config	`/api/config/email/status`, `/api/config/email/instructions`, `/api/config/email/test`, `/api/config/email`	`access_config_panel`
Branding	`/api/config/branding`, `/api/config/branding/logo/{logo_type}`	`access_config_panel` for `PUT` and logo upload/delete; any authenticated user for `GET` routes
License management	`/api/license/status`, `/api/license/activate`, `/api/license/deactivate`, `/api/license/check`	`access_config_panel`
Auth bootstrap	`/api/config/auth`	Public
User runtime config	`/api/config/user-config`	`access_config_panel`
SCIM admin config	`/api/config/scim/config`, `/api/config/scim/tokens/rotate`, `/api/config/scim/tokens/revoke`, `/api/config/scim/group-role-mapping`	`access_config_panel`
Slack configuration and runtime	`/api/slack/status`, `/api/slack/test`, `/api/slack/bot/{bot_id}/status`, `/api/slack/bot/{bot_id}/runtime`, `/api/slack/bot/{bot_id}/reconnect`	`access_config_panel`
Microsoft Teams Bot Framework runtime	`/api/teams/health`, `POST /api/teams/messages/{bot_id}`, `/api/teams/ingress-canary`	Public when listed; Bot Framework JWT or relay-forwarded JWT on `POST /api/teams/messages/{bot_id}`; ingress canary requires `teams.ingress_canary_enabled`
Google Chat direct-message runtime	`POST /api/google-chat/events/{bot_id}`	Public route; Google-signed Bearer token is validated against the connection’s endpoint audience
Microsoft Teams per-bot credentials and runtime	`GET /api/teams/bot/{bot_id}/credentials`, `POST /api/teams/bot/{bot_id}/credentials`, `GET /api/teams/bot/{bot_id}/app-package`, `GET /api/teams/bot/{bot_id}/runtime`	`manage_agents`
Custom endpoints	`/api/config/custom-endpoints`, `/api/config/custom-endpoints/{group_name}`	`access_config_panel`
Warehouse config	`/api/config/warehouse/status`, `/api/config/warehouse/test-access`, `/api/config/warehouse/apply`	`access_config_panel`
OAuth provider bootstrap	`/api/config/oauth_providers/databricks`, `/api/config/oauth_providers/snowflake`, `/api/config/oauth_providers/github`, `/api/config/oauth_providers/gitlab`, `/api/config/oauth_providers/jira`, `/api/config/oauth_providers/sharepoint`, `/api/config/oauth_providers/microsoft_teams`, `/api/config/oauth_providers/google_workspace`	`access_config_panel`
AI Providers page overview (read-only)	`/api/config/ai-providers/overview`	any authenticated user (response carries no secret plaintext)
AI Providers embedding health	`/api/config/ai-providers/embedding-health`	`access_config_panel` or `view_model_config`
LLM provider config	`/api/config/llm-providers/info`, `/api/config/llm-providers/mark-configured`, `/api/config/llm-providers/{provider}/admission`, `/api/config/llm-providers/{provider}/ensure-endpoints`, `/api/config/llm-providers/databricks`, `/api/config/llm-providers/openai`, `/api/config/llm-providers/litellm-proxy`, `/api/config/llm-providers/other`, `/api/config/llm-providers/other/{provider}`, `/api/config/llm-providers/{llm_type}/activate`	`access_config_panel`; LiteLLM Proxy create and update routes also require admin, and updates additionally require `manage_secrets`
LLM provider debug	`/api/config/llm-providers/debug`	`manage_secrets`
LLM model assignments	`/api/config/models/main/assignments`, `/api/config/models/main/assignments/{provider}`, `/api/config/models/main/models/{provider}`, `/api/config/models/main/defaults/{provider}`, `/api/config/models/twin-scanner-tier`, `/api/config/models/embeddings/config`, `/api/config/models/embeddings/models/{provider}`, `/api/config/models/embeddings/stranded-corpora`, `/api/config/models/embeddings/reindexing-status`, `/api/config/models/cache/invalidate`	`GET /api/config/models/main/assignments` and `GET /api/config/models/embeddings/config` accept `access_config_panel` or `view_model_config`; mutating routes and other reads require `access_config_panel`; `GET /api/config/models/twin-scanner-tier` is available to any authenticated caller
Model universe	`/api/config/model-universe/catalog`, `/api/config/model-universe/models`, `/api/config/model-universe/test-model`, `/api/config/model-universe/refresh`	`access_config_panel`
EAI config and assignment	`/api/config/eai/{reference_name}/assigned`, `/api/config/eai/assign`	`access_config_panel`
Provider connection tests	`/api/config/databricks/test-connection`, `/api/config/openai/test-connection`, `/api/config/azure/test-connection`, `/api/config/cortex/test-connection`, `/api/config/bedrock/test-connection`, `/api/config/litellm-proxy/test-connection`, `/api/config/genesis-ai/test-connection`, `/api/config/bedrock/iam-status`	`access_config_panel`
Snowflake context	`/api/config/snowflake/context`	`access_config_panel`
Database connections	`/api/config/db-connections`	`access_config_panel`, `manage_all_connections`, or `view_connections` (any one)
Harvester status and controls	`/api/config/harvester`, `/api/config/harvester/connections/{connection_type}/{connection_name}`	`access_config_panel`
Context Graph admin	`/api/context-graph/logs/twin`, `/api/context-graph/logs/twin/download`, `/api/context-graph/check-permissions`, `/api/context-graph/export`, `/api/context-graph/import`, `/api/context-graph/clear`	`access_config_panel`
Genesis enhancements admin routes	`/api/genesis-enhancements/settings`, `/api/genesis-enhancements/dormant-review/status`, `/api/genesis-enhancements/dormant-review/settings`, `/api/genesis-enhancements/dormant-review/run-once`, `/api/genesis-enhancements/cursor-agent/status`, `/api/genesis-enhancements/reports/{report_id}/cursor-agent/status`, `/api/genesis-enhancements/reports/{report_id}/cursor-agent/start`, `/api/genesis-enhancements/reports/{report_id}/discard`, `/api/genesis-enhancements/export-zip`, `/api/genesis-enhancements/import-status-zip`, `/api/genesis-enhancements/receiver-update`	`access_config_panel` or `manage_genesis_enhancements`
Genesis enhancements dormant-review scheduler controls	`/api/genesis-enhancements/dormant-review/scheduler/start`, `/api/genesis-enhancements/dormant-review/scheduler/stop`	`manage_scheduler`
Genesis enhancements EAI helpers	`/api/genesis-enhancements/eai/assigned`, `/api/genesis-enhancements/eai/assign`	`access_config_panel` or `manage_genesis_enhancements`
Push notification metrics	`/api/push-metrics/summary`, `/api/push-metrics/cleanup`	`access_config_panel`
Secrets, encryption keys, and embedded Tailscale (Native App)	`/api/secrets`, `/api/secrets/{secret_name}`, `/api/secrets/encryption-key/status`, `/api/secrets/encryption-key/enable`, `/api/secrets/encryption-key/backup-sql-objects`, `/api/secrets/encryption-key/verify-setup`, `/api/secrets/tsnet-auth-key/status`, `/api/secrets/tsnet-auth-key/setup`, `/api/secrets/tsnet-auth-key/enable`, `/api/secrets/tsnet-auth-key/verify-setup`, `/api/secrets/tsnet-auth-key/egress`, `/api/secrets/tsnet-auth-key/advertise-tags`, `/api/secrets/tsnet-auth-key/disable`, `/api/secrets/tsnet-auth-key/disable-template`	`manage_secrets`
Secret schema fields	`/api/config/secret-fields/status`, `/api/config/secret-fields/status/{field_path}`, `/api/config/secret-fields/{field_path}/set-value`, `/api/config/secret-fields/{field_path}/set-reference`, `/api/config/secret-fields/{field_path}/use-default`	`manage_secrets`

On PostgreSQL or SQLite metadata deployments, GET /api/config/warehouse/status reports a successful non-Snowflake status with is_snowflake: false, no current warehouse, and an empty available_warehouses list. The application name remains GENESIS_DATA_AGENTS. On those same deployments, the email settings endpoints report and manage the saved default email in the metadata database. GET /api/config/email/status returns that address when configured, with is_validated: false; email sending and test sends are unavailable because they require a Snowflake notification integration. DELETE /api/config/email clears the saved address.

LLM provider delete request fields

The DELETE routes for /api/config/llm-providers/openai, /api/config/llm-providers/cortex, /api/config/llm-providers/databricks, /api/config/llm-providers/litellm-proxy, and /api/config/llm-providers/other accept the same JSON request fields:

Field	Type	Default	Description
`force`	boolean	`false`	Force deletion even when the configuration is active.
`sub_provider`	string or null	`null`	Selects the LiteLLM sub-provider for the `/other` route, for example `anthropic` or `bedrock`.

These request models reject undeclared fields instead of ignoring them. Use sub_provider—not provider—when deleting a LiteLLM sub-provider; an unknown field returns request validation feedback rather than deleting the base provider or reporting that no base configuration exists.

Encryption key endpoints

These routes back the Encryption Key Configuration card on Config → Secrets and related setup flows in Snowflake Native App (SPCS) deployments. All require manage_secrets. The /encryption-key/enable and /encryption-key/verify-setup routes return 400 with "Not running in Native App mode" when SPCS_MODE is not TRUE. First-time setup SQL is shown by the dashboard and generates the key inside Snowflake; no route generates, returns or receives key material.

Method	Path	Description
`GET`	`/api/secrets/encryption-key/status`	Report whether the master encryption key is configured, confirmed missing, or temporarily unavailable, and whether the customer can back it up in Snowsight. No endpoint returns a master key.
`GET`	`/api/secrets/encryption-key/backup-sql-objects`	Names of the secret and external access integration bound to the app, for the Snowsight backup SQL: `{"backup_available", "backup_objects": {"secret", "integration"} or null}`. One Snowflake query (`SYSTEM$GET_ALL_REFERENCES`) when the key is the customer’s Snowflake secret; never resolves key status or the key.
`POST`	`/api/secrets/encryption-key/enable`	Calls `CORE.ENABLE_ENCRYPTION_KEY_ACCESS()` after Native App references are bound.
`GET`	`/api/secrets/encryption-key/verify-setup`	Verifies `GENESIS_SECRETS` exists and the master key secret is readable.

`GET /api/secrets/encryption-key/status` response

Field	Type	Description
`status`	string	`configured`, `missing`, or `unavailable`. Use this field — not `configured` alone — to decide whether encryption is confirmed absent.
`configured`	boolean or null	`true` when `status` is `configured`; `false` when `status` is `missing`; `null` when `status` is `unavailable`.
`source`	string	Where the key was resolved from: `environment` (`GENESIS_MASTER_KEY`), `external` (`GENESIS_MASTER_KEY_REF`), `secret` (Snowflake Native App or Databricks secret), or `none`. A key served from the in-process cache reports the source it was loaded from. A deployment with no key configured, running on the built-in development key, reports `status: "missing"` and `source: "none"`.
`error_category`	string or null	Non-sensitive failure category when `status` is `unavailable` (for example `warehouse_unavailable`, `connector_error`, `permission_denied`, `external_secret_error`, `databricks_secret_error`). Omitted or `null` otherwise.
`backup_available`	boolean	`true` when the key is the customer’s own Snowflake secret (Snowflake Native App, no `GENESIS_MASTER_KEY` or `GENESIS_MASTER_KEY_REF` override), so it can be backed up by running SQL in Snowsight. `false` everywhere else: there the key is supplied by the platform configuration and is backed up there.

When status is unavailable, treat encryption as not confirmed missing — retry after the underlying Snowflake or external-secret outage clears. Older backends may return only configured and source; clients map that to status: "configured" or status: "missing".

`POST /api/secrets/encryption-key/enable` response

Field	Type	Description
`success`	boolean	Whether `CORE.ENABLE_ENCRYPTION_KEY_ACCESS()` reported success.
`message`	string	Procedure result message.

Returns 503 when the database connector is unavailable.

`GET /api/secrets/encryption-key/verify-setup` response

Field	Type	Description
`verified`	boolean	`true` when all checks pass.
`checks`	object	`{ "database_exists": boolean, "secret_readable": boolean }`.
`message`	string or null	Failure guidance when `verified` is `false`.

Embedded Tailscale auth-key endpoints (Native App)

These routes back the Tailscale tab of Config → Secrets in Snowflake Native App (SPCS) deployments. They return 400 with "Not running in Native App mode" when SPCS_MODE is not TRUE. All require manage_secrets. The Tailscale auth key never crosses these APIs — operators paste it into Snowflake SQL locally.

Method	Path	Description
`GET`	`/api/secrets/tsnet-auth-key/status`	Auth-key configuration plus embedded Tailscale runtime status.
`GET`	`/api/secrets/tsnet-auth-key/setup`	Operator-run SQL template for `GENESIS_TSNET.SECRETS.TSNET_AUTH_KEY`.
`POST`	`/api/secrets/tsnet-auth-key/enable`	Calls `CORE.ENABLE_TSNET_ACCESS()` after both Native App references are bound.
`GET`	`/api/secrets/tsnet-auth-key/verify-setup`	Verifies prerequisites (`CORE.GET_TSNET_AUTH_KEY()` resolves).
`GET`	`/api/secrets/tsnet-auth-key/egress`	Returns the embedded-Tailscale egress allow-list (`host_ports`).
`PUT`	`/api/secrets/tsnet-auth-key/egress`	Replaces the egress allow-list; takes effect on the EAI after re-connecting the control-plane reference and suspending/resuming the service.
`GET`	`/api/secrets/tsnet-auth-key/advertise-tags`	Returns the stored Tailscale `--advertise-tags` value (empty when unset).
`PUT`	`/api/secrets/tsnet-auth-key/advertise-tags`	Replaces the stored `--advertise-tags` value; takes effect after suspending/resuming the service (read at container boot).
`POST`	`/api/secrets/tsnet-auth-key/disable`	Calls `CORE.DISABLE_TSNET_ACCESS()` and returns teardown SQL for consumer-owned objects.
`GET`	`/api/secrets/tsnet-auth-key/disable-template`	Returns the operator-run teardown SQL without disabling.

`GET /api/secrets/tsnet-auth-key/status` response

Field	Type	Description
`configured`	boolean	`true` when `CORE.GET_TSNET_AUTH_KEY()` resolves to a non-empty string (proves references are bound; does not return the key).
`enabled`	boolean	`true` when `GENESIS_TSNET_ENABLED=true` and embedded Tailscale was started by `launch.sh`.
`online`	boolean	Tailscale node reports online (meaningful when `enabled` is `true`).
`backend_state`	string or null	Tailscale `BackendState` from `tailscale status --json` when enabled.

When enabled is false, online is false and backend_state is omitted.

`GET /api/secrets/tsnet-auth-key/setup` response

Field	Type	Description
`sql`	string	`CREATE SECRET` template for `GENESIS_TSNET.SECRETS.TSNET_AUTH_KEY` plus inline next-step guidance.

`POST /api/secrets/tsnet-auth-key/enable` response

Field	Type	Description
`success`	boolean	Whether `CORE.ENABLE_TSNET_ACCESS()` reported success.
`message`	string	Procedure result message.
`restart_required`	boolean	Defaults to `true`; set to `true` on success (suspend/resume the service so the container reads the key at boot).

Returns 503 when the database connector is unavailable.

`GET /api/secrets/tsnet-auth-key/verify-setup` response

Field	Type	Description
`verified`	boolean	`true` when all checks pass.
`checks`	object	`{ "auth_key_resolves": boolean }` — `auth_key_resolves` proves both Native App references are bound and the auth-key UDF is readable.
`message`	string or null	Failure guidance when `verified` is `false`.

`GET` / `PUT /api/secrets/tsnet-auth-key/egress`

GET returns the stored egress allow-list read from APP1.TSNET_EGRESS (instance schema). When unset, the response is ["0.0.0.0:443"] — the broad default that permits outbound TCP/443 to any host. PUT accepts a JSON body:

Field	Type	Required	Description
`host_ports`	string[]	Yes	`host:port` entries the embedded-Tailscale EAI may reach (for example `["0.0.0.0:443"]` or enumerated control-plane and DERP hosts).

Validation trims blanks, de-duplicates (order-preserving), requires at least one entry, allows at most 256 entries, and enforces host:port shape (DNS name or IPv4 host, port 1–65535). Returns 400 on invalid input. Both routes return:

Field	Type	Description
`host_ports`	string[]	Saved allow-list after a successful read or write.

The saved list takes effect on the running EAI only after the operator re-connects Tailscale Control Plane External Access in Snowsight, then suspends/resumes the Genesis service.

`GET` / `PUT /api/secrets/tsnet-auth-key/advertise-tags`

GET returns the operator-set Tailscale ACL tag(s) read from APP1.TSNET_ADVERTISE_TAGS (instance schema). When unset or the table is missing, the response is an empty string. The value is folded into CORE.GET_TSNET_BOOT_CONFIG() at container boot (one round-trip with the auth key). PUT accepts a JSON body:

Field	Type	Required	Description
`advertise_tags`	string	Yes	Comma-separated Tailscale ACL tag(s) the SPCS device asserts at boot (for example `tag:genesis-spcs` or `tag:genesis-spcs,tag:prod`). Send an empty string to clear the tag. The field is required so an empty `{}` body cannot accidentally clear the stored value.

Validation trims the input, de-duplicates tags (order-preserving), and rejects blank tokens inside a non-empty list (stray or doubled commas). Each tag must match tag:<name> where <name> is letters, digits, or hyphens (starting alphanumeric). Allows at most 32 tags and a total stored length of 512 characters. Returns 400 on invalid input. Both routes return:

Field	Type	Description
`advertise_tags`	string	Saved tag string after a successful read or write (empty when cleared).

The saved value takes effect on the device only after the operator suspends and resumes the Genesis service (read at container boot via CORE.GET_TSNET_BOOT_CONFIG()). Required for the OAuth-client auth path when the auth key is an OAuth client secret — Tailscale requires --advertise-tags in that case.

`POST /api/secrets/tsnet-auth-key/disable` response

Disables embedded Tailscale for Native App deployment by calling CORE.DISABLE_TSNET_ACCESS() (reverts the auth-key UDF, removes the Tailscale EAI from the running service, unbinds references). The stored egress allow-list is left intact for a later re-enable.

Field	Type	Description
`success`	boolean	Whether the procedure reported a successful disable.
`message`	string	Procedure result message.
`restart_required`	boolean	Defaults to `true`; set to `true` on success (suspend/resume so the container drops the tunnel).
`teardown_sql`	string	Operator-run SQL template to drop consumer-owned objects the app cannot remove (auth-key secret, orphan reference EAIs and network rules).

`GET /api/secrets/tsnet-auth-key/disable-template` response

Field	Type	Description
`sql`	string	Same teardown SQL as `POST .../disable` returns in `teardown_sql`, without calling `CORE.DISABLE_TSNET_ACCESS()`.

External Access Integration (EAI) assignment endpoints

These routes back Assign to Genesis in the Config UI for Snowflake Native App / SPCS deployments. All require access_config_panel.

Method	Path	Description
`GET`	`/api/config/eai/{reference_name}/assigned`	Check whether a Snowflake external-access reference is bound to Genesis.
`POST`	`/api/config/eai/assign`	Persist the EAI binding in `EAI_CONFIG`, call `CORE.UPGRADE_SERVICES()`, then verify the reference on the live `GENESISAPP_SERVICE_SERVICE` service.
`GET`	`/api/config/eai/assign`	Deprecated — use `POST /api/config/eai/assign`.

Genesis stores each binding as its own EAI_CONFIG row keyed by the reference identity (EAI_NAME = reference('<reference_name>')), not by EAI_TYPE. Multiple references can share the same type (for example genesis_external_access and tailscale_external_access both use CUSTOM); assigning one reference updates only that row and does not replace bindings for other references. On startup, Genesis also seeds one EAI_CONFIG row per external-access reference on the running service (splitting Snowflake’s comma-joined external_access_integrations list) so disable/cleanup paths such as CORE.DISABLE_TSNET_ACCESS() can match each reference independently.

`GET /api/config/eai/{reference_name}/assigned` query fields

Field	Type	Default	Description
`nocache`	boolean	`false`	When `true`, bypass the five-minute assignment cache and fail closed if the live Snowflake check does not confirm the binding.

`POST /api/config/eai/assign` request fields

Field	Type	Required	Description
`reference_name`	string	Yes	Snowflake Native App reference identifier (for example `genesis_external_access`, `tailscale_external_access`, `jira_external_access`). Must match `[A-Za-z0-9_]+`.
`eai_type`	string or null	No	Snowflake `EAI_TYPE` value to persist (for example `CUSTOM`, `SERPER`). When omitted, Genesis infers from `reference_name`. Must match `[A-Za-z0-9_]+` when supplied.

Returns success: false with error: "Invalid EAI reference name or type" when reference_name or eai_type contains characters outside letters, digits, or underscore. When reference_name is genesis_external_access, a successful assign may also return refreshed_connection_egress with updated connection egress preflight states. Assignment does not treat a non-throwing CORE.UPGRADE_SERVICES() call as success. That procedure returns Services upgraded successfully even when it attached nothing (for example when the service had no prior external-access list and ALTER SERVICE was skipped). After the upgrade, Genesis reads SHOW SERVICES and confirms the reference is on GENESISAPP_SERVICE_SERVICE (the service CORE.UPGRADE_SERVICES upgrades). The same verification runs on POST /api/genesis-enhancements/eai/assign.

`POST /api/config/eai/assign` response fields

Field	Type	Description
`success`	boolean	`true` only when the live service check confirms the reference is attached, or when the live service check could not run (non-SPCS).
`message`	string	Present when `success` is `true` (for example `EAI assigned to Genesis`).
`error`	string	Present when `success` is `false`. When the live check fails after `EAI_CONFIG` was updated, describes that the reference was recorded but is not on the running service.
`verification`	object	Live service postcondition. See EAI assignment verification object. Always included on assignment responses.
`refreshed_connection_egress`	object	Present when `reference_name` is `genesis_external_access` and assignment succeeded. Updated connection egress preflight states.

EAI assignment verification object

Returned in verification on POST /api/config/eai/assign, and POST /api/genesis-enhancements/eai/assign.

Field	Type	Description
`checked`	boolean	`true` when Genesis successfully read live Snowflake service external-access state via `SHOW SERVICES`. `false` on non-SPCS deployments, connector failure, or when the service map could not be parsed.
`applied`	boolean	`true` when `checked` is `true` and the requested reference identity is an exact element of the target service’s `external_access_integrations` list.
`detail`	string	Diagnostic text (for example the live `external_access_integrations` value for `GENESISAPP_SERVICE_SERVICE`, or why the check could not run).

Callers should treat assignment as failed only when checked is true and applied is false. When checked is false, Genesis does not fail a request that otherwise completed — for example local SQLite has no live service to inspect. The verification object uses exact reference identity matching on GENESISAPP_SERVICE_SERVICE, not the looser substring matching GET /api/config/eai/{reference_name}/assigned may use for status display.

Config setup apply endpoints

These routes validate and apply YAML or JSON configuration through the setup API. All require access_config_panel.

Method	Path	Description
`POST`	`/api/config/setup/validate`	Validate config content without writing.
`POST`	`/api/config/setup/validate-file`	Validate an uploaded config file without writing.
`POST`	`/api/config/setup/apply`	Replace persisted configuration from the request body.
`POST`	`/api/config/setup/apply-partial`	Merge only the supplied paths onto the current database state.
`POST`	`/api/config/setup/apply-file`	Replace persisted configuration from an uploaded file.

`POST /api/config/setup/apply` vs `POST /api/config/setup/apply-partial`

POST /api/config/setup/apply fully replaces persisted configuration: it clears existing APP_CONFIG values, writes only the supplied paths, drops fields not in the schema, and relies on schema defaults at read time for omitted fields. POST /api/config/setup/apply-file uses the same full-replace semantics for uploaded YAML or JSON. Use these routes for profile import and full-environment activation flows. POST /api/config/setup/apply-partial merges the payload on top of the current database state. Only paths present in the body are written; every other field keeps its existing value. Use this for targeted YAML/JSON patches where a full replace would be too destructive. A field’s storage semantics depend on the field’s schema, not on the write door: apply-partial and the Advanced Settings UI both write through the same ConfigApplier, so any given field is persisted identically whichever path sets it. apply-partial rejects connection payloads — manage connections through their dedicated /api/connections API instead.

Shared apply request fields

POST /api/config/setup/apply accepts:

Field	Type	Default	Required	Description
`content`	string	none	Yes	YAML or JSON config content.
`output_format`	string	`"yaml"`	No	Content format: `yaml` or `json`.
`dry_run`	boolean	`false`	No	Preview changes without applying.

POST /api/config/setup/apply-file accepts multipart form field file (YAML or JSON) and optional query parameter dry_run (boolean, default false). It does not accept content or output_format in the body. POST /api/config/setup/apply-partial accepts:

Field	Type	Default	Required	Description
`content`	string	none	Yes	YAML or JSON config content.
`output_format`	`"yaml"` \| `"json"`	`"yaml"`	No	Content format.
`dry_run`	boolean	`false`	No	Preview changes without applying.

Partial apply strips optional metadata keys schema_version, name, and description before validation. The configuration root must be a mapping.

Partial apply restrictions

Schema sections that own a dedicated REST write surface cannot be applied through partial apply. Requests that include connection (nested or dotted keys such as connection.api_key) are rejected with a validation error directing callers to /api/connections instead. This prevents mixed-row storage and bypasses secret-migration and cache-invalidation hooks on the connections API.

Apply response shape

Both apply routes return ConfigApplyResponse with top-level success and a result object containing added, updated, deleted, skipped (integers), changes (array of path, old_value, new_value, action), and errors (string array).

Opaque `dict` schema fields

Schema fields declared with type: dict (currently connection and pricing.model_overrides) are stored as a single JSON blob in one APP_CONFIG row (KEY empty) rather than flattened into dotted path segments. Export, drift, and partial-apply merge operations preserve these dicts as opaque units. Connection changes must still go through /api/connections, not partial apply. Use partial apply or Advanced Settings for pricing.model_overrides updates.

Config sources endpoint

GET /api/config/setup/sources resolves where each configuration value comes from — the effective value and every layer in the priority chain. The Config Profiles Show Sources modal and Advanced Settings per-field source badges call this route. Requires access_config_panel.

Method	Path	Description
`GET`	`/api/config/setup/sources`	Return source information for one path or for all schema fields (optionally filtered by section).

`GET /api/config/setup/sources` query parameters

Parameter	Type	Default	Description
`path`	string	none	Dot-notation config path (for example `server.debug`). When set, returns a single `SingleValueSourceResponse`; `section` is ignored.
`section`	string	none	Top-level schema section prefix (for example `server`). When `path` is omitted, returns source info for every field whose path starts with `{section}.`.

When neither parameter is supplied, Genesis resolves source information for every schema field (~640 paths). This is a database-intensive operation — prefer path or section when calling programmatically.

`GET /api/config/setup/sources` response fields

When path is set, the response is SingleValueSourceResponse:

Field	Type	Description
`success`	boolean	Whether resolution succeeded.
`path`	string	Config path.
`effective_value`	any	Resolved value in use (secret fields may be masked references).
`source`	string	Winning layer: `env_override`, `database`, `db_env_var`, `default_env_var`, `default_plain`, `custom_secret_ref`, or `default_secret_ref`.
`all_sources`	object	Values from every layer; only relevant keys are populated for the field type.

When path is omitted, the response is ConfigSourcesResponse with sources mapping each path to the same ValueSourceInfo shape (path, effective_value, source, all_sources).

Snowflake context endpoint

GET /api/config/snowflake/context backs Snowflake-aware setup helpers in the Config UI, including generated Snowsight approval links and Snowflake endpoint values shown for outbound-access setup.

Method	Path	Description
`GET`	`/api/config/snowflake/context`	Return the current Snowflake org/account context plus the resolved Snowsight base URL and any detected PrivateLink account host.

`GET /api/config/snowflake/context` response fields

Field	Type	Description
`success`	boolean	Whether context resolution succeeded.
`data.organization`	string or null	Current Snowflake organization name.
`data.account`	string or null	Current Snowflake account identifier.
`data.region`	string or null	Current Snowflake region when available.
`data.database`	string or null	Current application database when available.
`data.snowsight_base_url`	string or null	Resolved Snowsight base URL. Public SPCS uses `https://app.snowflake.com`; PrivateLink SPCS returns the matching PrivateLink Snowsight host when detected.
`data.privatelink_account_url`	string or null	PrivateLink Snowflake account host without a scheme when the current deployment is using PrivateLink; otherwise `null`.

Snowflake Native App install status procedure

CORE.GET_INSTALL_STATUS() reports the Native App’s installation or restart progress from Snowflake service state and Genesis startup progress. Call it from a Snowflake worksheet using the installed application’s database name:

CALL <application_database>.CORE.GET_INSTALL_STATUS();

The procedure takes no arguments, returns one row, and is granted to the application’s APP_PUBLIC role. It does not wait for startup. Each call reads Snowflake privilege, reference, compute-pool, service, container, and endpoint state; a failed probe leaves its fields NULL rather than failing the call. Genesis publishes changed startup details to APP1.STARTUP_STATUS every 15 seconds after its metadata connection is available.

`CORE.GET_INSTALL_STATUS()` result fields

Field	Type	Description
`STAGE`	string or null	`NEEDS_GRANTS`, `NEEDS_ACTIVATION`, `POOL_PROVISIONING`, `IMAGE_PULLING`, `INITIALIZING`, `READY`, `DEGRADED`, `FAILED`, or `SUSPENDED`. `DEGRADED` means Genesis is ready with an impairment; `FAILED` and `SUSPENDED` are outside the normal install path.
`STAGE_INDEX`	integer or null	Position in the six-stage install path. `DEGRADED` uses index 6; off-path states have no index.
`STAGE_COUNT`	integer	Number of stages in the normal path: `6`.
`PROGRESS_PCT`	integer or null	Estimated overall progress against the 870-second cold-install baseline; remains below 100 until ready.
`CURRENT_STEP`	string or null	Human-readable detail from Genesis or Snowflake about the current stage.
`STAGE_STARTED_AT`	timestamp or null	Start time for the current stage, when available.
`INSTALL_STARTED_AT`	timestamp or null	Creation time of the current service.
`ETA_SECONDS`	integer or null	Estimated seconds until ready. It is `NULL` while grants or activation are needed and for failed or suspended states; ready and degraded states return `0`.
`MISSING_PRIVILEGES`	string or null	Account privileges the application does not hold.
`UNBOUND_REFERENCES`	string or null	Comma-separated unbound Native App references. Kept for existing callers; `OPTIONAL_UNBOUND_REFERENCES` states that they are optional.
`POOL_STATE`	string or null	Current compute-pool state.
`SERVICE_STATUS`	string or null	Current Genesis service status.
`CONTAINER_STATUS`	string or null	Current service-container status.
`CONTAINER_MESSAGE`	string or null	Snowflake’s current container message.
`RESTART_COUNT`	integer or null	Container restart count, when reported.
`VERSION`	string or null	Genesis version reported for the current container.
`DEGRADED_REASON`	string or null	Genesis degradation detail when the stage is `DEGRADED`.
`LAST_ERROR`	string or null	Most recent Genesis error, or the service/container failure detail when the stage is `FAILED`.
`NEXT_ACTION_SQL`	string or null	Suggested SQL for the reported stage, when an action is available. Activation passes `GRANT_CALLBACK` the four account privileges the app requests: `BIND SERVICE ENDPOINT`, `CREATE COMPUTE POOL`, `CREATE WAREHOUSE` and `CREATE DATABASE`. Review it before running.
`APP_URL`	string or null	Genesis ingress URL when Snowflake reports the endpoint as available.
`OPTIONAL_UNBOUND_REFERENCES`	string or null	Comma-separated unbound references that are optional: none is needed to activate Genesis or reach `READY`. Bind one later in Snowsight, on the app’s page, to turn on that integration (for example Slack or Jira access).
`EVENT_SHARING_ENABLED`	boolean or null	Whether this install shares its logs with Genesis, from Snowflake’s `SYSTEM$IS_APPLICATION_SHARING_EVENTS_WITH_PROVIDER()`: `TRUE` when sharing is on and the account has an active event table, `FALSE` when not, `NULL` when Snowflake could not say. Computed live on every `GET_INSTALL_STATUS` call by running `SELECT SYSTEM$IS_APPLICATION_SHARING_EVENTS_WITH_PROVIDER()`, so each call issues one extra Snowflake query and the value changes as soon as sharing or the event table changes.
`EVENT_SHARING_SQL`	string or null	When `EVENT_SHARING_ENABLED` is `FALSE`, the SQL an account administrator (a role with `MANAGE EVENT SHARING`) runs to share the logs: `ALTER APPLICATION <app> SET AUTHORIZE_TELEMETRY_EVENT_SHARING = TRUE;`. New installs share from the start; this is for installs from before log sharing was required, which an upgrade does not turn on. This SQL only authorizes sharing: logs reach Genesis only when sharing is authorized and the account has an active event table (check with `SHOW PARAMETERS LIKE 'EVENT_TABLE' IN ACCOUNT;`; see Snowflake’s event table setup). Otherwise `NULL`. See Log sharing with Genesis.

The ETA uses cold-install baselines of 270 seconds for pool provisioning, 150 seconds for image pulling, and 450 seconds for Genesis initialization. When Genesis has reported progress for the current container, that progress informs the initialization ETA. These are estimates, not startup time guarantees.

Database connections config endpoint

GET /api/config/db-connections backs the Data tab connection list and other read-only database-connection pickers. Unlike most Config routes, this endpoint accepts any one of access_config_panel, manage_all_connections, or view_connections via require_any_permission.

Method	Path	Description
`GET`	`/api/config/db-connections`	Return database connections visible to the authenticated user. Includes legacy `CUST_DB_CONNECTIONS` rows and, when `SNOWFLAKE_METADATA=TRUE`, the virtual System `Snowflake` connection when it is not already present in the saved-connection list.

`GET /api/config/db-connections` response fields

Each item in data[] includes:

Field	Type	Description
`connection_id`	string	External connection identifier (legacy name or `type.name`).
`db_type`	string	Database connector type.
`owner_bot_id`	string	Legacy `CUST_DB_CONNECTIONS` rows only: the owning bot id (`System` for the virtual native Snowflake row). Empty on a Connections-API record. Read-only.
`allowed_bot_ids`	string[] or null	The agents a legacy `CUST_DB_CONNECTIONS` row admits. Never read `null` as unrestricted — resolve it with `storage` and `sensitive_fields_visible`: `sensitive_fields_visible: false` means the list was withheld from you and may be any restriction; `storage: "connections_api"` means the record carries no such list at all and uses RBAC roles. Only `storage: "legacy"` with `sensitive_fields_visible: true` makes `null` mean the row admits every agent. Read-only.
`allowed_user_ids`	string[] or null	The users a legacy `CUST_DB_CONNECTIONS` row admits. Never read `null` as unrestricted — resolve it with `storage` and `sensitive_fields_visible`: `sensitive_fields_visible: false` means the list was withheld from you and may be any restriction; `storage: "connections_api"` means the record carries no such list at all and uses RBAC roles. Only `storage: "legacy"` with `sensitive_fields_visible: true` makes `null` mean the row admits every user. Read-only.
`description`	string or null	Connection description.
`connection_string`	string or null	Legacy connection string when the caller may view sensitive metadata; embedded credentials are masked while non-secret connection details remain visible. Otherwise `null`; resolve that with `sensitive_fields_visible` too.
`storage`	string	Which store holds the record: `"legacy"` for a `CUST_DB_CONNECTIONS` row, `"connections_api"` for one held by the Connections API. This is what says whether `owner_bot_id`, `allowed_bot_ids` and `allowed_user_ids` apply to the row at all. Always present.
`sensitive_fields_visible`	boolean	Whether this caller may see the record’s sensitive fields. When `false`, `allowed_bot_ids`, `allowed_user_ids` and `connection_string` are withheld and returned as `null` whatever they hold. Always present — it exists so a withholding is never indistinguishable from an absence.
`created_at`	string	Creation timestamp.
`updated_at`	string	Last update timestamp.

The three access fields above are read-only here. They describe legacy CUST_DB_CONNECTIONS rows, where every connection access gate still enforces them; a connection stored by the Connections API carries none of them and controls access with scope and role_names instead — this API’s spelling of the RBAC role grant; roles_with_access is the connections_action spelling and is not an HTTP alias. Sending a deprecated access field back to POST /api/connections, PUT /api/connections/{type}/{name} or connections_action CREATE/UPDATE is refused rather than accepted and dropped. * on an allowlist is the one accepted value, because it restricts nobody — on an HTTP body, and inside connections_action’s locator_json. That exception does not cover a deprecated name passed as a top-level tool parameter: connections_action does not declare those names, so its unknown-parameter guard rejects the call before any of this applies, * included. owner_bot_id has no wildcard: omit it. Sending roles_with_access to either HTTP route is also refused, with 422 — it is the connections_action spelling and not a field of this API, and unknown fields are dropped here, so accepting it would answer success having applied no grant. Sensitive fields (allowed_bot_ids, allowed_user_ids, connection_string) are returned only when the caller has manage_all_connections or owns the connection (owner_user_id match). For the virtual System Snowflake row injected when native Snowflake metadata is enabled, sensitive fields require manage_all_connections.

Microsoft Teams OAuth provider bootstrap endpoints

These routes are mounted under /api/config/oauth_providers/microsoft_teams and back the shared-default UI in Config -> Advanced Settings -> OAuth Providers. They require access_config_panel.

Method	Path	Description
`GET`	`/api/config/oauth_providers/microsoft_teams`	Return the saved Microsoft Teams OAuth provider bootstrap state used as the shared default for `microsoft_teams` connections.
`PUT`	`/api/config/oauth_providers/microsoft_teams`	Create or update the shared Microsoft Teams OAuth provider bootstrap state.

Microsoft Teams OAuth provider fields

Field	Used by	Type	Default	Description
`client_id`	`GET /api/config/oauth_providers/microsoft_teams` response `data.client_id`, `PUT /api/config/oauth_providers/microsoft_teams` body	`string`	`GET: ""; PUT: none`	OAuth client ID.
`authorization_url`	`GET /api/config/oauth_providers/microsoft_teams` response `data.authorization_url`, `PUT /api/config/oauth_providers/microsoft_teams` body	`string`	`GET: https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/authorize; PUT: none`	Authorization endpoint. Genesis resolves `{tenant_id}` from the target connection `tenant_id`.
`token_url`	`GET /api/config/oauth_providers/microsoft_teams` response `data.token_url`, `PUT /api/config/oauth_providers/microsoft_teams` body	`string`	`GET: https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token; PUT: none`	Token endpoint. Genesis resolves `{tenant_id}` from the target connection `tenant_id`.
`scopes`	`GET /api/config/oauth_providers/microsoft_teams` response `data.scopes`, `PUT /api/config/oauth_providers/microsoft_teams` body	`string[]` in responses; `string[] or comma/space-delimited string` in requests	`GET: ChannelMessage.Send, ChatMessage.Send, Chat.ReadWrite, Team.ReadBasic.All, Channel.ReadBasic.All, User.Read.All, offline_access`	Delegated Microsoft Graph scopes. Empty or omitted request values fall back to the default list.
`client_secret`	`PUT /api/config/oauth_providers/microsoft_teams` body	`string or null`	`null`	Optional client secret. Omit it to keep the currently stored secret unchanged.
`guide_base_url`	`GET /api/config/oauth_providers/microsoft_teams` response `data.guide_base_url`, `PUT /api/config/oauth_providers/microsoft_teams` body	`string` in responses; `string or null` in requests	`GET: ""; PUT: null`	Optional base URL used when the setup guide generates redirect URIs. It must include only scheme and host, with no path, query, or fragment.
`guide_connection_name`	`GET /api/config/oauth_providers/microsoft_teams` response `data.guide_connection_name`, `PUT /api/config/oauth_providers/microsoft_teams` body	`string` in responses; `string or null` in requests	`GET: ""; PUT: null`	Optional helper connection name used when the setup guide generates redirect URIs. It must start with a letter and contain only lowercase letters, numbers, or underscores.
`client_secret_is_set`	`GET /api/config/oauth_providers/microsoft_teams` response `data.client_secret_is_set`	`boolean`	`false`	Whether a client secret is already stored. Genesis does not return the plaintext secret.
`configured`	`GET /api/config/oauth_providers/microsoft_teams` response `data.configured`	`boolean`	`false`	Whether provider bootstrap is complete.

License management endpoints

These routes are mounted under /api/license/... and back the Config -> Activation page. They require access_config_panel. In bypass mode, GET /api/license/status can still return activated: true. When no real license is stored, Genesis returns a synthetic placeholder so clients can distinguish bypass mode from a genuinely activated key. When a real license is stored, the same endpoint surfaces the real license details while still reporting spcs_mode and enforcement_disabled.

Method	Path	Description
`GET`	`/api/license/status`	Return current license status for the Activation UI, including bypass flags.
`POST`	`/api/license/activate`	Verify and store a license key.
`POST`	`/api/license/deactivate`	Remove the stored license.
`GET`	`/api/license/check`	Return whether current license rules allow protected operations.

`GET /api/license/status` response fields

Field	Type	Description
`success`	boolean	Whether the request completed successfully.
`activated`	boolean	Whether Genesis reports an active license state. In bypass mode this is also `true` when Genesis is returning a synthetic placeholder because no real key is required.
`spcs_mode`	boolean	Whether the deployment is running in Snowpark Container Services (SPCS).
`enforcement_disabled`	boolean	Whether `LICENSE_ENFORCEMENT_ENABLED` is currently disabled. SPCS bypass is reported separately through `spcs_mode`, so this can be `false` even when bypass is still active in SPCS.
`client_name`	string or null	Real license client name when a stored license exists. In bypass mode with no stored license, Genesis returns one of `SPCS_DEPLOYMENT`, `LICENSE_FREE`, or `BYPASS_MODE`.
`is_trial`	boolean or null	License trial flag. Synthetic bypass placeholders return `false`.
`expiration_date`	string or null	ISO expiration date. Synthetic bypass placeholders return `2099-12-31`.
`days_until_expiration`	integer or null	Days remaining until expiration. Synthetic bypass placeholders use a large positive value.
`is_expired`	boolean or null	Whether the current real license is expired. Synthetic bypass placeholders always return `false`.
`concurrent_agent_slots`	integer or null	Licensed concurrent agent slot count. Synthetic bypass placeholders return `999`.
`enforce_expiration`	boolean or null	Whether expiration blocks access after the license expires. Synthetic bypass placeholders always return `false`.
`enforce_agent_slots`	boolean or null	Whether the concurrent agent slot limit is enforced. Synthetic bypass placeholders always return `false`.

`POST /api/license/activate` request and response fields

Field	Used by	Type	Default	Description
`license_key`	request body	string	none	License key string to activate. Minimum length `10`, maximum length `5000`.
`success`	response body	boolean	none	Whether activation completed successfully.
`message`	response body	string	none	Activation result message.
`activated`	response body	boolean	`false`	Whether the supplied key was verified and stored.
`client_name`	response body	string or null	`null`	Client name from the stored real license.
`expiration_date`	response body	string or null	`null`	ISO expiration date from the stored real license.
`is_expired`	response body	boolean	`false`	Whether the activated real license is already expired.

`POST /api/license/deactivate` response fields

Field	Type	Description
`success`	boolean	Whether the stored license was removed.
`message`	string	Deactivation result message.

`GET /api/license/check` response fields

Field	Type	Description
`allowed`	boolean	Whether protected operations may continue.
`message`	string	Empty string or a warning/error message describing the current license state.
`requires_activation`	boolean	Whether Genesis needs a stored license before proceeding.
`is_expired`	boolean	Whether the current real license is expired.

Jira automation and service-worker endpoints

These routes are mounted under /api/config/jira/.... The base Jira config routes and Jira EAI helpers require access_config_panel. The shared Jira automation and Jira service-worker routes in this section accept either access_config_panel or manage_all_connections, and Genesis exposes them only when Jira automation rollout is enabled. When rollout is off, these automation and service-worker routes return 404 with the disabled-feature message instead of exposing partial setup state. The web client discovers that rollout through GET /api/config/frontend field jira_automation_enabled.

Method	Path	Description
`GET`	`/api/config/jira/automation`	Return the saved Jira webhook and polling automation settings plus the derived `webhook_url`.
`PUT`	`/api/config/jira/automation`	Create or update the webhook and polling automation settings. If the settings are saved but polling Flow synchronization fails, the response reports `success: false` and explains that the settings were saved.
`GET`	`/api/config/jira/automation/options`	Return Jira-backed project, status, and optional assignee suggestions for the saved config or a supplied `jira_connection_id`.
`POST`	`/api/config/jira/automation/poll-now`	Run one manual polling pass against the saved automation settings. When `lookback_minutes` is omitted, Genesis can skip the run if the previous poll started too recently (see Jira automation polling behavior).
`GET`	`/api/config/jira/service-worker`	Return the saved Jira service-worker provisioning settings.
`PUT`	`/api/config/jira/service-worker`	Create or update the Jira service-worker provisioning settings.
`POST`	`/api/config/jira/service-worker/validate`	Validate the configured worker identity and assignment-trigger binding.
`POST`	`/api/config/jira/service-worker/provision`	Provision or invite the worker identity, then bind it to assignment-trigger automation.

Jira automation and service-worker auth fields

Field	Used by	Type	Default	Description
`jira_connection_id`	`PUT /api/config/jira/automation` request body, `GET /api/config/jira/automation` response `data.jira_connection_id`, `GET /api/config/jira/automation/options` query	`string or null` in requests; `string` in the saved response	`null` in the update request; `""` in the saved response	Optional explicit shared Jira connection id such as `jira.shared`. Personal connections are unsupported for automation. When set, Genesis uses that saved connection for automation intake and Jira write-backs. When omitted, automation-managed threads fall back to the Jira service-worker path when a worker token is configured.
`worker_api_token`	`PUT /api/config/jira/service-worker` request body	`string or null`	`null`	Optional Jira token for the dedicated worker identity so Genesis writes back as that worker.
`data.worker_api_token_configured`	`GET /api/config/jira/service-worker` response	`boolean`	`false`	Whether a Jira worker API token is currently saved. Genesis does not return the plaintext token.

Jira automation poll-now request field

Field	Used by	Type	Default	Description
`lookback_minutes`	`POST /api/config/jira/automation/poll-now` request body	`integer or null`	`null`	Optional manual override for how far back to scan Jira changes. When omitted, manual polling respects the saved `poll_interval_seconds` throttle (with a 2-second schedule-drift allowance) and can return a success message stating the request was skipped because the previous poll ran too recently.

Jira automation polling behavior

Scheduled Jira Ticket Poller runs and steady-state poll-now calls (when lookback_minutes is omitted) share the same cursor and throttle rules:

Poll cursor overlap: After the first successful poll, steady-state runs search from last_successful_poll_at minus 600 seconds (10 minutes). Genesis replays this wider window because Jira enhanced search is eventually consistent — a delayed issue can still appear after the successful-poll cursor advances. The first poll and manual poll-now runs with an explicit lookback_minutes use poll_lookback_minutes from the saved config instead.
Poll throttle: When lookback_minutes is omitted on poll-now, Genesis compares the later of last_poll_started_at and poller_last_run_at against poll_interval_seconds. A poll is allowed when elapsed time is at least poll_interval_seconds minus 2 seconds — managed interval Flows can start just before the nominal boundary, and without this allowance sub-second drift would skip every other scheduled poll. Skipped responses include next_poll_seconds with the remaining wait time.
Duplicate-trigger metadata refresh: When an issue still matches the poller but Genesis has already recorded the same trigger fingerprint, the issue is skipped for redispatch. If that issue already has an open Request row in the observation ledger and the Jira summary changed since the stored title, Genesis records a metadata_changed ledger event and updates the Request title without redispatching the bot. When no open Request exists for that issue key, Genesis skips the metadata refresh and does not create ledger activity from summary drift alone.

ServiceNow automation endpoints

These routes are mounted under /api/config/servicenow/... and require access_config_panel or manage_all_connections.

Method	Path	Description
`GET`	`/api/config/servicenow/automation`	Return the saved ServiceNow polling and webhook automation settings plus the derived `webhook_url` and `webhook_secret_configured` flag.
`PUT`	`/api/config/servicenow/automation`	Create or update ServiceNow automation settings and optionally rotate `webhook_secret`.
`GET`	`/api/config/servicenow/automation/options`	Return table/state suggestions and live ServiceNow user assignee hints for the selected connection.
`POST`	`/api/config/servicenow/automation/poll-now`	Run one manual polling pass against the saved automation settings.

ServiceNow webhook endpoint

Method	Path	Description
`POST`	`/api/servicenow/webhook`	Accept a minimal signed poke payload (`table`, `sys_id`). Genesis validates `X-Hub-Signature: sha256=<hmac-hexdigest>` when `webhook_secret` is configured, re-reads the record from ServiceNow, and processes the event asynchronously.

ServiceNow automation request fields

Field	Used by	Type	Default	Description
`enabled`	`PUT /api/config/servicenow/automation`	`boolean`	`false`	Master switch for ServiceNow automation.
`ingestion_mode`	`PUT /api/config/servicenow/automation`	`string`	`polling`	One of `polling`, `webhook`, `hybrid`.
`connection_name`	`PUT /api/config/servicenow/automation`	`string`	`""`	Saved shared ServiceNow connection name (for example `servicenow.prod`). Personal connections are unsupported for automation.
`bot_id`	`PUT /api/config/servicenow/automation`	`string`	`Eve`	Genesis bot that receives triggered records.
`tables`	`PUT /api/config/servicenow/automation`	`array of strings`	`["incident"]`	Tables to monitor.
`record_query`	`PUT /api/config/servicenow/automation`	`string`	`""`	Optional encoded query ANDed into every poll.
`trigger_type`	`PUT /api/config/servicenow/automation`	`string`	`hybrid`	One of `assignment`, `status`, `status_or_assignment`, `comment_keyword`, `hybrid`.
`assigned_to`	`PUT /api/config/servicenow/automation`	`string`	`""`	Genesis worker assignee (`user_name`, sys_id, or display name).
`trigger_on_states`	`PUT /api/config/servicenow/automation`	`array of strings`	`[]`	State values or labels that trigger pickup.
`trigger_on_comment_keywords`	`PUT /api/config/servicenow/automation`	`array of strings`	`["@genesis", "genesis"]`	Keywords matched in new comments and work notes.
`state_on_pickup`	`PUT /api/config/servicenow/automation`	`string`	`""`	Optional state applied on pickup.
`state_on_needs_info`	`PUT /api/config/servicenow/automation`	`string`	`""`	Optional state when the agent needs input.
`state_on_done`	`PUT /api/config/servicenow/automation`	`string`	`""`	Optional state when work finishes.
`writeback_journal_field`	`PUT /api/config/servicenow/automation`	`string`	`work_notes`	`work_notes` or `comments` for automation write-backs.
`poll_interval_seconds`	`PUT /api/config/servicenow/automation`	`integer`	`60`	Polling cadence (30–3600).
`poll_lookback_minutes`	`PUT /api/config/servicenow/automation`, `POST /api/config/servicenow/automation/poll-now`	`integer`	`15` in config; optional on poll-now	Lookback window for polling (1–1440).
`poll_max_results`	`PUT /api/config/servicenow/automation`	`integer`	`50`	Max records per table per poll (1–200).
`webhook_secret`	`PUT /api/config/servicenow/automation`	`string or null`	`null`	Shared HMAC secret (minimum 8 characters when provided). Omitted or empty leaves the existing secret unchanged.

Linear automation endpoints

These routes are mounted under /api/config/linear/... and require access_config_panel or manage_all_connections. Saving automation settings with enabled: true requires a shared Linear api_key connection; personal connections are rejected.

Method	Path	Description
`GET`	`/api/config/linear/automation`	Return the saved Linear polling automation settings plus `feature_enabled`, `gating_reason`, and poll telemetry.
`PUT`	`/api/config/linear/automation`	Create or update Linear automation settings.
`GET`	`/api/config/linear/automation/options`	Return Linear team suggestions for the saved `connection_name`.
`POST`	`/api/config/linear/automation/poll-now`	Run one manual polling pass. Disabled while `feature_enabled` is `false` (the selected coding backend is disabled or cannot run concurrent tickets).

Each dispatched issue attempt is recorded durably with its own orchestration thread and idempotency identity. Re-queuing an issue starts a new attempt rather than reusing a terminal run from an earlier attempt. Coding runs that were dispatched before a process restart are reconciled during startup recovery; a manual poll-now pass handles issue pickup and dispatch, not that startup recovery step.

Linear automation request fields

Field	Used by	Type	Default	Description
`enabled`	`PUT /api/config/linear/automation`	`boolean`	`false`	Master switch for Linear automation.
`poll_interval_seconds`	`PUT /api/config/linear/automation`	`integer`	`60`	Polling cadence (30–3600).
`connection_name`	`PUT /api/config/linear/automation`	`string`	`""`	Saved Linear connection id (for example `linear.shared`). Must be a shared connection when `enabled` is `true`.
`agent_identity`	`PUT /api/config/linear/automation`	`string`	`Eve`	Linear delegate name or ID whose assigned issues are handled across all accessible teams, regardless of status.
`working_state`	`PUT /api/config/linear/automation`	`string`	`Agent-Working`	State applied on claim before dispatch.
`review_state`	`PUT /api/config/linear/automation`	`string`	`HumanReview`	State mapped when work is ready for review.
`needs_info_state`	`PUT /api/config/linear/automation`	`string`	`Clarify`	State mapped when the agent needs input.
`orchestrator_bot_id`	`PUT /api/config/linear/automation`	`string`	`Eve`	Genesis bot that receives the kickoff or resume prompt.

Azure DevOps automation endpoints

These routes are mounted under /api/config/azure-devops/... and require access_config_panel or manage_all_connections. Saving automation settings with enabled: true requires a usable Azure DevOps connection and project.

Method	Path	Description
`GET`	`/api/config/azure-devops/automation`	Return the saved Azure Boards assignment-intake settings plus poll telemetry (`run_as_configured`, `last_poll_started_at`, `last_successful_poll_at`, `last_poll_error`). Does not return `run_as_user_id`.
`PUT`	`/api/config/azure-devops/automation`	Create or update Azure DevOps assignment-intake settings. When `enabled` is `true`, records the saving user as the automation owner (`run_as_user_id`). Background polls use that identity for connection secret resolution, orchestrator thread ownership, and kickoff message dispatch.
`POST`	`/api/config/azure-devops/automation/poll-now`	Run one manual assignment polling pass. Returns `matched_work_item_ids`, `dispatched_work_item_ids`, `skipped_work_item_ids`, and `failed_work_item_ids`.

Azure DevOps automation request fields

Field	Used by	Type	Default	Description
`enabled`	`PUT /api/config/azure-devops/automation`	`boolean`	`false`	Master switch for Azure DevOps assignment intake.
`poll_interval_seconds`	`PUT /api/config/azure-devops/automation`	`integer`	`60`	Polling cadence (30–3600).
`connection_name`	`PUT /api/config/azure-devops/automation`	`string`	`""`	Saved Azure DevOps connection id (for example `azure_devops.shared`). Required when `enabled` is `true`.
`project`	`PUT /api/config/azure-devops/automation`	`string`	`""`	Azure DevOps project whose assigned work items are polled. Required when `enabled` is `true`.
`orchestrator_bot_id`	`PUT /api/config/azure-devops/automation`	`string`	`Eve`	Genesis bot that receives the kickoff prompt.

run_as_user_id is not a request field. When enabled is true, Genesis persists it from the authenticated caller and clears it when automation is disabled. Scheduled polls and poll-now pass that stored owner into connection resolution, orchestrator thread ownership (create new stable threads with user_id / user_email, or reassign existing azure-devops-<connection>-<work-item-id> threads to the stored owner and synchronize thread metadata), and kickoff send_message (user_context). The GET response exposes only run_as_configured (whether an owner is recorded).

Azure DevOps automation poll-now response fields

Field	Type	Description
`success`	`boolean`	Whether the poll completed without a top-level error.
`message`	`string`	Human-readable result or error summary.
`matched_work_item_ids`	`integer[]`	Non-terminal work items assigned to the connection identity that were candidates this pass.
`dispatched_work_item_ids`	`integer[]`	Work items for which Genesis claimed assignment and dispatched a new kickoff this pass.
`skipped_work_item_ids`	`integer[]`	Work items skipped (terminal state or already claimed).
`failed_work_item_ids`	`integer[]`	Work items whose dispatch failed.

Ticket automation endpoints

Read-only routes backing the Requests page Activity view and the Config → Request sources Health panel. They aggregate the observation ledger and per-provider configuration. Routes are sync def handlers (FastAPI runs them on the thread pool).

Method	Path	Description
`GET`	`/api/ticket-automation/activity`	List work items (one row per external ticket, agent-managed Azure DevOps work item, or promoted chat conversation), newest first. Supports repeatable `provider` (`jira`, `linear`, `servicenow`, `azure_devops`, `slack`, or `teams`) and `state` query parameters; repeating either matches any of the supplied values. Also supports repeated `thread_id` values, `limit` (1–200, default `50`), and `offset` (default `0`). At most 200 `thread_id` values may be supplied; the filter keeps only items linked to those agent threads.
`GET`	`/api/ticket-automation/activity/{work_item_id}`	Return one work item with its full event timeline.
`GET`	`/api/ticket-automation/health`	Per-provider source health with an ordered diagnosis checklist. Always includes Jira, Linear, ServiceNow, Azure DevOps, Slack, and Teams. Polled ticket providers report automation configuration and poller freshness; Azure DevOps polls non-terminal work items assigned to its connection identity and dispatches them to the configured Genesis agent. Slack and Teams report workspace connectivity (`configured` from the agent roster, plus `teams.enabled` for Teams) and chat intake mode (`intake`: `automatic` when `ticket_automation.auto_track_chat_requests` is enabled, otherwise `manual promotion`).

When the ledger store is unreachable, activity and health responses set ledger_degraded: true with ledger_degraded_reason instead of returning HTTP 500. Event detail objects are redacted to an operational allowlist (no prompt text or customer content). Timeline kind values include detected, claimed, claim_failed, dispatched, resumed, suppressed_duplicate, status_changed, metadata_changed, writeback, error, promoted, and follow_up. A metadata_changed event means provider-side metadata (for Jira polling, the issue summary) changed on an already-tracked open Request; Genesis does not emit it when the open-work-item lookup is empty. For Jira polling, a status_changed event is also emitted when the provider status is unchanged but its configured lifecycle mapping differs from the ledger. Its summary identifies the provider status as remapped and includes the mapped lifecycle state when one exists, allowing a newly configured terminal mapping to close an item that already recorded that provider status. For Slack and Teams health entries, intake is automatic or manual promotion according to ticket_automation.auto_track_chat_requests (defaults to true). The intake checklist step is labeled Automatic chat intake or Manual chat promotion with matching detail text. For Azure DevOps (provider: azure_devops) health entries, intake is polling. Checks report whether assignment automation is Enabled, whether its connection, project, and owner are Configured, and whether a Recent poll completed. A poller that has not completed within its freshness window is reported as stale. source_key is {organization}/{project} (lowercased). Activity rows use the same provider, source_key, and external_key (the Azure DevOps work item id) identity.

SCIM admin configuration endpoints

These routes back inbound SCIM setup in the Genesis Config panel and require access_config_panel. In a Databricks App, every route in this admin group and every /scim/v2 provisioning route returns HTTP 501 with error_type: "not_available_here" for the admin API, or a SCIM error response with status "501" for the provisioning API. The response detail explains that users and groups come from Databricks SSO and recommends managing access with Databricks groups and Genesis roles. An identity provider cannot reach SCIM through the App’s sign-in flow. GENESIS_SCIM_REQUIRE_PROVISIONED_USERS is ignored in a Databricks App, including for SCIM-deactivated users in a migrated metadata database; sign-in eligibility comes from the App’s CAN_USE permission. If the variable is set, startup logs one warning that it is ignored.

Method	Path	Description
`GET`	`/api/config/scim/config`	Return the current SCIM tenant summary, effective group-role mapping, token state, and admission mode.
`POST`	`/api/config/scim/tokens/rotate`	Create a new persisted SCIM bearer token and return it once.
`POST`	`/api/config/scim/tokens/revoke`	Revoke persisted SCIM bearer tokens for the current tenant.
`PUT`	`/api/config/scim/group-role-mapping`	Replace the persisted SCIM group-to-role mapping for the current tenant.

Okta directory sync settings endpoint

PUT /api/config/scim/okta-sync/settings requires the MANAGE_USERS permission. It saves the Okta connection settings and returns the refreshed directory sync status. Omit private_key to keep the stored key; the key itself is never returned.

Field	In	Type	Default	Required	Description
`org_url`	body	string (max 500 characters)	none	Yes	Okta org base URL, such as `https://example.okta.com`.
`client_id`	body	string (max 200 characters)	none	Yes	Client ID of the Okta API service app.
`app_id`	body	string (max 200 characters)	none	Yes	ID of the Genesis app in Okta whose assigned users are provisioned.
`key_id`	body	string (max 200 characters)	`""`	No	Key ID of the service app’s public key, when it has several.
`private_key`	body	string or null (max 20,000 characters)	`null`	No	Service app PEM private key. Whitespace and line breaks are accepted; omit it to keep the stored key.

The response data contains the refreshed status, including these connection fields:

Field	Type	Description
`org_url`	string	Okta org base URL.
`client_id`	string	Client ID of the Okta API service app.
`app_id`	string	ID of the Genesis app in Okta.
`key_id`	string	Key ID of the service app’s public key.
`private_key_set`	boolean	Whether a private key is stored; the key itself is never returned.

`GET /api/config/scim/config` response fields

Field	Type	Description
`success`	boolean	Whether the request completed successfully.
`data.tenant_id`	string	Effective SCIM tenant identifier.
`data.group_role_mapping`	object	Effective mapping from SCIM group keys to Genesis role names.
`data.persisted_token_count`	integer	Number of active persisted SCIM bearer tokens for the tenant.
`data.env_token_configured`	boolean	Whether `GENESIS_SCIM_BEARER_TOKEN` is configured from the environment.
`data.require_provisioned_users`	boolean	Whether Genesis currently limits sign-in to active SCIM-provisioned users.

SCIM admin mutation fields

Field	Used by	Type	Default	Description
`group_role_mapping`	`PUT /api/config/scim/group-role-mapping` request body	object	none	Required mapping from SCIM group keys to Genesis role names.
`data.tenant_id`	All SCIM admin mutation responses	string	none	Tenant identifier for the affected SCIM config.
`data.token`	`POST /api/config/scim/tokens/rotate` response	string	none	Newly generated SCIM bearer token. Genesis returns it only on rotation.
`data.revoked`	`POST /api/config/scim/tokens/revoke` response	boolean	none	`true` after persisted tokens are deactivated.
`data.group_role_mapping`	`PUT /api/config/scim/group-role-mapping` response	object	none	Normalized mapping saved for the tenant.

Slack configuration and runtime endpoints

These routes are mounted under /api/slack/... and back the Slack Integration admin flow, saved-token connection testing, per-bot deployment status, and live Socket Mode diagnostics. Except for the OAuth callback at /api/slack/oauth/callback, the admin routes in this section require access_config_panel.

Method	Path	Description
`GET`	`/api/slack/status`	Return instance-wide Slack integration status, including whether tokens are configured.
`POST`	`/api/slack/test`	Test either the supplied Slack access token or the currently saved token.
`GET`	`/api/slack/bot/{bot_id}/status`	Return Slack deployment status for a specific bot.
`GET`	`/api/slack/bot/{bot_id}/runtime`	Return live Socket Mode diagnostics for a specific bot, including runtime health and queue signals.
`POST`	`/api/slack/bot/{bot_id}/reconnect`	Force a targeted reconnect of a bot’s live Slack Socket Mode session.

Slack path and request fields

Field	In	Type	Default	Required	Description
`bot_id`	path	string	none	Yes	Bot identifier used by the `/api/slack/bot/{bot_id}/...` routes.
`oauth_token`	body	string or null	`null`	No	Optional Slack Access Token (`xoxe.xoxp-...`) to test directly with `POST /api/slack/test`. When omitted, Genesis tests the currently saved token.
`reason`	query	string or null	`null`	No	Optional operator note for `POST /api/slack/bot/{bot_id}/reconnect`. When omitted or blank, Genesis uses `manual_api_reconnect`.

`POST /api/slack/test` response fields

Field	Type	Description
`success`	boolean	Whether the request completed successfully.
`is_valid`	boolean	Whether the Slack connection test passed.
`message`	string	Human-readable connection test result.
`error_details`	string or null	Error detail text when the test fails.

`GET /api/slack/bot/{bot_id}/runtime` response fields

If no live adapter exists for the bot, the route returns success: true, has_adapter: false, and a message indicating that the session may not be running. When diagnostic collection fails unexpectedly, the route returns success: false with message and error.

Field	Type	Description
`success`	boolean	Whether the diagnostics request completed successfully.
`bot_id`	string	Bot identifier that was inspected.
`has_adapter`	boolean	Whether a live Slack adapter was found for the bot.
`adapter_type`	string	Live adapter class name when `has_adapter` is `true`.
`is_subprocess_proxy`	boolean	Whether the bot is using the subprocess-backed Slack proxy runtime.
`socket_mode_enabled`	boolean	Whether Socket Mode is enabled for the live runtime.
`socket_thread_alive`	boolean or null	Whether the Socket Mode worker thread is alive.
`socket_watchdog_thread_alive`	boolean or null	Whether the Socket Mode watchdog thread is alive.
`socket_connected_at`	string or null	ISO timestamp for the current Socket Mode connection.
`socket_last_error`	string or null	Most recent socket/runtime error recorded by the adapter.
`socket_last_event_at`	string or null	ISO timestamp for the most recent inbound Slack event.
`socket_last_reconnect_at`	string or null	ISO timestamp for the most recent reconnect.
`socket_last_reconnect_reason`	string or null	Reason recorded for the most recent reconnect.
`socket_reconnect_count`	integer	Count of reconnects recorded by the live runtime.
`events_queue_len`	integer or null	Aggregate pending event queue length.
`proxy_inbound_queue_len`	integer or null	Pending inbound proxy queue length when the subprocess proxy is used.
`worker_events_queue_len`	integer or null	Pending worker event queue length.
`worker_last_enqueued_at`	string or null	ISO timestamp when the worker last enqueued an event.
`worker_last_enqueued_event_ts`	string or null	Slack event timestamp of the last enqueued worker event.
`worker_last_forwarded_at`	string or null	ISO timestamp when an event was last forwarded from the worker.
`worker_last_forward_error`	string or null	Most recent error while forwarding a worker event.
`worker_last_drain_error`	string or null	Most recent error while draining worker events.
`socket_last_signal_at`	string or null	Most recent ISO timestamp across socket input, worker enqueue, or worker forward signals.
`socket_connected_age_seconds`	float or null	Age in seconds since `socket_connected_at`.
`socket_last_event_age_seconds`	float or null	Age in seconds since `socket_last_event_at`.
`worker_last_enqueued_age_seconds`	float or null	Age in seconds since `worker_last_enqueued_at`.
`worker_last_forwarded_age_seconds`	float or null	Age in seconds since `worker_last_forwarded_at`.
`socket_last_signal_age_seconds`	float or null	Age in seconds since `socket_last_signal_at`.
`health.status`	string	Runtime health classification: `healthy`, `warning`, or `reconnect_recommended`.
`health.warnings`	string[]	Warning codes derived from backlog, thread state, or recorded errors.
`health.should_reconnect`	boolean	Whether Genesis currently recommends a targeted reconnect.
`health.reconnect_reason`	string or null	Reconnect reason Genesis would use when `health.should_reconnect` is `true`.
`health.stale_reconnect_seconds`	integer	Staleness threshold loaded from `GENESIS_SLACK_STALE_RECONNECT_SECONDS`.
`health.min_reconnect_gap_seconds`	integer	Reconnect rate-limit threshold loaded from `GENESIS_SLACK_MIN_RECONNECT_GAP_SECONDS`.

`POST /api/slack/bot/{bot_id}/reconnect`

When the reconnect request succeeds, Genesis returns success, bot_id, the normalized requested_reason, a low-level result object from the adapter, and a fresh runtime snapshot. If no live adapter exists, the route returns 404. If targeted reconnect is unsupported or the reconnect does not complete successfully, the route returns 400.

Field	Type	Description
`success`	boolean	Whether the reconnect request completed successfully.
`bot_id`	string	Bot identifier that was reconnected.
`requested_reason`	string	Final reconnect reason used after blank/null normalization.
`result.ok`	boolean	Whether the adapter reported the reconnect as active/connected.
`result.reason`	string	Reason string echoed back by the live adapter.
`result.socket_connected_at`	string or null	ISO timestamp for the active Socket Mode connection after reconnect.
`result.socket_last_error`	string or null	Most recent socket/runtime error after reconnect.
`result.socket_last_reconnect_at`	string or null	ISO timestamp for the reconnect that just ran.
`result.socket_last_reconnect_reason`	string or null	Reconnect reason stored by the adapter after reconnect.
`result.socket_reconnect_count`	integer	Total reconnect count recorded by the live adapter.
`runtime`	object	Fresh runtime diagnostics payload in the same shape returned by `GET /api/slack/bot/{bot_id}/runtime`.

Microsoft Teams Bot Framework endpoints

These routes back the Bot Framework messaging surface, per-bot credential management in Agents → [bot] → Teams, and optional ingress diagnostics. POST /api/teams/messages/{bot_id} and GET /api/teams/health are public — Genesis validates the Microsoft-signed Bot Framework JWT inside the adapter (or accepts a relay-forwarded JWT in X-Teams-Bot-Authorization only after the configured relay Snowflake identity passes confinement). Per-bot credential routes require manage_agents; the confined relay identity is denied every credential path.

Method	Path	Description
`GET`	`/api/teams/health`	Liveness probe; returns `status` and `registered_bots` (count of bots whose Teams adapter is registered).
`POST`	`/api/teams/messages/{bot_id}`	Receive a Bot Framework activity for `bot_id`. Returns `202 Accepted` for normal activities; Adaptive Card `invoke` activities return JSON with the invoke status.
`GET`, `POST`	`/api/teams/ingress-canary`	Return a value-redacted characterization of headers reaching FastAPI. Available only when `teams.ingress_canary_enabled` is `true`; otherwise `404`.
`GET`	`/api/teams/bot/{bot_id}/credentials`	Read a bot’s Teams credentials (never the client secret).
`POST`	`/api/teams/bot/{bot_id}/credentials`	Save a bot’s Teams credentials. A blank or omitted password preserves the stored secret.
`GET`	`/api/teams/bot/{bot_id}/runtime`	Report whether this bot’s Teams adapter is registered right now, whether Teams is enabled server-wide, and whether inbound activities are actually accepted. Distinguishes configured (credentials saved) from working (adapter live and kill-switch off). Mirrors `GET /api/slack/bot/{bot_id}/runtime`.
`GET`	`/api/teams/bot/{bot_id}/app-package`	Download the per-bot Teams app `.zip` for sideload in Teams Admin Center.

Microsoft Teams path and request fields

Field	In	Type	Default	Required	Description
`bot_id`	path	string	none	Yes	Case-sensitive Genesis bot identifier (`Eve`, not `eve`).
`teams_app_id`	body	string	none	Yes on `POST /api/teams/bot/{bot_id}/credentials`	Azure AD / Bot Framework application (client) ID.
`teams_app_password`	body	string or null	`null`	No	Bot Framework client secret. Omit or leave blank to keep the stored secret.
`teams_app_tenant_id`	body	string or null	`null`	No	Azure AD tenant ID (required for `SingleTenant` apps).
`teams_app_type`	body	string	`SingleTenant`	No	`SingleTenant` or `MultiTenant`.
`teams_active`	body	boolean	none	Yes on `POST /api/teams/bot/{bot_id}/credentials`	Whether the Teams adapter should be active for this bot.
`Authorization`	header	string	none	No on webhook	Microsoft-signed Bot Framework JWT on direct public ingress.
`X-Teams-Bot-Authorization`	header	string	none	No	Bot Framework JWT forwarded by the SPCS inbound relay; accepted only when middleware has authenticated the configured relay identity and confined it to Teams ingress routes.
`X-Canary-Nonce`	header	string or null	`null`	No	Optional nonce echoed in `GET`/`POST /api/teams/ingress-canary` responses.

`GET /api/teams/bot/{bot_id}/credentials` and `POST /api/teams/bot/{bot_id}/credentials` response fields

Field	Type	Description
`success`	boolean	Whether the request completed successfully.
`bot_id`	string	Bot identifier.
`teams_active`	boolean	Whether the Teams adapter is active for this bot.
`teams_app_id`	string or null	Azure AD / Bot Framework application (client) ID.
`teams_app_type`	string or null	`SingleTenant` or `MultiTenant`.
`teams_app_tenant_id`	string or null	Azure AD tenant ID when configured.
`has_password`	boolean	Whether a Bot Framework client secret is stored. Genesis never returns the plaintext secret.

Credential changes take effect on the next bot session reload or Genesis restart.

`GET /api/teams/bot/{bot_id}/runtime` response fields

Saving Teams credentials does not guarantee a live adapter — registration also requires teams_active, the server-wide teams.enabled switch, and a non-empty teams_app_id. This route answers whether the adapter is registered, whether Teams is enabled server-wide, and whether inbound activities are actually accepted. POST /api/teams/messages/{bot_id} refuses inbound traffic when teams.enabled is false even if an adapter is still registered, and when no adapter is registered. Both cases return 404. If the bot’s session has not been created since the server started, decision, reason, detail, and decided_at are null and message explains that no registration decision was recorded yet.

Field	Type	Description
`success`	boolean	Whether the request completed successfully.
`bot_id`	string	Bot identifier.
`adapter_registered`	boolean	Whether a Teams adapter is registered in the live registry right now. Does not by itself mean inbound activities are accepted — see `accepting_inbound`.
`globally_enabled`	boolean	Whether the server-wide `teams.enabled` kill-switch is on. When `false`, inbound activities are refused on the next `POST /api/teams/messages/{bot_id}` even if `adapter_registered` is still `true`.
`accepting_inbound`	boolean	Whether inbound Teams activities for this bot are accepted right now (`adapter_registered` and `globally_enabled`). When `false`, `POST /api/teams/messages/{bot_id}` returns `404`.
`decision`	string or null	Outcome of the last registration pass: `registered`, `skipped`, or `failed`. `null` if this bot’s session has not been created since the server started.
`reason`	string or null	Stable token explaining the decision: `ok`, `bot_teams_inactive`, `globally_disabled`, `missing_app_id`, or `construction_error`. `null` when no decision was recorded.
`detail`	string or null	Human-readable elaboration of `reason`, including the error text when `reason` is `construction_error`.
`decided_at`	string or null	UTC ISO-8601 timestamp of the last registration decision.
`stale`	boolean	`true` when the live adapter registry contradicts the last recorded registration decision — the registry was mutated outside the normal registration transitions.
`message`	string	Operator-facing summary of the current state. When `globally_enabled` is `false` but `adapter_registered` is `true`, notes that inbound activities are already refused and the adapter will be dropped at the next session build. When `stale` is `true`, includes a warning that the registry disagrees with the last decision.

`reason` values and typical `message` text

`reason`	Meaning
`ok`	Teams adapter is registered. Inbound activities are accepted only when `globally_enabled` is also `true` (`accepting_inbound`).
`bot_teams_inactive`	This bot’s `teams_active` flag is not `Y`.
`globally_disabled`	Teams is disabled server-wide (`teams.enabled` is `false`).
`missing_app_id`	The bot is marked `teams_active` but has no `teams_app_id`. Save the bot’s Teams credentials and restart the server.
`construction_error`	Adapter construction failed at startup. See `detail` and the server log.

Genesis never returns the Bot Framework client secret from this route.

`POST /api/teams/messages/{bot_id}` behavior

202 — activity accepted for normal message, conversation-update, or installation-update activities.
200 (or other invoke status) — Adaptive Card invoke activity; response body is the invoke payload.
401 — Bot Framework JWT validation failed.
403 — inbound serviceUrl host is not allowed (see teams.allowed_service_url_hosts in Advanced Settings).
404 — no adapter registered for bot_id, or Teams is disabled server-wide (teams.enabled is false). The error text distinguishes the global kill-switch from an unknown bot.
503 — transient failure reaching Microsoft’s signing metadata (JWKS); Bot Framework may retry.

Google Chat direct-message endpoint

POST /api/google-chat/events/{bot_id} receives Google Chat HTTP endpoint events for a bot. The route is public so Google Chat can deliver events, but Genesis requires a Google-signed Bearer token whose audience matches the configured Google Chat endpoint audience. Genesis accepts only verified Google Chat service tokens, direct messages from human users, and users whose Google Workspace domain ID matches the connection’s allowed domain ID. Other event types, non-DM spaces, and non-human users are ignored.

Method	Path	Description
`POST`	`/api/google-chat/events/{bot_id}`	Receive one Google Chat interaction event for `bot_id`; dispatch accepted direct messages and return either an empty acknowledgement or an interactive response that replaces an approval card.

Field	In	Type	Default	Required	Description
`bot_id`	path	string	none	Yes	Case-sensitive Genesis bot identifier.
`Authorization`	header	string	none	Yes	`Bearer` token issued for the configured endpoint audience.
`type`	body	string	none	Yes for processed events	Google Chat event type. Only `MESSAGE` events are processed.
`space.spaceType`	body	string	none	Yes for processed events	Must be `DIRECT_MESSAGE` (legacy `space.type` value `DM` is also recognized).
`user.domainId`	body	string	none	Yes for processed events	Must match `google_chat_allowed_domain_id`.
`message.name`	body	string	none	Yes for processed events	Google Chat message resource name used for correlation and deduplication.
`message.text`	body	string	none	Yes for processed events	Nonempty message text. The reserved `/new` message starts a new Genesis DM episode.

The endpoint returns an empty acknowledgement for accepted, ignored, or successfully dispatched events that do not require a synchronous card update. Approval-card interactions return a Google Chat update response with actionResponse.type: "UPDATE_MESSAGE" and a replacement cardsV2 entry. The replacement keeps the approval message in the conversation while showing its result. Authentication, validation, missing-adapter, or transient delivery failures are reported by the API service boundary.

`GET`/`POST /api/teams/ingress-canary` response fields

When teams.ingress_canary_enabled is false, the route returns 404. When enabled, the response is value-redacted — header values are summarized by presence, length, and a sha256_prefix only.

Field	Type	Description
`headers`	object	Map of interesting header names to `{present, value_length, sha256_prefix}`. Includes `Authorization`, `X-Teams-Bot-Authorization`, Snowflake ingress headers, and any `Sf-*` headers present.
`total_header_count`	integer	Total headers on the request.
`body_size`	integer	Request body size in bytes.
`content_type`	string	`Content-Type` header value when present.
`nonce`	string or null	Echo of `X-Canary-Nonce` when supplied.

Launchpad endpoints

Launchpad checklist and guided-start endpoints. They are authenticated-only with no RBAC permission gate, so brand-new non-admin users can load their checklist and guided-start cards on first login.

Method	Path	Description
`GET`	`/api/launchpad/checklist`	Return configured checklist items with per-item `completed` flags and `mandatory_complete` for the current user.
`POST`	`/api/launchpad/guide`	Choose the next guided-start card from the answers so far, or return the opening message that hands off into chat.

When launchpad.checklist_enabled is false, the response still succeeds with data.items: [] and data.mandatory_complete: true.

`GET /api/launchpad/checklist` response fields

Field	Type	Description
`success`	boolean	Whether the request completed successfully.
`data.items`	object[]	Configured checklist rows after server-side validation. Malformed or unknown kinds are omitted.
`data.mandatory_complete`	boolean	`true` when every item with `mandatory: true` is completed, when no mandatory items exist, or when the checklist is disabled.

Checklist item fields (`data.items[]`)

Field	Type	Description
`key`	string	Stable identifier from `launchpad.checklist_items` (for example `database`, `first_chat`).
`label`	string	Display label from config (not localized by the API).
`kind`	string	Completion resolver kind: `database_connection`, `git_connection`, `first_thread`, `encryption_key`, or `connection:<type>`.
`mandatory`	boolean	When `true`, the item contributes to `mandatory_complete`.
`completed`	boolean	Derived from backend state for the authenticated user (connection visibility, Bitbucket config, Eve threads, or whether the master encryption key is configured).

Completion rules match the operator table in Advanced Settings — Launchpad setup checklist. The encryption_key item is returned only when the in-app Snowflake setup applies and the user can manage secrets; see RBAC Practical Guide. Connection visibility uses the same predicates as the Connections API (user_can_see_connection).

`POST /api/launchpad/guide`

This authenticated endpoint uses the fast model to select the next card or handoff, and its calls are billed. A response can require a second completion if the model repeats a question already answered. See Cost accounting for its Cost & Usage classification. Requests are rate-limited per user to 20 per minute and 6 per 10 seconds. Request body:

Field	Type	Default	Description
`answers`	object[]	—	Required; `1`–`8` entries containing `question` (string, `1`–`300` characters) and `answer` (string array, at most `12` labels; empty when skipped).
`asked_steps`	integer	`0`	Number of model-chosen questions already answered (`0`–`8`). The guide hands off after two adaptive questions.
`agent_name`	string	`"Eve"`	Agent name used in the handoff (`1`–`64` characters).
`goal`	string	`""`	Selected Launchpad journey, up to `200` characters; empty for first-run guidance.
`opening_hint`	string	`""`	Classic journey’s chat opening, up to `2,000` characters; its instructions are retained in the handoff.

The response uses the standard {success, data} envelope.

Field	Type	Description
`data.type`	string	`question` or `handoff`.
`data.narration`	string	Short line about the latest answer; empty when none is returned.
`data.question`	object or null	Present for `question`; null for `handoff`.
`data.opening_message`	string	Empty for `question`; chat opening for `handoff`.

For a question, data.question contains id (string), text (string), multi_select (boolean, default false), and options (two to six option objects). Each option has id (string), label (string), and description (string, default ""). GET /api/config/cli-login returns the narrow, unauthenticated OAuth bootstrap contract used by genesis login for its loopback+PKCE browser flow. It returns only IdP coordinates and authentication state; it does not assemble the broader frontend runtime configuration.

Method	Path	Description	Auth behavior
`GET`	`/api/config/cli-login`	Return OAuth bootstrap fields for the terminal CLI login.	Public; the caller is obtaining its first credential.

Field	Type	Default	Description
`success`	boolean	`true`	Whether the bootstrap response was produced.
`auth_enabled`	boolean	`false`	Whether authentication is enabled for the deployment.
`auth_provider`	string	`"none"`	Authentication provider identifier such as `auth0`, `oidc`, or `none`.
`auth0_domain`	string	`""`	Auth0 domain from `AUTH0_DOMAIN`, or the hostname derived from `auth.issuer` when the environment variable is unset.
`auth0_client_id`	string	`""`	Browser OAuth client ID from `auth.client_id`.
`cli_client_id`	string	`""`	Native/public OAuth client ID from `auth.cli_client_id`; when empty, the CLI falls back to `auth.client_id`.
`auth0_audience`	string	`""`	OAuth audience from `auth.audience`.
`oidc_authority`	string	`""`	OIDC issuer from `auth.issuer`.
`oidc_scope`	string	`""`	OIDC scope from `auth.scope`.

Frontend bootstrap config

GET /api/config/frontend is the lightweight bootstrap contract the web client uses for auth-safe runtime flags and chat UI limits.

Method	Path	Description
`GET`	`/api/config/frontend`	Return frontend runtime configuration including auth bootstrap fields, feature flags, and chat composer limits.

`GET /api/config/frontend` response fields

Field	Type	Default	Description
`auth0_domain`	string	`""`	Auth bootstrap domain for the web client. When `AUTH0_DOMAIN` is set in the environment, that value is returned. Otherwise Genesis derives the domain from `auth.issuer` (stripping the `https://` or `http://` prefix).
`supports_logout`	boolean	`false`	Whether the web client should expose Sign out. `true` when authentication is enabled and the provider supports logout or a proxy sign-out URL is configured.
`proxy_sign_out_url`	string	`""`	Resolved sign-out URL when authentication is enabled and `auth_provider` is `proxy`; empty otherwise or when the configured URL is rejected. When non-empty, the web client’s Sign out action navigates the browser here to end the proxy session.
`additional_logins`	array of objects	`[]`	Additional browser sign-in options from `auth.additional_issuers`. Each object has string fields `id`, `label`, `authority`, `client_id`, and `scope`. `label` falls back to the entry name, and `scope` is empty when `login_scope` is unset. Returned only when authentication is enabled and `auth_provider` is `auth0` or `oidc`; entries without `issuer`, `login_client_id`, or `jwks_url` are omitted. This affects browser sign-in only; CLI and MCP OAuth continue using the primary IdP.
`cli_client_id`	string	`""`	Native/public OAuth client ID for the terminal CLI login. Read from `auth.cli_client_id`; when empty, Genesis returns `auth.client_id` so the CLI can reuse the browser client.
`coding_agents_available`	boolean	`true`	Whether coding-agent panels are supported by this deployment. `false` on Genesis Desktop, where Genesis starts no coding agents. The startup-fallback response defaults to `true`.
`is_databricks_app`	boolean	`false`	Whether the server process runs as a Databricks App (`DATABRICKS_APP_NAME` is non-empty). Available in both the normal and startup-fallback bootstrap responses, before the remaining frontend config is ready.
`show_wiki`	boolean	`true`	Controls whether wiki UI is exposed in the web client, including the standalone Wiki workspace and the Digital Twin node detail panel wiki tab. Derived from `WIKI_ENABLED`; Genesis lowercases the value and treats `true`, `1`, and `yes` as enabled.
`show_estate`	boolean	`true`	Controls whether the web client exposes the top-level Estate (Prover) workspace for source-contract characterization. Read from AppConfig `features.show_estate` (schema default `true`). On by default — no environment variable is needed. To hide it, set `features.show_estate` to `false` through the config API, or `GENESIS__FEATURES__SHOW_ESTATE=false` to force it off and gray out the Advanced Settings toggle. Hiding it removes navigation only; the estate routes stay reachable for a permitted caller.
`show_action_review`	boolean	`true`	Controls whether the web client exposes Action Review: its navigation entries, its default-homepage option, and the `/action-review` page. Read from AppConfig `features.show_action_review` (schema default `true`). On by default; set it to `false` to hide the web surfaces. In-chat approval cards and the Action Review API are not gated by this field.
`show_work`	boolean	`true`	Controls whether the web client exposes the Work center and permits direct navigation to `/work/`. The Work center is on by default and contains Missions as a tab. Set `GENESIS_SHOW_WORK=false` to turn it off and give Missions its own sidebar entry. `TRUE`, `1`, `YES`, and `ON` enable it.
`unified_chrome`	boolean	`true`	Controls whether the web dashboard uses Genesis Desktop-style chrome. Read from AppConfig `features.unified_chrome` (schema default `true`); details and configuration are in Advanced Settings — Web dashboard chrome. The desktop app uses its own chrome.
`wiki_write_enabled`	boolean	`false`	Controls whether Team Wiki learning authoring controls are exposed in the web client. Read from AppConfig `wiki.write_enabled` (schema default `false`). On upgrade, truthy legacy `WIKI_WRITE_ENABLED` is migrated into AppConfig once when that path is unset.
`use_internal_docs`	boolean	`true`	Controls where in-app documentation links (for example Help, changelog links) open. When `true`, links open the locally served offline export at `/client-docs`. When `false`, links open the hosted docs at `docs.genesiscomputing.com` directly. Read from AppConfig `docs.use_internal_docs` (schema default `true`). Override or lock at runtime with `GENESIS__DOCS__USE_INTERNAL_DOCS`. The packaged offline export remains available at `/client-docs` regardless of this flag.
`software_factory_enabled`	boolean	`false`	Controls whether the web client exposes the Software Factory page in the main navigation. Derived from the enabled flag of the backend named by `genesis_enhancements.coding_agent.backend`, and from no other backend’s flag: `genesis_enhancements.cursor_agent.enabled` for Cursor (which honors `CURSOR_AGENT_TICKET_ENABLED` when unset), otherwise `genesis_enhancements.coding_agent.<backend>.enabled`. A backend name the server does not recognise reads as `false`. When `false`, the web client redirects direct visits away from the Software Factory route instead of rendering it.
`jira_automation_enabled`	boolean	`true`	Controls whether the web client exposes shared Jira automation and Jira service-worker setup flows. Derived from `GENESIS_ENABLE_JIRA_AUTOMATION`, `GENESIS_JIRA_AUTOMATION_ENABLED`, or `ENABLE_JIRA_AUTOMATION`; unset values default to enabled, while falsey values such as `false`, `0`, `no`, or `off` hide the shared Jira setup tabs and related automation calls.
`agent_gateways_enabled`	boolean	`false`	Whether the experimental A2A and Naylence gateway routes and services are enabled. Derived from `GENESIS_ENABLE_AGENT_GATEWAYS`, and forced to `false` in a Databricks App. This flag does not disable the hosted MCP gateway.
`hosted_mcp_gateway_enabled`	boolean	`true`	Whether the hosted MCP gateway is available. Remains enabled in a Databricks App even though `agent_gateways_enabled` is forced off there.
`cli_terminal_enabled`	boolean	`false`	Whether the Pulse CLI Workspaces surface is offered. Requires `cli_terminal.enabled`; in a Databricks App it is also hidden unless `cli_terminal.runtime` is `kubernetes` (the unset runtime defaults to `docker`).
`presenter_controls_enabled`	boolean	`false`	Controls whether the web client shows staff the Presentation mode toggle and permits presenter-bound Mission starts. Read from AppConfig `features.presenter_controls_enabled` (schema default `false`).
`threads.max_message_size_bytes`	integer	`16384`	Maximum UTF-8 payload size for a chat message. The web client validates the fully expanded outbound message against this limit before sending and shows byte-count feedback when the payload is too large.
`demo_env`	boolean	`false`	Whether the deployment is running in demo mode (`is_demo_mode()`). Mirrors the enabled flag returned by `GET /api/config/demo-mode`.
`is_demo`	boolean	`false`	Same meaning as `demo_env` — whether demo mode is enabled.
`sales_url`	string	`""`	Booking URL from `demo.sales_url` surfaced in budget-exceeded UI and conversion cards.
`token_budget_usd`	float or null	`null`	Aggregate demo cost cap in USD when budget enforcement is active (`demo.token_budget_usd`). `null` when demo mode is off, budget is unlimited, or spend could not be computed.
`aggregate_spent_usd`	float or null	`null`	Instance-wide aggregate LLM spend in USD (four decimal places) when budget enforcement is active. `null` when not applicable.
`blocked`	boolean	`false`	`true` when aggregate spend has reached `token_budget_usd`. The web client polls this field (with jitter, about every 60 seconds) to drive the demo budget bar, warning banner, and block screen without re-querying the full auth config.
`show_client_file_onboarding_journey`	boolean	`false`	Controls whether the web client exposes the Onboard client files Launchpad journey. Read from AppConfig `features.show_client_file_onboarding_journey` (schema default `false`; honors `SHOW_CLIENT_FILE_ONBOARDING_JOURNEY` when unset).
`managed_upgrade_panel`	boolean	`false`	Whether the web client exposes the Upgrades page. See Advanced Settings — Launchpad feature flags for managed-deployment enablement.

Managed upgrades endpoints

The routes are mounted only when the managed deployment enables the panel flag; see Advanced Settings — Launchpad feature flags. For route access requirements, including the human-only write rule, see Genesis Agent Security Controls — Permissions.

Method	Path	Description
`GET`	`/api/managed-upgrades`	Return saved controls and the management agent’s latest state.
`PUT`	`/api/managed-upgrades/controls`	Save the upgrade policy, pause state, maintenance window, optional pull-source repository, and optional customer scan deadline.
`POST`	`/api/managed-upgrades/approval`	Approve the offered release for immediate upgrade or the next maintenance window.
`POST`	`/api/managed-upgrades/scan-verdict`	Record a pass or fail verdict for the offered image digest. A failure requires a reason.

PUT /api/managed-upgrades/controls accepts expected_revision (integer or null for the first save), policy_mode (automatic-in-window, approval-required, approve-then-next-window, or by-version-class), paused (boolean), and window with iso_weekday (1–7), start_local (HH:MM), an IANA timezone, duration_seconds, and maximum_graceful_drain_seconds. It may also include pull_source_repository (an untagged OCI repository or null) and customer_scan (null or an object with result_deadline_seconds, from 1 to 30 days). The GET /api/managed-upgrades response includes agent_reported (false until the agent has pushed state since app startup), settings_rolled_back, agent_state (null or the latest controls_floor_generation, upgrade_state, and running_release), and controls (null or the saved document with its revision, generation, updated_by, and updated_at). A save returns those stored-control fields. Approval returns them under controls plus the approval_id the agent records when it consumes the approval. The approval body contains expected_revision and choice (upgrade-now or next-window). The scan-verdict body contains expected_revision, linux_amd64_digest (sha256: plus 64 lowercase hexadecimal characters), verdict (pass or fail), and optional reason (up to 200 characters; a failure needs a non-empty reason). The reason cannot contain control, format, or surrogate characters. This route returns the saved-control fields. The management agent uses two additional routes, mounted only when the feature flag is on and GENESIS_UPGRADE_CHECK_TOKEN is set. Both require that bearer token; hosted mode refuses /api/internal/ routes.

Method	Path	Description
`GET`	`/api/internal/managed-upgrades/controls`	Return the saved controls document text for the agent to read; `document` is `null` before the first save.
`PUT`	`/api/internal/managed-upgrades/state`	Push the agent’s latest state; returns `204 No Content`.

The agent state body has schema_version: "internal-managed-upgrade-state-v1", controls_floor_generation, upgrade_state, and running_release. The agent pushes its latest state once per cycle; it is held in memory since app startup.

Hosted documentation session

POST /api/docs/session creates the short-lived Mintlify callback URL used when docs.use_internal_docs is false. The route accepts only a relative path in the hosted /docs tree and requires a genuinely authenticated human; delegated, machine, system, Snowflake, and auth-disabled callers are refused. For the configuration, secret-management, and hosted-docs rollout requirements, see Advanced Settings — Documentation settings.

Method	Path	Description	Auth behavior
`POST`	`/api/docs/session`	Return a short-lived authenticated Mintlify callback URL for one hosted-docs path.	Requires an eligible authenticated human and hosted docs mode.

`POST /api/docs/session` request

Field	In	Type	Default	Required	Description
`redirect_path`	body	string	none	Yes	Relative destination under `/docs` (1–2,048 characters), optionally including a query string or fragment. Absolute URLs, protocol-relative URLs, and path traversal are rejected.

Example:

curl -sS -X POST "$GENESIS_URL/api/docs/session" \
  "${AUTH[@]}" -H "Content-Type: application/json" \
  -d '{"redirect_path":"/docs/Setup/Advanced-Settings"}'

`POST /api/docs/session` response

{
  "success": true,
  "url": "https://docs.genesiscomputing.com/login/jwt-callback?redirect=%2Fdocs%2FSetup%2FAdvanced-Settings#<short-lived-jwt>"
}

The url is for immediate browser navigation and contains a ten-second Mintlify login JWT. The resulting hosted documentation session can remain valid for up to one hour. The endpoint returns 400 for an invalid redirect, 403 for an ineligible caller, and 503 when hosted mode or signing-key/session creation is unavailable.

Demo mode status

GET /api/config/demo-mode returns demo-mode status and the limits the web client needs to render budget and concurrency UI. The route is public (no RBAC permission required).

Method	Path	Description
`GET`	`/api/config/demo-mode`	Return whether demo mode is enabled and the configured demo limits.

`GET /api/config/demo-mode` response fields

Field	Type	Default	Description
`success`	boolean	none	Whether the request completed successfully.
`demo_env`	boolean	`false`	Legacy alias for demo-mode enabled state.
`demo_mode`	boolean	`false`	Whether demo mode is enabled. True when `config.demo.enabled` is true or when `DEMO_MODE` / legacy `IS_DEMO` is set to a truthy value in the process environment.
`token_budget_usd`	float or null	`null`	Effective aggregate cost cap in USD across all bots for the lifetime of this demo instance (`demo.token_budget_usd`). `null` means no finite cap in this response; use the internal budget-cap endpoint to change this value on a running instance and inspect the resulting `budget_state`.
`default_model_tier`	string	`"main"`	Default LLM tier when a bot has no explicit override (`demo.default_model_tier`). One of `frontier`, `main`, or `fast`.
`max_cwa_concurrency`	integer	`10`	Cap on concurrent agent slots (CWA) in demo mode (`demo.max_cwa_concurrency`). Genesis clamps the effective slot limit to `min(license/env cap, max_cwa_concurrency)` when demo mode is on and `demo.allow_full_concurrency` is `false`.
`sales_url`	string	`"https://genesiscomputing.ai"`	URL surfaced in budget-exceeded responses and UI (`demo.sales_url`).

Hosted Genesis AI

Hosted Try Me instances configured to use their owner’s Genesis AI credit expose these endpoints for the dashboard’s Genesis AI status, activation, and credit meter. Configuration keys and defaults are in Advanced Settings.

Method	Path	Description
`GET`	`/api/demo/genesis-ai`	Return whether Genesis AI is available on this instance, whether the Genesis-issued key is configured, and whether Genesis AI is the active provider.
`GET`	`/api/demo/genesis-ai/credit`	Return the owner’s shared Genesis AI allowance for the hosted instance’s meter.
`POST`	`/api/demo/genesis-ai/activate`	For the instance owner, fetch and configure a Genesis AI key from the provisioner when needed.

The status response also includes data.genesis_ai_only. It is true on hosted instances using their owner’s Genesis AI plan, even before the key is available or configured. In this mode, other AI providers cannot be configured, selected, tested, or called. On these pot-backed instances, startup removes AI provider configurations and their stored credentials that were baked into the golden image, including LiteLLM proxy, OpenAI, and Bedrock providers. This cleanup is enabled by demo.genesis_ai_from_pot, which defaults to false. The activation endpoint requires the owner’s Authorization: Bearer <access-token>. It returns the same success envelope with data.available, data.configured, and data.active booleans as the status endpoint. A completed activation is idempotent: if the Genesis AI key is already configured and its first issue completed, no provisioner request is made. Otherwise, activation makes one HTTPS request to the provisioner, which mints the owner’s key in five or six LiteLLM calls, then writes the instance’s LLM configuration. The provisioner rate-limits key issuance to 10 requests per minute. Before checking whether a key needs fetching, activation also removes any remaining baked-in providers and reloads the runtime if it removed any. The endpoint returns 404 when this is not a pot-backed hosted instance, 401 when the bearer token is missing, 403 when the caller is not the owner or has not completed the Try Me profile or email verification, and 503 when the provisioner cannot be reached or refuses the instance request, or when a baked-in provider cannot be removed; in that case Genesis AI is not configured. Grants are issued only to the instance’s recorded owner. The credit endpoint reads the same pot shared with the owner’s Genesis Desktop computers. It accepts the optional boolean query parameter fresh, which defaults to false: successful readings are reused for up to three minutes, while fresh=true reuses a reading only while it is younger than 15 seconds. When Genesis AI is not active or the provisioner cannot provide a reading, data.available is false. The response’s data uses the same credit fields as GET /api/desktop/credit. In demo mode, GET /api/demo/user-info-status also reports has_submitted: true for the instance owner when Try Me already collected and pushed the owner’s profile with the owner record, so the in-instance profile prompt is not shown again.

`GET /api/internal/demo-budget/aggregate` (provisioner poll)

Cold-provisioned Try Me instances expose this internal route so the provisioner can read deployment-wide spend vs cap and drive auto-destroy when the budget is exhausted, and read the instance’s latest LLM call and user sign-in to decide when an idle free-tier instance may sleep. It is separate from per-agent RBAC budgets under /api/budgets/....

Method	Path	Description
`GET`	`/api/internal/demo-budget/aggregate`	Return aggregate demo spend vs cap for the instance.
`PUT`	`/api/internal/demo-budget/cap`	Change the instance’s effective demo budget cap without restarting it.

Authentication: Send X-Genesis-Internal-Token with an eligible demo provisioner token (see demo access gate settings) or a valid internal service token. Demo provisioner tokens work only in demo mode and only for /api/internal/* route dependencies; they are not user credentials for other API paths. These routes do not use the Bearer token required by other /api/internal/... flow routes. Response fields:

Field	Type	Description
`total_spent_usd`	number	Known-priced aggregate spend in USD (four decimal places); a lower bound when `unpriced_call_count` is greater than zero.
`capped_at_usd`	number or null	Effective cap in USD. `null` can mean demo enforcement is off, the cap is unlimited, configuration is unavailable, or the cap is misconfigured; use `budget_state` to distinguish these cases.
`blocked`	boolean	`true` when aggregate spend has reached the cap.
`budget_state`	string	Current budget state: `enforced`, `unlimited`, `demo_off`, `unavailable`, or `misconfigured`.
`unpriced_call_count`	integer or null	Calls with no price, excluded from `total_spent_usd` and enforcement. `null` when the count was not measured because the budget was not enforced or its first spend read failed.
`last_llm_call_at`	datetime or null	Latest timestamp recorded for a cost-tracked LLM call. `null` when no call is recorded or the activity read fails.
`last_user_login_at`	datetime or null	Latest sign-in or authenticated request by a non-system user; writes are throttled to at most once per minute per user. `null` when unknown or the activity read fails.

Each poll also performs two activity reads in addition to the budget read. The LLM-call timestamp comes from the metrics service’s LLM_CALLS store and may lag a call by up to one metrics export interval. The user timestamp comes from the users table. An activity-read failure returns null for that field without failing the budget response.

`PUT /api/internal/demo-budget/cap`

Change the effective demo budget cap for the running instance. The change is applied immediately without a process restart; aggregate spend is not read by this operation, and the next budget enforcement refresh uses the new cap. Authentication: Uses the same X-Genesis-Internal-Token authentication as GET /api/internal/demo-budget/aggregate: the header must match demo.instance_auth_token, the eligible legacy demo.internal_auth_token, or a valid internal service token. An Authorization: Bearer token or session cookie is not accepted for this route. Request body:

Field	Type	Required	Description
`token_budget_usd`	number or null	Yes	New aggregate cap in USD. Must be greater than or equal to `0`; `0` causes the next enforcement check to block the budget, while explicit `null` sets the instance to unlimited. The field must be present even when its value is `null`.

Response fields:

Field	Type	Description
`token_budget_usd`	number or null	Effective cap after the runtime change. It can be `null` when enforcement is off, unavailable, unlimited, or misconfigured.
`budget_state`	string	Resulting state: `enforced`, `unlimited`, `demo_off`, `unavailable`, or `misconfigured`.

Example — set a USD 250 cap:

curl -X PUT https://<instance>/api/internal/demo-budget/cap \
  -H 'X-Genesis-Internal-Token: <internal-token>' \
  -H 'Content-Type: application/json' \
  -d '{"token_budget_usd":250}'

Example response:

{
  "token_budget_usd": 250.0,
  "budget_state": "enforced"
}

Provisioner owner and state routes

Hosted Try Me provisioners use these internal endpoints to register an instance owner and export its state. They use the internal-token authentication described above and do not accept a Bearer token or session cookie in its place.

Method	Path	Description
`PUT`	`/api/internal/demo-access/owner`	Record or administratively reassign the instance owner.
`POST`	`/api/internal/demo-state/export-state`	Stream the full-fidelity state tar used by the golden-image pipeline.
`POST`	`/api/internal/demo-state/export-content`	Stream a human-readable export of the instance’s work.
`POST`	`/api/internal/demo-state/export-microapps`	Stream a tar.gz of microapp workspaces.

`PUT /api/internal/demo-access/owner`

The provisioner calls this at claim to record the owner. Repeating the same owner is idempotent. A different existing owner produces 409 unless the request sets force for an administrator reassignment. email must be a non-empty verified owner email; sub is the owner’s Auth0 subject and may be empty for an email-based administrator reassignment.

Field	Type	Required	Default	Description
`sub`	string	No	`""`	Owner’s Auth0 subject.
`email`	string	Yes	—	Non-empty owner email.
`display_name`	string	No	`""`	Informational owner display name.
`profile`	object	No	`{}`	Reserved for company and trial-agreement version/time.
`force`	boolean	No	`false`	Replace a different recorded owner for administrator reassignment.

Example:

curl -X PUT https://<instance>/api/internal/demo-access/owner \
  -H 'X-Genesis-Internal-Token: <internal-token>' \
  -H 'Content-Type: application/json' \
  -d '{"sub":"auth0|user-id","email":"[email protected]","display_name":"Instance owner"}'

Response fields: owner_sub, owner_email, owner_display_name (strings), and changed (boolean). Returns 401 for a missing or invalid internal token, 409 if another owner is recorded and force is false, and 200 on success.

`POST /api/internal/demo-state/export-state`

Streams the same raw, full-fidelity application/x-tar archive documented for POST /api/admin/export-state. It includes Cache-Control: no-store, private and Pragma: no-cache headers. No request body or query parameters are required.

`POST /api/internal/demo-state/export-content`

Streams a human-readable export in the selected format. The artifact is not cached (Cache-Control: no-store, private and Pragma: no-cache).

Query parameter	Type	Required	Default	Description
`format`	string enum	No	`json`	Output format: `json`, `yaml`, `md`, `html`, or `archive` (tar.gz).
`updated_after`	datetime or null	No	`null`	Limit the export to content updated after this timestamp.

`POST /api/internal/demo-state/export-microapps`

Streams a microapp workspace archive as application/gzip with Cache-Control: no-store, private and Pragma: no-cache headers.

Query parameter	Type	Required	Default	Description
`include_venv`	boolean	No	`false`	Include packed microapp virtual environments.
`updated_after`	datetime or null	No	`null`	Limit the export to workspaces updated after this timestamp.

Presenter Controls endpoints

These routes backed the Presenter Controls panel, which is no longer in the web UI, and remain available when features.presenter_controls_enabled is true. They prepare, reset, and clean up Sales Engineering vignettes scoped to one browser-local presenter_session_id and the authenticated caller. All routes require the capability plus Genesis Staff (is_staff) or a valid X-Genesis-Internal-Token. The process-local internal token works on any enabled instance; the shared demo token remains limited to demo mode. Shared request field:

Field	In	Type	Required	Description
`presenter_session_id`	query or body	string	Yes	Browser-local presenter session. Pattern `^presenter-[a-z0-9]{1,20}$` (11–30 characters).

Reusable demo versions (`/api/demo/versions`)

These routes back the Demo version controls in each Presenter Controls scenario card. They list shared ready revisions and the caller’s private drafts, prepare a tailored revision once, create isolated presentation runs, and retain run history. They use the same presenter-operator authorization as the other Presenter Controls routes.

Method	Path	Description
`GET`	`/api/demo/versions`	List shared ready versions and the authenticated presenter’s private drafts.
`POST`	`/api/demo/versions`	Create a private draft from a scenario and industry or prospect context.
`POST`	`/api/demo/versions/{revision_id}/prepare`	Compile and validate a draft. A successful preparation makes it shared and ready; prepared revisions are immutable.
`GET`	`/api/demo/versions/{revision_id}/bundle`	Download the exact immutable synthetic client-file archive for a ready `data_onboarding` revision. Returns `application/zip`, an `ETag`, and `X-Demo-Bundle-Id`.
`POST`	`/api/demo/versions/runs`	Create a fresh isolated presentation run from a ready revision and presenter session.
`POST`	`/api/demo/versions/runs/{run_id}/gold`	Mark one completed run as the recommended example without deleting other runs.
`DELETE`	`/api/demo/versions/{revision_id}/gold`	Clear the recommendation marker while retaining run history.

POST /api/demo/versions body fields:

Field	Type	Required	Description
`scenario`	string	Yes	One of `proactive_pipeline_recovery`, `data_onboarding`, or `ticket_dashboard_rca`.
`industry_context`	string	Yes	Industry or prospect context, 2–240 characters.
`name`	string or null	No	Optional version name, 2–100 characters.

POST /api/demo/versions/runs body fields:

Field	Type	Required	Description
`revision_id`	string	Yes	Ready revision identifier. Pattern `^[a-zA-Z0-9_-]+$`, 3–120 characters.
`presenter_session_id`	string	Yes	Browser-local presenter session.
`run_key`	string or null	No	Optional caller idempotency key, 2–60 characters; pattern `^[a-zA-Z0-9_.-]+$`.

The catalog response exposes each version’s status (draft, validating, ready, or failed), visibility (creator or environment), preview and compiled configuration, optional onboarding bundle metadata, and runs with recommended_gold, latest, and complete history. Presentation runs use prepared, running, completed, failed, or incomplete statuses. When this catalog is listed, Genesis reconciles nonterminal client-file onboarding runs against their durable Mission status before returning the catalog, so a refreshed Presenter Controls view can reflect progress from a run that continued after the original request.

Proactive pipeline recovery (`/api/demo/rca`)

Method	Path	Description
`GET`	`/api/demo/rca/status`	Validate the shared dbt Cloud connection and job and refresh the active external run. Returns current and prior dbt/Slack artifact links; it also provides a delivery fallback if the background monitor is temporarily unavailable.
`POST`	`/api/demo/rca/reset`	Validate and re-arm the configured pipeline fixture. Existing dbt runs, Slack incidents, and investigation threads are preserved. When supplied, `demo_version_revision_id` and `demo_presentation_run_id` bind the reset to one prepared proactive-pipeline version run.
`POST`	`/api/demo/rca/fresh-session`	Release this presenter’s terminal shared-job ownership before the browser adopts a new presenter session ID. For the ticket-dashboard RCA scenario, also make the ticket fixture retryable.
`POST`	`/api/demo/rca/trigger`	Start the real dbt Cloud job with the configured deterministic-failure command overrides and resume Genesis’s dbt monitor. The monitor delivers Slack after dbt reports the failure, even if Presenter Controls is closed.
`POST`	`/api/demo/rca/correct`	Compatibility endpoint. Recovery and verification are performed by Eve in the trusted dbt Cloud Slack investigation.
`POST`	`/api/demo/rca/cleanup`	Compatibility endpoint that preserves external dbt Cloud and Slack artifacts. Presenter Controls intentionally does not expose destructive cleanup for this vignette.

GET /api/demo/rca/status returns data.investigation_thread for the current Slack investigation when the delivered notification includes both a target bot ID and a Slack root message timestamp. The field is null when either value is missing; otherwise it includes the bot ID, the Slack root timestamp as the Genesis thread ID, and a URL-encoded relative href to the investigation chat.

Field	Type	Description
`investigation_thread`	object or null	Current Genesis investigation thread projected from the delivered Slack root. Includes `bot_id`, `thread_id`, and `href` (`/chat/{bot_id}/thread/{thread_id}` with both path segments percent-encoded).

POST /api/demo/rca/reset accepts these optional body fields in addition to presenter_session_id and source_type:

Field	Type	Required	Description
`demo_version_revision_id`	string or null	No	Ready proactive-pipeline revision to use. Supply it together with `demo_presentation_run_id`; pattern `^[a-zA-Z0-9_-]+$`, 3–120 characters.
`demo_presentation_run_id`	string or null	No	Prepared presentation run to use. Supply it together with `demo_version_revision_id`; pattern `^[a-zA-Z0-9_-]+$`, 3–120 characters.

POST /api/demo/rca/fresh-session accepts this body:

Field	Type	Default	Required	Description
`presenter_session_id`	string	—	Yes	Current browser-local presenter session. Pattern `^presenter-[a-z0-9]{1,20}$` (11–30 characters).
`new_presenter_session_id`	string	—	Yes	New browser-local presenter session. Must differ from `presenter_session_id`; use the same pattern and length constraints.
`source_type`	`flow`, `dbt_cloud`, or `matillion`	`dbt_cloud`	No	Presenter pipeline source. Fresh-session release is supported for dbt Cloud; Matillion returns an error, while other non-dbt sources return an empty release result.
`scenario`	`proactive_pipeline_recovery` or `ticket_dashboard_rca`	—	Yes	Presenter card whose ownership should be superseded.
`provider_connection_id`	string or null	`null`	No	Optional dbt Cloud provider connection to use. Pattern `^dbt_cloud\.[a-zA-Z0-9][a-zA-Z0-9_.-]*$` (11–255 characters).

The endpoint releases only the authenticated presenter’s terminal dbt Cloud ownership. The run must no longer be active, its provider status must be a terminal error, Slack failure delivery must be complete, and any recovery run must be terminal. It returns success: true with data containing superseded_scope_ids, incomplete_run_ids, and retryable_fixture_count. For ticket_dashboard_rca, a ticketed dashboard fixture is changed to retryable and its active Jira issue pointer is cleared so the new session can retry preparation; presentation runs affected by the supersession are marked incomplete.

Interactive AUM dashboard (`/api/demo/aum`)

Method	Path	Description
`GET`	`/api/demo/aum/status`	Return readiness for the caller’s scoped AUM scenario (fixture, connection, context scan, and app state).
`POST`	`/api/demo/aum/prepare`	Prepare or reset the scoped AUM scenario (removes any caller-owned app, then rebuilds the canonical SQLite fixture and read-only connection).
`POST`	`/api/demo/aum/cleanup`	Remove the caller’s scoped AUM scenario. Body includes `confirmation` — type `cleanup {connection_id}` using the `connection_id` from status.

Cost optimization (`/api/demo/optimization`)

Method	Path	Description
`GET`	`/api/demo/optimization/status`	Return readiness for the caller’s scoped optimization scenario. Query also requires `connection_id` (fully qualified Snowflake connection id).
`POST`	`/api/demo/optimization/prepare`	Prepare or reset the scoped optimization database on the selected connection. Body includes `connection_id`.
`POST`	`/api/demo/optimization/cleanup`	Drop the marker-proven optimization database. Body includes `connection_id` and `confirmation` — type `cleanup {database_name}` using the `database_name` from status.

Presenter Control Missions (`/api/demo/presenter-missions`)

Tracks exact caller-owned Missions for disposable blueprint vignettes.

Method	Path	Description
`GET`	`/api/demo/presenter-missions/status`	Return `presenter_scope` and `missions_by_blueprint` for `demo_data_migration`, `client_file_onboarding`, and `demo_dashboard_root_cause`.
`POST`	`/api/demo/presenter-missions/reset`	Reset one exact caller-owned Dashboard anomaly Mission (`blueprint_name` must be `demo_dashboard_root_cause`). Body includes `project_id` and `confirmation` — type `reset {project_id}`.
`POST`	`/api/demo/presenter-missions/cleanup`	Clean one exact caller-owned Presenter Control Mission. Body includes `blueprint_name` (`demo_data_migration`, `client_file_onboarding`, or `demo_dashboard_root_cause`), `project_id`, and `confirmation` — type `cleanup {project_id}`.

Ticket-driven dashboard anomaly (`/api/demo/ticket-rca`)

Orchestrates the Jira ticket-driven RCA presenter vignette. Genesis creates a real Jira issue tied to a caller-owned demo_dashboard_root_cause Mission, attaches a dashboard screenshot, starts the selected ETL failure fixture, and records Work-item linkage when Jira automation picks up the ticket. The issue is left unassigned after preparation; assign it to one of the configured assignment_targets to trigger Genesis pickup. When the dashboard RCA work is completed, Genesis posts a Jira comment beginning with “Fixed.” It includes the recorded root cause when available, a link to the RCA report, and a Prover result link to the report’s #prover-evidence section.

Method	Path	Description
`GET`	`/api/demo/ticket-rca/status`	Return readiness, pipeline options, assignment targets, and any active or completed example issue for the caller’s presenter scope.
`POST`	`/api/demo/ticket-rca/reset`	Start or reset the isolated dashboard failure fixture for a prepared ticket-dashboard RCA version run. Existing evidence remains in that run’s history.
`POST`	`/api/demo/ticket-rca/prepare`	Create the Jira ticket for the active dashboard fixture. The selected version run supplies the dashboard scenario and pipeline fixture.

Shared request field (query on GET, body on POST):

Field	In	Type	Required	Description
`presenter_session_id`	query or body	string	Yes	Browser-local presenter session. Pattern `^presenter-[a-z0-9]{1,20}$` (11–30 characters).

POST /api/demo/ticket-rca/prepare body fields:

Field	Type	Required	Description
`coding_agent`	string	Yes	Coding agent recorded on the ticket: `eve`, `codex`, or `claude_code`.

POST /api/demo/ticket-rca/reset body fields:

Field	Type	Required	Description
`presenter_session_id`	string	Yes	Browser-local presenter session.
`demo_version_revision_id`	string or null	No	Ready ticket-dashboard RCA revision. Supply it together with `demo_presentation_run_id`; pattern `^[a-zA-Z0-9_-]+$`, 3–120 characters.
`demo_presentation_run_id`	string or null	No	Prepared ticket-dashboard RCA run. Supply it together with `demo_version_revision_id`; pattern `^[a-zA-Z0-9_-]+$`, 3–120 characters.

The two demo-version fields must be supplied together. The reset operation validates that the revision, run, presenter session, and scenario still match; the prepare operation then uses that isolated fixture when it creates the Jira issue. Presenter RCA pickups are serialized per presenter scope while an earlier ticket still owns the active fixture in ticketed state. A later assigned ticket is retried on a subsequent polling pass after that fixture leaves ticketed; completed example issues do not block a new RCA pickup. GET /api/demo/ticket-rca/status response data fields:

Field	Type	Description
`state`	string	Lifecycle state such as `needs_setup`, `not_prepared`, `ready`, `busy`, `preparing`, `ticketed`, `awaiting_assignment`, `investigating`, `completed`, or `failed`. A bound run can also be `incomplete`; provider reconciliation may expose `cancelled` or `released` as failed terminal states.
`scope_id`	string	Presenter scope for this vignette (`trca-…`).
`ready`	boolean	`true` when Jira automation is enabled and configured for ticket pickup.
`assignment_targets`	array of strings	Jira assignee identities that trigger Genesis pickup.
`pipeline`	object or null	Active or completed dbt Cloud fixture run, including its run status and links when available.
`project_key`	string or null	First monitored Jira project key from automation config.
`active_issue`	object or null	Current prepared issue with `issue_key`, `issue_url`, `dashboard_url`, `pipeline`, `coding_agent`, and optional `work` linkage.
`completed_example`	object or null	Most recent completed example issue in the caller’s presenter scope, when present.
`demo_version_revision_id`	string or null	Version revision bound to the caller’s active dashboard fixture, when the fixture was started from a prepared version run.
`demo_presentation_run_id`	string or null	Presentation run bound to the caller’s active dashboard fixture, when the fixture was started from a prepared version run.
`dashboard`	object	Dashboard projection for the retained or active fixture, including `app_id`, `dataset_id`, `dashboard_url`, `ready`, `incident_id`, `failed_run_url`, `affected_apps`, and `lineage_root`. `affected_apps` contains the single packaged app whose persisted lineage identity and proxy path match the dashboard scenario; invalid or ambiguous lineage leaves it empty and makes the projection unavailable. If a retained fixture has no valid dbt Cloud run URL, `ready` is `false` and `projection_error` is `The retained dashboard fixture lacks a valid dbt Cloud run URL.`; when the retained run URL is valid HTTPS, its origin is used to reconstruct the dashboard projection.
`setup`	object	`{ "path": "/config/jira/", "message": … }` when automation needs configuration or the dashboard fixture cannot be projected.
`warning`	string	Optional non-fatal prepare warnings (for example screenshot or Jira comment attachment failures).

When present, active_issue.work also includes the persisted Jira provider_status. During status reconciliation, Genesis maps that provider status with the current Jira lifecycle configuration; mapped done, needs_info, or working states replace a stale work state and are recorded as a provider_status_observed event. An issue is reported as completed only when its current Jira status maps to done and the durable Work item contains the exact agent writeback receipt for the dashboard_rca_debrief comment. The receipt includes issue_key, work_item_id, thread_id, receipt_id, comment_sha256, and terminal event metadata; a missing or mismatched receipt leaves the fixture in its nonterminal state even when Jira is already done. When a retained legacy fixture has no dbt_cloud_access_url, reconciliation can still complete it after the linked Jira Work reaches done or released. It uses the fixture’s jira_issue_key and then marks the fixture completed while releasing that exact issue pointer. Prepare failures return success: false with error.code such as JIRA_SETUP_REQUIRED, JIRA_ISSUE_TYPE_UNAVAILABLE, CODING_AGENT_UNSUPPORTED, or DBT_PROVIDER_BUSY when an earlier presenter run still owns the shared dbt Cloud job. Version-bound resets can also return DEMO_VERSION_BINDING_INVALID or DEMO_VERSION_PROFILE_UNAVAILABLE.

Status	Meaning
`401`	Caller is not authenticated.
`403`	Presenter Controls is disabled, or the caller is not Genesis Staff and did not present a valid internal token.

Auth and user runtime config endpoints

These routes back lightweight auth bootstrap and the persisted background-job settings used by Pulse and Digital Twin.

Method	Path	Description
`GET`	`/api/config/auth`	Return auth bootstrap flags used by the web client.
`GET`	`/api/config/user-config`	Return persisted user-facing runtime job flags. Requires `access_config_panel`.
`POST`	`/api/config/user-config`	Update persisted user-facing runtime job flags. Requires `access_config_panel`.

`GET /api/config/auth` response fields

Field	Type	Default	Description
`success`	boolean	none	Whether the request completed successfully.
`data.auth_enabled`	boolean	`false`	Whether authentication is enabled for the current deployment.
`data.auth_provider`	string	`"none"`	Authentication provider identifier such as `auth0`, `oidc`, or `none`.

`GET /api/config/user-config` response fields

GET /api/config/user-config returns success and config.

`config` fields for `/api/config/user-config`

Field	Type	Default	Description
`auto_harvest`	boolean	`false`	Enable/disable automatic harvesting.
`harvester_job`	boolean	`false`	Enable/disable harvester job functionality.
`project_todo_job`	boolean	`false`	Enable/disable project todo job processing.
`dbt_cloud_job`	boolean	`false`	Enable/disable dbt Cloud job monitoring.
`harvester_watchdog_job`	boolean	`false`	Enable/disable harvester watchdog job.
`sandbox_monitor_job`	boolean	`true`	Enable/disable sandbox timeout monitor job.
`twin_harvest_enabled`	boolean	`false`	Master kill switch for Twin harvesting. When off, the daily `twin_daily_scan` prompt job is paused and per-connection `auto_twin_harvest` triggers are short-circuited.
`file_cleanup_job`	boolean	`true`	Enable/disable orphan files cleanup job.
`metrics_bridge_upload_job`	boolean	`true`	Enable/disable metrics bridge upload job.
`microapps_ttl_cleanup_job`	boolean	`true`	Enable/disable microapps TTL cleanup job.
`microapps_runtime_cleanup_job`	boolean	`true`	Enable/disable microapps runtime cleanup job. Cleanup only deletes runtime trees under the configured allowlisted roots; stage-backed storage is excluded from the storage-derived root.
`dataset_cleanup_job`	boolean	`true`	Enable/disable dataset snapshot cleanup job. See Dataset retention and cleanup for scheduling and batch behavior.
`coding_agent_session_cleanup_job`	boolean	`true`	Enable/disable coding-agent session cleanup job.
`slack_runtime_monitor_job`	boolean	`true`	Enable/disable Slack runtime monitor job.
`cost_cube_v2_retention_job`	boolean	`true`	Enable/disable cost cube v2 retention cleanup job.
`thread_retention_archive_job`	boolean	`false`	Enable/disable thread retention archival job.

`POST /api/config/user-config`

Send a JSON body shaped as { "config": { ... } } using the same field names listed above. The response returns success and message.

Branding endpoints

These routes back Config → Branding. See Branding for the customer-facing workflow.

Method	Path	Description
`GET`	`/api/config/branding`	Return organization branding settings and logo URLs. Any authenticated user.
`PUT`	`/api/config/branding`	Update branding settings. Requires `access_config_panel`.
`GET`	`/api/config/branding/logo/{logo_type}`	Serve a logo image file. Any authenticated user.
`POST`	`/api/config/branding/logo/{logo_type}`	Upload a logo (PNG, JPEG, or SVG; max 2 MB). Requires `access_config_panel`.
`DELETE`	`/api/config/branding/logo/{logo_type}`	Remove a logo. Requires `access_config_panel`.

logo_type is square, wide, header_light, or header_dark. The header_light and header_dark types are optional overrides for the main Genesis header and are not copied into generated app workspaces.

`GET /api/config/branding` and `PUT /api/config/branding` fields

GET /api/config/branding returns success and data. PUT /api/config/branding accepts any subset of the writable fields below; omitted fields are left unchanged.

Field	Type	Default	Writable	Description
`organization_name`	string \| null	`null`	Yes	Organization display name.
`primary_color`	string \| null	`null`	Yes	Primary brand color (hex).
`secondary_color`	string \| null	`null`	Yes	Secondary brand color (hex).
`tertiary_color`	string \| null	`null`	Yes	Tertiary brand color (hex).
`app_design_guidance`	string \| null	`null`	Yes	Freeform guidance injected into Genesis-generated app prompts.
`use_logo_in_header`	boolean	`false`	Yes	When `true`, show the uploaded organization logo in the main Genesis header. Off by default; uploaded logos are always applied to generated apps regardless of this value.
`square_logo_url`	string \| null	`null`	No	URL to the square logo when one is uploaded. `null` when no square logo exists.
`wide_logo_url`	string \| null	`null`	No	URL to the wide logo when one is uploaded. `null` when no wide logo exists.
`header_light_logo_url`	string \| null	`null`	No	URL to the light-mode header logo override. `null` means the header uses the default logo for light mode.
`header_dark_logo_url`	string \| null	`null`	No	URL to the dark-mode header logo override. `null` means the header uses the default logo for dark mode.

Logo URL fields are read-only on PUT. Each non-null URL includes a ?v={version} query parameter that changes when the underlying file is replaced, so clients can cache the image until the version changes. POST /api/config/branding/logo/{logo_type} returns success and logo_url with the uploaded file’s URL (including the version query parameter).

The one-shot startup storage-cleanup audit is separate from these persisted job flags. It is controlled only by environment variables:

GENESIS_STORAGE_CLEANUP_STARTUP_AUDIT defaults to false. Set it to true or another truthy value such as 1, yes, or on to schedule the startup dry-run audit.
GENESIS_STORAGE_CLEANUP_STARTUP_AUDIT_DELAY_S defaults to 30 and controls the startup-audit delay in seconds.

When enabled, Genesis writes a dry-run reclaim report under storage_cleanup_reports/, including a timestamped startup-dry-run-<timestamp>.json file and latest.json. The audit does not delete files.

LLM provider create duplicate guard

POST routes that create an LLM provider configuration run a pre-write duplicate check before persisting submitted credentials, endpoint metadata, or process environment state. Affected routes include:

POST /api/config/llm-providers/openai
POST /api/config/llm-providers/cortex
POST /api/config/llm-providers/databricks
POST /api/config/llm-providers/litellm-proxy
POST /api/config/llm-providers/other (for example Bedrock, Anthropic, Google Gemini)

When the provider is already configured, Genesis returns LlmOperationResponse with success: false and does not write the submitted API key or other credentials to the secret store, mutate process-global LiteLLM environment variables, delete backing connections, or run model discovery. The response message is: Configuration for {display_name} already exists. Use configure endpoint to update and enable it. where {display_name} is the provider’s human-readable title (for example OpenAI, Databricks, LiteLLM Proxy). Use the matching provider PUT route — for example PUT /api/config/llm-providers/openai — to update an existing configuration instead of calling POST again.

Route	Refusal when already configured	Exception
`POST /api/config/llm-providers/openai`, `POST /api/config/llm-providers/cortex`, `POST /api/config/llm-providers/other`	Yes	Skipped when no main chat provider is active (`active_provider` is `null`). In that first-provider case, `POST` may activate the existing configuration instead of refusing.
`POST /api/config/llm-providers/databricks`	Always	None — this route never auto-activates, so an existing configuration is always refused.
`POST /api/config/llm-providers/litellm-proxy`	Yes, unless activation is certain from the request	Skipped when the payload includes a non-empty `model` and no explicit active provider is set (`active_provider_raw` is `null`; the Snowflake Cortex zero-config default does not count). Otherwise a `POST` with no `model` against an already-configured proxy is refused up front rather than deleting the backing connection or running discovery first.

If the duplicate check itself fails (for example the existence probe raises), Genesis fails open and proceeds with the create so the route does not introduce a new 500 where it previously returned 200.

LLM provider save validation and rollback

Provider create and update routes that persist credentials run under a rollback guard. Genesis snapshots the provider’s stored configuration (managed secrets, APP_CONFIG paths, and any process env keys the validation step may mutate). When a save has an applicable probe target, Genesis runs the save-time connection test when test_connection is true; it also tests a submitted secret value that differs from a credential already configured for that provider, even when test_connection is false. Process env (for example OPENAI_API_KEY or LITELLM_PROXY_*) is committed only after validation passes. The replacement check applies when a provider already has a stored credential; initial setup with no stored credential, re-sending an unchanged value, and submitting a secret reference do not trigger an automatic test. An Azure OpenAI connection-only save without a deployment has no probe target and remains untested. When validation fails, Genesis restores the snapshot and answers with LlmOperationResponse where success is false and message carries the validation error directly (for example Connection test failed: ...) — not a generic Failed to save configuration: ... wrapper. The prior working credential remains in the secret store and runtime caches are invalidated so the restored value is served on the next read. Bedrock is admitted differently: when test_connection is true, Genesis tests the submitted candidate before writing it. A rejected Bedrock candidate leaves the existing configuration untouched and does not require a rollback; the response still reports success: false with the connection-test message. After a successful provider save, model-assignment save, or provider credential mutation through the secret-fields API, Genesis publishes the change to the running process-local LLM runtime. The next operation re-resolves provider credentials and model assignments; a server restart is not required. Failed guarded saves and rollbacks do not publish a runtime change. Successful provider saves that persist an embedding model preference may also include optional embedding_adoption on LlmOperationResponse — the first-save-wins adoption outcome when no global embedding identity exists yet. See First-save embedding adoption.

Failure	`success`	Typical `message`
Connection test rejected the submitted credential	`false`	Validation error from the test (connection failure text).
Another provider save holds the guard lock for 30 seconds	`false`	`Another provider configuration is being saved right now; nothing was saved. Wait for it to finish and try again.`
Snapshot of the current configuration could not be taken	`false`	`Could not snapshot the current provider configuration; nothing was saved.`
Persist step failed before validation	`false`	Persist error from the provider write path.

If rollback itself fails, message appends Previous credentials could not be restored automatically; please re-enter them. For LiteLLM Proxy, a final step runs after validation succeeds under the same save lock: it syncs the shared OAuth backing connection (litellm_proxy.shared when auth_mechanism is oauth) or deletes that backing connection for other auth modes, then sets providers.litellm_proxy.admission to auto and invalidates LLM runtime caches. These side effects are not covered by the AppConfig snapshot and are not rolled back — they run through finalize_without_rollback on the provider write guard. Affected routes include POST and PUT on /api/config/llm-providers/openai, /cortex, /databricks, /azure, /litellm-proxy, and /other (Bedrock, Anthropic, Gemini, and other LiteLLM-backed providers). LiteLLM Other Providers defer commit_env until after test_connection succeeds so invalid keys are never published to OPENAI_API_KEY, ANTHROPIC_API_KEY, or related env vars. For AWS Bedrock behind a custom endpoint (endpoint_mode: "custom"), the first POST /api/config/llm-providers/other create deliberately skips the save-time connection test even when test_connection is true because there is no reachable probe target on that path; use POST /api/config/bedrock/test-connection or retry with PUT once the configuration exists (updates always honor test_connection).

Azure OpenAI connection test API version

POST /api/config/azure/test-connection accepts an optional api_version. When the field is omitted or null, Genesis uses the saved providers.azureopenai.connection.api_version; if none is saved, it uses 2025-04-01-preview. Set api_version explicitly to test a different Azure API version without changing the saved provider configuration. Provider saves also default providers.azureopenai.connection.api_version to 2025-04-01-preview when no version is supplied. See Azure OpenAI provider setup.

Cortex provider configuration endpoints

These routes back the Snowflake Cortex card on Config -> AI Providers.

Method	Path	Description
`GET`	`/api/config/llm-providers/cortex`	Return current Cortex configuration status, including masked credentials and runtime capability flags.
`POST`	`/api/config/llm-providers/cortex`	Create a Cortex configuration.
`PUT`	`/api/config/llm-providers/cortex`	Update an existing Cortex configuration.
`POST`	`/api/config/cortex/test-connection`	Test Cortex connectivity. When `api_key` or `account_url` are supplied, Genesis validates those submitted values — not the runtime-resolved credential exported to `CORTEX_API_KEY` on Cortex-active installs. When both are omitted, Genesis falls back to saved or native runtime configuration.

In Snowflake-native runtimes where Cortex is already available, POST and PUT /api/config/llm-providers/cortex can omit credential fields. In other deployments, provide either PAT credentials (account_url and api_key) or key-pair credentials (snowflake_account, snowflake_user, and private_key). Set auth_method to "pat" or "keypair" to make the mode explicit; when omitted, Genesis infers key-pair mode when private_key and snowflake_account are present without api_key. On Snowflake Native App / SPCS hosts, Genesis registers Cortex whenever it is available but does not overwrite an existing llm.active_provider. Saving or testing Cortex adds or updates the cortex provider row; activation happens only when no chat provider is active yet unless the request sets force_activation: true or the operator explicitly switches the active provider. POST and PUT with test_connection: true validate the submitted api_key and account_url when present. On Cortex-active installs where activation exports the working PAT into CORTEX_API_KEY, Genesis does not re-validate that exported credential instead of the PAT being saved — a rejected submission fails and the rollback guard restores the prior working key.

Shared Cortex request fields

Field	Used by	Type	Default	Description
`auth_method`	`POST /api/config/llm-providers/cortex`, `PUT /api/config/llm-providers/cortex`, `POST /api/config/cortex/test-connection`	`"pat" \| "keypair" \| null`	`null`	Request authentication mode. `pat` uses a Snowflake programmatic access token. `keypair` uses PEM key-pair JWT auth. When `null`, Genesis infers key-pair mode from `private_key` and `snowflake_account` when `api_key` is absent. The UI defaults to `pat`. Genesis Desktop can also store `connection` as an AppConfig mode; see Snowflake Cortex setup.
`connection_name`	Genesis Desktop AppConfig, not these request bodies	string	`""`	Snowflake connection name used with the AppConfig `connection` auth mode; omit the `snowflake.` prefix.
`account_url`	`POST /api/config/llm-providers/cortex`, `PUT /api/config/llm-providers/cortex`, `POST /api/config/cortex/test-connection`	string or null	`null`	Snowflake account host, full account URL, or account identifier. Genesis normalizes this to the account host. Required for PAT-backed create requests unless `snowflake_account` is provided for key-pair mode.
`api_key`	`POST /api/config/llm-providers/cortex`, `PUT /api/config/llm-providers/cortex`, `POST /api/config/cortex/test-connection`	string or null	`null`	Snowflake programmatic access token for PAT mode. Send `null` in key-pair mode.
`model`	`POST /api/config/llm-providers/cortex`, `PUT /api/config/llm-providers/cortex`, `POST /api/config/cortex/test-connection`	string or null	`null`	Optional model name for connection tests and for persisted public config. Genesis writes `model` to provider metadata only when the request includes a non-null value — omitted or `null` does not invent or persist an env default such as `CORTEX_MODEL`. Runtime defaults still apply through the schema `default_env_var` chain when no saved assignment exists.
`embedding_method`	`POST /api/config/llm-providers/cortex`, `PUT /api/config/llm-providers/cortex`	`"rest" \| "sql" \| null`	`null`	How Cortex embeddings run when Snowflake Cortex is the active embedding provider. `rest` uses the Cortex REST API with the saved PAT or key-pair JWT. `sql` opens a direct Snowflake SQL connection and calls `EMBED_TEXT_768`. The UI defaults to `rest` when omitted. In Snowflake Native App / SPCS runtimes, embeddings always use SQL via the deployment session regardless of this field.
`snowflake_account`	`POST /api/config/llm-providers/cortex`, `PUT /api/config/llm-providers/cortex`, `POST /api/config/cortex/test-connection`	string or null	`null`	Snowflake account identifier for key-pair auth (for example `ORGID-ACCTID` or full host). Required for key-pair create requests when `account_url` is omitted.
`snowflake_user`	`POST /api/config/llm-providers/cortex`, `PUT /api/config/llm-providers/cortex`, `POST /api/config/cortex/test-connection`	string or null	`null`	Snowflake username for SQL-path embeddings or key-pair auth. Required when `embedding_method` is `sql` or for key-pair mode.
`private_key`	`POST /api/config/llm-providers/cortex`, `PUT /api/config/llm-providers/cortex`, `POST /api/config/cortex/test-connection`	string or null	`null`	PEM-encoded private key for key-pair auth. Required for key-pair create requests.
`private_key_passphrase`	`POST /api/config/llm-providers/cortex`, `PUT /api/config/llm-providers/cortex`, `POST /api/config/cortex/test-connection`	string or null	`null`	Optional passphrase for an encrypted private key.
`warehouse`	`POST /api/config/llm-providers/cortex`, `PUT /api/config/llm-providers/cortex`	string or null	`null`	Optional Snowflake warehouse for SQL-path embedding connections.
`role`	`POST /api/config/llm-providers/cortex`, `PUT /api/config/llm-providers/cortex`	string or null	`null`	Optional Snowflake role for SQL-path embedding connections.
`test_connection`	`POST /api/config/llm-providers/cortex`, `PUT /api/config/llm-providers/cortex`	boolean	`true`	Test connectivity before or while saving the provider configuration.
`force_activation`	`POST /api/config/llm-providers/cortex`, `PUT /api/config/llm-providers/cortex`	boolean	`false`	Force provider activation even if basic checks fail.

`GET /api/config/llm-providers/cortex` response fields

Field	Type	Description
`success`	boolean	Whether the request completed successfully.
`data.configured`	boolean	Whether Cortex is currently usable through native runtime access or saved public credentials.
`data.auth_method`	`"pat" \| "keypair" \| null`	Saved authentication mode when present in provider metadata.
`data.account_url`	string or null	Saved Snowflake account host or URL when public Cortex config is stored.
`data.api_key_masked`	string or null	Masked Snowflake PAT when PAT-backed public Cortex config is stored.
`data.model`	string or null	Saved public Cortex model, when present.
`data.embedding_method`	`"rest" \| "sql" \| null`	Saved Cortex embedding execution mode when present in provider metadata.
`data.snowflake_account`	string or null	Saved Snowflake account identifier for key-pair auth, when present.
`data.snowflake_user`	string or null	Saved Snowflake username for SQL-path embeddings or key-pair auth, when present.
`data.private_key_masked`	string or null	Masked PEM private key when key-pair public Cortex config is stored.
`data.private_key_passphrase_masked`	string or null	Masked private-key passphrase when present.
`data.warehouse`	string or null	Saved Snowflake warehouse for SQL-path embeddings, when present.
`data.role`	string or null	Saved Snowflake role for SQL-path embeddings, when present.
`data.native_runtime_available`	boolean	Whether this deployment can use Cortex natively without saved public credentials.
`data.public_configured`	boolean	Whether a saved PAT- or key-pair-backed public Cortex config exists.
`data.credential_entry_required`	boolean	Whether callers must provide public credentials instead of relying on native runtime access.

Databricks provider configuration endpoints

These routes back the Databricks card on Config -> AI Providers.

Method	Path	Description
`GET`	`/api/config/llm-providers/databricks`	Return current Databricks configuration status, including the saved auth mode, serving endpoint, masked PAT, and saved OAuth connection name.
`POST`	`/api/config/llm-providers/databricks`	Create a Databricks configuration.
`PUT`	`/api/config/llm-providers/databricks`	Update an existing Databricks configuration.
`POST`	`/api/config/databricks/test-connection`	Test Databricks Model Serving via a LiteLLM completion using provided PAT credentials, a selected OAuth connection, the saved configuration, or the configured Databricks App identity.

POST /api/config/llm-providers/databricks defaults auth_mode to pat. In PAT mode, llm_endpoint and api_key are required on create. In OAuth mode, oauth_connection_name is required, llm_endpoint is optional, and Genesis derives https://<connection-host>/serving-endpoints from the selected connection when the field is omitted. Runtime and OAuth-backed test flows resolve the acting user’s OAuth grant from that saved connection instead of persisting a user access token on the provider. Headless calls cannot use a per-user grant: Databricks embeddings, embedding adoption, and embedding-model save/activation require either PAT credentials plus a workspace URL, or OAuth mode with a resolvable service_principal M2M connection configured in genesis-config.yaml at providers.databricks.connection.oauth.m2m_connection_name (not exposed on these REST routes). U2M-only OAuth remains valid for user-present chat and test flows, but it does not make Databricks ready for embeddings. app_identity is deployment-selected for Databricks Apps, not a credential supplied by these routes: with providers.databricks.connection.auth_mode=app_identity, runtime and connection-test calls use the App service principal token, and provider settings saves are refused so a PAT or OAuth credential cannot replace it. The App runtime must supply DATABRICKS_HOST, DATABRICKS_CLIENT_ID, and DATABRICKS_CLIENT_SECRET; calls fail without them and do not fall back to PAT or user OAuth credentials. Genesis routes calls through LiteLLM with per-call api_key and api_base, not ambient DATABRICKS_* variables. See Databricks App identity setup.

Databricks configuration request fields

Field	Used by	Type	Default	Description
`auth_mode`	`POST /api/config/llm-providers/databricks`, `PUT /api/config/llm-providers/databricks`, `POST /api/config/databricks/test-connection`	`"pat" \| "oauth" \| null`	`POST: "pat"; otherwise: null`	Databricks authentication mode submitted to these routes. `POST` defaults to `pat` when omitted. `PUT` and test requests can omit this field to use the saved behavior. `app_identity` is selected through deployment configuration rather than these provider-setting requests; provider settings saves are refused while it is active.
`llm_endpoint`	`POST /api/config/llm-providers/databricks`, `PUT /api/config/llm-providers/databricks`, `POST /api/config/databricks/test-connection`	`string or null`	`null`	Databricks Model Serving base URL. In PAT mode on create it is required. In OAuth mode, `null` lets Genesis derive `https://<connection-host>/serving-endpoints` from the selected connection.
`api_key`	`POST /api/config/llm-providers/databricks`, `PUT /api/config/llm-providers/databricks`, `POST /api/config/databricks/test-connection`	`string or null`	`null`	Databricks personal access token. Required for PAT-backed create requests. Send `null` in OAuth mode.
`oauth_connection_name`	`POST /api/config/llm-providers/databricks`, `PUT /api/config/llm-providers/databricks`, `POST /api/config/databricks/test-connection`	`string or null`	`null`	Existing Databricks connection name whose current user’s OAuth grant is used at test and runtime. Required when `auth_mode` is `oauth`.
`test_connection`	`POST /api/config/llm-providers/databricks`, `PUT /api/config/llm-providers/databricks`	`boolean`	`true`	Test or validate the selected Databricks credentials or OAuth connection before saving. This user-present test can succeed with U2M OAuth; embedding readiness is evaluated separately and requires PAT or the configured headless M2M service-principal connection.

`GET /api/config/llm-providers/databricks` response fields

Field	Type	Description
`success`	boolean	Whether the request completed successfully.
`data.configured`	boolean	Whether Databricks is currently configured.
`data.auth_mode`	`string or null`	Saved Databricks auth mode. Older configs default to `pat` when the mode is not stored explicitly.
`data.llm_endpoint`	`string or null`	Saved Databricks Model Serving base URL.
`data.oauth_connection_name`	`string or null`	Saved Databricks OAuth connection name when OAuth mode is configured.
`data.api_key_masked`	`string or null`	Masked Databricks PAT when PAT mode is configured.

Databricks connection test request fields

Field	In	Type	Default	Required	Description
`auth_mode`	body	`string or null`	`null`	No	Databricks authentication mode for the test. Set this to `oauth` to test a specific OAuth-backed connection. When App configuration selects `app_identity`, the test uses the App service principal instead of supplied or saved personal credentials.
`api_key`	body	`string or null`	`null`	No	Databricks personal access token. When `null`, Genesis uses the saved PAT config unless OAuth mode is selected.
`llm_endpoint`	body	`string or null`	`null`	No	Databricks Model Serving base URL. When `null`, Genesis uses the saved endpoint or derives one from the selected OAuth connection.
`model`	body	`string or null`	`null`	No	Optional Databricks serving endpoint name to test. When `null`, Genesis uses the configured or default model.
`oauth_connection_name`	body	`string or null`	`null`	No	Existing Databricks connection name. Required when `auth_mode` is `oauth`.

If POST /api/config/databricks/test-connection receives neither PAT fields nor OAuth fields, Genesis tests the saved Databricks configuration. When the saved config uses OAuth, Genesis resolves the current user’s grant for the saved oauth_connection_name.

Bedrock provider configuration endpoints

These routes back the AWS Bedrock card on Config -> AI Providers.

Method	Path	Description
`GET`	`/api/config/llm-providers/other/bedrock`	Return current Bedrock configuration status, including masked credentials and saved custom-endpoint settings.
`POST`	`/api/config/llm-providers/other`	Create a Bedrock configuration. Set `provider` to `bedrock`.
`PUT`	`/api/config/llm-providers/other`	Update an existing Bedrock configuration. Set `provider` to `bedrock`.
`POST`	`/api/config/bedrock/test-connection`	Test Bedrock connectivity using provided credentials or the saved configuration.
`GET`	`/api/config/bedrock/iam-status`	Detect whether the deployment’s attached IAM role has Bedrock permissions.

For POST and PUT /api/config/llm-providers/other, an omitted auth_mode, endpoint_mode or bedrock_chat_route_mode keeps the effective value — the stored one, or the schema default (api_key, default, invoke) when nothing is stored. When auth_mode is api_key, aws_bearer_token is required. When endpoint_mode is default, aws_region is required. When endpoint_mode is custom, custom_endpoint_url is required. Each requirement is evaluated against the effective configuration the write would produce — the submitted fields over the stored values, deployment environment inputs and schema defaults — so a value already in effect satisfies it without being resent. Only the submitted fields are written; an inherited value is used for the check and the connection test but is not copied into the stored configuration. Custom endpoints support api_key authentication only; auth_mode: "iam_role" with endpoint_mode: "custom" is rejected before the configuration is saved. When you save a Bedrock custom-endpoint configuration, Genesis also syncs the runtime options into App Config under providers.litellm_bedrock.settings.*. GET /api/config/bedrock/iam-status accepts region and refresh query parameters. region defaults to us-east-1, and refresh defaults to false.

`GET /api/config/bedrock/iam-status` response fields

Field	Type	Description
`success`	boolean	Whether the request completed successfully.
`data.status`	`"available" \| "missing_perms" \| "not_aws"`	IAM detection result for the current Bedrock region check.
`data.message`	string	Human-readable status summary for the detected IAM state.
`data.account_id`	string	Resolved AWS account ID. Genesis prefers `AWS_ACCOUNT_ID`, then the account embedded in `AWS_ROLE_ARN`, then an STS caller-identity lookup. Returns an empty string when unavailable.

Bedrock configuration request fields

Field	Used by	Type	Default	Description
`provider`	`POST /api/config/llm-providers/other`, `PUT /api/config/llm-providers/other`	string	none	Must be `bedrock`.
`model`	`POST /api/config/llm-providers/other`, `PUT /api/config/llm-providers/other`	string or null	`null`	Bedrock model identifier. On `POST`, Genesis falls back to the default Bedrock chat model when omitted. On `PUT`, `null` keeps the existing value.
`aws_bearer_token`	`POST /api/config/llm-providers/other`, `PUT /api/config/llm-providers/other`	string or null	`null`	API key or bearer token used when `auth_mode` is `api_key`. When `endpoint_mode` is `custom` and `custom_auth_header` is a non-bearer header such as `x-api-key`, Genesis stores the value in `GENESIS_BEDROCK_CUSTOM_HEADER_KEY` at runtime instead of `AWS_BEARER_TOKEN_BEDROCK` so LiteLLM does not send `Authorization: Bearer`.
`aws_region`	`POST /api/config/llm-providers/other`, `PUT /api/config/llm-providers/other`	string or null	`null`	AWS region for the default Bedrock endpoint. Required when `endpoint_mode` is `default`. For custom endpoints, Genesis normalizes a blank value to `us-east-1` as a placeholder because the custom endpoint URL overrides routing.
`aws_account_id`	`POST /api/config/llm-providers/other`, `PUT /api/config/llm-providers/other`	string or null	`null`	AWS account ID used for Bedrock ARN formation. Optional: the chat runtime resolves models by short-form inference-profile id, so only the invoke-route connection test uses this value.
`auth_mode`	`POST /api/config/llm-providers/other`, `PUT /api/config/llm-providers/other`	`"api_key" \| "iam_role" \| null`	`null`	Bedrock authentication mode. Missing values default to `api_key`.
`endpoint_mode`	`POST /api/config/llm-providers/other`, `PUT /api/config/llm-providers/other`	`"default" \| "custom" \| null`	`null`	Bedrock endpoint mode. Missing values default to `default`.
`custom_endpoint_url`	`POST /api/config/llm-providers/other`, `PUT /api/config/llm-providers/other`	string or null	`null`	Custom Bedrock-compatible endpoint URL. Required when `endpoint_mode` is `custom`.
`custom_auth_header`	`POST /api/config/llm-providers/other`, `PUT /api/config/llm-providers/other`	string or null	`null`	HTTP header name used to send the API key to custom endpoints, for example `bearer` or `x-api-key`.
`bedrock_chat_route_mode`	`POST /api/config/llm-providers/other`, `PUT /api/config/llm-providers/other`	`"invoke" \| "converse" \| null`	`null`	Bedrock chat API route mode. `invoke` sends the model unprefixed and lets LiteLLM select the route; `converse` pins the Converse API. Missing values default to `invoke`.
`strip_regional_prefix`	`POST /api/config/llm-providers/other`, `PUT /api/config/llm-providers/other`	boolean or null	`null`	Remove AWS cross-region prefixes such as `us.`, `eu.`, `apac.`, and `global.` from model IDs before sending them to custom endpoints.
`fake_stream`	`POST /api/config/llm-providers/other`, `PUT /api/config/llm-providers/other`	boolean or null	`null`	Use the non-streaming `/converse` path internally and chunk the response for the UI. Useful for proxies that do not support `/converse-stream`.
`extra_headers_json`	`POST /api/config/llm-providers/other`, `PUT /api/config/llm-providers/other`	string or null	`null`	Additional HTTP headers for custom endpoints, encoded as a JSON object string. The value must be blank/`null` or parse to a JSON object, for example `{"x-tenant-id": "abc", "anthropic-version": "bedrock-2023-05-31"}`.
`verify_ssl`	`POST /api/config/llm-providers/other`, `PUT /api/config/llm-providers/other`	boolean or null	`null`	Verify TLS certificates for custom endpoints. The effective default is `true`; send `false` to allow self-signed certificates.
`test_connection`	`POST /api/config/llm-providers/other`, `PUT /api/config/llm-providers/other`	boolean	`true`	Request a save-time connection test. On the first `POST` create for Bedrock with `endpoint_mode: "custom"`, Genesis skips the save-time test even when `true` — use `POST /api/config/bedrock/test-connection` or save again with `PUT`. Updates to an existing Bedrock config always honor `test_connection`; the submitted candidate is tested before it is persisted. A rejected candidate leaves the prior configuration untouched (see LLM provider save validation and rollback).

GET /api/config/llm-providers/other/bedrock returns the saved auth_mode, endpoint_mode, custom_endpoint_url, custom_auth_header, strip_regional_prefix, fake_stream, extra_headers_json, verify_ssl, and masked credentials, and always includes the effective bedrock_chat_route_mode value. The saved provider config also keeps bedrock_chat_route_mode, so later Bedrock test requests can omit it and reuse the current setting. The synced App Config keys are providers.litellm_bedrock.settings.strip_regional_prefix, providers.litellm_bedrock.settings.fake_stream, providers.litellm_bedrock.settings.extra_headers, and providers.litellm_bedrock.settings.verify_ssl.

Bedrock connection test request fields

Field	In	Type	Default	Required	Description
`aws_bearer_token`	body	string or null	`null`	No	AWS bearer token for authentication.
`aws_access_key_id`	body	string or null	`null`	No	AWS access key ID, used as an alternative to bearer-token auth.
`aws_secret_access_key`	body	string or null	`null`	No	AWS secret access key, used as an alternative to bearer-token auth.
`aws_region`	body	string or null	`null`	No	AWS region for Bedrock. If `null`, Genesis uses the saved value or `us-east-1`.
`aws_account_id`	body	string or null	`null`	No	AWS account ID for inference profile ARN generation.
`custom_endpoint_url`	body	string or null	`null`	No	Custom Bedrock-compatible endpoint URL.
`auth_mode`	body	`"api_key" \| "iam_role" \| null`	`null`	No	Selected Bedrock auth mode from the UI.
`endpoint_mode`	body	`"default" \| "custom" \| null`	`null`	No	Selected Bedrock endpoint mode from the UI.
`custom_auth_header`	body	string or null	`null`	No	HTTP header name for sending the API key to custom endpoints.
`extra_headers_json`	body	string or null	`null`	No	Additional HTTP headers as a JSON object string for custom proxy tests. The value must be blank/`null` or parse to a JSON object. `null` falls back to saved headers; `""` clears saved extra headers for this test request.
`verify_ssl`	body	boolean or null	`null`	No	Verify TLS certificates for custom-endpoint probes. If `null`, Genesis uses the saved value or `true`.
`bedrock_chat_route_mode`	body	`"invoke" \| "converse" \| null`	`null`	No	Pick the custom-endpoint probe route and body shape. If `null`, Genesis uses the saved value or `invoke`.

When a Bedrock test request omits a field or sends it as null, Genesis resolves the effective parameters from the saved Bedrock configuration first, then falls back to documented defaults such as aws_region: "us-east-1", verify_ssl: true, and bedrock_chat_route_mode: "invoke". For test requests, send either an AWS bearer token or a complete access-key/secret-key pair, not both. A partial key pair or conflicting credentials is rejected. If auth_mode is omitted, explicit credentials in the request select api_key mode; requests using iam_role must not include explicit credentials. Access-key authentication requires the default Bedrock endpoint. For custom endpoints, POST /api/config/bedrock/test-connection sends a lightweight probe that matches bedrock_chat_route_mode: invoke targets /model/{modelId}/invoke with an Anthropic-style body, while converse targets /model/{modelId}/converse with the Bedrock Converse body. When a Bedrock model is already configured, Genesis probes that model; otherwise it uses a dummy model ID. When auth_mode is iam_role and endpoint_mode is custom, the test route returns success: false and instructs callers to use API-key auth for custom proxies. When custom_auth_header is a non-bearer header such as x-api-key, Genesis adds a structurally valid SigV4 Authorization header plus the selected custom header so API Gateway-based Bedrock proxies can validate the request. A custom proxy that returns 403 for the lightweight test model is reported as success: true with details.warning and details.status_code so callers can surface the warning while still treating the endpoint as reachable.

Bedrock connection test response fields

Field	Type	Description
`success`	boolean	Whether the Bedrock connection test succeeded. For some custom proxies, a `403` probe response can still return `true` with a warning.
`message`	string	Human-readable Bedrock test result.
`details.warning`	string or null	Optional warning text for reachable-but-ambiguous custom-proxy results, such as a `403` response for the lightweight test model.
`details.status_code`	integer or null	Upstream HTTP status code from the custom-endpoint probe when Genesis has one to report.

Gemini connection test request fields

POST /api/config/gemini/test-connection tests Google Gemini through LiteLLM. The request can use a submitted API key or the saved Gemini credential.

Field	In	Type	Default	Required	Description
`api_key`	body	string or null	`null`	No	Google Gemini API key from AI Studio. When `null`, Genesis uses the saved credential.
`model`	body	string or null	`null`	No	Gemini model to probe. When omitted or `null`, Genesis uses the configured model; when no configured model is available, it falls back to `gemini-3.6-flash`.

The AI Providers test flow supplies the selected model when available, preferring the fast_model assignment, then default_chat, then the first model in the test list. This prevents a valid credential from failing because a different unsupported fallback model was probed.

Genesis AI connection test

Method	Path	Description
`POST`	`/api/config/genesis-ai/test-connection`	Test Genesis AI using the Genesis-issued key. Requires `access_config_panel`; available on Genesis Desktop. No request body is required.

The test does not save or change configuration. It makes one or two HTTPS requests to Genesis AI: a model listing and, when applicable, a one-token message probe. Each request can take up to 10 seconds. The response uses success and message, with optional details fields:

Field	Type	Description
`details.elapsed_ms`	integer	Elapsed time for a configured Genesis AI test, in milliseconds.
`details.reason`	string	`not_set_up` when Genesis AI is not configured on this computer, or `unreachable` when the proxy could not be reached.

Genesis Desktop embedding test restriction

POST /api/config/llm-providers/embedding-config/test accepts only Genesis AI on Genesis Desktop. A request for another provider returns 403; if the provider is omitted and inferred from the model, the inferred provider is checked as well.

AI Providers page overview endpoints

These routes back the Beta AI Providers page (/config/ai-providers/). They are read-only and available to any authenticated user. Responses expose masked connection subtitles in extraInfo — never secret plaintext.

Method	Path	Description
`GET`	`/api/config/ai-providers/overview`	Page-level overview for eight providers (`openai`, `anthropic`, `gemini`, `cortex`, `azure`, `databricks`, `bedrock`, `litellm_proxy`) with setup stage, credential state, and active chat/embedding assignments.
`GET`	`/api/config/ai-providers/embedding-health`	Return Twin’s current verdict about whether the configured embedding identity can actually embed. Requires `access_config_panel` or `view_model_config`; returns an explicit `unavailable` status when no verdict can be obtained.

`GET /api/config/ai-providers/overview` response fields

Top-level response:

Field	Type	Description
`success`	boolean	Always `true` on success.
`summary`	object	Cross-provider summary (see below).
`providers`	array	One object per supported provider UI id.

summary object:

Field	Type	Description
`activeChatProvider`	string or null	UI id of the active chat provider (for example `openai`, `litellm_proxy`).
`activeEmbProvider`	string or null	UI id of the active embedding provider.
`embModel`	string or null	Technical name of the active embedding model.
`activeAssignments`	object or null	Chat-tier assignments for the active chat provider. Present only when a chat provider is active.
`activeAssignments.defaultChat`	string or null	Main chat model assignment.
`activeAssignments.defaultFast`	string or null	Fast-tier model assignment.
`activeAssignments.defaultPremier`	string or null	Premiere-tier model assignment.
`embeddingState`	string or null	Standing embedding identity state: `unset`, `pointer_set`, `incomplete`, or `mode_override`. Present when Genesis can classify the effective embedding identity; `null` in degraded overview responses. The UI uses `unset` and `incomplete` to decide when to show the no-active-embedding card and corpus recovery surface. Distinct from the one-shot `embedding_adoption` field on provider saves.

Each providers[] item:

Field	Type	Description
`name`	string	Short UI id (`openai`, `anthropic`, `gemini`, `cortex`, `azure`, `databricks`, `bedrock`, `litellm_proxy`).
`displayName`	string	Human-readable provider title.
`envCredsDetected`	boolean	`true` when provider env vars (for example `OPENAI_API_KEY`) are set but Genesis has no saved credentials yet. For `litellm_proxy`, `true` only when the effective proxy configuration is complete and `providers.litellm_proxy.connection.base_url` is still supplied by its `default_env_var` (`LITELLM_PROXY_API_BASE`) rather than an explicit DB/UI value.
`configured`	boolean	Whether the provider’s connection parameters are sufficient. Computed on every read; never stored.
`admitted`	boolean	Whether operator policy permits the provider to be used.
`missingParameters`	string[]	Names of required parameters that are not currently supplied; empty when none are missing.
`hasSavedCreds`	boolean	Whether required secrets exist in the managed secret store.
`isActiveChat`	boolean	Whether this provider is the active chat provider.
`isActiveEmb`	boolean	Whether this provider is the active embedding provider.
`eaiRequired`	boolean	`true` for every provider except Snowflake Cortex.
`setupStage`	string	Server-computed setup progress: `disabled`, `active`, `needs_eai`, `needs_models`, `ready`, `env_detected`, or `not_configured`. `disabled` means admission is denied; a provider missing required parameters reports `not_configured` rather than `active`.
`extraInfo`	string or null	Ready-to-display subtitle (for example `API key: sk-·····8f2a`, `Endpoint: https://...`, `IAM Role`).

`GET /api/config/ai-providers/embedding-health` response fields

This endpoint carries the verdict already maintained by Digital Twin rather than inferring health from recorded provider configuration. The request can take up to 5 seconds while Genesis obtains the verdict from Twin. A slow or unavailable Twin does not become a false healthy or failed result; the endpoint returns status: "unavailable" instead.

Field	Type	Description
`success`	boolean	Always `true` when Genesis returns a response, including when the health verdict is unavailable.
`status`	string	Twin’s verdict: `ok`, `unverified`, or `systemic_failure`; `unavailable` means Genesis did not obtain a verdict from Twin.
`reason`	string	Operator-facing explanation from Twin, or the reason Genesis could not obtain a verdict.
`provider`	string or null	Embedding provider associated with Twin’s verdict. `null` when the verdict is unavailable.
`model`	string or null	Resolved embedding model associated with Twin’s verdict. `null` when the verdict is unavailable.

Mark provider configured endpoint

Secret-only providers (openai, anthropic, gemini) have no non-secret configuration PUT step. Saving their API key through the secret fields API already runs the common save finalize: it sets providers.<namespace>.admission to auto and, when no chat provider is selected and exactly one eligible provider remains, selects it. The Beta wizard still calls this endpoint once after the Secrets step succeeds; it re-admits the provider when its parameters are sufficient and adopts it for embeddings when no embedding pair is saved.

Method	Path	Description
`POST`	`/api/config/llm-providers/mark-configured`	Re-admit a secret-only provider whose stored parameters are sufficient, then adopt it for embeddings when no pair is saved. Requires `access_config_panel`.

Request body:

Field	Type	Description
`provider`	string	Provider name (for example `openai`, `anthropic`, `gemini`).

Response (LlmOperationResponse):

Field	Type	Description
`success`	boolean	`true` when the provider was marked configured.
`message`	string	Human-readable result (for example `openai marked configured` or `No stored secret found for openai`).

On Genesis Desktop, this endpoint accepts only the Genesis AI provider; requests for other providers return 403.

Ensure provider endpoints endpoint

Secret-only providers (openai, anthropic, gemini) persist credentials through the generic secret-fields API rather than a full provider-save PUT, so they skip the CUSTOM_ENDPOINTS registration those PUT routes perform as a side effect. The Beta wizard calls this endpoint once after the Secrets step succeeds and before the SPCS Approve External Access step, so there are egress hosts to approve.

Secret schema field endpoints

These routes back Config → Secrets and Advanced Settings secret-field editors. Plaintext values are stored in the managed secret store; references (secret_*, env_*, aws_*, and related forms) are stored in APP_CONFIG.

Method	Path	Description
`GET`	`/api/config/secret-fields/status`	List every `is_secret: true` schema field and whether a value is configured.
`GET`	`/api/config/secret-fields/status/{field_path}`	Return status for one field (for example `providers.openai.connection.api_key`).
`POST`	`/api/config/secret-fields/{field_path}/set-value`	Store a plaintext secret value and clear any custom reference on the field.
`POST`	`/api/config/secret-fields/{field_path}/set-reference`	Pin the field to an external or managed secret reference.
`POST`	`/api/config/secret-fields/{field_path}/use-default`	Reset the field to its schema `default_secret` reference.

`POST /api/config/secret-fields/{field_path}/set-value` provider credential guard

When field_path maps to a provider credential (for example providers.openai.connection.api_key) and the field already resolves to a configured credential, Genesis runs the same connection test used by the matching provider save before accepting the overwrite. First-time writes skip the guard because there is no prior credential to restore.

Status	When returned
`400`	Connection test rejected the submitted value (`failure_stage: "validation"`).
`503`	The rollback guard could not complete (for example another provider save holds the lock, or the pre-save snapshot failed; `failure_stage: "guard"`).
`404`	`field_path` is not a secret schema field.
`403`	Caller lacks secret access for the write.

On validation failure, the previous credential remains stored. On success, the response follows SetSecretValueResponse with success: true. Full provider-save routes also call the same registration helper, but treat failures as best-effort (they do not fail the whole config save). Callers whose sole purpose is endpoint registration should check the response success field instead of assuming registration succeeded.

Method	Path	Description
`POST`	`/api/config/llm-providers/{provider}/ensure-endpoints`	Register a provider’s default egress hosts in `CUSTOM_ENDPOINTS`. Requires `access_config_panel`.

Path parameter:

Field	Type	Description
`provider`	string	Wizard provider id (for example `openai`, `anthropic`, `gemini`). LiteLLM-routed providers register under a `litellm_{provider}` key — Genesis maps `anthropic` → `litellm_anthropic` and `gemini` → `litellm_gemini` before registration. Providers such as `openai`, `azureopenai`, `databricks`, and `litellm_proxy` use their bare provider name.

Response (LlmOperationResponse):

Field	Type	Description
`success`	boolean	`true` when egress hosts were registered.
`message`	string	Human-readable result (for example `Ensured endpoints for litellm_anthropic` or `Failed to register endpoints for openai. Check server logs and retry.`).

Provider admission endpoint

PUT /api/config/llm-providers/{provider}/admission changes the operator’s admission decision without deleting the provider connection or its embedding identity. Use deny to refuse provider use, or auto to permit use when its parameters are sufficient. The operation requires access_config_panel.

Field	Used by	Type	Values	Description
`admission`	Request body	string	`auto`, `deny`	Admission policy to save for this provider.

The response uses LlmOperationResponse with success and message fields.

LLM provider activation endpoint

POST /api/config/llm-providers/{llm_type}/activate switches the active chat provider without rewriting that provider’s saved model assignments. The Beta AI Providers page uses this route for Set Active on the Chat tab instead of PUT /api/config/models/main/assignments with use_defaults: true, which would reset tier overrides back to Genesis defaults.

Method	Path	Description
`POST`	`/api/config/llm-providers/{llm_type}/activate`	Activate an existing configured provider as the active chat provider. Requires `access_config_panel`.

Request body (LLMActivateRequest):

Field	Type	Default	Description
`force`	`boolean`	`false`	Force activation even when pre-activation checks would otherwise block it. The Beta UI sends `true` for Set Active.

Response (LlmOperationResponse):

Field	Type	Description
`success`	boolean	Whether activation completed.
`message`	string	Human-readable result. When `success` is `false`, the Beta New connection wizard Done step surfaces this text in an error toast instead of showing a success toast.

When activation succeeds, Genesis runs an AI-provider environment sync that applies the active provider’s saved Change Models tier assignments and clears stale LiteLLM process globals (LITELLM_MODEL, LITELLM_FAST_MODEL, LITELLM_PREMIER_MODEL, and the LiteLLM SDK api_base override) when switching between LiteLLM-engine providers (azureopenai, databricks, litellm_*, including litellm_proxy). It does not delete LITELLM_PROXY_* bootstrap env vars. For composite providers (litellm_*, including litellm_proxy), activation uses the saved provider configuration and does not persist llm_endpoint from the activation request. LiteLLM Proxy runtime calls resolve proxy_api_base from providers.litellm_proxy.connection.base_url in AppConfig on each request, so switching to or from litellm_proxy does not require a server restart. Runtime chat resolves main, fast, and frontier models from llm.active_provider assignments on each call.

LLM providers overview endpoint

GET /api/config/llm-providers/info backs the Stable AI Providers overview grid on Config -> AI Providers (/config/llm-providers/). It returns enhanced provider rows plus a summary of configured, effective, and active main and embedding providers. Each provider object in data includes:

Field	Type	Description
`llm_type`	string	Technical provider identifier (for example `openai`, `litellm_proxy`, `litellm_gemini`).
`display_name`	string	Human-readable provider title for UI cards (for example `LiteLLM Proxy`, `Other Providers`, `Google Gemini`).
`configured`	boolean	Whether the provider’s effective connection parameters are sufficient. Computed on each read; a stored configured marker is never read.
`admitted`	boolean	Whether operator policy permits this provider to be used. A denied provider remains distinct from an unconfigured provider.
`available`	boolean	Whether the provider can be selected in the current deployment.
`effective`	boolean	Whether this row is the provider `summary.effective_provider` names — a projection of configured state, not an observation of runtime routing. It does not always match `active`: `effective_provider` is the 5-value enum form, so an active `litellm_bedrock` row reports `active: true` with `effective: false`, while the aggregate `litellm` entry under `summary.providers` reports both as true.
`is_fallback`	boolean	Always `false`; retained for compatibility (Genesis no longer serves chat from a synthetic fallback provider).
`active`	boolean	Whether the provider is marked active in `APP_CONFIG`.
`key_preview`	string	Masked credential summary (for example `OAuth`, `Static headers`, or a redacted API key).
`llm_endpoint`	string	Saved or runtime endpoint URL when applicable.
`model_types`	string[]	Supported assignment types (`llm`, `embeddings`).
`supports_model_selection`	boolean	Whether the provider exposes model pickers in the UI.

If the runtime LLM state is unavailable, this endpoint still returns success: true with the stored provider rows enhanced for the response. Those rows retain configured: true, but report available: false, effective: false, and is_fallback: false because runtime availability and effectiveness could not be confirmed. Stored rows without llm_type are omitted, matching the healthy response path. When usable LiteLLM Proxy settings are loaded from genesis-config.yaml or legacy LITELLM_PROXY_* environment variables (and proxy_api_base plus the selected auth_mechanism credentials are complete), Genesis adds or updates a litellm_proxy row in data and may omit the generic litellm row so Helm-managed proxy deployments surface LiteLLM Proxy instead of Other Providers. For those deployments, summary.active_main_provider can report litellm_proxy while summary.configured_provider and summary.effective_provider remain litellm. When LiteLLM Proxy runtime configuration is incomplete or temporarily unavailable, the litellm_proxy row reports configured: false, available: false, and empty key_preview / llm_endpoint, and summary fields that would route chat through the proxy (active_main_provider, effective_provider, main_model_assignments, fallback_provider, and embedding selections on the proxy) are cleared so the overview does not show a stale active proxy. The exception is a concrete non-fallback litellm_<vendor> active provider (for example, litellm_bedrock or litellm_anthropic): its default remains in the summary even though effective_provider is normalized to litellm. If runtime config resolution fails, the response may include message: "LiteLLM Proxy runtime configuration is temporarily unavailable". The top-level summary object also includes:

Field	Type	Description
`configured_provider`	string or null	Provider configured as the primary chat provider in `APP_CONFIG` (`llm.active_provider`).
`effective_provider`	string or null	The active provider in normalized enum form — the same selection as `configured_provider`, not a separate runtime observation.
`active_main_provider`	string or null	Active main chat provider used for model assignments on the Chat tab.
`main_model_assignments`	object	Role-to-model map for `active_main_provider` (for example `default_chat`, `fast_model`).
`active_embedding_provider`	string or null	Active embedding provider, as the provider card id (for example `litellm_gemini`, not the stored `embedding.active_provider` value `gemini`).
`active_embedding_model`	string or null	Active embedding model (`embedding.active_model`).
`is_fallback_active`	boolean	Always `false`; retained for compatibility.
`fallback_provider`	string or null	Always `null`; retained for compatibility.
`environment_overrides`	object	Effective LLM-related environment-variable overrides.
`providers`	object	Per-provider status map keyed by provider id.

On Snowflake Native App / SPCS hosts, summary.configured_provider reflects llm.active_provider and wins over CORTEX_MODE. Genesis defaults chat to Cortex only when configured_provider is unset and Cortex is available. CORTEX_OVERRIDE no longer affects these state reads (legacy execution layers may still honor it until their cleanup). Provider selection is APP_CONFIG state written through the config API, Config -> AI Providers, or a mounted genesis-config.yaml; schema-bound environment defaults only seed unset fields. Startup migration aa011_cortex_active_override_heal restores a pre-fix install whose active provider was incorrectly forced to cortex when legacy EXT_SERVICE_CONFIG.model_config.main_provider still records the operator’s original choice. After startup migrations, Genesis invalidates the AppConfig snapshot, LLM runtime cache, and this overview cache so the response reflects the post-migration active provider on the same boot.

LiteLLM Proxy provider configuration endpoints

These routes back the LiteLLM Proxy card on Config -> AI Providers.

Method	Path	Description
`GET`	`/api/config/llm-providers/other/litellm-proxy`	Return current LiteLLM Proxy configuration status with masked credentials.
`POST`	`/api/config/llm-providers/litellm-proxy`	Create a LiteLLM Proxy configuration. See LiteLLM Proxy setup for first-save authentication behavior.
`PUT`	`/api/config/llm-providers/litellm-proxy`	Update an existing LiteLLM Proxy configuration.
`POST`	`/api/config/litellm-proxy/test-connection`	Test LiteLLM Proxy connectivity using provided credentials or the saved configuration.

When test_connection is true or model is omitted, Genesis calls the proxy /models endpoint to validate the connection and discover models. Genesis requests {proxy_api_base}/models directly; when the proxy responds with HTTP 301, 302, 303, 307, or 308, Genesis follows up to two same-origin redirects whose target path ends in /models or /models/. Cross-origin redirects and redirects to non-/models paths are refused so authentication headers are not forwarded to another host. Genesis accepts the standard OpenAI-compatible response shape {"data": [{"id": "..."}]}, a bare array of model objects such as [{"id": "..."}], or the temporary Ally-compatible response shape {"data": {"Items": [{"model_id": "..."}]}}. For model discovery, Genesis uses model_type when the proxy returns it. model_type: "embedding" places the model in the embeddings list, model_type: "chat" places it in the chat list, and providers that omit model_type fall back to the historical model-name heuristic. Discovery responses may include transport prefixes such as proxy/ or litellm_proxy/; Genesis strips those prefixes before persisting catalog entries, Model Universe technical names, and saved assignments, then re-applies litellm_proxy/ only when applying runtime environment variables for LiteLLM calls. LiteLLM Proxy sentinel permission ids such as all-team-models, all-proxy-models, and no-default-models are excluded from picker and universe technical-name lists; allow-all sentinels can still expand discovery against the /v2/model/info catalog when the proxy does not return explicit model ids. On a successful POST, or on a PUT with initialize_models: true or a non-empty model, Genesis runs enriched discovery (/models permissions intersected with /v2/model/info metadata when available), upserts the result into Model Universe with source_type: "discovered", and infers default tier assignments from alias plus underlying model names. An ordinary PUT that changes configuration or credentials is assignment-neutral. When persisting inferred assignments, Genesis preserves any tier the operator already pinned with assignment_sources[task_type] == "override" (set via PUT /api/config/models/main/assignments or the Change Models UI). Override tiers keep their persisted model ids across proxy credential rotation, partial first save, or other re-save that re-runs catalog inference; freshly inferred tiers are saved with assignment_sources: "default". Materialization failures are logged but do not block the config save. When the /models fetch itself fails (network error, HTTP error, or invalid response), Genesis skips Model Universe materialization on that attempt and preserves any previously materialized discovered rows rather than reconciling against an empty failed fetch. When discovery is complete, Genesis reconciles stale discovered rows that are no longer advertised; custom rows are never overwritten. When no chat provider is explicitly active in APP_CONFIG (active_provider_raw is null — the Snowflake Cortex zero-config default does not count), Genesis auto-activates LiteLLM Proxy on create, or on an assignment-intent update, only when discovery yields usable tier assignments or the request includes a non-empty model. A failed or empty discovery with no model saves credentials but leaves the provider inactive and omits the GenesisApp reload. On Snowflake Native App / SPCS, the first save often runs with test_connection: false while External Access is pending; when discovery fails with no assignments and no model, the response includes an SPCS-specific warning_message directing the operator to Approve External Access and use Continue setup for the provider. A later PUT with initialize_models: true after EAI approval can activate the proxy when models become reachable. Regardless of auto-activation, a successful save always publishes providers.litellm_proxy.admission: auto in the finalize step described under LLM provider save validation and rollback, so POST /api/config/llm-providers/{llm_type}/activate and the New connection wizard Done step can switch the provider active without a separate POST /api/config/llm-providers/mark-configured call. When auth_mechanism is oauth and the effective oauth_credential_policy is per_user_oauth, Genesis skips admin-side service-account /models discovery on save and test; runtime calls use each user’s browser OAuth grant. Genesis resolves the effective policy by merging the request payload, genesis-config.yaml (providers.litellm_proxy.settings.oauth_credential_policy, providers.litellm_proxy.settings.allow_user_oauth_fallback_for_non_interactive), saved metadata, and LITELLM_PROXY_OAUTH_CREDENTIAL_POLICY / LITELLM_PROXY_ALLOW_USER_OAUTH_FALLBACK_FOR_NON_INTERACTIVE (explicit env vars take precedence over file-backed values). When auth_mechanism is oauth but the OAuth client configuration is incomplete, or when auth_mechanism is static_headers but static_headers_json is missing, invalid JSON, not a JSON object, or an empty object, Genesis falls back to API-key discovery headers when proxy_api_key or LITELLM_PROXY_API_KEY is configured; otherwise model discovery is skipped for that save or test request. In service_account mode, Genesis resolves oauth_custom_header_descriptors from the merged provider metadata first and, when that list normalizes to empty, from oauth_custom_header_descriptors on the shared backing LiteLLM Proxy connection (litellm_proxy.shared). It applies the effective descriptor list to the OAuth token request (applies_to token_exchange), forwards downstream headers during client-credentials token acquisition, and sends downstream headers on proxy /models discovery, background model-catalog loading, and runtime proxy calls.

Helm-managed deployments can bootstrap the same provider settings from genesis-config.yaml (providers.litellm_proxy, providers.litellm_proxy.settings.oauth_credential_policy, and related fields). Genesis merges file-backed values with saved metadata and legacy LITELLM_PROXY_* environment variables at runtime, including LITELLM_PROXY_TRANSPORT, LITELLM_PROXY_OAUTH_CREDENTIAL_POLICY, LITELLM_PROXY_ALLOW_USER_OAUTH_FALLBACK_FOR_NON_INTERACTIVE, and LITELLM_PROXY_OAUTH_CUSTOM_HEADER_DESCRIPTORS_JSON.

LiteLLM Proxy configuration request fields

Field	Used by	Type	Default	Description
`proxy_api_base`	`POST`, `PUT`	string	required	Base URL of the LiteLLM Proxy server. Genesis strips any trailing slash before saving.
`auth_mechanism`	`POST`, `PUT`	`"api_key"` \| `"static_headers"` \| `"oauth"` \| `"none"`	`"api_key"`	Primary authentication mechanism for the proxy.
`transport`	`POST`, `PUT`	`"auto"` \| `"openai"` \| `"anthropic"`	`"auto"`	Wire transport for proxy chat turns. `auto` sends Anthropic-family models over native Anthropic `/v1/messages` and all other models over OpenAI-compatible `/chat/completions`; `openai` and `anthropic` pin one route. Caching occurs on both routes, but whether a proxy shares one upstream cache across routes and what usage details it reports are properties of the proxy, so measure your proxy before pinning. On both the Genesis lab proxy and the Railway proxy, streamed OpenAI-route calls returned full `prompt_tokens` and both cache counters, and extended thinking behaved the same on both routes; an earlier measurement on a different proxy build saw zero cache counters and under-reported `prompt_tokens`. On the Anthropic route, LiteLLM sends the credential as `x-api-key` unless it is an OAuth credential (which Genesis sends as `Authorization: Bearer`) or carries Anthropic’s own `sk-ant-oat` prefix. Pin `openai` if the proxy authenticates only on `Authorization` while this connection uses an API key or static headers, or if it exposes no Anthropic `/v1/messages` endpoint. One-shot utility completions with `response_format` (for example the blueprint recommendation wizard) stay on the OpenAI-compatible path regardless of this setting. Persisted as `providers.litellm_proxy.connection.transport`.
`proxy_api_key`	`POST`, `PUT`	string or null	`null`	API key used when `auth_mechanism` is `api_key`. Required on create when using API-key auth.
`static_headers_json`	`POST`, `PUT`	string or null	`null`	JSON object of static headers used when `auth_mechanism` is `static_headers`. Required on create when using static-header auth.
`oauth_authorization_url`	`POST`, `PUT`	string or null	`null`	OAuth authorization endpoint for per-user browser flows when `auth_mechanism` is `oauth`.
`oauth_token_url`	`POST`, `PUT`	string or null	`null`	OAuth token endpoint. Required when `auth_mechanism` is `oauth`.
`oauth_client_id`	`POST`, `PUT`	string or null	`null`	OAuth client ID. Required when `auth_mechanism` is `oauth`.
`oauth_client_secret`	`POST`, `PUT`	string or null	`null`	OAuth client secret. Required on create when `auth_mechanism` is `oauth`.
`oauth_token_endpoint_auth_method`	`POST`, `PUT`	`"client_secret_post"` \| `"client_secret_basic"`	`"client_secret_post"`	How client credentials are sent to the token endpoint.
`oauth_scopes`	`POST`, `PUT`	string or null	`null`	Optional comma- or space-delimited OAuth scopes.
`oauth_credential_policy`	`POST`, `PUT`	`"per_user_oauth"` \| `"service_account"` \| `"per_user_oauth_with_service_fallback"` or null	`null`	OAuth ownership policy. Required when `auth_mechanism` is `oauth`. Defaults to `per_user_oauth` when unset at runtime.
`allow_user_oauth_fallback_for_non_interactive`	`POST`, `PUT`	boolean	`false`	When `true`, allows temporary fallback to a user OAuth token for non-interactive runs if service-account execution is unavailable.
`oauth_custom_header_descriptors`	`POST`, `PUT`	array	`[]`	Supplemental custom header definitions for OAuth token exchange and downstream proxy calls. Each item includes `header_name` (required), optional `field_key`, `required`, `description`, `placeholder`, `is_secret` (default `true`), and `applies_to` (`"token_exchange"`, `"downstream"`, or `"both"`, default `"both"`). When descriptor settings are submitted for saving, malformed descriptors are rejected rather than silently skipped; `header_name` must be an HTTP header name, not a generated Genesis field key such as `oauth_header_x_tenant`. In `service_account` mode, Genesis resolves matching values from `oauth_service_account_header_values_json` and sends `token_exchange` headers on the OAuth token request, forwards `downstream` headers during client-credentials token acquisition, and sends `downstream` headers on proxy calls. When the saved provider list is empty after normalization, Genesis falls back to descriptors on the shared backing LiteLLM Proxy connection (`litellm_proxy.shared`).
`oauth_service_account_header_values_json`	`POST`, `PUT`	string or null	`null`	JSON object of admin-supplied header values used in `service_account` mode. Keys may be the descriptor `field_key` or a matching header-name alias (see LiteLLM Proxy OAuth setup). Submitted keys that match no effective descriptor are rejected. On `PUT`, omitted or `null` preserves existing saved values; a submitted object merges with the stored mapping (the UI may send only edited keys). Genesis stores matching values under their descriptor `field_key` and prunes values whose descriptor is removed. Runtime resolution also reads `providers.litellm_proxy.connection.oauth.service_account_header_values` from `APP_CONFIG` when present (dict form takes precedence over saved `_json` metadata).
`model`	`POST`, `PUT`	string or null	`null`	Optional primary model identifier from the proxy. Genesis stores the normalized bare proxy model id (transport prefixes `litellm_proxy/` and `proxy/` are stripped). When omitted, Genesis derives default chat assignments from the discovered model list.
`test_connection`	`POST`, `PUT`	boolean	`true`	Test the connection to the proxy before saving.
`initialize_models`	`PUT`	boolean	`false`	Explicitly request initial model-assignment setup. When `true`, Genesis may infer and save tier assignments from the discovered catalog, while an ordinary update remains assignment-neutral. Supplying a non-empty `model` also requests assignment handling.
`secret_updates`	`PUT`	object	`{}`	Stage managed-secret changes in the same candidate save. Keys may be `proxy_api_key`, `static_headers_json`, `oauth_client_secret`, or `oauth_service_account_header_values_json`; each value is `{ "mode": "value", "value": "..." }`, `{ "mode": "reference", "value": "..." }`, or `{ "mode": "default" }`. Do not send a secret field both here and as a direct request field.

On PUT, omitting auth_mechanism, transport, oauth_token_endpoint_auth_method, or allow_user_oauth_fallback_for_non_interactive preserves its stored value. Send a value explicitly to update it; schema defaults apply when no value is stored. For OAuth saves, Genesis checks secret references in backing-connection header values during prevalidation. Required headers used by service-account policies must have a value and resolve; unresolved required references reject the save. An optional unresolved reference is omitted from the shared backing connection, while its App Config reference remains available for later runtime resolution. The backing-connection writer checks references again during registration, so a secret that disappears after prevalidation can still cause a save failure after provider settings are committed; restore the secret and retry.

LiteLLM Proxy configuration response fields

GET /api/config/llm-providers/other/litellm-proxy also returns oauth_service_account_header_issue as a string or null. When a saved shared service-account configuration cannot send an OAuth header, the field explains the descriptor or missing required value that needs attention; it does not expose header values. The AI Providers status panel displays this issue. Before returning, GET /api/config/llm-providers/other/litellm-proxy merges safe runtime LiteLLM Proxy settings from genesis-config.yaml and legacy LITELLM_PROXY_* environment variables into the saved metadata payload (non-secret display fields such as proxy_api_base, auth_mechanism, transport, OAuth URLs and client ID, oauth_credential_policy, allow_user_oauth_fallback_for_non_interactive, oauth_custom_header_descriptors, and model; masked markers for configured secrets; oauth_service_account_header_value_keys derived from runtime providers.litellm_proxy.connection.oauth.service_account_header_values when present, otherwise saved oauth_service_account_header_values_json). When the merged runtime config is complete for the selected auth_mechanism, Genesis may set configured: true even when UI metadata alone would not. When runtime config resolution fails, Genesis sets configured: false and configuration_status: "unavailable" instead of returning stale saved fields. The response includes configured, configuration_status ("unavailable" when runtime config cannot be resolved; omitted when config loads normally), provider, proxy_api_base (admins only), model, auth_mechanism, transport, masked secret markers (proxy_api_key_masked, static_headers_json_masked, oauth_client_secret_masked, oauth_service_account_header_values_json_masked), the non-secret OAuth fields above, oauth_custom_header_descriptors, oauth_service_account_header_value_keys (sorted field_key entries without exposing secret values), oauth_service_account_header_issue, and allow_user_oauth_fallback_for_non_interactive. Non-admin callers receive a sanitized subset of these fields (including transport, oauth_custom_header_descriptors, and the masked markers, but not proxy_api_base or raw secret values) so per-user OAuth flows can show required custom headers without granting full provider configuration access. The Reconfigure form in Config -> AI Providers keeps the last saved descriptor list when oauth_custom_header_descriptors is omitted from the status payload, falls back to the backing LiteLLM Proxy connection copy when the field is present but normalizes to an empty array, and uses oauth_service_account_header_value_keys to show that a service-account header value is already configured even when the backing connection copy does not expose shared defaults.

LiteLLM Proxy configuration operation response fields

POST /api/config/llm-providers/litellm-proxy and PUT /api/config/llm-providers/litellm-proxy return LlmOperationResponse:

Field	Type	Description
`success`	boolean	Whether the configuration save succeeded.
`message`	string	Primary result message. When per-user OAuth defers admin-side discovery, this may include deferred-discovery guidance.
`warning_message`	string or null	Optional non-blocking warning. The AI Providers UI shows this as a warning toast after save. Populated when discovery failed with no usable assignments and no `model` (create: saved but not activated; update: existing defaults kept), when SPCS External Access is likely pending (discovery failed without an effective connection test; a changed credential may require a test even when `test_connection` is `false`), or when a recovery activation attempt failed after update. Omitted when discovery succeeded, an explicit `model` was supplied, or assignments were inferred from a `models_only` discovery result.
`connection_check`	object or null	Access check for the save, independent of model-assignment readiness. `status` is `passed`, `failed`, `deferred`, or `not_requested`; `catalog_empty` is `true` when access succeeded but the proxy advertised no usable models; `reason` may identify why the check was deferred or unavailable.

For PUT, initialize_models: true explicitly requests initial model-assignment setup. Routine configuration or credential updates leave existing assignments unchanged unless a non-empty model is supplied. The save validates the complete candidate, including any secret_updates, before committing it; a failed candidate save leaves the previously stored proxy credential in place.

LiteLLM Proxy connection test request fields

For an Anthropic-family probe, Genesis removes one trailing /v1 from the configured proxy base URL, then posts to /v1/messages.

Field	In	Type	Default	Required	Description
`proxy_api_base`	body	string or null	`null`	No	LiteLLM Proxy base URL. When `null`, Genesis uses the saved configuration.
`proxy_api_key`	body	string or null	`null`	No	LiteLLM Proxy API key. When `null`, Genesis uses the saved configuration.
`auth_mechanism`	body	`"api_key"` \| `"static_headers"` \| `"oauth"` \| `"none"` or null	`null`	No	Optional auth mechanism override for the test request.
`transport`	body	`"auto"` \| `"openai"` \| `"anthropic"` or null	`null`	No	Optional wire transport override for the test request. When `null`, Genesis uses the saved configuration. With `auto`, Genesis resolves the probe route from the model family.
`static_headers_json`	body	string or null	`null`	No	JSON object of static headers when testing `static_headers` auth.
`oauth_token_url`	body	string or null	`null`	No	OAuth token endpoint when testing `oauth` auth.
`oauth_client_id`	body	string or null	`null`	No	OAuth client ID when testing `oauth` auth.
`oauth_client_secret`	body	string or null	`null`	No	OAuth client secret when testing `oauth` auth.
`oauth_token_endpoint_auth_method`	body	`"client_secret_post"` \| `"client_secret_basic"` or null	`null`	No	Token-endpoint client authentication method.
`oauth_scopes`	body	string or null	`null`	No	OAuth scopes used during service-account token acquisition.
`oauth_credential_policy`	body	`"per_user_oauth"` \| `"service_account"` \| `"per_user_oauth_with_service_fallback"` or null	`null`	No	OAuth ownership policy for the test request.
`oauth_custom_header_descriptors`	body	array or null	`null`	No	Optional supplemental OAuth header descriptors (same shape as configuration requests). When omitted or `null`, Genesis leaves the field unset so the test inherits descriptors from saved provider metadata merged with runtime `genesis-config.yaml` / `LITELLM_PROXY_*` settings. Send an explicit empty array (`[]`) only to test without request-supplied descriptors — Genesis does not substitute saved descriptors for that field. When the effective descriptor list normalizes to empty, Genesis falls back to descriptors on the shared backing LiteLLM Proxy connection (`litellm_proxy.shared`).
`oauth_service_account_header_values_json`	body	string or null	`null`	No	JSON object of service-account header values keyed by descriptor `field_key`. Genesis merges submitted values with saved or runtime config when resolving headers for the test.

When request fields are omitted, POST /api/config/litellm-proxy/test-connection fills gaps from saved provider metadata merged with the same runtime LiteLLM Proxy config used for GET display. In service_account OAuth mode, Genesis sends descriptor values with applies_to token_exchange on the OAuth token request, forwards applies_to downstream headers during client-credentials token acquisition, and sends downstream headers on the proxy /models probe. When the effective transport is anthropic, Genesis also probes the configured model (from saved assignments when available, otherwise the first model returned by /models) via /messages. When the effective transport is auto, Genesis resolves the probe from the configured model or the models returned by the proxy, and probes /messages when an Anthropic-family model is among the candidates.

LiteLLM Proxy connection test response

POST /api/config/litellm-proxy/test-connection returns the standard success / message payload. When auth_mechanism is oauth and the effective oauth_credential_policy is per_user_oauth, Genesis returns success: true with a message that service-account testing was skipped and may include details.discovery_deferred: true because runtime calls authenticate with each user’s browser grant instead of client credentials. When transport is anthropic and the probe succeeds, the success message notes that the Anthropic /messages probe succeeded. Submitted secret references are resolved before testing the proxy API key, static headers JSON, OAuth client ID, and OAuth client secret. The OAuth client secret is not read when the effective policy is per_user_oauth. If a submitted reference cannot be resolved, the test fails with details.reason: "credentials". Failed tests may include details.reason to identify the failure category:

`details.reason`	Meaning
`credentials`	The proxy rejected credentials with HTTP 401 or 403, or a submitted secret reference could not be resolved.
`certificate`	TLS certificate verification failed because the proxy certificate chain is not trusted.
`wrong_endpoint`	The proxy returned HTTP 404, non-JSON content, or JSON that is not a supported model list.
`token_endpoint`	The OAuth token endpoint request failed.

Embedding configuration endpoints

These routes back the Embeddings tab on Config -> AI Providers and are independent from the main chat-provider assignments. Persisted active values are stored in APP_CONFIG at embedding.active_provider and embedding.active_model. Per-provider embedding preferences (saved during setup before activation) are stored at providers.<provider>.models.embedding_model. GET /api/config/models/embeddings/config is read-only and accepts either access_config_panel or view_model_config. The PUT route and the other embedding model routes require access_config_panel. After a committed provider-configuration change, Genesis resends the current embedding identity when Twin’s lineage tool is registered; unchanged identities can be refreshed without a document re-index. See Digital Twin reload behavior.

Method	Path	Description
`GET`	`/api/config/models/embeddings/config`	Return the current active embedding provider and normalized model name. With the optional `provider` query parameter, also return that provider’s saved preference (`provider_model`), the model activating it would use (`activation_model`), and whether it is the active embedding provider (`is_active`); an unknown or blank `provider` is rejected with `422`.
`PUT`	`/api/config/models/embeddings/config`	Save an embedding provider/model selection. With `activate: true` (default), switch the global active embedding and start background re-indexing when replacing an existing active embedding. With `activate: false`, persist `providers.<provider>.models.embedding_model`; first-save adoption may also activate it when no identity exists, without reindexing an older embedding space. With `apply_if_active: true`, the server applies the selection only if that provider is active at save time; otherwise it saves a provider preference, which may also be adopted when no identity exists. `allow_reindex: false` makes an active identity change return a confirmation-required response before saving.
`POST`	`/api/config/llm-providers/embedding-config/test`	Run an embedding configuration test using the embedding config request body.
`GET`	`/api/config/models/embeddings/models/{provider}`	Return embedding models for one provider. Supports `with_display_names` (query, boolean, default `true`).
`GET`	`/api/config/models/embeddings/stranded-corpora`	Return on-disk document corpora whose recorded embedding identity is not active or cannot be reconciled safely.
`GET`	`/api/config/models/embeddings/reindexing-status`	Return consolidated document and harvester re-indexing progress.

POST /api/config/llm-providers/embedding-config/test accepts the embedding configuration request body and returns success, message, optional warning, and dimensions. The live embedding request has a 15-second timeout. The effective embedding identity is resolved in this order:

A complete embedding.active_provider plus embedding.active_model pair from APP_CONFIG is authoritative. EMBEDDING_PROVIDER and EMBEDDING_MODEL are default_env_var seeds for those fields — applied only while no value is stored, and outranked by any stored pair. LITELLM_EMBEDDING_MODEL is no longer read as an input.
When no complete active pair exists, an eligible Cortex mode override may provide the runtime identity.
Otherwise, the identity is unset or incomplete. Genesis does not infer an OpenAI fallback.

Document-index writes fail closed when the identity cannot be used. The API returns HTTP 409 with error_type: "embedding_not_configured" when no identity resolves, or error_type: "provider_not_configured" when the selected provider lacks required configuration or credentials. GET /api/config/models/embeddings/models/{provider} returns data.provider, data.models, and data.with_display_names. When building the list, Genesis reads only persisted embedding configuration for the requested provider — it does not inject the globally inferred OpenAI default when another provider is active, so the active embedding model does not leak into unrelated provider pickers. When with_display_names=true, each model is an object with technical_name and display_name (provider prefixes stripped from technical_name). When with_display_names=false, data.models is a string array of normalized technical identifiers. For live-discovery proxy providers (litellm_proxy), Genesis also returns data.discovery_status ("ok" | "empty" | "error") and data.discovery_error (string or null) using the same semantics as GET /api/config/models/main/models/{provider}. When Model Universe already contains materialized litellm_proxy rows, Genesis serves the picker from those entries instead of calling the proxy on every request; live /models discovery is used only before the first materialization or when the universe list is empty. Recommended-default catalogs are still bypassed for these pickers. discovery_status: "empty" reflects what was advertised or materialized before assignment injection.

Stranded embedding corpora response

GET /api/config/models/embeddings/stranded-corpora returns success and a data array. The array contains one row per reconciled recorded identity plus one row per unreadable collection directory.

Field	Type	Description
`provider`	string	Recorded provider; empty when no provider could be read.
`model`	string	Primary recorded model (the Chroma record when complete); empty when no complete model could be read. For `conflict`, this and `provider` identify one record while the `conflicting_*` fields identify the other.
`status`	`"proposable"` \| `"conflict"` \| `"indeterminate"` \| `"unreadable"`	Whether the corpus can be offered for adoption and, when it cannot, why.
`conflicting_provider`	string	Second recorded provider when `status` is `conflict`; empty otherwise.
`conflicting_model`	string	Second recorded model when `status` is `conflict`; empty otherwise.
`collection_names`	string[]	Collection directories carrying this identity, or the unreadable directory.
`document_count`	integer	User documents in the row’s collections, excluding system-written records.

proposable means Chroma metadata carries a complete identity with no contradictory sidecar record. conflict means two complete records disagree. indeterminate means no complete provider/model pair was recorded; Genesis never invents the missing model. unreadable means no trustworthy identity could be extracted.

Test an embedding model without saving

POST /api/config/llm-providers/embedding-config/test requires access_config_panel. Send provider and model, or provider with use_defaults: true; a model-only request resolves its provider through the existing embedding resolver. The route uses already saved provider credentials. It does not test an unsaved API key, save a model preference, activate a provider, or start reindexing.

{"provider": "openai", "model": "text-embedding-3-small"}

The response carries success, message, and dimensions. Non-Cortex providers generate a small embedding through the existing provider transport on each test; the live request may consume provider quota and incur charges. The Cortex branch checks Snowflake availability and obtains catalog dimensions; it does not execute a sample embedding, so its successful response alone is not a full embedding inference check. Provider failures remain visible in message.

Embedding configuration request and response fields

Field	Used by	Type	Default	Description
`provider`	`GET /api/config/models/embeddings/config` response or optional query parameter; `PUT /api/config/models/embeddings/config` request body	`string` in responses; `string or null` in requests	`null` in requests	Embedding provider to use. On `GET`, the active pair remains in `provider` and `model`; supplying this parameter adds the requested provider’s preference, activation model, and active status. On `PUT`, it is optional when Genesis can auto-detect the provider from `model`.
`model`	`GET /api/config/models/embeddings/config` response `model`; `PUT /api/config/models/embeddings/config` request body	`string` in responses; `string or null` in requests	`null` in requests	Embedding model identifier. `GET` returns the normalized picker value with any provider prefix removed. For LiteLLM Proxy this remains the bare proxy model id (`litellm_proxy/` and `proxy/` transport prefixes are stripped on save and read).
`use_defaults`	`PUT /api/config/models/embeddings/config` request body	`boolean`	`false`	Use the provider’s default embedding model. Requires `provider`.
`test_before_save`	`PUT /api/config/models/embeddings/config` request body	`boolean`	`true`	Test the embedding configuration before saving. Genesis pre-checks credentials for providers whose headless credential shape is known. Databricks is ready with either PAT plus a workspace URL, or OAuth plus a resolvable M2M `service_principal` connection; a U2M-only OAuth connection is insufficient for embeddings. A failed live test blocks the save. When `false`, the live probe is skipped, but activation still rejects a provider whose required headless credentials are unavailable.
`activate`	`PUT /api/config/models/embeddings/config` request body	`boolean`	`true`	When `true`, switch the global active embedding to this provider/model and reindex when replacing an existing active embedding. When `false`, persist `providers.<provider>.models.embedding_model`; if no identity exists, the first-save adoption rule may also make this the active identity without reindexing an older embedding space.
`provider` (query)	`GET /api/config/models/embeddings/config` query string	`string`	omitted	Scope the response to one provider. Any recognized spelling is accepted and normalized (for example `gemini` or `litellm_gemini`); an unknown or blank value is rejected with `422`.
`provider_model`	`GET /api/config/models/embeddings/config` response	`string or null`	`null`	The requested `provider`’s saved embedding-model preference only, with any provider prefix removed: `providers.<provider>.models.embedding_model`, found under any spelling of that provider. `null` when no `provider` was requested or it has no saved preference.
`activation_model`	`GET /api/config/models/embeddings/config` response	`string or null`	`null`	The model activating the requested `provider` would use, with any provider prefix removed: its saved preference under any spelling, otherwise its packaged or catalog default — the same resolution Set Active for Embeddings uses. `null` when no `provider` was requested or none resolves.
`is_active`	`GET /api/config/models/embeddings/config` response	`boolean or null`	`null`	Whether the requested `provider` is the persisted active embedding provider, compared across spellings. A provider served only by a mode override (for example Cortex zero-config) reads as `false`, matching what an `apply_if_active` save decides. `null` when no `provider` was requested; `false` for a recognized provider that is not active.
`reset_to_default`	`PUT /api/config/models/embeddings/config` request body	`boolean`	`false`	Reset to the provider’s packaged default embedding model: ignores `model` and the saved preference, applies the default and records it as the provider’s saved model. Requires `provider`. Refused (`success: false`, nothing changed) when the provider has no packaged default or the default is not accepted. If the switch succeeds but the saved model cannot be recorded, the response is successful with `details.warning`.
`apply_if_active`	`PUT /api/config/models/embeddings/config` request body	`boolean`	`false`	Let the server decide: when the provider is the persisted active embedding provider at save time, apply the model to the global identity; otherwise save it as the provider’s preference only. `activate` is ignored. The response reports `details.applied` and `details.reindex_required`. Cannot be combined with `reset_to_default`.
`allow_reindex`	`PUT /api/config/models/embeddings/config` request	`boolean`	`true`	With `apply_if_active`, set to `false` until the user confirms an active-model change. The server refuses a changed active identity before writing and returns `success: false`, `details.confirmation_required: true`, and `details.current_model`; retry with `true` after confirmation. Inactive preference saves and equivalent active identities do not require confirmation.

PUT /api/config/models/embeddings/config requires either model or use_defaults: true. If provider is omitted while model is present, Genesis attempts to infer the provider from the model identifier. When activate: false, the response includes details.reindex_required: false. details.activated is normally false, but is true when first-save adoption successfully names the first global embedding identity. With apply_if_active: true, details.applied reports whether Genesis applied the selection to the active identity; if allow_reindex: false would change that identity, the request returns details.confirmation_required: true and details.current_model without saving. Retry with allow_reindex: true after confirmation. When activating a provider later (for example via Set Active for Embeddings), Genesis resolves the embedding model in this order: saved providers.<provider>.models.embedding_model, then the packaged yaml default, then recommended/available models from Model Universe.

First-save embedding adoption

Provider configuration saves that persist an embedding preference, and PUT /api/config/models/embeddings/config with activate: false, may return the optional top-level embedding_adoption field. This is the outcome of a one-time attempt to adopt the saved provider/model when no global embedding identity exists. It is separate from the standing embedding identity state returned by provider-overview APIs.

Value	Meaning
`adopted`	The saved provider/model became the first active embedding identity.
`refused_corpus_present`	Existing user documents made automatic adoption unsafe.
`refused_evidence_unreadable`	Genesis could not prove that the existing corpus was empty.
`refused_not_eligible`	The saved provider/model was not eligible for adoption.
`refused_save_failed`	Persisting the active pointer failed.
`refused_busy`	A harvester or embedding operation made adoption temporarily unsafe; the caller may retry.
`pointer_already_set`	A persisted active embedding identity already exists.
`override_active`	A mode override or an already-effective identity is in force, so Genesis did not write a new pointer.

GET /api/config/models/embeddings/config returns the effective runtime provider and model after coherence correction — for example, a Cortex-only catalog model paired with a non-Cortex provider in a Cortex-capable deployment resolves to provider: cortex. At server startup, Genesis also runs a one-time embedding connection smoke test (5-second timeout for LiteLLM-routed providers) and logs failures without blocking boot.

`PUT /api/config/models/embeddings/config` response details

This route returns the generic OperationResponse shape with top-level success, message, optional details, and optional embedding_adoption when a save triggers a first-identity adoption attempt.

Field	Type	Description
`details.provider`	string or null	Provider that Genesis saved or attempted to save.
`details.model`	string or null	Model that Genesis saved or attempted to save.
`details.activated`	boolean	For the legacy `activate: false` path, whether first-save adoption also made the saved preference the active embedding identity. Omitted on the regular `activate: true` path.
`details.applied`	boolean	For `apply_if_active: true`, whether Genesis applied the selection to the active embedding identity rather than saving only a provider preference.
`details.reindex_required`	boolean	Whether existing indexed content needs embedding re-indexing. It is `false` for preference-only saves and may be `true` when the active embedding changes.
`details.confirmation_required`	boolean	For an `apply_if_active` save with `allow_reindex: false`, whether an active embedding change was refused pending caller confirmation.
`details.current_model`	string or null	Current active model returned when `confirmation_required` is `true`; use it to explain the proposed change before retrying with `allow_reindex: true`.
`details.warning`	string or null	Optional warning emitted during save/apply — for example re-index guidance, or when the saved embedding provider differs from `llm.active_provider` and has no configured API key (common when `test_before_save` is `false`).
`details.phase`	string or null	Save/apply phase for a failure or in-progress condition, such as `operation_in_progress` or `harvester_busy`.
`details.provider_changed`	boolean	Whether the provider changed versus the current saved config.
`details.harvester_restarted`	boolean	Whether Genesis restarted the Harvester immediately after a provider change.
`details.harvester_running`	boolean	Present when the request is rejected because the Harvester is still running.
`details.operation_in_progress`	boolean	Whether a background embedding re-index operation is active.
`details.operation_id`	string or null	Identifier of the background embedding re-index operation, when one was started or is already running.

PUT /api/config/models/embeddings/config writes the embedding identity to APP_CONFIG, and GET reads it back from there; EMBEDDING_PROVIDER / EMBEDDING_MODEL act only as seeds for unset fields. Manage embeddings from Config -> AI Providers -> Embeddings, from this endpoint, or through genesis-config.yaml — the same three surfaces that configure a chat provider. Saved values take precedence over env seeds; GENESIS__* overrides pin effective values while set.

Main-provider model list endpoint

GET /api/config/models/main/models/{provider} backs the Change Models modal on Config -> AI Providers. It returns the model lists used by the per-tier pickers (Premiere, Main, Fast).

Query parameter	Type	Default	Description
`model_type`	string	`"all"`	Filter hint passed through to the service layer. The UI requests `"all"`.
`with_display_names`	boolean	`true`	When `true`, each model entry is an object with `technical_name` and `display_name`. When `false`, lists are string arrays of normalized technical identifiers.

data always includes provider, type (echo of model_type), models, main_models, fast_models, frontier_models, and with_display_names. For providers other than live-discovery proxies, Genesis builds these lists from Model Universe, recommended defaults, and the provider’s saved assignments (the active assignment is injected when missing so the picker can show the current value). For live-discovery proxy providers (litellm_proxy), Genesis prefers materialized Model Universe rows (source_type: "discovered") when present. Opening Change Models or an embedding model picker also calls POST /api/config/model-universe/refresh?provider=litellm_proxy so models added to the proxy after the connection was saved appear without re-saving that connection; tier assignments are not re-inferred. The refresh is throttled per process by llm.proxy_universe_refresh_interval_seconds (default 300). When the universe is empty, Genesis idempotently runs ensure_litellm_proxy_universe_materialized() on this read path (discovery plus upsert when no litellm_proxy rows exist yet) before building the picker lists. If materialization cannot reach the proxy, Genesis falls back to live /models discovery. Recommended-default catalogs are still bypassed. The same discovered set is used for every tier (main_models, fast_models, and frontier_models). The saved assignment may still be injected into those tier lists for picker continuity even when the proxy did not advertise that model. When no tier assignments are persisted yet, Genesis read-only infers premiere/main/fast technical defaults from the materialized universe for picker preselection; this inference does not persist or activate the provider. When with_display_names=true, each litellm_proxy model object may include underlying_model (string or null) — the backend model id from proxy catalog metadata when known. Proxy-only fields on data:

Field	Type	Description
`discovery_status`	`"ok"` \| `"empty"` \| `"error"`	Whether live `/models` discovery succeeded. `"empty"` reflects what the proxy advertised before assignment injection — a saved assignment can still appear in `main_models` when the proxy returned `data: []`.
`discovery_error`	string or null	One-line failure summary when `discovery_status` is `"error"` (for example `HTTP 404` or `ConnectError: ...`). `null` when discovery succeeded or returned an empty list.
`discovered_models`	string[]	Technical model names advertised or materialized on this fetch, before assignment injection. The UI uses this set to flag stale selections that are not in the live list.

Model Universe list item fields

GET /api/config/model-universe/models returns data[] items with the standard model metadata plus proxy-specific fields when present:

Field	Type	Description
`source_type`	`"recommended"` \| `"custom"` \| `"discovered"`	How the row entered the universe. LiteLLM Proxy save-time materialization uses `"discovered"`.
`underlying_model`	string or null	Backend model id behind a proxy alias (for example `global.anthropic.claude-opus-4-8`). `null` for non-proxy providers or when enrichment was unavailable.
`proxy_model_info`	object or null	Raw proxy catalog metadata block (token caps, `litellm_provider`, capability flags). `null` for non-proxy models.

Discovered LiteLLM Proxy rows are reconciled on later saves when discovery is complete; custom rows are never overwritten by materialization.

`POST /api/config/model-universe/test-model`

Test a model using the provider’s saved credentials. The llm mode runs a minimal completion; embedding sends one embedding request with a 15-second timeout and returns the vector dimensions in details on success. Each call spends one request against the provider and requires access_config_panel.

JSON field	Type	Required	Default	Description
`provider`	string	yes	—	Genesis provider name, such as `openai` or `litellm_bedrock`.
`technical_name`	string	yes	—	Technical model identifier to test.
`model_type`	`"llm"` or `"embedding"`	no	`"llm"`	Select a completion test or an embedding request.

The response contains success (boolean), message (string), and optional details (object). For a successful embedding test, details.dimensions is the embedding vector size.

{
  "provider": "openai",
  "technical_name": "text-embedding-3-small",
  "model_type": "embedding"
}

`POST /api/config/model-universe/refresh`

Re-discover a live-discovery proxy provider’s models and update Model Universe. The Change Models modal, Embeddings model step, and new-connection models step call this automatically for litellm_proxy. Static-catalog providers return HTTP 400. When /models discovery fails, Genesis returns success: false with message Could not refresh the model list; the saved list is unchanged and leaves existing materialized rows untouched.

Query parameter	Type	Required	Description
`provider`	string	yes	Live-discovery proxy provider id (currently `litellm_proxy`).

Response fields:

Field	Type	Description
`success`	boolean	Whether the refresh completed without error. May be `false` when `/models` discovery fails or when throttled after a failed attempt inside the window.
`message`	string	Human-readable outcome (for example `Refreshed: 3 added, 0 removed`, `Skipped: models were refreshed recently`, or `Could not refresh the model list; the saved list is unchanged`).
`changed`	boolean	Models were added or removed. Clients invalidate cached chat and embedding model lists when `true`; metadata-only updates do not set this.
`throttled`	boolean	Skipped because a refresh already ran inside `llm.proxy_universe_refresh_interval_seconds` (default `300`). Set the interval to `0` to disable throttling.
`inserted`	integer	Models added to the universe.
`removed`	integer	Models removed from the universe.

Tier assignments are not re-inferred — only the universe snapshot is refreshed.

Provider seed defaults for main assignments

GET /api/config/models/main/defaults/{provider} returns the technical and display default model map Genesis uses when Change Models resets a provider to shipped defaults or when PUT /api/config/models/main/assignments is called with use_defaults: true. A PUT /api/config/models/main/assignments that sets default_chat also assigns it to supervisor, harvester, and knowledge_server, except a role whose assignment_sources entry is default (every role, under use_defaults: true without sources), which keeps its catalog seed. For databricks and cortex those seeds equal default_chat. The shipped OpenAI main chat default is gpt-6.1-sol; its catalog seeds fast_model, harvester, and knowledge_server on gpt-6-luna. The shipped Azure OpenAI defaults are the gpt-5.5 deployment name for every role except fast_model, which is gpt-5-mini. Startup reconciliation applies the same seeds to roles still managed by defaults, so save and restart agree. For litellm_openai, the shipped default_chat is openai/gpt-6.1-sol and fast_model is openai/gpt-6-luna; both are included in this endpoint’s provider default map. For litellm_anthropic, default_chat and premier_model are anthropic/claude-opus-5-5 and fast_model is anthropic/claude-haiku-4-5; for litellm_bedrock they are global.anthropic.claude-opus-5-5 and global.anthropic.claude-haiku-4-5-20251001-v1:0.

Main-provider assignment fields

The main-provider assignment endpoints expose model tier assignments, source metadata, and a provider-level inherited chat tier:

GET /api/config/models/main/assignments
GET /api/config/models/main/assignments/{provider}
PUT /api/config/models/main/assignments

GET /api/config/models/main/assignments is read-only and accepts either access_config_panel or view_model_config. The provider-specific read and the PUT route require access_config_panel.

Field	Used by	Type	Default	Description
`default_model_tier`	`GET` response `data.default_model_tier`; `PUT` request body	`"frontier" \| "main" \| "fast" \| null`	`null` in requests	Provider-level inherited chat tier used whenever the agent and thread do not set an explicit tier override.
`assignment_sources`	`GET` response `data.assignment_sources`; `PUT` request body	`dict[string, "default" \| "override"]`	`{}` in requests	Per task-type source metadata (for example `default_chat`, `fast_model`, `premier_model`). `"default"` means Genesis-managed (inferred or shipped defaults). `"override"` means operator-managed via Change Models or an explicit `PUT`. On `PUT`, omit a task type to let Genesis derive the source by comparing `assignments` to provider defaults. When `use_defaults: true` and `assignment_sources` is omitted, all capabilities are saved as `"default"`. Override tiers survive `POST` / `PUT /api/config/llm-providers/litellm-proxy` re-saves that re-run catalog inference.

Each GET assignment response reads the active provider, assignments, source metadata, inherited chat tier, and capabilities from one current APP_CONFIG snapshot. These fields therefore describe the same configuration state instead of mixing values from separate reads or a stale response cache. When PUT /api/config/models/main/assignments targets a provider that does not yet have saved credentials, Genesis can still persist the submitted assignments and default_model_tier without changing the current main_provider. Configure that provider’s credentials and activate it later to make the saved assignments live. A successful assignment save is available to the running process immediately; it does not require a server restart. Saving assignments without activation still leaves the current main_provider unchanged. When provider is litellm_proxy, Genesis calls ensure_litellm_proxy_universe_materialized() before saving assignments so underlying-model metadata is available for the Change Models picker even when the universe was never populated by a prior provider save. On PUT /api/config/models/main/assignments, Genesis validates each non-empty assignment value (after display-name conversion) against LiteLLM’s provider-prefix routing rules before persisting. Bare model names with no / (for example gpt-5 or an Azure deployment name) are accepted — the active provider strategy prefixes them at request time. Slash-prefixed values are accepted only when the first segment is a recognized LiteLLM provider prefix (for example azure/gpt-5 or bedrock/global.anthropic.claude-opus-5). Values whose first segment is not a recognized provider — such as an endpoint hostname genesis-azure-1/gpt-5 — are rejected with HTTP 400 and a message naming the offending task type and model value, for example:

Model assignment 'default_chat'='genesis-azure-1/gpt-5' is not routable: 'genesis-azure-1' is not a recognized LiteLLM provider. Use a bare model name or prefix it with a valid provider (e.g. 'azure/<deployment>', 'bedrock/<model>').

Empty or null assignment values are skipped. This check is not applied when provider is litellm_proxy, because proxy model aliases are admin-defined free-form strings that may contain / yet still resolve via the proxy’s own alias table.

Context graph scanner model tier

Twin’s context-graph scanner uses a chat model for bulk description generation. Genesis stores the tier in llm.twin_scanner_model_tier (default fast) and resolves it against the active provider’s tier assignments (fast → fast_model, main → default_chat, frontier → premier_model, falling back to the provider’s main chat model when the chosen tier has no assignment).

Method	Path	Description
`GET`	`/api/config/models/twin-scanner-tier`	Return the active scanner tier and the effective model per tier for the active provider.
`PUT`	`/api/config/models/twin-scanner-tier`	Persist a new tier and push the resolved model to Twin immediately. Requires `access_config_panel`.

PUT request body:

Field	Type	Default	Description
`tier`	`"fast" \| "main" \| "frontier"`	— (required)	Chat-model tier the scanner uses on the next scan.

GET and PUT responses include success, tier, and models — a map of each tier name to the effective model id for the active provider (values may be null when the provider or its assignments cannot be resolved).

SCIM provisioning endpoints

These endpoints implement Phase 1 inbound SCIM provisioning. They are mounted outside the authenticated /api surface at /scim/v2/... and authenticate with Authorization: Bearer <scim_token> using the SCIM bearer token instead of a Genesis PAT. For Databricks App behavior across these routes and the admin endpoints, see SCIM admin configuration endpoints. A machine-readable SCIM OpenAPI artifact is maintained in docs/features/scim-openapi.yaml in the Genesis repository. Genesis intentionally advertises ETag support as false for this release; clients should not rely on If-Match concurrency semantics.

SCIM metadata endpoints

Method	Path	Description
`GET`	`/scim/v2/ServiceProviderConfig`	Return SCIM service-provider capability metadata.
`GET`	`/scim/v2/ResourceTypes`	Return the supported SCIM resource types: `User` and `Group`.
`GET`	`/scim/v2/Schemas`	Return the supported SCIM schema metadata.

SCIM user and group resource endpoints

Method	Path	Description
`POST`	`/scim/v2/Users`	Create or upsert a SCIM-managed user.
`GET`	`/scim/v2/Users`	List SCIM-managed users.
`GET`	`/scim/v2/Users/{user_id}`	Return one SCIM-managed user resource.
`PUT`	`/scim/v2/Users/{user_id}`	Replace a SCIM-managed user resource.
`PATCH`	`/scim/v2/Users/{user_id}`	Apply supported SCIM patch operations to a user.
`DELETE`	`/scim/v2/Users/{user_id}`	Soft-deactivate a SCIM-managed user. Returns `204 No Content`.
`POST`	`/scim/v2/Groups`	Create or replace a SCIM group membership snapshot.
`GET`	`/scim/v2/Groups`	List SCIM groups.
`GET`	`/scim/v2/Groups/{group_id}`	Return one SCIM group resource.
`PUT`	`/scim/v2/Groups/{group_id}`	Replace a SCIM group resource.
`PATCH`	`/scim/v2/Groups/{group_id}`	Apply supported SCIM patch operations to a group.
`DELETE`	`/scim/v2/Groups/{group_id}`	Remove SCIM-managed group role memberships. Returns `204 No Content`.

Shared SCIM list query fields

Field	In	Type	Default	Required	Description
`filter`	query	string or null	`null`	No	Optional SCIM filter expression.
`startIndex`	query	integer	`1`	No	One-based result offset for list responses. Minimum `1`.
`count`	query	integer	`100`	No	Maximum number of resources to return. Minimum `0`.

SCIM user create and replace request fields

Field	In	Type	Default	Required	Description
`schemas`	body	string[]	`[]`	No	SCIM schema identifiers supplied by the caller.
`externalId`	body	string or null	`null`	No	External identity identifier.
`userName`	body	string	none	Yes	Unique SCIM user name. Genesis expects email-like values in Phase 1.
`active`	body	boolean or null	`true`	No	Whether the user is active.
`displayName`	body	string or null	`null`	No	Display name.
`name`	body	object or null	`null`	No	Structured name object with optional `givenName` and `familyName`.
`emails`	body	object[]	`[]`	No	Email values. Each item includes `value` (string, required) and `primary` (boolean, default `false`).

SCIM patch request fields

Field	In	Type	Default	Required	Description
`schemas`	body	string[]	`[]`	No	SCIM schema identifiers supplied by the caller.
`Operations`	body	object[]	`[]`	No	Patch operations. Each item includes `op` (string, required), `path` (string or null, default `null`), and `value` (object or null, default `null`).

SCIM group create and replace request fields

Field	In	Type	Default	Required	Description
`schemas`	body	string[]	`[]`	No	SCIM schema identifiers supplied by the caller.
`id`	body	string or null	`null`	No	Group identifier.
`externalId`	body	string or null	`null`	No	External group identifier.
`displayName`	body	string	none	Yes	Display name for the SCIM group.
`members`	body	object[]	`[]`	No	Group members. Each item can include `value`, `display`, `email`, and `$ref`.

User resource responses return id, externalId, userName, displayName, active, emails, roles, name, and meta. Group resource responses return id, displayName, members, and meta. List routes return the standard SCIM ListResponse envelope with schemas, totalResults, startIndex, itemsPerPage, and Resources.

Genesis enhancement report artifact endpoints

These routes are mounted under /api/genesis-enhancements/... and back the Support and Enhancements report workflow.

Report list endpoint

Method	Path	Description
`GET`	`/api/genesis-enhancements/reports`	Return support and enhancement reports for the main Support and Enhancements table, with optional source, status, type, and version-aware filtering.

`GET /api/genesis-enhancements/reports`

Field	In	Type	Default	Required	Description
`status`	query	string or null	`null`	No	Exact status filter for the returned reports.
`ticket_type`	query	string or null	`null`	No	Optional report type filter. Current values are `support` and `enhancement`.
`source_filter`	query	string or null	`null`	No	Optional source filter. `dormant_thread_review` returns self-improvement generated reports; `direct` returns reports created directly by agents or users. Omit this field, or use any other value, to return all sources.
`include_closed`	query	boolean	`true`	No	When `false`, exclude reports whose `status` is `closed`.
`limit`	query	integer	`200`	No	Maximum number of reports to return. Minimum `0`, maximum `10000`. `0` disables the result cap.
`client_version`	query	string or null	`null`	No	Optional Genesis client version used to decorate each report with version-aware readiness fields such as `fixed_in_version`.

This endpoint returns the standard response envelope with success plus reports, where each item uses the same base report shape returned by GET /api/genesis-enhancements/reports/{report_id}. Reports created through this API record the requesting user’s ID, email, and display name as the creator. These values come from the request’s user context, not creator fields supplied in the request body. When submitting a report with no recorded creator, Genesis records the submitting user’s identity.

Report field	Type	Description
`created_by_user_id`	string	User ID recorded as the report creator.
`created_by_email`	string	Email recorded for the report creator; an empty string when unavailable.
`created_by_name`	string	Display name recorded for the report creator; an empty string when unavailable.

Discard a report

Method	Path	Description
`POST`	`/api/genesis-enhancements/reports/{report_id}/discard`	Mark a report filed in error as discarded, unless Genesis has already received it.

`POST /api/genesis-enhancements/reports/{report_id}/discard`

This route accepts either access_config_panel or manage_genesis_enhancements. For the storage cost, see discard_enhancement_report.

Field	In	Type	Default	Required	Description
`report_id`	path	string	none	Yes	Report identifier.
`reason`	body	string	none	Yes	Why the report was filed in error; length must be 1–2000 characters.

A successful response has success: true and a report object whose status is discarded. Its discard object records the following fields:

Field	Type	Description
`discarded_at`	string	Time the report was discarded.
`discarded_by_user_id`	string	User ID of the person who discarded it, or an empty string when unavailable.
`discarded_by_email`	string	Email of the person who discarded it, or an empty string when unavailable.
`reason`	string	Reason supplied in the request.
`previous_status`	string	Report status before it was discarded.

Status	Meaning
`200`	Report discarded, or the report was already discarded.
`404`	No report has the requested ID.
`409`	Genesis already received the report; it cannot be discarded locally.

Artifact-backed report creation fields

POST /api/genesis-enhancements/reports accepts these artifact-related body fields in addition to the standard report fields:

Field	In	Type	Default	Required	Description
`title`	body	string	none	Yes	Report title.
`ticket_type`	body	string	`enhancement`	No	Report type: `support` or `enhancement`.
`attachments`	body	object[]	`[]`	No	Optional pre-attached artifact metadata entries.
`attach_thread_id`	body	string or null	`null`	No	Export this thread and attach it to the report.
`include_server_log`	body	boolean or null	`null`	No	When `attach_thread_id` is set, include support logs (`server.log` and `twin.log`) in the exported bundle. When omitted, the export layer includes them automatically only when `bug_report` is present; workspace policy can still suppress log capture.
`bug_report`	body	string or null	`null`	No	Optional Markdown bug report bundled into the attached thread ZIP as `bug_report.md`.
`bot_id`	body	string or null	`null`	No	Optional agent ID used when exporting `attach_thread_id`.

When a report has attached artifacts, GET /api/genesis-enhancements/reports/{report_id} returns an attachments array. Each attachment entry includes these fields:

Field	Type	Description
`artifact_id`	string	Attachment identifier used by the download route.
`type`	string	Artifact type such as `thread_export`, `server_log`, or `twin_log`.
`filename`	string	Download filename shown in the UI.
`size_bytes`	integer	File size in bytes.
`created_at`	string	Artifact creation timestamp.
`source_thread_id`	string or null	Source thread when the artifact came from a thread export.

Report detail bundle preview fields

GET /api/genesis-enhancements/reports/{report_id} also accepts these fields for the report-detail drawer:

Field	In	Type	Default	Required	Description
`report_id`	path	string	none	Yes	Report identifier.
`client_version`	query	string or null	`null`	No	Optional client version for compatibility gating and version-aware enhancement status/readiness fields.
`include_bundle`	query	boolean	`false`	No	When `true`, Genesis attempts to enrich the response with `report.bundle` delivery-preview fields.

When bundle preview generation succeeds, report.bundle can include:

Field	Type	Description
`scrub_status`	string	Bundle scrub status used to gate email delivery actions in the drawer.
`size_bytes`	integer	Finished support-bundle size in bytes.
`size_limit_bytes`	integer	Configured support-bundle email ceiling in bytes; `0` means no ceiling.
`exceeds_size_limit`	boolean	Whether the finished support bundle exceeds `size_limit_bytes`. When `true`, use the download-only path and share the bundle through another channel.
`mailto_url`	string	Prefilled `mailto:` URL to the configured support address. Present only when `scrub_status` is `ok`.
`mailto_link`	string	Markdown link string for `mailto_url`. Present only when `scrub_status` is `ok`.

Version-aware ticket fields

Report responses can also include these version-tracking fields under report.ticket:

Field	Type	Description
`report.ticket.fixed_in_version`	string	Provider version where the fix shipped, or `""` when unknown. Clients can compare this semver-style value with `client_version` to present labels such as Released to v1.2.1 or Included in this version.
`report.ticket.ready_for_validation_from_version`	string	Provider version from which the change is expected to be ready for customer validation, or `""` when unknown.

Bundle preview enrichment is best-effort. If preview generation fails, Genesis still returns the base report payload instead of failing the entire request.

Artifact download endpoint

Method	Path	Description
`GET`	`/api/genesis-enhancements/reports/{report_id}/artifacts/{artifact_id}`	Download one attachment from a report.

`GET /api/genesis-enhancements/reports/{report_id}/artifacts/{artifact_id}`

Field	In	Type	Default	Required	Description
`report_id`	path	string	none	Yes	Report identifier.
`artifact_id`	path	string	none	Yes	Attachment identifier from the report’s `attachments` array.

Status	Meaning
`200`	Binary file download. ZIP artifacts use `application/zip`; other files use `application/octet-stream`.
`404`	Attachment not found for the requested report.

Full report bundle endpoint

Method	Path	Description
`GET`	`/api/genesis-enhancements/reports/{report_id}/download-bundle`	Download one user-facing ZIP bundle for a report.

`GET /api/genesis-enhancements/reports/{report_id}/download-bundle`

Field	In	Type	Default	Required	Description
`report_id`	path	string	none	Yes	Report identifier.

This ZIP contains report.md, report.json, scrub_manifest.json, and all attached artifact files for the report. When enhancement bundle scrubbing is enabled, Genesis redacts supported text artifacts before packaging and records the outcome in scrub_manifest.json; binary attachments pass through unchanged. If the report includes a nested thread_export.zip, that inner ZIP carries its own scrub_manifest.json; support-bundle workflows rewrite role: "tool" output content in thread.json and message_log.csv to schema-only descriptors by default and record the applied mode plus redaction counts there. The same single ZIP is also the only attachment Genesis sends during online report submission. If Genesis cannot build a safe bundle or the receiver cannot accept multipart uploads, POST /api/genesis-enhancements/reports/{report_id}/submit returns success: false instead of falling back to a bundleless submission.

Status	Meaning
`200`	Binary ZIP download with a `Content-Disposition` filename such as `enhancement_<report_id>.zip`.
`404`	Report not found for the requested bundle download.

Support email draft endpoint

Method	Path	Description
`GET`	`/api/genesis-enhancements/reports/{report_id}/email.eml`	Download a pre-filled `.eml` draft with the scrubbed ZIP already attached.

`GET /api/genesis-enhancements/reports/{report_id}/email.eml`

Field	In	Type	Default	Required	Description
`report_id`	path	string	none	Yes	Report identifier.

This endpoint returns message/rfc822 content with X-Unsent: 1 so Outlook and Thunderbird open the file as a draft the user is composing. Apple Mail and browser-based webmail flows should use the mailto: fallback together with the plain ZIP download instead.

Status	Meaning
`200`	Binary `.eml` download with a `Content-Disposition` filename such as `enhancement_<report_id>.eml`.
`404`	Report not found.
`409`	Email draft unavailable because bundle scrubbing did not finish with `scrub_status: ok`.
`500`	Bundle generation or `.eml` assembly failed.

Enhancement settings endpoints

Method	Path	Description
`GET`	`/api/genesis-enhancements/settings`	Read Genesis enhancement workflow settings.
`PUT`	`/api/genesis-enhancements/settings`	Update Genesis enhancement workflow settings.

PUT /api/genesis-enhancements/settings is a partial update. Omit a field to keep its current stored value. When autosend_enabled is false, report submission paths force offline delivery regardless of mode_preference. On non-SQLite Snowflake deployments, enabling autosend upserts the receiver host parsed from receiver_base_url into CUSTOM_ENDPOINTS under egress group GENESIS_ENHANCEMENTS with type CUSTOM; disabling autosend removes that endpoint; changing receiver_base_url while autosend stays enabled replaces the previous host. Endpoint reconciliation failures are logged but do not fail the settings update. Each successful PUT also invalidates the cached EAI assignment check for report_eai_reference.

Connectivity and receiver settings fields

Field	In	Type	Default	Required	Description
`autosend_enabled`	`GET` response `settings.autosend_enabled`; `PUT` body	boolean	`false`	No	When `true`, Genesis may submit scrubbed support and enhancement bundles to `receiver_base_url`. When `false`, submissions stay offline (ZIP/email/manual) regardless of `mode_preference`.
`mode_preference`	`GET` response `settings.mode_preference`; `PUT` body	string	`auto`	No	Preferred delivery mode when autosend is enabled. Allowed values are `auto`, `online`, and `offline`.
`receiver_base_url`	`GET` response `settings.receiver_base_url`; `PUT` body	string	`https://enhancements.genesiscomputing.ai`	No	Base URL for the Genesis enhancement receiver used during online submission.
`sender_id`	`GET` response `settings.sender_id`; `PUT` body	string	`genesis-local`	No	Sender identifier included in receiver requests.
`receiver_timeout_seconds`	`GET` response `settings.receiver_timeout_seconds`; `PUT` body	integer	`20`	No	HTTP timeout for receiver calls. Stored values below `3` are normalized to `3`.
`report_eai_reference`	`GET` response `settings.report_eai_reference`; `PUT` body	string	`genesis_external_access`	No	Snowflake external-access reference name used by the Support and Enhancements EAI helpers.
`verify_offline_signatures`	`GET` response `settings.verify_offline_signatures`; `PUT` body	boolean	`false`	No	When `true`, verify signatures on imported offline status ZIPs.
`receiver_shared_secret`	`GET` response `settings.receiver_shared_secret`; `PUT` body	string	`""`	No	Shared secret for receiver authentication. `GET` returns `"*"` when a secret is stored and `""` when unset. `PUT` requests that send `"*"` leave the stored secret unchanged.

Bundle-delivery settings fields

Field	In	Type	Default	Required	Description
`scrub_bundle_enabled`	`GET` response `settings.scrub_bundle_enabled`; `PUT` body	boolean	`true`	No	When `true`, Genesis scrubs supported text artifacts before writing support and enhancement ZIP bundles and also redacts downstream report free-text fields such as `title`, `summary`, `details`, and `component` before online submission. `false` preserves original text.
`scrub_extra_terms`	`GET` response `settings.scrub_extra_terms`; `PUT` body	string[]	`[]`	No	Additional case-insensitive whole-word terms to redact from scrubbed text artifacts and downstream report free-text fields.
`support_email_address`	`GET` response `settings.support_email_address`; `PUT` body	string	`[email protected]`	No	Recipient used for the bundle `mailto:` preview and the `.eml` draft download.

Dormant thread review endpoints

These routes are mounted under /api/genesis-enhancements/dormant-review/... and back the Genesis Self-Improvement panel on Config -> Support and Enhancements plus the compact dormant-review summary shown in Pulse. The UI label uses Genesis Self-Improvement; the API path and stored metadata still use dormant-review. Status, saved settings, and manual run-once use access_config_panel. Scheduler start and stop require manage_scheduler.

Method	Path	Description	Required permission
`GET`	`/api/genesis-enhancements/dormant-review/status`	Return the current dormant-review settings, scheduler state, queued windows, latest run summary, and recent generated reports.	`access_config_panel`
`PUT`	`/api/genesis-enhancements/dormant-review/settings`	Partially update the stored dormant-review settings.	`access_config_panel`
`POST`	`/api/genesis-enhancements/dormant-review/run-once`	Run one dormant-review pass immediately using the saved settings plus any provided request overrides.	`access_config_panel`
`POST`	`/api/genesis-enhancements/dormant-review/scheduler/start`	Resume the dormant-review background job and persist `settings.enabled = true`.	`manage_scheduler`
`POST`	`/api/genesis-enhancements/dormant-review/scheduler/stop`	Pause the dormant-review background job and persist `settings.enabled = false`.	`manage_scheduler`

PUT /api/genesis-enhancements/dormant-review/settings is a partial update. Omit a field to keep its current stored value. The current build does not accept autosubmit_enabled in the update body and always normalizes that response field back to false. POST /api/genesis-enhancements/dormant-review/scheduler/start and POST /api/genesis-enhancements/dormant-review/scheduler/stop do not accept a request body. On success they return success: true with data.job_id: "dormant_thread_review".

Dormant-review settings fields

Field	In	Type	Default	Required	Description
`enabled`	`GET /status` response `settings.enabled`; `PUT /settings` body and response `settings.enabled`	boolean	`false`	No	Stored master toggle for automatic scanning. `POST /scheduler/start` sets it to `true`; `POST /scheduler/stop` sets it to `false`.
`dry_run`	`GET /status` response `settings.dry_run`; `PUT /settings` body and response `settings.dry_run`	boolean	`true`	No	Evaluate dormant threads and persist review telemetry without creating draft tickets.
`create_drafts`	`GET /status` response `settings.create_drafts`; `PUT /settings` body and response `settings.create_drafts`	boolean	`false`	No	Allow actionable findings to create draft enhancement reports. Drafts are only created when the effective `dry_run` value is `false`.
`autosubmit_enabled`	`GET /status` response `settings.autosubmit_enabled`; `PUT /settings` response `settings.autosubmit_enabled`	boolean	`false`	No	Reserved for future use. The current build always returns `false` and the update route does not accept this field.
`interval_minutes`	`GET /status` response `settings.interval_minutes`; `PUT /settings` body and response `settings.interval_minutes`	integer	`15`	No	Scheduler cadence between automatic dormant-review runs.
`dormant_after_minutes`	`GET /status` response `settings.dormant_after_minutes`; `PUT /settings` body and response `settings.dormant_after_minutes`	integer	`60`	No	Minimum inactivity window a thread must exceed before it is eligible for review.
`scan_lookback_days`	`GET /status` response `settings.scan_lookback_days`; `PUT /settings` body and response `settings.scan_lookback_days`	integer	`7`	No	Skip threads older than this many days. `0` disables the lookback cutoff.
`min_assistant_messages`	`GET /status` response `settings.min_assistant_messages`; `PUT /settings` body and response `settings.min_assistant_messages`	integer	`5`	No	Minimum assistant-message count required before Genesis reviews a thread.
`min_tool_calls`	`GET /status` response `settings.min_tool_calls`; `PUT /settings` body and response `settings.min_tool_calls`	integer	`2`	No	Minimum tool-call count required before Genesis reviews a thread.
`min_new_assistant_messages_after_review`	`GET /status` response `settings.min_new_assistant_messages_after_review`; `PUT /settings` body and response `settings.min_new_assistant_messages_after_review`	integer	`5`	No	Minimum new assistant messages required after the previous completed or `noop` review before the same thread is eligible again.
`max_threads_scanned_per_run`	`GET /status` response `settings.max_threads_scanned_per_run`; `PUT /settings` body and response `settings.max_threads_scanned_per_run`	integer	`20`	No	Maximum thread records Genesis inspects while building the candidate list for one run.
`max_threads_per_run`	`GET /status` response `settings.max_threads_per_run`; `PUT /settings` body and response `settings.max_threads_per_run`	integer	`20`	No	Maximum candidate threads reserved and reviewed in one run.
`max_reports_per_thread`	`GET /status` response `settings.max_reports_per_thread`; `PUT /settings` body and response `settings.max_reports_per_thread`	integer	`1`	No	Stored per-thread report-cap setting returned by the API. The initial rollout keeps the default at `1`.
`review_timeout_seconds`	`GET /status` response `settings.review_timeout_seconds`; `PUT /settings` body and response `settings.review_timeout_seconds`	integer	`90`	No	Timeout for the LLM-backed dormant-thread self-review.
`reservation_timeout_minutes`	`GET /status` response `settings.reservation_timeout_minutes`; `PUT /settings` body and response `settings.reservation_timeout_minutes`	integer	`30`	No	Age after which `reserved` or `processing` review windows are marked `stale` and can be retried.
`model_tier`	`GET /status` response `settings.model_tier`; `PUT /settings` body and response `settings.model_tier`	string	`fast`	No	Review model tier. Allowed values are `nano`, `fast`, `main`, and `frontier`.

Run-once request fields

When POST /api/genesis-enhancements/dormant-review/run-once omits a field, Genesis uses the currently saved setting for that value.

Field	In	Type	Default	Required	Description
`dry_run`	body	boolean or null	`null`	No	One-run override for `settings.dry_run`.
`create_drafts`	body	boolean or null	`null`	No	One-run override for `settings.create_drafts`. Drafts are created only when the effective `dry_run` value is `false`.
`max_threads_per_run`	body	integer or null	`null`	No	One-run override for `settings.max_threads_per_run`.

Dormant-review status response fields

Field	Type	Description
`settings`	object	Current dormant-review settings object.
`scheduler`	object	Scheduler state object described below.
`counts`	object	Review-window counts keyed by `completed`, `failed`, `noop`, `processing`, `reserved`, `stale`, and `total`.
`latest_run`	object or null	Most recent saved run summary, or `null` when no dormant review has run yet.
`queue`	object[]	Up to 25 review-window items whose `status` is `reserved` or `processing`.
`recent_windows`	object[]	Up to 25 most recent review-window items, newest first.
`generated_reports`	object[]	Up to 25 dormant-review generated reports sorted by `updated_at` descending.
`recent_failures`	object[]	Up to 10 recent-window items whose `status` is `failed` or `stale`.

queue, recent_windows, and recent_failures reuse the review-window item fields below.

Scheduler state fields

Field	Type	Description
`job_id`	string	Scheduler job identifier. Current value is `dormant_thread_review`.
`status`	string	Scheduler state string. Current values are `not_registered`, `stopped`, and `running`.
`next_run_time`	string or null	Next scheduled execution timestamp, or `null` when the job is paused or missing.
`running`	boolean	`true` when the scheduler has a next run time for this job.

Review-window item fields

Field	Type	Description
`window_key`	string	Stable review-window identifier derived from the thread and its last-activity snapshot.
`bot_id`	string	Source agent identifier.
`thread_id`	string	Source thread identifier.
`thread_title`	string	Best available thread title used for review status displays.
`last_activity_at`	string	Source thread last-activity timestamp used for dormant-window selection.
`message_count`	integer	Total message count loaded for the review candidate.
`assistant_message_count`	integer	Assistant-message count loaded for the review candidate.
`user_message_count`	integer	User-message count loaded for the review candidate.
`tool_call_count`	integer	Tool-call count loaded for the review candidate.
`status`	string	Review-window status. Current values are `reserved`, `processing`, `completed`, `noop`, `failed`, and `stale`.
`reserved_at`	string or null	Timestamp when Genesis reserved the review window.
`started_at`	string or null	Timestamp when Genesis started processing the review window.
`completed_at`	string or null	Timestamp when Genesis completed, no-oped, failed, or marked the review window stale.
`prompt_version`	string	Dormant-review prompt version recorded for that window.
`created_report_ids`	string[]	New draft report ids created from this review window.
`updated_report_ids`	string[]	Existing report ids updated with deduped evidence from this review window.
`regression_report_ids`	string[]	New report ids created as regression follow-ups to completed reports.
`deduped_finding_count`	integer	Number of findings attached to existing reports instead of creating a new draft.
`created_finding_count`	integer	Number of findings that remained new after dedupe.
`dedupe_adjudications`	object[]	Per-finding dedupe decisions recorded during draft creation.
`last_error`	string	Failure or stale-window summary when the review did not complete cleanly.
`proposal`	object	Parsed dormant-review proposal payload stored for this review window.

Generated-report item fields

Field	Type	Description
`report_id`	string	Enhancement report identifier.
`title`	string	Report title.
`status`	string	Current enhancement-report status.
`created_at`	string	Report creation timestamp.
`updated_at`	string	Last report update timestamp.
`source_thread_id`	string	Source thread id recorded in the report metadata.
`source_thread_title`	string	Source thread title recorded in the report metadata.
`source_bot_id`	string	Source agent id recorded in the report metadata.
`review_window_key`	string	Review-window id recorded in the report metadata.

Latest run summary fields

Field	Type	Description
`run_id`	string	Unique run identifier, such as `dormant-review-abc123def456`.
`started_at`	string	Run start timestamp.
`completed_at`	string	Run completion timestamp.
`config`	object	Effective dormant-review settings used for that run. Present when Genesis constructed the run config.
`scanned_count`	integer	Thread records inspected during candidate scanning.
`eligible_count`	integer	Threads that passed the scan filters and were eligible for reservation.
`reserved_count`	integer	Threads successfully reserved for review in that run.
`reviewed_count`	integer	Reserved threads whose review logic ran.
`noop_count`	integer	Reviewed threads that produced `decision: "no_report"`.
`proposal_count`	integer	Reviewed threads that produced `decision: "report"`.
`draft_created_count`	integer	New draft reports created in that run.
`skipped_recent_count`	integer	Threads skipped because they were not dormant long enough yet.
`skipped_too_old_count`	integer	Threads skipped because they were older than `scan_lookback_days`.
`skipped_too_short_count`	integer	Threads skipped because they had too few assistant messages.
`skipped_too_few_tools_count`	integer	Threads skipped because they had too few tool calls.
`skipped_already_reviewed_count`	integer	Threads skipped because too few new assistant messages arrived since the previous review.
`scan_limit_reached_count`	integer	`1` when scanning hit `max_threads_scanned_per_run`; otherwise `0`.
`skipped_disabled_count`	integer	`1` when the process-level dormant-review gate prevented the run; otherwise `0`.
`skipped_running_count`	integer	`1` when another dormant review was already running and this run was skipped; otherwise `0`.
`failed_count`	integer	Review windows that failed during scanning or processing.
`deduped_finding_count`	integer	Findings attached to existing reports during the run. Present when draft creation is enabled and dedupe occurs.
`created_finding_count`	integer	Findings that remained new after dedupe. Present when draft creation is enabled.
`updated_report_count`	integer	Existing reports updated with new evidence. Present when draft creation is enabled and dedupe occurs.

Cursor Agent admin endpoints

These routes back report-specific Cursor Agent actions. All of them require access_config_panel. The Software Factory page reads the provider-neutral factory endpoints below instead. The web client exposes the Software Factory route only when GET /api/config/frontend returns software_factory_enabled: true.

Method	Path	Description
`POST`	`/api/genesis-enhancements/reports/{report_id}/cursor-agent/start`	Launch a Cursor Agent run for one enhancement report and return the generated prompt preview, prompt hash, and initial run metadata. On the cloud adapter, when `genesis_enhancements.cursor_agent.model` is non-empty, Genesis maps that slug into the Cursor Cloud `POST /v1/agents` body as `model: { "id": "<slug>" }`; an empty string (schema default) omits `model` so Cursor inherits the workspace default. This route does not accept a per-request model override.
`GET`	`/api/genesis-enhancements/cursor-agent/status`	Return the global Cursor Agent summary.
`GET`	`/api/genesis-enhancements/reports/{report_id}/cursor-agent/status`	Return Cursor Agent status for one enhancement report.

Software Factory operator endpoints

These back the Software Factory page and read the coding lane rather than a single enhancement report. GET accepts either access_config_panel or manage_genesis_enhancements; stopping a run requires manage_genesis_enhancements alone, because ending someone else’s run is an operator action rather than a read.

Method	Path	Description
`GET`	`/api/genesis-enhancements/factory/status`	Return lane state, the run currently in flight, and one page of run history. `limit` (1-100, default 20) and `offset` (default 0) page the history; `total_runs` reports the full count. `lane.slots_in_use` is the claim ledger’s own count, so a slot reserved before its run is written already counts. Costs one scan of the coding run root plus one JSON parse per stored run, a scan of the claim directory to attach each run’s review position, and one tombstone read per shown run whose claim has been archived.
`GET`	`/api/genesis-enhancements/factory/lane`	Return the lane block alone — backend, whether it is enabled and configured, its concurrency bound and `slots_in_use` — for surfaces that render no run history. Counts slots as admission does, so it still reads the run store once, but skips the history projection, the review join and the tombstone reads. Same permissions as `factory/status`.
`POST`	`/api/genesis-enhancements/factory/runs/{run_id}/stop`	Ask the run’s own backend to cancel it. Answers `success: true, stopped: false` when the backend has accepted the request but not yet confirmed termination — backends confirm on a later poll — and `success: false` with a `detail` when the run is unknown. A stop the backend confirms later is retired by the reconciler on its next pass; stopping a run that has already ended finishes a stop requested earlier and leaves any other claim to its settlement. The ticket stays delegated, so the lane can pick it up again.

Software Factory response fields

The status and lane responses wrap their payload in data. The lane endpoint’s data has the same fields as data.lane in the status response. Current runs include every non-terminal run, newest first; recent_runs is the paginated history window, also newest first.

Field	Type	Description
`data.lane`	object	Selected backend and lane readiness. See lane fields below.
`data.current_runs`	object[]	All runs not yet in a terminal state.
`data.recent_runs`	object[]	Run-history page selected by `limit` and `offset`.
`data.total_runs`	integer	Count of readable stored run records, before pagination.
`data.generated_at`	string	UTC timestamp when the status projection was generated.

Software Factory lane fields

Field	Type	Description
`backend`	string	Selected backend identifier, or empty when the selector is invalid.
`enabled`	boolean	Whether the selected backend is enabled.
`configured`	boolean	Whether the selected backend has the configuration needed to launch.
`disabled_reason`	string	Configuration blocker, or empty when there is none.
`concurrent_runs`	boolean	Whether the backend supports concurrent runs.
`max_concurrent_runs`	integer	Configured concurrency limit, or `0` when no limit is set.
`slots_in_use`	integer	Slots reserved in the claim ledger, including a reservation made before its run record is written.

Software Factory run fields

Each run in current_runs or recent_runs has this projected shape. verification and pr_status contain backend-provided evidence when available; review is the claim’s review-loop projection when one exists.

Field	Type	Description
`run_id`	string	Durable run identifier.
`backend`	string	Backend that owns the run.
`status`	string	Lowercase run status.
`issue_key`	string	Delegated issue associated with the run, when present.
`branch_name`	string	Working branch name, when present.
`agent_url`	string	Link to the hosted agent session, when provided.
`started_at`, `updated_at`, `completed_at`, `deadline_at`	string	Run timestamps; empty when unavailable.
`last_error`	string	Latest run error, when present.
`workflow_file`	string	Workflow file associated with the run, when present.
`pr_url`	string	Pull request URL, when available.
`pr_number`	integer or null	Pull request number, when available.
`published_commit_sha`	string	Commit published by the run, when available.
`verification`	object or null	Backend verification evidence, when available.
`pr_status`	object or null	Pull request and CI status evidence, when available.
`review`	object or null	Review-loop projection; see review fields below.

Software Factory review fields

Field	Type	Description
`issue_key`	string	Issue whose claim owns the review state.
`phase`	string	Current review-loop phase.
`round`	integer	Current correction round.
`cycle`	integer	Current review-cycle number.
`max_rounds`	integer	Effective correction limit; `0` means unlimited.
`stop_reason`	string	Reason the review loop stopped, or empty when it has not stopped.
`deadline_at`	string	Deadline for the active review cycle, when set.
`settlement_phase`	string	Current settlement phase for the claim.
`last_result`	string	Most recent recorded review result.
`stop_requested`	boolean	Whether an operator stop has been requested for the claim.

Software Factory stop response fields

Field	Type	Description
`success`	boolean	Whether the stop request was handled; this can be `true` before termination is confirmed.
`stopped`	boolean	Whether the backend has confirmed the run stopped.
`detail`	string	Explanation when the run is unknown or the stop request cannot be completed.

Cursor Agent response envelope fields

Field	In	Type	Description
`report`	`POST /api/genesis-enhancements/reports/{report_id}/cursor-agent/start` response and `GET /api/genesis-enhancements/reports/{report_id}/cursor-agent/status` response	object or null	Enhancement report payload for the targeted report.
`cursor_agent`	all three responses	object	Backward-compatible coding-agent status object. The global status route returns a summary object with nested `active_run`, `latest_run`, and `recent_runs`; the report-scoped routes return one report-associated status object. The selected provider is identified by `backend`.
`prompt_preview`	`POST /api/genesis-enhancements/reports/{report_id}/cursor-agent/start` response	string	Leading prompt text returned to the client after Genesis builds the task request.
`prompt_hash`	`POST /api/genesis-enhancements/reports/{report_id}/cursor-agent/start` response	string	SHA-256 hash of the generated prompt.
`error`	all three responses	string or null	Error summary when `success` is `false` or the launcher refuses to start.

Global status summary fields

Field	In	Type	Description
`enabled`	`GET /api/genesis-enhancements/cursor-agent/status` response `cursor_agent.enabled`	boolean	`true` only when `genesis_enhancements.cursor_agent.enabled` is `true`.
`configured`	`GET /api/genesis-enhancements/cursor-agent/status` response `cursor_agent.configured`	boolean	Whether Genesis can launch a supported Cursor Agent adapter.
`disabled_reason`	`GET /api/genesis-enhancements/cursor-agent/status` response `cursor_agent.disabled_reason`	string	Empty string when configured; otherwise the blocking config reason shown in the UI.
`active`	`GET /api/genesis-enhancements/cursor-agent/status` response `cursor_agent.active`	boolean	Whether the local-command launcher slot is occupied by an active run. Active states are `starting`, `queued`, and `running`. The cloud adapter allows multiple concurrent runs, so `active` may be `false` even while cloud agents are still running.
`active_run`	`GET /api/genesis-enhancements/cursor-agent/status` response `cursor_agent.active_run`	object	Active run metadata, or `{}` when no run is active.
`latest_run`	`GET /api/genesis-enhancements/cursor-agent/status` response `cursor_agent.latest_run`	object	Latest known run metadata, or `{}` when no run has been recorded yet.
`recent_runs`	`GET /api/genesis-enhancements/cursor-agent/status` response `cursor_agent.recent_runs`	object[]	Compact run metadata history with up to 8 entries, newest first. Each entry uses the same run metadata shape as `latest_run` except `prompt_preview` and `output_lines` are omitted.

Coding Agent run metadata fields

These fields can appear on the report-scoped cursor_agent object, on the global cursor_agent.active_run / cursor_agent.latest_run objects, and on entries inside cursor_agent.recent_runs unless noted otherwise. The Factory-only factory_result field is top-level in AutoDev action responses; it is not part of the compact Cursor Agent history entries.

Field	Type	Description
`status`	string	Run state such as `starting`, `queued`, `running`, `completed`, `failed`, `cancelled`, `disabled`, or `idle`.
`enabled`	boolean	Whether the selected coding backend is enabled for this runtime.
`configured`	boolean	Whether the launcher has enough configuration to attempt a run.
`disabled_reason`	string	Config blocker summary when the run cannot start.
`source`	string	Trigger source recorded when the run was started. Current values are `enhancement` for report launches and `tool` for direct tool-started runs.
`origin_trigger`	string	Same trigger classification as `source`, retained for client compatibility.
`run_id`	string	Durable run identifier.
`report_id`	string	Related enhancement report id, or `""` for tool-started runs.
`backend`	string	Provider backend that owns the run, such as `cursor` or `claude_code`. Runs continue to refresh through this backend after the configured selector changes.
`agent_id`	string	Cursor Cloud agent identifier when the cloud adapter created the run; local runner session identifier when returned by the runner.
`cloud_run_id`	string	Cursor Cloud run identifier used for `/v1/agents/{agent_id}/runs/{cloud_run_id}` status polling. Present on cloud-adapter runs.
`idempotency_agent_id`	string	Stable idempotency key Genesis sends to Cursor Cloud when creating an agent. Present on cloud-adapter runs. Derived from `idempotency_seed` when `genesis_enhancement_action` passes one to `START_CURSOR_AGENT`; otherwise from the per-run `run_id`.
`target_repo`	string	Repository targeted by the run. For cloud runs, taken from `genesis_enhancements.cursor_agent.target_repo_url`.
`target_branch`	string	Effective base ref configured for the run target. For cloud runs, taken from `genesis_enhancements.cursor_agent.target_base_ref` (default `main`); for Claude Code runs, this is also the ref used for worktree creation and verification.
`branch_name`	string	Working branch name used by the run.
`working_directory`	string	Filesystem working directory passed to the runner.
`session_handle`	string	Provider-neutral handle used to look up the current run and send follow-up messages.
`pr_url`	string	Pull request URL when the run opened or updated a PR.
`agent_url`	string	Cursor Agent session URL when the runner provides one.
`transcript_url`	string	Hosted transcript URL when the runner provides one.
`log_path`	string	Local run log path used to build `output_lines`.
`transcript_path`	string	Local transcript path when available.
`pid`	integer or string	Local launcher process id when available.
`process_id`	integer or string	Alternate process id field when the runner reports one.
`prompt_hash`	string	SHA-256 hash of the prompt stored with the run metadata.
`prompt_preview`	string	Prompt preview stored with the run metadata.
`requested_at`	string	Timestamp when Genesis queued the run request.
`started_at`	string	Timestamp when the run started. For cloud runs Genesis reads `startedAt` (or `createdAt`) from Cursor Cloud status polling; for local runs, when Genesis marked the run as started.
`updated_at`	string	Timestamp of the latest metadata refresh.
`completed_at`	string	Timestamp when the run reached a terminal state.
`last_error`	string	Most recent launch or run failure summary. Git failures preserve a sanitized diagnostic tail instead of using only a generic failure message; credential values, token-shaped strings, and URL userinfo are redacted before the bounded output is stored. For a completed GitHub Actions run that has no evidence artifact, the summary includes the workflow conclusion and, when available, the name of the first step that did not complete. For a Claude Code run interrupted by a CLI record larger than the 64 MiB transport buffer, the summary includes the truncation message and the number of truncated turns.
`adapter`	string	Launcher adapter name: `disabled`, `local-command`, or `cloud`.
`output_lines`	string[]	Tail of the run log returned inline for UI display.
`blocker`	object	Sanitized runtime-stop contract when the run cannot continue. It identifies the blocker `kind` and `source`, includes a stable `fingerprint` and summary, and points to bounded private evidence through `evidence_refs` and `partial_work`.
`verification`	object	Self-verification rollup when the backend produces verification evidence. See Coding Agent verification fields.
`pr_status`	object	Live GitHub pull request CI rollup for cloud runs when tool `GET_CURSOR_AGENT_STATUS` is called with `agent_id` and the run has a `pr_url`. See Cursor Agent cloud pull request status fields. Omitted when no pull request URL is available.
`git`	object	Git, branch, pull request, CI, and CodeRabbit rollup derived from the safe `working_directory` on local-command runs. When the worktree is unavailable or outside the allowed repo root, Genesis returns `git.available: false` and sets `git.error`. Cloud runs omit local git inspection and surface `branch_name`, `pr_url`, and `agent_url` from Cursor Cloud polling instead.
`factory_result`	object	Top-level server-managed PR review and Linear settlement state in AutoDev responses for enrolled Factory runs. Omitted for runs outside the Factory review loop.

Entries inside recent_runs omit prompt_preview and output_lines to keep the global status payload compact.

Factory review result fields

factory_result is returned by AutoDev review actions and by status responses for enrolled Factory runs. Follow current_agent_id and current_run_id until terminal is true, including after the current coding child reaches a terminal status. The server owns the final Linear settlement. The repository skill and orchestration context used by Factory workers is runtime-provided and is not represented as an additional response field or configuration key; see autodev_lane_tools.

Field	Type	Description
`available`	boolean	Whether the run is enrolled in the server-managed Factory review loop.
`enrolled`	boolean	`true` for runs using the Factory review contract.
`settlement_id`	string	Durable identity for the Linear coding-task settlement.
`phase`	string or null	Current review phase, such as dispatching or watching.
`terminal`	boolean	Whether the Factory delivery has reached a terminal outcome.
`outcome`	string	`pending`, `converged`, or `needs_info`.
`current_agent_id`	string	Agent ID for the currently admitted coding child, or empty while dispatching or stale.
`current_run_id`	string	Run ID that must be followed for the current review cycle.
`round`	integer	Current correction round.
`max_rounds`	integer	Effective correction limit. `0` means unlimited.
`deadline_at`	string or null	Deadline for the active review correction cycle. Idle monitoring for later feedback has no deadline.
`next_action`	string	Human-readable reason for the next Factory action.
`stop_reason`	string	Reason the Factory stopped and needs information, or empty when it can continue.
`settlement_delivery`	string	`pending` or `completed` status of final Linear settlement delivery.
`watching`	boolean	Whether the server is watching the open PR for later reviewer feedback.
`cycle`	integer	Review-cycle counter.

Factory runtime recovery fields

An enrolled Factory run exposes factory_result.recovery when a coding child stops at a trusted runtime boundary or when a recovery answer is awaiting adjudication. The recovery controller preserves the task’s orchestration thread and branch, but starts a fresh coding run after a retry, supported context or environment remedy, or accepted human answer. It never resumes the previous SDK session. Use recovery.snapshot_id as the optimistic-concurrency token for autodev_run_action(action="recover").

Field	Type	Description
`available`	boolean	Whether runtime recovery is available for the enrolled Factory claim.
`phase`	string	Recovery phase, such as `adjudicating`, `question_pending`, `awaiting_answer`, `answer_pending`, `dispatching`, `running`, `resolved`, `stopped`, or `revoked`.
`outcome`	string	`pending` while recovery can continue, `needs_info` while a human answer is needed, `technical_stop` when recovery stopped without a useful human question, or `revoked` when the delegation is no longer valid.
`run_id`	string	Run ID of the blocked parent run that opened the recovery episode.
`source_run_id`	string	Run ID that produced the current blocker evidence.
`current_run_id`	string	Current recovery child run ID, or the parent run ID before a child is dispatched.
`snapshot_id`	string	Exact recovery snapshot required by `recover`; changes when the blocker or answer candidate changes.
`blocker`	object	Sanitized runtime blocker with `kind`, `source`, `fingerprint`, `summary`, `requested_input`, `attempted_remedies`, `evidence_refs`, and `partial_work`.
`candidate`	object	Candidate answer extracted from a matching Linear reply; pass its `id` as `recovery_answer_id` when accepting it.
`question`	string	Human question posted to the assigned Linear issue when recovery needs an answer.
`human_request`	object	Structured explanation for an `ask` handoff: `reason`, `evidence`, `checked`, `why_human`, and `resume_condition`.
`recovery_deadline_at`	string	Absolute deadline shared by the recovery attempt and every backend stage.
`stop_reason`	string	Concrete technical reason when recovery stops, or an empty string when no stop has been recorded.

Coding Agent verification fields

Provider backends that produce verification evidence include a verification object on report-scoped cursor_agent metadata, on global active_run / latest_run, on tool GET_CURSOR_AGENT_STATUS responses, and on entries inside recent_runs. For Claude Code runs, verification uses the effective target_branch base ref configured by genesis_enhancements.coding_agent.claude_code.target_base_ref (default main), rather than always comparing against main. Genesis fetches Cursor Cloud artifacts only after the run reaches a terminal state (completed, failed, cancelled, or disabled). While a run is still active, verification.verdict is unverified with reason verification artifacts are fetched only after the run is terminal. After FOLLOWUP_CURSOR_AGENT advances cloud_run_id, Genesis resets verification to unverified until the new run finishes and fresh artifacts are available. Stored verification is bound to the current cloud_run_id through verified_run_id; Genesis never surfaces a verdict recorded for a different run. Genesis lists and downloads artifacts/verification.json and, when the envelope declares a python_unit_tests check, optionally artifacts/junit.xml from the Cursor Cloud agent artifact store. Each artifact download is capped at 8 MiB.

Field	Type	Description
`verdict`	string	`passed`, `failed`, or `unverified`. Genesis uses a conservative classifier: missing evidence, stale artifacts, contradictions, or skipped mandatory checks yield `unverified` rather than `passed`.
`reason`	string	Human-readable explanation when `verdict` is not `passed`; empty when `verdict` is `passed`. For a local Claude Code sandbox preparation failure, this carries the same sanitized diagnostic as `last_error`.
`all_passed`	boolean	`true` only when `verdict` is `passed`.
`verified_run_id`	string	`cloud_run_id` this verdict describes; empty when unverified.
`total`	integer	Number of check items in the summary.
`passed`	integer	Checks classified as passed.
`failed`	integer	Checks classified as failed.
`pending`	integer	Checks still unverified or pending.
`skipped`	integer	Skipped checks.
`required_checks`	string[]	Check names the agent declared as mandatory in `verification.json`.
`items`	object[]	Individual check entries. See Cursor Agent verification check item fields.

Cursor Agent verification check item fields

Field	Type	Description
`name`	string	Check name from the verification envelope.
`workflow`	string	`cursor_stop_hook` for envelope checks.
`state`	string	Raw status in uppercase, such as `PASSED`, `FAILED`, `SKIPPED`, `UNVERIFIED`, or `ADVISORY`.
`status`	string	Normalized status: `passed`, `failed`, `skipped`, `pending`, or `advisory`. An `advisory` item is informational — it is named for the reviewer, counts toward `total`, and counts toward no other bucket, so `total` is not the sum of the rest when one is present.
`completed_at`	string	Completion timestamp from the envelope `generated_at` when available.
`link`	string	Reserved; empty for Cursor verification items.
`description`	string	Check summary text from the envelope.
`executed`	boolean	Whether the check actually ran (`verification.json` `executed` flag).

Cursor Agent cloud pull request status fields

Tool GET_CURSOR_AGENT_STATUS responses that poll a specific Cursor Cloud run by agent_id include a top-level pr_status object when the run has a pr_url. Genesis fetches check state with gh pr checks and does not cache this snapshot across keyed polls.

Field	Type	Description
`available`	boolean	Whether Genesis could read pull request checks from GitHub.
`reason`	string	Error summary when `available` is `false`; empty when checks were fetched successfully.
`url`	string	Pull request URL. Present when `available` is `true`.
`checks`	object	Normalized check summary. See Cursor Agent pull request check summary fields.

Cursor Agent git overview fields

The git object is attached when Genesis can safely inspect the saved working_directory. The comparison base ref defaults to origin/main and can be overridden with CURSOR_AGENT_GIT_BASE_REF.

Field	Type	Description
`available`	boolean	Whether Genesis could inspect the run worktree and collect git metadata.
`error`	string	Error summary when `available` is `false`.
`worktree`	string	Resolved working directory used for git lookups.
`active_branch`	string	Currently checked out branch in the worktree.
`base_ref`	string	Base ref used for compare math and GitHub compare links.
`base_ref_available`	boolean	Whether `base_ref` exists in the worktree.
`upstream`	string	Upstream ref for the active branch when configured.
`head_sha`	string	Full `HEAD` commit SHA.
`short_sha`	string	Short `HEAD` commit SHA.
`is_dirty`	boolean	Whether `git status --porcelain=v1` returned any changes.
`untracked_count`	integer	Number of untracked files in the worktree.
`commit_count`	integer or null	Compatibility alias of `commits_since_base`.
`commits_since_base`	integer or null	Number of commits between the merge base of `base_ref` and `HEAD`.
`commits_ahead`	integer or null	Number of commits present in `HEAD` but not in the configured upstream ref.
`commits_behind`	integer or null	Number of commits present in the configured upstream ref but not in `HEAD`.
`last_commit_subject`	string	Subject line of the latest commit in the worktree.
`last_commit_at`	string	Commit timestamp of the latest commit in the worktree.
`remote_url`	string	Raw `remote.origin.url` value from the worktree.
`repo_url`	string	Normalized GitHub repository URL when `remote.origin.url` points at GitHub; otherwise an empty string.
`branch_url`	string	GitHub URL for the active branch when Genesis can derive one.
`compare_url`	string	GitHub compare URL from `base_ref` to the active branch when both values are available.
`pr_created`	boolean	Whether `gh pr view` found pull request metadata for the active branch.
`pr_url`	string	Pull request URL derived from GitHub CLI metadata.
`pr_number`	integer or null	Pull request number when a pull request is found.
`pr_state`	string	Pull request state returned by GitHub, such as `OPEN` or `MERGED`.
`pr_head_ref`	string	Pull request head ref name returned by GitHub.
`pr_status`	object	Nested pull request rollup including review decision, merge state, CI checks, and CodeRabbit activity.

Cursor Agent pull request status fields

Genesis caches the nested pr_status snapshot for 30 seconds per worktree / pull request. updated_at records when that cached snapshot was last rebuilt.

Field	Type	Description
`available`	boolean	Whether Genesis could read pull request details from GitHub.
`url`	string	Pull request URL.
`number`	integer or null	Pull request number.
`state`	string	Pull request state returned by GitHub.
`head_ref`	string	Pull request head ref name.
`is_draft`	boolean	Whether the pull request is currently marked as a draft.
`review_decision`	string	GitHub review decision summary such as `APPROVED` or `REVIEW_REQUIRED`.
`merge_state_status`	string	GitHub mergeability summary such as `CLEAN` or `DIRTY`.
`updated_at`	string	Timestamp when Genesis last refreshed the cached pull request snapshot.
`checks`	object	Normalized check summary derived from `gh pr checks`.
`coderabbit`	object	CodeRabbit review summary derived from PR reviews and comments.

Cursor Agent pull request check summary fields

Field	Type	Description
`total`	integer	Total number of checks returned by GitHub.
`passed`	integer	Checks normalized to `passed`.
`failed`	integer	Checks normalized to `failed`.
`pending`	integer	Checks normalized to `pending`.
`skipped`	integer	Checks normalized to `skipped`.
`executed`	integer	Number of checks that ran to completion (`passed` + `failed`).
`skipped_names`	string[]	Names of checks normalized to `skipped`.
`behavioral_lanes`	object	Observed CI evidence for the internal `test_e2e` and `test_llm` lanes. A check belongs to a lane when its name equals the caller job name or begins with `<lane> /` . Values: `ran` (at least one non-placeholder member job completed with passed or failed status), `not_run` (a skipped caller was published; the cause is unknown), `not_yet_reported` (observed lane checks are pending), or `not_measured` (execution could not be confirmed from recognised rows). Job completion does not prove that every test executed.
`all_passed`	boolean	`true` when at least one check exists and none are failed or pending. Does not require behavioral lanes to have run; a green rollup whose E2E and LLM lanes never ran can still leave `all_passed` `true`.
`green_is_earned`	boolean	`true` only when `all_passed` is `true`, every lane is `ran` or `not_run`, and at least one lane is `ran`. Non-enrolled settlement requires this flag. Enrolled review keeps its separate convergence policy: a `false` flag alone does not prevent HumanReview, and the Linear comment reports incomplete behavioural evidence without inferring skip causes. Missing or legacy lane maps receive a generic evidence-unavailable note. Earned green, including one completed lane and one skipped caller, does not require that additional note.
`items`	object[]	Individual check entries included in the rollup.

Cursor Agent pull request check item fields

Field	Type	Description
`name`	string	Check name from GitHub.
`workflow`	string	Workflow name associated with the check when provided.
`state`	string	Raw GitHub check state or bucket value before normalization.
`status`	string	Normalized check state: `passed`, `failed`, `pending`, or `skipped`.
`completed_at`	string	Completion timestamp reported by GitHub for the check.
`link`	string	GitHub URL for the individual check when available.
`description`	string	Additional GitHub check description text when present.

Cursor Agent CodeRabbit summary fields

Field	Type	Description
`reviews`	integer	Number of PR reviews attributed to CodeRabbit.
`comments`	integer	Number of PR comments attributed to CodeRabbit.
`review_states`	string[]	Review state values recorded on CodeRabbit-authored PR reviews.
`latest_activity_at`	string	Latest review or comment timestamp attributed to CodeRabbit.

When a report has no saved Cursor Agent run yet, GET /api/genesis-enhancements/reports/{report_id}/cursor-agent/status returns a lightweight cursor_agent object with enabled, configured, and status. The status is idle when the launcher is ready, or disabled plus disabled_reason when the integration is not configured. Agents can poll a specific Cursor Cloud run by agent_id (and optional cloud_run_id) through genesis_enhancement_action with GET_CURSOR_AGENT_STATUS. The returned cursor_agent object includes the same verification rollup described above once the run is terminal, plus pr_status with live GitHub CI checks when the run has a pr_url. Treat a cloud run as fully evidenced only when verification.verdict is passed and pr_status.checks.green_is_earned is true; unverified is not a pass, and all_passed alone does not prove behavioral lanes ran. That keyed lookup is not exposed as a separate REST route; the REST admin endpoints remain report-scoped or global-summary only. Agents can steer an existing Cursor Cloud agent with genesis_enhancement_action and FOLLOWUP_CURSOR_AGENT. This action is also tool-only (no REST route). It requires agent_id and followup_prompt, works only on the cloud adapter, and posts a new run to POST /v1/agents/{agent_id}/runs so the follow-up inherits the agent’s repo, branch, and model. Cursor Cloud accepts the follow-up only when the agent is idle; while a run is still active the tool returns success: false, busy: true, and retryable: true. Poll GET_CURSOR_AGENT_STATUS until the run reaches a terminal state, then retry. On success the response includes cursor_agent with agent_id, cloud_run_id, and status for the new follow-up run; Genesis advances its tracked cloud_run_id, resets started_at, and clears verification to unverified so subsequent status polling follows the follow-up run and waits for new verification artifacts. For tool-started cloud runs, genesis_enhancement_action with START_CURSOR_AGENT accepts an optional model parameter that overrides genesis_enhancements.cursor_agent.model for that run when task_prompt is provided. Genesis maps the chosen slug to model: { "id": "<slug>" } on POST /v1/agents the same way as the REST start route. Report-scoped tool starts that pass only report_id use the deployment config the same way as the REST start route above.

Status	Meaning
`200`	Status returned successfully, or the start request returned its initial run metadata.
`404`	`report_id` was not found for a report-scoped Cursor Agent route.

Advanced settings read and update endpoints

Configuration paths use lowercase dot-notation (for example server.debug). All advanced-settings routes normalize path arguments to lowercase before schema lookup, validation, and secret-field guards — mixed-case paths such as Server.Debug resolve to the same field as server.debug. GET /api/config/advanced/schema, GET /api/config/advanced, and GET /api/config/advanced/{section_name} return field metadata plus current values. Each field includes is_default: true when no value has been explicitly stored in APP_CONFIG for that path (startup NULL scaffold rows do not count as an explicit operator choice). When is_default is true, the resolved value comes from the config priority chain (default_env_var or schema default). Current-value responses from GET /api/config/advanced and GET /api/config/advanced/{section_name} include forced_reason on each field, normally null. On Genesis Desktop, desktop.local_cli_enabled has forced_reason: "desktop" and its effective value is true regardless of the stored value. Attempts to update or reset a setting Desktop holds fixed are refused without changing the stored value. The section objects returned by GET /api/config/advanced and GET /api/config/advanced/{section_name} also include warnings, an array of operator warnings about effective configuration; it is empty when there are no warnings. The CLI Terminal warning condition and remediation are documented in Advanced Settings. The schema description for genesis_enhancements.coding_agent.sandbox_claude.session_retention_seconds documents when an unrecovered or unpublished coding run’s workspace is released; see Provider-neutral coding-agent backend. The collection read used by the Advanced Settings page batches its storage and secret-status reads into two database queries; see Advanced Settings for the resulting Snowflake-hosted page-load behavior. Non-admin callers with access_config_panel still receive most advanced settings on the read routes, but Genesis omits admin-only paths from GET /api/config/advanced/schema, GET /api/config/advanced, and GET /api/config/advanced/{section_name} responses. PUT /api/config/advanced/value, PUT /api/config/advanced/values, and POST /api/config/advanced/reset return HTTP 403 when a non-admin includes any admin-only path. Admin-only paths:

Path	Section
`auth.group_role_mapping`	`auth`
`providers.litellm_proxy.settings.oauth_credential_policy`	`providers.litellm_proxy`
`providers.litellm_proxy.settings.allow_user_oauth_fallback_for_non_interactive`	`providers.litellm_proxy`
`desktop.local_cli_enabled`	`desktop`
`desktop.local_cli_srt_command`	`desktop`
`wiki.write_enabled`	`wiki`
`wiki.extractor_model`	`wiki`
`wiki.admin_tools_enabled`	`wiki`
`wiki.admin_trace_bodies_enabled`	`wiki`
`wiki.correction_classifier_enabled`	`wiki`
`wiki.correction_classifier_model`	`wiki`
`wiki.correction_learning_write_enabled`	`wiki`
`wiki.correction_write_min_confidence`	`wiki`
`wiki.degradation_ranker_enabled`	`wiki`
`ticket_automation.auto_track_chat_requests`	`ticket_automation`
`sandbox_runner.enabled`	`sandbox_runner`
`sandbox_runner.bot_ids`	`sandbox_runner`
`sandbox_runner.image`	`sandbox_runner`
`sandbox_runner.model`	`sandbox_runner`
`sandbox_runner.proxy_base_url`	`sandbox_runner`
`sandbox_runner.network`	`sandbox_runner`
`sandbox_runner.llm_model`	`sandbox_runner`
`sandbox_runner.mcp_url`	`sandbox_runner`
`sandbox_runner.reap_idle_seconds`	`sandbox_runner`
`sandbox_runner.reap_interval_seconds`	`sandbox_runner`
`sandbox_runner.volume_gc_idle_seconds`	`sandbox_runner`
`sandbox_runner.session_store_path`	`sandbox_runner`
`sandbox_runner.runtime`	`sandbox_runner`
`sandbox_runner.k8s_namespace`	`sandbox_runner`
`sandbox_runner.k8s_runtime_class`	`sandbox_runner`
`sandbox_runner.k8s_service_account`	`sandbox_runner`
`sandbox_runner.k8s_storage_class`	`sandbox_runner`
`sandbox_runner.k8s_home_volume_size`	`sandbox_runner`
`sandbox_runner.k8s_pod_ready_timeout_seconds`	`sandbox_runner`
`sandbox_runner.backend_service`	`sandbox_runner`

sandbox_runner.* paths control container execution, networking, and which bots run arbitrary code in a sandbox — all are admin-only. See Advanced Settings — Sandbox thread runner for field semantics. Sandbox thread-runner tokens are not general API credentials. On the MCP transport, send the live token with Authorization: Bearer gsk_...; the optional x-genesis-thread-id header, when supplied, must identify the same thread. Genesis accepts the request only when the token belongs to that thread, resolves a non-system owner, and the route and HTTP method are in the sandbox capability contract. The request then runs as the owning user, so normal RBAC and tenancy checks still apply; invalid or expired tokens return 401, and routes outside the contract return 403. The same contract applies to the REST calls MCP makes on the agent’s behalf. See Sandbox thread token controls. wiki.correction_classifier_model selects the non-Claude model used by the H2 correction scan; wiki.correction_learning_write_enabled and wiki.correction_write_min_confidence control whether the classifier persists auto-supersession learnings and the minimum classifier confidence required to write. These settings are checked live when the scan or verdict runs (no restart). See Advanced Settings → Team Wiki / Librarian settings for field semantics.

Method	Path	Description	Required permission
`PUT`	`/api/config/advanced/value`	Update a single non-secret, non-env-locked schema field.	`access_config_panel`
`PUT`	`/api/config/advanced/values`	Update multiple values in one request. All paths are validated before any write.	`access_config_panel`

Secret fields (is_secret: true) and paths locked by GENESIS__* overrides are refused on both write routes (same guards as reset).

`PUT /api/config/advanced/value` request fields

Field	Type	Required	Description
`path`	`string`	Yes	Dot-notation config path (normalized to lowercase).
`value`	any	Yes	New value (typed per schema).

`PUT /api/config/advanced/values` request fields

Field	Type	Required	Description
`values`	object[]	Yes	List of `{ "path": string, "value": any }` objects. Each `path` is normalized to lowercase. The request is refused when the same path appears more than once (including duplicate spellings that normalize to the same path, for example `Server.Debug` and `server.debug`).

`PUT /api/config/advanced/value` and `PUT /api/config/advanced/values` response fields

Field	Type	Description
`success`	boolean	`false` when the request was refused or a write failed; `true` when every requested value was stored.
`updated_count`	integer	Number of values updated.
`message`	string	Human-readable outcome. On refusal, explains which guard blocked the request (secret field, env lock, duplicate path, validation error).

Status	Meaning
`200`	Returns `ConfigUpdateResponse` (check `success` for per-request outcome).
`403`	Caller lacks `access_config_panel`, or an admin-only path was requested by a non-admin.

Advanced settings reset endpoint

POST /api/config/advanced/reset deletes stored configuration values so each path returns to “never explicitly set” and resolves through the normal config priority chain — a field’s default_env_var when that environment variable is set, the schema default otherwise. Genesis does not write the schema default back into the database. For an env-backed leaf that Genesis previously bridged, the reset also restores the deployment’s original value from before that bridge overwrote the environment variable once no other path is still bridging it; if it was unset, Genesis unsets it again. This makes the next resolution use the deployment default rather than the value that was just reset. The whole request is refused (nothing deleted) when any path is not a schema field, is a secret field, or is locked by a GENESIS__* runtime override (the same guards as PUT /api/config/advanced/value). Secret fields must be reset through /api/config/secret-fields/... instead.

Method	Path	Description	Required permission
`POST`	`/api/config/advanced/reset`	Delete stored values for the supplied paths so they resolve through the default priority chain again.	`access_config_panel`

`POST /api/config/advanced/reset` request fields

Field	Type	Required	Description
`paths`	`string[]`	Yes	Dot-notation config paths to reset (for example `server.debug`). Each path is normalized and deduplicated.

`POST /api/config/advanced/reset` response fields

Field	Type	Description
`success`	boolean	`false` when the request was refused or a delete failed; `true` when every requested path was deleted.
`reset_count`	integer	Number of paths whose stored value was deleted.
`reset_paths`	`string[]`	Paths whose stored value was deleted.
`env_default_paths`	`string[]`	Subset of `reset_paths` whose restored value comes from a `default_env_var` rather than the schema default.
`message`	string	Human-readable outcome. On refusal, explains which guard blocked the request. When `env_default_paths` is non-empty, notes that those paths were restored from environment defaults rather than schema defaults.

Status	Meaning
`200`	Returns `ConfigResetResponse` (check `success` for per-request outcome).
`403`	Caller lacks `access_config_panel`, or an admin-only path was requested by a non-admin.

Manual thread-archive run endpoint

POST /api/config/advanced/archive/threads/run runs thread archival immediately using the currently saved archive settings. This route does not accept a request body. The endpoint returns 400 when threads are stored in Postgres; see thread archive settings for the storage-engine limitation. Each archived object is a ZIP bundle built from the thread’s stored source files and uploads, with message_log.csv included when available. If a prior run already uploaded the bundle, Genesis verifies that remote object and finishes local cleanup instead of rebuilding it.

Method	Path	Description	Required permission
`POST`	`/api/config/advanced/archive/threads/run`	Run thread archival immediately using the currently saved archive settings.	`access_config_panel`

Thread-archive run response fields

Field	Type	Description
`success`	boolean	Whether the manual archive run request completed successfully.
`message`	string	Human-readable outcome summary.
`dry_run`	boolean	`true` when `GENESIS_THREAD_ARCHIVE_DRY_RUN` was active for the run.
`summary`	object	Structured thread-archive run summary.

Thread-archive run summary fields

Field	Type	Description
`eligible_count`	integer	Threads eligible for archival at run start.
`archived_count`	integer	Threads whose archive bundle was uploaded or reused successfully and whose local hot-storage cleanup completed.
`resumed_cleanup_count`	integer	Previously archived threads whose local cleanup was completed in this run after Genesis verified the existing remote archive record/object.
`dry_run_count`	integer	Threads uploaded or deferred during dry-run without local cleanup.
`skipped_terminal_failure_count`	integer	Threads skipped because a prior non-retryable archival failure was recorded.
`skipped_running_count`	integer	Runs skipped because another archival run is already in progress.
`skipped_active_count`	integer	Threads skipped because they were active.
`skipped_idempotent_count`	integer	Reserved idempotent-skip counter. Genesis typically reuses pre-existing remote archives and completes cleanup instead of incrementing this value.
`skipped_disabled_count`	integer	Runs skipped because scheduled archival is disabled for this process or Postgres thread storage does not support archival.
`failure_count`	integer	Threads or cleanup steps that failed.

Status	Meaning
`200`	Returns `ThreadArchiveRunResponse` with `message`, `dry_run`, and `summary`.
`400`	The saved archive configuration is invalid, or the archival run failed before the request could complete successfully.
`409`	Another archive run is already in progress.
`500`	Server error.

Bot directory cleanup endpoint

POST /api/bot-directories/cleanup cleans up bot-thread directories under {STORAGE_PATH}/threads that do not match the bot registry. Genesis quarantines invalid directories to the reversible graveyard at {STORAGE_PATH}/graveyard, renames wrong-case directories to the canonical bot_id, and merges disjoint thread sets into the canonical bot. It never hard-deletes thread data. This route does not accept a request body.

Method	Path	Description	Required permission
`POST`	`/api/bot-directories/cleanup`	Clean up bot-thread directories that do not match the bot registry.	`manage_all_threads`

`POST /api/bot-directories/cleanup`

Returns BotDirectoryCleanupResponse with success: true and a data object describing the run.

Response field (`data`)	Type	Description
`mode`	string	Run label (for example `admin`).
`dry_run`	boolean	Always `false` for this endpoint.
`planned`	integer	Total non-keep actions the run considered.
`executed`	integer	Mutations actually performed.
`conflicts`	integer	Directories left untouched due to ambiguity.
`skipped_recent`	integer	Orphan directories left in place inside the grace window.
`capped`	integer	Mutations deferred because the per-run cap was reached.
`errors`	integer	Actions that failed during execution.
`actions`	object[]	Per-directory actions considered (excludes plain keeps).

Each actions[] item:

Field	Type	Description
`kind`	string	Action kind (for example `graveyard_orphan`, `rename_to_canonical`, `merge_into_canonical`, `merge_partial`, `graveyard_empty_variant`).
`name`	string	The bot directory this action applies to.
`canonical_bot_id`	string or null	Registry-canonical `bot_id` this directory maps to, if any.
`moved_threads`	integer	Threads moved into the canonical directory.
`conflicting_threads`	integer	Threads graveyarded because they collide with the canonical directory.
`reason`	string	Why the directory was classified this way.

Status	Meaning
`200`	Returns `BotDirectoryCleanupResponse`.
`403`	Caller lacks `manage_all_threads`.
`500`	Server error.

AWS connection bucket listing endpoint

GET /api/connections/aws/{name}/buckets lists the S3 bucket names visible to the resolved AWS connection. Genesis uses this helper route to suggest values for archive.threads.bucket in Advanced Settings.

Method	Path	Description	Auth behavior
`GET`	`/api/connections/aws/{name}/buckets`	List S3 bucket names visible to a specific AWS connection.	Caller must be able to see `aws.{name}` under the standard connection-visibility rules.

`GET /api/connections/aws/{name}/buckets`

Field	In	Type	Default	Required	Description
`name`	path	string	none	Yes	AWS connection name.

AWS connection bucket listing response fields

Field	Type	Description
`success`	boolean	Whether the bucket lookup completed successfully.
`data`	string[]	Bucket names returned by the resolved AWS connection.

Status	Meaning
`200`	Returns `ConnectionBucketListResponse` with bucket names in `data`.
`400`	Bucket discovery failed for the selected connection.
`403`	Bucket discovery hit a permission error while resolving or using the saved connection.
`404`	`aws.{name}` was not found or is not visible to the caller.

Connection registry and PAT-capability behavior

These routes live under /api/connections/... and back the Connections UI. Genesis treats auth types pat, api_token, and api_key as PAT-class saved credentials. When auth_type is omitted, PAT-style fields such as access_token are still treated as PAT-class for policy enforcement.

Connection AI provider endpoints

These laptop-mode routes list AI available through saved connections and let a person choose whether Genesis uses it. GET /api/connections/ai-providers returns one entry per connection that brings AI the caller can switch to, including Snowflake Cortex. Entries include provider, label, source_connection_id (<type>.<name>), chat_models, embedding_model, configured, active, reason, and sign_in_required. A Cortex entry that requires Snowflake OAuth reports sign_in_required: true; choosing it opens the browser sign-in before configuration is applied.

Method	Path	Description
`GET`	`/api/connections/ai-providers`	List AI providers the caller’s connections bring (laptop mode).
`GET`	`/api/connections/{connection_type}/{name}/ai-provider`	Return the AI provider offered by one connection, or `null`.
`POST`	`/api/connections/{connection_type}/{name}/ai-provider`	Choose how Genesis uses the connection’s AI. Requires `access_config_panel`.

Field	In	Type	Default	Required	Description
`choice`	body	`"chat_only" \| "chat_and_embeddings" \| "not_now"`	none	Yes	Use the connection for chat, use it for chat and embeddings, or decline the offer.

Activating replaces the current chat provider. Choosing chat_and_embeddings also switches embeddings and can re-index existing content; chat_only leaves the embedding provider unchanged. not_now declines the offer. The response’s data includes success, message, and optional warning_message. On Genesis Desktop, these connection-supplied AI alternatives are not available: the list and per-connection offer omit them, and attempts to submit chat_only or chat_and_embeddings are refused with HTTP 403. The connection itself remains usable for its other supported features. Snowflake also exposes restricted_callers_rights in the connection registry when Genesis runs in SPCS. That auth type is credential-free (credential_free: true, empty fields) and is not PAT-class. Saving it sets privatelink_same_account_rcr: true on the locator. POST /api/connections/test and POST /api/connections/{connection_type}/{name}/test return an advisory when RCR is validated outside SPCS because the SPCS caller token is required. BigQuery exposes application_default in its auth_types map for Application Default Credentials (Runtime Identity). The registry removes this auth type for callers without manage_all_connections, and the create, update, and test routes reject it for those callers. An update is also rejected when it transitions an existing connection into or out of this mode. See Connections — BigQuery for the stored fields and runtime credential behavior. For databricks_lakebase, the registry exposes app_identity only in a Databricks App and only to callers with manage_all_connections. Create, update, and test operations reject non-admin callers, including updates that transition a connection into or out of this shared runtime identity. See Connections — Databricks Lakebase connections for the target endpoint and credential rules. For Azure DevOps, the pat entry in auth_types includes principal_fields: ["pat"]. This declares the PAT field that users may bind through the personal credential endpoints when a shared Azure DevOps connection enables personal_credentials. An auth type may include an availability object with status and message. The Connections UI keeps that auth type visible but disabled and displays the message. The API is authoritative: POST /api/connections returns 400 when a request names an unavailable auth type, while POST /api/connections/test returns success: false with the same message. Any non-empty availability marker means the mode is not selectable; an auth type without the marker remains available. The palantir_foundry registry entry uses this marker for auth_type: "oauth2" with status: "coming_soon" and message Coming soon — contact Genesis to enable. In a Databricks App, the same marker disables BigQuery application_default, AWS and MWAA irsa, MWAA snowflake_workload_identity, and Snowflake restricted_callers_rights, with a mode-specific message. The Databricks App also refuses AWS or MWAA assume_role when access_key_id is missing, since that would use the App host’s credentials. These refusals apply to create, update, test, and saved-connection use; UPDATE also checks the effective stored auth type when the locator omits auth_type. See Connection mode chooser for the alternatives offered for these modes. Palantir Foundry’s selectable personal_token mode stores a non-secret base_url and a secret token. See Palantir Foundry connections for the UI fields and Palantir Foundry for the connector tools. Agent discovery follows the same policy: connections_action LIST_TYPES omits unavailable auth types, and HELP does not propose them. This includes the Databricks App restrictions above and registry modes marked unavailable such as coming_soon.

Method	Path	Description	Auth behavior
`GET`	`/api/connections`	List connections visible to the current user. Supports legacy-source expansion. Each row includes `last_seen_working_at`: the UTC ISO timestamp when a query or saved-connection test last succeeded through that connection in this server process, or `null` when none has succeeded since startup (also `null` for a per-user OAuth connection the caller has not authorized). This is an in-memory read and opens nothing; a server restart clears it. Legacy database connections with `hidden=true` are omitted unless the caller passes `include_hidden=true` and has `manage_all_connections`. The virtual System `Snowflake` connection uses a separate hide flag (`connections.hide_system_snowflake`); when hidden it is omitted by default and surfaced only with `include_hidden=true` for admins.	Standard connection-visibility rules apply.
`GET`	`/api/connections/{connection_type}/oauth/redirect-base`	Return `data.redirect_base_url`, the base the OAuth start route will put before this connection type’s callback path. The setup UI uses it to show the redirect URI sent to the provider.	Requires authentication. Returns `503` in a Databricks App when its public URL cannot be resolved, as OAuth initiation does.
`GET`	`/api/connections/oauth/flows/{flow_id}`	Return `data.status` (`waiting`, `succeeded`, or `failed`), plus nullable `data.message` (failure detail) and `data.warning` (completion caveat), for an OAuth flow started by the current user. The outcome is held in server memory; this read makes no database or provider call.	Requires authentication. Returns `404` when the flow is unknown, expired, or belongs to another user.
`GET`	`/api/connections/system-snowflake/hidden`	Report whether the virtual System `Snowflake` SPCS-token connection is hidden.	Requires `manage_all_connections`.
`POST`	`/api/connections/system-snowflake/hidden`	Hide or show the virtual System `Snowflake` SPCS-token connection. Request body: `{ "hidden": boolean }`. Hiding removes it from agent discovery and dashboard lists; internal metadata and harvest paths are unaffected.	Requires `manage_all_connections`.
`GET`	`/api/connections/registry`	Return the connection-type registry used to build connector forms. Registry entries may include `is_data_source: true` to mark that data lives in that type, separately from `is_database` (whether it is reached through a database connector) and `category`.	For each connector, Genesis removes PAT-class auth types from the `auth_types` map unless the caller has the matching `access_pat_connections_<category>` permission (categories: `databases`, `git`, `cloud`, `pipelines`, `tools`). BigQuery `application_default` is also removed unless the caller has `manage_all_connections`.
`POST`	`/api/connections/mcp/snippet/parse`	Read a pasted Claude Code `.mcp.json` server entry into MCP connection fields. The parser is pure: it stores nothing and makes no request to the pasted server.	Returns `200` with either parsed fields or a translated refusal reason.
`POST`	`/api/connections/test`	Test unsaved connection credentials without saving them. For GitHub, the test applies the same `enterprise_url` refusal rules as saving; see GitHub connections.	PAT-class payloads require the `access_pat_connections_<category>` permission for the target connector’s category. BigQuery `application_default` requires `manage_all_connections`.
`POST`	`/api/connections`	Create a saved connection. For an MCP locator with `auth_type: "auto"`, Genesis contacts the server, resolves the authentication mode, and stores the resolved locator before saving. If preparation or the connection check is refused, the request returns a validation error and does not create a row.	Standard scope rules still apply. PAT-class payloads also require the `access_pat_connections_<category>` permission for the target connector’s category. BigQuery `application_default` also requires `manage_all_connections`. Non-admin callers are still forced to `scope="personal"`. Request bodies with `is_default=true` return `400`. Request bodies naming the deprecated access fields `owner_bot_id`, `allowed_bot_ids` or `allowed_user_ids` — at the top level or inside `locator` — with a value that restricts anybody also return `400`, naming `scope` and `role_names` instead — `role_names` is this API’s spelling of the RBAC role grant, and `roles_with_access` is the `connections_action` spelling, not an HTTP alias; `*` on either allowlist is accepted because it restricts nobody, and `owner_bot_id` has no wildcard. These previously returned success and the value was discarded.
`PUT`	`/api/connections/{connection_type}/{name}`	Update a saved connection. When `locator` is supplied, Genesis verifies connectivity before persisting the update; for an MCP locator with `auth_type: "auto"`, it also resolves the authentication mode against the server. A failed preparation or check returns a validation error without committing the update, so the saved connection remains exactly as it was. See Connections action tools for the agent-facing credential-selection behavior.	Standard owner/shared mutation rules still apply. Changing `scope` or `owner_user_id` requires `manage_all_connections`. PAT-class effective locators, including updates that pivot an existing connection into a PAT mode, require the `access_pat_connections_<category>` permission for the target connector’s category. BigQuery `application_default` also requires `manage_all_connections`, including transitions into or out of that mode. In a Databricks App, changing a Databricks connection’s `auth_mode` without supplying a new `locator` also validates the stored locator under the requested mode; a mode change that would make a stored PAT usable is refused. Request bodies with `is_default=true` return `400`. Request bodies naming the deprecated access fields `owner_bot_id`, `allowed_bot_ids` or `allowed_user_ids` — at the top level or inside `locator` — with a value that restricts anybody also return `400`, naming `scope` and `role_names` instead — `role_names` is this API’s spelling of the RBAC role grant, and `roles_with_access` is the `connections_action` spelling, not an HTTP alias; `*` on either allowlist is accepted because it restricts nobody, and `owner_bot_id` has no wildcard. These previously returned success and the value was discarded.
`POST`	`/api/connections/{connection_type}/{name}/test`	Test a saved connection. A named request may leave secret fields empty; Genesis fills them from the stored connection before validation. A passing test records the connection as seen working in process memory and updates `last_seen_working_at` in connection lists; it is not persisted and a server restart clears it.	Caller must be able to see the connection, and PAT-class saved connections also require the `access_pat_connections_<category>` permission for the connector’s category. BigQuery `application_default` saved connections require `manage_all_connections`.
`GET`	`/api/connections/{connection_type}/{name}/activity`	List recorded statements run on a connection, including the user and credential mode used for each statement.	Requires `manage_all_connections`.
`GET`	`/api/connections/{connection_type}/{name}/credentials`	List scrubbed personal-credential bindings visible for a saved connection.	Standard connection visibility applies; administrators with `manage_all_connections` can manage bindings for the shared connection. Secret values are never returned.
`PUT`	`/api/connections/{connection_type}/{name}/credentials/me`	Bind the current user’s personal principal credential to a shared connection.	Requires access to the connection and a policy/authentication mode that supports personal credentials.
`DELETE`	`/api/connections/{connection_type}/{name}/credentials/me`	Revoke the current user’s personal principal binding.	Requires access to the connection.
`DELETE`	`/api/connections/{connection_type}/{name}/credentials/{user_id}`	Revoke a user’s personal principal binding.	The target user may revoke their own binding; revoking another user’s binding requires `manage_all_connections`.
`GET`	`/api/connections/{connection_type}/defaults`	Return user, role, and effective defaults for one connection type.	Returns only the caller’s relevant role defaults unless the caller has `manage_all_connections`.
`GET`	`/api/connections/{connection_type}/default`	Deprecated system-default lookup.	Returns `410 Gone`. Use an explicit connection id or a user/role-scoped default instead.
`PUT`	`/api/connections/{connection_type}/{name}/default`	Deprecated system-default setter.	Returns `410 Gone`. Use the user/role default routes instead.
`PUT`	`/api/connections/{connection_type}/{name}/defaults/user`	Set the current user’s default connection for a type.	Requires authentication and visibility to `connection_type.name`.
`DELETE`	`/api/connections/{connection_type}/defaults/user`	Clear the current user’s default connection for a type.	Requires authentication.
`PUT`	`/api/connections/{connection_type}/{name}/defaults/roles/{role_name}`	Set a role-scoped default connection.	Requires `manage_all_connections`. The target connection must be a shared non-legacy connection that the role can already access.
`DELETE`	`/api/connections/{connection_type}/defaults/roles/{role_name}`	Clear a role-scoped default connection.	Requires `manage_all_connections`.
`POST`	`/api/admin/demo-data/purge`	Hide all bundled demo legacy database connections and evict their Twin demo entries.	Requires `manage_all_connections`.

When Genesis runs as a Databricks App, /api/connections/registry omits the Databricks pat auth type for every caller and offers databricks_app_user (Signed-in Databricks user) for App-forwarded user-token SQL. Outside a Databricks App, the registry omits databricks_app_user because that runtime cannot provide the forwarded token. Databricks PAT connections are refused on create, locator updates, saved-connection tests, and auth-mode-only updates that would make a stored PAT usable inside the App; previously saved legacy Databricks rows that contain raw tokens cannot be used. See Connect to Databricks — Choose an authentication mode for supported alternatives and the signed-in-user SQL boundary. | POST | /api/connections/export-bundle | Export selected saved connections (with secrets) as an encrypted .genesis-bundle file. | Requires manage_all_connections. | | POST | /api/connections/import-bundle/preview | Decrypt a bundle and return a dry-run preview without applying changes. | Requires manage_all_connections. | | POST | /api/connections/import-bundle/apply | Import connections from an encrypted bundle. | Requires manage_all_connections. |

Connection test response fields

POST /api/connections/test and POST /api/connections/{connection_type}/{name}/test return a ConnectionTestResponse with the test result in data:

Field	Type	Description
`data.success`	boolean	Whether the connection test passed.
`data.message`	string	Human-readable test result or failure detail.
`data.status_code`	integer or null	HTTP status code held by the upstream response when the tester received one. This is populated for successful probes and HTTP failures, including when an HTTP error is wrapped by another exception; it is `null` for transport failures, timeouts, local validation failures, and non-HTTP checks.
`data.outpost`	string or absent	On either connection-test route, the name of the Outpost the test used, on success or failure, when live routing sends the connection through one, including when another connection’s route covers this host. Absent when no Outpost routes it.
`data.outpost_diagnosis`	object or absent	When a routed test failure can be diagnosed, or the host is routed for another connection, includes the Outpost, diagnosis state and cause, and a message and fix. Causes include `host_conflict` when the host name is claimed through multiple Outposts; Genesis routes it through none; `routed_by_another_connection` when a host this connection dials directly is routed through an Outpost for another connection; and `admission_refused` under the test-attribution rules in Outpost Troubleshooting. For `routed_by_another_connection`, the test outcome is unchanged, but the diagnosis explains that the host is reached through the Outpost.
`data.outpost_suggestion`	object or absent	When an unrouted test fails with an internal-looking DNS or timeout error and the caller may route through an Outpost, includes eligible Outpost names in `outposts` and a suggestion in `message`.
`data.remedy`	object or absent	For a PostgreSQL-family test that fails because the server does not support TLS, includes `field` (`ssl_mode`), `value` (`disable`), and `reason` (`server_no_tls`) as a suggested form change. The API does not apply the change automatically.

An unsaved-credentials test does not update last_seen_working_at. The UI can offer the remedy as an explicit retry for unsaved form values; callers must apply it only with the user’s choice. A saved-connection test returns the remedy for the caller to display, but does not change the saved connection. The status code is diagnostic metadata from the probe, not the HTTP status of the Genesis API response. For example, a failed credential check can return data.success: false with data.status_code: 401, while a transport failure has no upstream response and returns data.status_code: null. POST /api/connections and PUT /api/connections/{connection_type}/{name} accept additional_hosts as a list of up to four provider-allowed bare host authorities. The field is returned on connection list and detail rows. For type: "mcp", the locator can also include these fields:

Field	Type	Default	Description
`auth_type`	string	none	MCP authentication mode. Use `"auto"` to resolve open access versus interactive OAuth against the server before the connection is saved.
`headers`	object of string keys and values	`{}`	Static HTTP headers sent to the MCP server, including discovery requests. `Authorization` is not accepted here; use the `token` field for bearer authentication.
`transport`	`"http"` \| `"sse"`	`"http"`	Selects streamable HTTP or Server-Sent Events transport.
`auth_server_metadata_url`	string	empty	Optional OAuth metadata document URL used by the `auto` and `user_oauth` modes. It must use HTTPS, except for loopback hosts.

`POST /api/connections/mcp/snippet/parse`

Read a pasted Claude Code .mcp.json server entry without saving it or contacting the named server. The request can contain a complete mcpServers object, one named entry, or a bare server object. The parser accepts at most one server and limits text to 64,000 characters.

Field	In	Type	Default	Required	Description
`text`	body	string	none	Yes	Pasted JSON or a supported entry fragment. Server names, URLs, headers, transport, bearer authorization, and selected OAuth fields are mapped into connection fields.

The response is McpSnippetParseResponse:

Field	Type	Description
`ok`	boolean	`true` when the entry was read; `false` when it was refused.
`value`	object or null	Parsed fields when `ok` is `true`: `name`, `url`, `transport`, `headers`, `auth_type`, `token`, `client_id`, `scopes`, `metadata_url`, and `notes`. Bearer `Authorization` becomes `token`; other usable headers remain in `headers`.
`error`	object or null	Refusal code and string parameters when `ok` is `false`.

Refusals are returned as ordinary 200 responses so the Connections UI can explain them. Examples include invalid JSON, multiple servers, unsupported stdio transport, environment-variable references, and unusable headers. The registry includes the outbound MCP Server connector (type: mcp in connection requests, category tools). Its supported auth_types are none, bearer_token, oauth_client_credentials, and user_oauth. user_oauth accepts optional inline OAuth endpoints because Genesis can fill them from MCP metadata discovery and dynamic client registration. Creating or updating an MCP connection discovers and registers its remote tools; deleting it removes those tools. Interactive OAuth initiation is limited to the connection creator or an administrator because the resulting grant is shared by the connection’s agents. When the PAT gate blocks one of these routes, Genesis returns 403 with:

Your role does not allow PAT-based tool connections. Use OAuth instead, or ask an admin to enable PAT capability for your role.

Outpost API

These endpoints administer customer-run Outposts and back the connection form. Every route requires authentication. Administration routes require access_config_panel; the route-lookup and choices endpoints require authentication only.

Method	Path	Description	Auth behavior
`GET`	`/api/outposts`	Return whether Outpost routing is enabled and each configured Outpost’s live status. Where Outposts are available, contacts each Outpost once for health; every answer must be proven by that Outpost’s own tunnel key (a secret-store read the first time each key is used); an Outpost not yet issued a key is sent nothing and carries a `tunnel_key_warning` saying it cannot sign in and how to issue its key. In a Snowflake Native App without the Outpost tunnel endpoint, returns `enabled: false` and an `unavailable_reason` without contacting Outposts. See Genesis Outposts for availability.	Requires `access_config_panel`.
`PUT`	`/api/outposts/enabled`	Set the feature switch. Body: `{ "enabled": boolean }`. Enabling in a Snowflake Native App without the Outpost tunnel endpoint returns HTTP 501 with the reason; disabling remains allowed.	Requires `access_config_panel`.
`GET`	`/api/outposts/choices`	Return the Outposts this caller may choose for a connection and the feature’s enabled state.	Authentication only.
`GET`	`/api/outposts/route-for-connection`	Resolve routing for query fields `connection_type` and `host`, with optional `port`.	Authentication only.
`POST`	`/api/outposts/route-for-connection`	Resolve routing for a full locator. Body: `{ "connection_type": string, "locator": object }`.	Authentication only.
`PUT`	`/api/outposts/{name}`	Create an Outpost in the lowest free slot or update its routing patterns and roles. Optional body fields: `serves` (host-pattern array) and `route_roles` (role-name array); omitted fields remain unchanged. A new definition needs a separate tunnel-key issuance before its Outpost can sign in. A pattern change is rejected if it would make saved connections reach one host name through multiple Outposts.	Requires `access_config_panel`.
`DELETE`	`/api/outposts/{name}`	Remove the Outpost definition and delete its issued tunnel key. Query `force=true` to delete while saved connections still name it (`force` is boolean, default `false`). Without it, returns HTTP `409` with `code: outpost_in_use` and a `payload` containing `outpost` and `connections` (`{ type: string, name: string }` objects). This does not stop the customer-run process.	Requires `access_config_panel`.
`GET`	`/api/outposts/{name}/status`	Return one Outpost’s live status and diagnosis. Contacts that Outpost once for health. The status includes `version` (string or `null`): its release as reported by `/health`, or `null` for releases before 0.4.0 or when status was not requested.	Requires `access_config_panel`.
`POST`	`/api/outposts/{name}/test-route`	Ask the Outpost to check DNS and TCP reachability from the customer network. Body: `{ "host": string, "port": integer }`.	Requires `access_config_panel`.
`GET`	`/api/outposts/{name}/install`	Return generated identity and install steps for the selected target. Query: `target` (`laptop`, `vm`, `docker`, or `kubernetes`; default `docker`), `os`, `arch`, `namespace`, and `allowed` (comma-separated `host:port` values); optional secret-store settings are `secrets_source` (`aws`, `azure`, or `gcp`), `secret_prefix`, `key_vault_url` (Azure only), and `gcp_project` (GCP only), each a string defaulting to `null`. Secret-store settings are unsupported for `target=laptop`. Returns HTTP 501 with the reason in a Snowflake Native App without the Outpost tunnel endpoint; otherwise, without an `outpost.tunnel_endpoint_url` override, the URL is derived from the address the install wizard was opened at (the `/outpost-tunnel` path for self-hosted Genesis, the Native App endpoint in Snowflake, and the App URL for a Databricks App).	Requires `access_config_panel`.
`POST`	`/api/outposts/{name}/tunnel-key`	Issue the Outpost a new tunnel key of its own and return it once: `outpost`, `user` (`outpost-<slot>`), `key`, `key_id` and `env` (what to set on the Outpost). It replaces the previous key at once; within about 15 seconds Genesis’s tunnel ends that Outpost’s session (`key_rotated`), and other Outposts stay connected. The answer is not cacheable and the key is never returned again. Costs one secret write (with a secrets-audit row), one config write and one issuance audit row; replacing an existing key also deletes the previous secret (another secrets-audit row).	Requires `access_config_panel`.

In the /api/outposts response, each Outpost not yet issued its own key has a tunnel_key_warning (string or null): it cannot sign in until the key is issued, and the warning says how. It is null once the Outpost has its key. The response’s data.unavailable_reason is a string when the Snowflake Native App has no Outpost tunnel endpoint and null where Outposts can be used. The status response includes reachable, diagnosis (state, cause, message, and fix), routes, and tunnel_key_warning when applicable. Each route reports its host, port, using connections, and any refusal. A route withheld because multiple Outposts claim the same host name has cause host_conflict; Genesis leaves that host unrouted. unproven means Genesis received a control answer without a valid proof from that Outpost’s key and did not use the answer. When the Outpost’s /health reports a release version, status includes it as version; earlier releases and status responses without a health result return null. The route-lookup responses return data.outpost as the selected Outpost name or null. To route an individual connection, include its Outpost name in the connection locator’s optional outpost field. Rows returned by GET /api/connections also include outpost_route when a live route applies: outpost, routed_by (chosen or pattern), and the matching pattern when routing came from a host pattern. Other connection response routes return this field as null.

Connection visibility rules

Genesis applies these rules before returning connection list or detail payloads (routes that reference “standard connection-visibility rules”):

Scope	Who can see the connection
Any	Callers with `manage_all_connections` see every connection.
`personal`	Only the owner (`owner_user_id` matches the authenticated user). Other callers receive `404` on detail routes and the row is omitted from list responses.
`shared` with Roles with Access configured	Callers whose RBAC role (or user id) intersects the connection’s granted principals.
`shared` with no Roles with Access	Callers with `view_connections` (or `manage_all_connections`).

If Genesis cannot load access grants for a shared connection, it treats the connection as not visible (fail closed). Credential resolution for personal connections is also owner-only; other users receive a permission error instead of resolved secrets.

`GET /api/connections`

Field	In	Type	Default	Required	Description
`include_legacy`	query	boolean	`true`	No	Include legacy non-database connections alongside saved `APP_CONFIG` connections.
`include_legacy_db`	query	boolean	`true`	No	Include legacy database connections from `CUST_DB_CONNECTIONS`.
`include_hidden`	query	boolean	`false`	No	Include discovery-hidden connections (for example the System `Snowflake` row hidden via `POST /api/connections/system-snowflake/hidden`). Honored only for callers with `manage_all_connections`; non-admins always receive the default list with hidden rows omitted.
`search`	query	string or null	`null`	No	Match connection name, type, or provider display label. Maximum length: 200 characters.
`category`	query	`all` \	`databases` \	`git` \	`cloud` \	`pipelines` \	`tools` or null	`null`	No	Filter by the provider registry category. `databases` also matches entries marked `is_database` or `is_data_source`, even when their registry category is different. `all` and an omitted value do not apply a category filter.
`owner`	query	string or null	`null`	No	Filter by the connection owner key. Owner keys use `owner:<user-id>`, `bucket:system`, `bucket:legacy`, or `bucket:unknown`. Maximum length: 200 characters.
`scope`	query	`shared` \	`personal` \	`unknown` or null	`null`	No	Filter by connection scope. Connections without a recognized scope match `unknown`.
`auth`	query	string or null	`null`	No	Filter by effective authentication type. Maximum length: 100 characters.
`sort`	query	`name` \	`owner` \	`provider` \	`scope` \	`updated` or null	`null`	No	Sort matching rows by the selected field. If omitted, the endpoint preserves its discovery order.
`direction`	query	`asc` \	`desc`	`asc`	No	Sort direction when `sort` is provided.

GET /api/connections returns FilteredConnectionListResponse. The data[] array contains only rows matching the active search, category, owner, scope, and auth filters. Filtering and sorting are applied after visibility rules, so callers never receive rows they are not allowed to see. The response also includes total_visible, the number of visible rows before active filters, matched_count, the number of rows in data[], and facets. facets.owners[] and facets.auth_types[] contain value, label, and count for the full visible set before active filters. Use these facets to populate stable filter choices and counts without making a separate request. Connection list and detail responses do not return locator credentials. Fields whose names identify secrets are represented by redacted placeholders; credential values embedded in URLs, connection strings, DSNs, or other locator text are masked while the remaining text is preserved. Secret references remain visible as names. This applies even when the caller can view other sensitive connection metadata; it does not change the stored locator used to connect. Legacy database connections marked hidden=true in CUST_DB_CONNECTIONS are omitted from data[] unless include_hidden=true and the caller has manage_all_connections. The virtual System Snowflake connection uses the separate AppConfig flag connections.hide_system_snowflake; when that flag is true the row is omitted unless include_hidden=true for an admin caller. Connection rows in list responses can also include scoped-default metadata:

Response field	Type	Description
`is_default`	boolean	Deprecated legacy system-default flag. Always `false` in responses. `true` values in create/update requests return `400`.
`is_system_default`	boolean	Deprecated. Always `false` in responses. System/shared default connections are no longer supported.
`is_user_default`	boolean	Whether this row is the current user’s default connection for its type.
`is_role_default`	boolean	Whether this row is a default for at least one of the current user’s roles.
`is_effective_default`	boolean	Whether this row is the resolved effective default for the current caller.
`effective_default_source`	string or null	Resolution layer for the effective default on this row: `user` or `role`.
`scope`	string	`personal` or `shared`.
`owner_user_id`	string or null	Stable creator/owner id for personal connections.
`user_oauth_grants`	object	Per-user OAuth grant metadata keyed by user id. Token values are never returned. For non-admin callers, Genesis includes only the current user’s entry; callers with `manage_all_connections` receive all users’ entries.
`user_oauth_fields`	object	Per-user supplemental OAuth metadata keyed by user id. Scoped the same way as `user_oauth_grants`.
`personal_credentials`	string	Shared-connection credential policy: `disabled` (default), `optional`, or `required`. Personal connections do not use a shared policy.
`access_intent`	string	Declared read-vs-modify intent: `unspecified` (default), `read_only`, or `read_modify`. `read_only` is enforced for SQL that Genesis runs (query tools, governed writes, flows, the Prover): write-class statements (DDL, DML, CTAS, grants) are refused on the connection. Not covered: MongoDB connections, the native Snowflake connection and the Snowflake SQL API tools. `read_modify` is a declared label only. The Connections UI exposes this field for database connection types; `POST` and `PUT` accept it for any saved connection type.
`additional_hosts`	string[]	Additional host authorities that identify the same connection. Values are normalized, deduplicated, and limited to four validated host authorities.
`egress_preflight_state`	object or null	Latest external-access preflight result. When live routing sends all required endpoints through Outposts, the effective state is `ready` and identifies the Outpost routes; uncovered endpoints still use Snowflake external access.
`hidden`	boolean	Whether the connection is hidden from discovery lists. For legacy database rows this mirrors `CUST_DB_CONNECTIONS.HIDDEN`. For the virtual System `Snowflake` connection (`snowflake.Snowflake`, `created_by="legacy"`) this reflects the dedicated `connections.hide_system_snowflake` flag instead.

`GET /api/connections/system-snowflake/hidden`

Returns SystemSnowflakeHiddenResponse with data.hidden (boolean) reporting the current hide state for the virtual System Snowflake SPCS-token connection.

Status	When
`403`	Caller lacks `manage_all_connections`.

`POST /api/connections/system-snowflake/hidden`

Request body (SystemSnowflakeHiddenRequest):

Field	In	Type	Required	Description
`hidden`	body	boolean	Yes	`true` hides the connection from agents and dashboard lists; `false` shows it.

Returns SystemSnowflakeHiddenResponse with data.hidden set to the persisted state after the write. Genesis stores the flag at connections.hide_system_snowflake in AppConfig (not in CUST_DB_CONNECTIONS).

Status	When
`403`	Caller lacks `manage_all_connections`.

`PUT /api/connections/{connection_type}/{name}`

Genesis accepts partial update bodies. These scope-related fields apply on update:

Field	In	Type	Default	Required	Description
`connection_type`	path	string	none	Yes	Saved connection type.
`name`	path	string	none	Yes	Saved connection name.
`scope`	body	`"personal" \| "shared" \| null`	`null`	No	Updated connection scope. Omit to keep the existing value. Requires `manage_all_connections`; callers without it receive `403`.
`owner_user_id`	body	string or null	`null`	No	Owner user id for personal connections. Requires `manage_all_connections`. When `scope` changes to `personal` and this field is omitted, Genesis defaults to the authenticated caller. When `scope` changes to `shared`, Genesis keeps the existing `owner_user_id`.
`personal_credentials`	body	`"disabled" \| "optional" \| "required" \| null`	`null`	No	Updated shared-connection personal-credential policy. Omit to keep the existing value. `optional` and `required` require an authentication mode with registered principal fields; personal connections are stored as `disabled`.
`additional_hosts`	body	string[] or null	`null`	No	Additional host authorities for the connection. On update, omit to keep the existing list; provide a list to replace it. Each value must be a bare, provider-allowed host authority, and no more than four may be supplied.

An update that includes locator performs a live connectivity check before the request is committed. A failed check returns a validation error and leaves the saved connection unchanged; an update that changes only metadata does not need a live connection attempt. The agent-facing update action documents how conflict resolution selects the credential used for its check.

Connection activity endpoint

`GET /api/connections/{connection_type}/{name}/activity`

Lists recorded statements run on the selected connection and attributes each statement to the user and credential mode that ran it. This endpoint requires manage_all_connections.

Field	In	Type	Default	Required	Description
`connection_type`	path	string	none	Yes	Saved connection type.
`name`	path	string	none	Yes	Saved connection name.
`since`	query	ISO-8601 datetime or null	`null`	No	Inclusive lower bound for `created_at`.
`until`	query	ISO-8601 datetime or null	`null`	No	Inclusive upper bound for `created_at`.
`limit`	query	integer	`50`	No	Maximum number of statements. Allowed range: `1` to `500`. Results are newest first.

The response is ConnectionActivityResponse: success plus data, an array of ConnectionActivityItem objects:

Field	Type	Description
`activity_id`	string	Identifier of the recorded statement.
`connection_id`	string	Connection id exactly as recorded. It may be the bare name rather than `<type>.<name>`; use it to distinguish connections that share a name.
`user_id`	string or null	Acting user, or `null` when the connection’s service credential ran the statement.
`credential_mode`	`shared` \| `personal` \| `oauth` or null	Credential that resolved for the statement.
`statement_type`	string or null	Canonical operation.
`title`	string or null	Statement title or summary.
`access_modes`	string[]	Whether the statement read, wrote, or both.
`created_at`	string or null	UTC ISO-8601 execution time.
`resources`	object[]	Resources touched by the statement. Each object contains `resolved_qn` and `ref_kind` (`read` or `write`). Empty when the statement could not be linked to a resource.

The connection match checks both the bare name and the qualified <connection_type>.<name> form, case-insensitively. Connections of different types that share a name can therefore appear together; inspect each item’s connection_id. The call performs a filtered activity-table scan and an anchor lookup, so its scan cost grows with recorded activity.

Personal credential endpoints

Personal credentials are per-user principal bindings for shared connections. They are controlled by the connection’s personal_credentials policy: disabled (default), optional, or required. The authentication mode must declare the principal fields that users may provide. These endpoints never return secret values; responses contain scrubbed binding metadata such as user_id, status, principal_label, updated_at, and is_current_user.

`GET /api/connections/{connection_type}/{name}/credentials`

Returns ConnectionPersonalCredentialsResponse with data as the visible binding rows. A regular user receives their own binding; a caller with manage_all_connections can review bindings for the shared connection.

`PUT /api/connections/{connection_type}/{name}/credentials/me`

Request body:

Field	In	Type	Required	Description
`principal`	body	`object<string, string>`	Yes	Principal fields and values declared by the connection registry for the selected authentication mode. Secret values are accepted for binding but are never returned.

The route binds or replaces the authenticated user’s principal and returns ConnectionPersonalCredentialResponse with scrubbed binding metadata.

`DELETE /api/connections/{connection_type}/{name}/credentials/me`

Revokes the authenticated user’s binding and returns GenericResponse.

`DELETE /api/connections/{connection_type}/{name}/credentials/{user_id}`

Revokes the specified user’s binding and returns GenericResponse. The user may target only their own binding unless they have manage_all_connections.

Scoped default response fields

The scoped-default routes return ConnectionDefaultsResponse with data:

Field	Type	Description
`connection_type`	string	Connection type.
`system_default`	string or null	Deprecated. Always `null`. System/shared default connections are no longer supported.
`user_default`	string or null	Current user’s default connection id.
`role_defaults`	object	Role-to-connection-id mappings relevant to the current user. Callers with `manage_all_connections` receive the full role-default map for the type.
`effective_default`	string or null	Effective default connection id after user, then role resolution. `null` when no scoped default applies or when role defaults are ambiguous.
`effective_default_source`	string or null	Resolution layer for `effective_default`: `user` or `role`.
`matched_roles`	string[]	Roles that participated in role-default resolution.
`ambiguous`	boolean	Whether role defaults are ambiguous for the current user and no effective default could be chosen.

`GET /api/connections/{connection_type}/defaults`

Field	In	Type	Default	Required	Description
`connection_type`	path	string	none	Yes	Saved connection type to inspect.

This route returns ConnectionDefaultsResponse.

`PUT /api/connections/{connection_type}/{name}/defaults/user`

Field	In	Type	Default	Required	Description
`connection_type`	path	string	none	Yes	Saved connection type.
`name`	path	string	none	Yes	Visible saved connection name to mark as the caller’s default.

This route returns the updated ConnectionDefaultsResponse.

`DELETE /api/connections/{connection_type}/defaults/user`

Field	In	Type	Default	Required	Description
`connection_type`	path	string	none	Yes	Saved connection type whose user default should be cleared.

This route returns the updated ConnectionDefaultsResponse.

`PUT /api/connections/{connection_type}/{name}/defaults/roles/{role_name}`

Field	In	Type	Default	Required	Description
`connection_type`	path	string	none	Yes	Saved connection type.
`name`	path	string	none	Yes	Shared saved connection name to assign as the role default.
`role_name`	path	string	none	Yes	Role identifier to update.

Requires manage_all_connections. The target connection must be shared, non-legacy, and already accessible to role_name.

`DELETE /api/connections/{connection_type}/defaults/roles/{role_name}`

Field	In	Type	Default	Required	Description
`connection_type`	path	string	none	Yes	Saved connection type.
`role_name`	path	string	none	Yes	Role identifier whose default should be cleared.

Requires manage_all_connections.

`POST /api/admin/demo-data/purge`

This route accepts no query or body fields. POST /api/admin/demo-data/purge hides every bundled demo legacy database connection and asks Twin to evict that connection’s demo graph and search entries. The bundled set is the union of Twin-managed demo databases and locally seeded SQLite demos, including baseball_sqlite, formula_1_sqlite, hcls_demo_1_sources, credit_card_sqlite, asset_mgmt_sqlite, and lab_source_data.

Response field	Type	Description
`success`	boolean	`true` when the route completes (including partial Twin eviction).
`connections_hidden`	integer	Number of demo connections newly marked hidden.
`twin_entries_evicted`	integer	Number of Twin graph/vector entries evicted.
`errors`	string[]	Best-effort Twin eviction errors. Non-empty when connection hide succeeded but Twin eviction failed.

Genesis returns 403 when the caller lacks manage_all_connections.

Connection bundle export / import

These routes support cross-instance migration of saved connections with their secrets. Bundles use AES-256-GCM encryption; the passphrase must be at least 16 characters. Bundles expire 24 hours after export. Uploads larger than 10 MiB return 413. The Connections guide covers the import workflow and auth-mode inference for bundle entries that omit auth_mode.

`POST /api/connections/export-bundle`

Field	In	Type	Default	Required	Description
`passphrase`	body	string	none	Yes	Encryption passphrase (minimum 16 characters).
`connection_ids`	body	string[] or null	`null`	No	`type.name` identifiers to export. When omitted, exports all saved connections (`include_legacy=false`).

Returns 200 with Content-Type: application/octet-stream and Content-Disposition: attachment; filename="connections.genesis-bundle". Returns 400 when the passphrase is too short, a requested connection is not found, one or more selected connections fail to export (message lists failed type.name ids), or there are no connections to export. Returns 403 when the caller lacks manage_all_connections.

`POST /api/connections/import-bundle/preview`

Multipart form upload.

Field	In	Type	Default	Required	Description
`file`	form	file	none	Yes	`.genesis-bundle` file (maximum 10 MiB).
`passphrase`	form	string	none	Yes	Passphrase used during export.

Returns ConnectionBundlePreviewResponse with:

Response field	Type	Description
`new`	object[]	Connections that will be created. Each item includes `connection` (`type.name`), `type`, and `name`.
`conflicts`	object[]	Connections that already exist on the target. Same shape as `new`.
`warnings`	object[]	Non-fatal issues. Each item includes `connection` and `message` (for example OAuth re-authorization required, unknown connection type).
`exported_at`	string	Export timestamp (ISO-8601).
`source_instance`	string	Source instance identifier recorded at export time.

Returns 400 on decryption failure, expired bundle, or invalid format. Returns 413 when the uploaded file exceeds 10 MiB. Returns 403 when the caller lacks manage_all_connections.

`POST /api/connections/import-bundle/apply`

Multipart form upload.

Field	In	Type	Default	Required	Description
`file`	form	file	none	Yes	`.genesis-bundle` file (maximum 10 MiB).
`passphrase`	form	string	none	Yes	Passphrase used during export.
`conflict_resolutions`	form	string (JSON object) or null	`null`	No	JSON object mapping each conflicting `type.name` to `"skip"` or `"overwrite"`. Conflicts default to `"skip"` when omitted. Invalid JSON, non-object values, or values other than `"skip"` / `"overwrite"` return `400`.

Returns ConnectionBundleApplyResponse with:

Response field	Type	Description
`created`	string[]	`type.name` ids that were created.
`updated`	string[]	`type.name` ids that were overwritten.
`skipped`	string[]	`type.name` ids that were skipped.
`warnings`	object[]	Import-time warnings. Each item includes `connection` and `message`.

Returns 400 on decryption failure, expired bundle, invalid conflict_resolutions JSON (including keys or values outside "skip" / "overwrite"), or per-connection apply errors surfaced as ValueError. Returns 413 when the uploaded file exceeds 10 MiB. Returns 403 when the caller lacks manage_all_connections.

Health endpoints

`GET /api/health`

Readiness-oriented health check. Returns 200 only after startup has reached 100% progress; returns 503 with startup progress while the server is still initializing. For pure liveness without readiness gating, use GET /api/health/live. When the server is ready but impaired (for example agent warmup did not finish, or embedded Tailscale egress is down), Genesis still returns HTTP 200 so load balancers and SPCS keep routing traffic. In that case status is "degraded" and degraded_reason names the impairment for operators.

Response field	Type	Description
`status`	string	`"healthy"` when ready and not impaired; `"degraded"` when ready but impaired.
`ready`	boolean	`true` when startup is complete.
`degraded`	boolean	`true` when the server is reachable but impaired (for example incomplete agent warmup or embedded Tailscale egress loss).
`degraded_reason`	string	Human-readable impairment summary when `degraded` is `true`; empty string otherwise.
`llm_configured`	boolean	Whether the AppConfig-selected active chat provider is currently usable. This check uses runtime provider readiness, so stale environment overrides do not make an unready provider appear configured.
`llm_validation_error`	string or null	Validation error when `llm_configured` is false.
`timestamp`	string	ISO-8601 UTC timestamp.
`uptime_seconds`	number	Seconds since server start.
`version`	string	Application version with pre-release tags stripped (for example `1.7.2`). A development build with no version baked in reports `dev.<short commit>` (for example `dev.a18c97af20`). Use `GET /api/version` when you also need the full build identity.
`full_version`	string	Full version including pre-release tags (for example `1.7.2-rc.1`), or `dev.<short commit>` for a development build.
`tsnet`	object or omitted	Present when `GENESIS_TSNET_ENABLED=true`. Includes `enabled`, `online`, `backend_state`, `self_hostname`, `self_dns_name`, `self_tags`, or an `error` string when the Tailscale CLI is unreachable.

`GET /api/health/ready`

Kubernetes-style readiness probe. Returns 200 with ready: true when the static assets check and error-rate check pass; otherwise returns 503 with the same values in the response detail. The error-rate check passes when the current rate is below 50 errors per minute. Genesis measures that rate over at least one full minute after startup, so during the first 60 seconds it uses a 60-second denominator instead of treating the short uptime as a full-minute rate.

`GET /api/health/startup`

Startup progress endpoint used by the web UI. Always returns 200 with the current initialization state. When startup reaches 100%, the response includes degraded and degraded_reason (same semantics as GET /api/health) so clients can surface a ready-but-impaired state.

`GET /api/version`

Returns the live runtime version, the Genesis release carried by the build, and changelog and post-upgrade-advisor payloads used by the web client’s upgrade notice modal and header About Genesis menu. Release notes, changelog details, and the advisor key on the Genesis release version. On Genesis Desktop, version is the desktop app version, while genesis_version identifies the Genesis release. Genesis sets Cache-Control: no-cache on this route so the UI can poll while Eve generates a personalized upgrade summary.

Response field	Type	Description
`success`	boolean	`true` when the route completes.
`version`	string	Application version with pre-release tags stripped (for example `1.19.75`). A development build with no version baked in reports `dev.<short commit>` (for example `dev.32fb8e0fe3`); read `commit_sha` for the full build identity.
`full_version`	string or null	Full version including pre-release tags (for example `1.19.75-rc.2`), or `dev.<short commit>` for a development build.
`display_version`	string or null	Version shown to a person. For a named Genesis Desktop or hosted build, this is the display name: for example, `1.19.98` for its first build and `1.19.98d3` for its third later build (whose `full_version` is `1.19.98-3`). For other builds, this is `version`.
`build_source`	object or null	Recorded origin of a named build: `sha` (commit), `kind` (`main` or `patch` for a branch on top of a release), and `branch`. `null` when the build recorded no source.
`build_changes`	string[]	Changes recorded for a later build on a release, newest first (for example, a build named `1.19.98d3`). Empty for other builds.
`genesis_version`	string or null	Genesis release carried by this build, with pre-release tags stripped. Equals `version` except on Genesis Desktop, where `version` is the desktop app’s own version (for example `0.2.10`). Changelog and post-upgrade-advisor data key on this release.
`genesis_full_version`	string or null	`genesis_version` including pre-release tags.
`commit_sha`	string or null	Git commit this process is serving. `null` only when `commit_unavailable_reason` explains why the commit cannot be determined; Genesis does not substitute a placeholder.
`commit_source`	string or null	Source of `commit_sha`: `startup_snapshot` for the commit captured at process startup, or `environment` when the Docker image’s `GENESIS_COMMIT_SHA` build arg supplies the commit. `null` when the commit is unknown.
`commit_unavailable_reason`	string or null	Reason the serving commit could not be determined; `null` when `commit_sha` is set.
`repo_root`	string or null	Repository root directory the backend is running from.
`changelog_summary`	string[]	Up to three short feature highlights extracted from the internal `changelogs/changelog_*_to_v<version>.md` artifact when one exists for `genesis_version`.
`changelog_url`	string or null	Docs URL for the full release notes. For GA semver `genesis_version` values (`major.minor.patch`), Genesis returns the per-version Mintlify page — for example `https://docs.genesiscomputing.com/docs/Getting-Started/changelog/v1.8.4`. For non-semver releases, Genesis returns the changelog index (`.../Getting-Started/changelog`). The shared docs-link flow rewrites this to `/client-docs/...` when `docs.use_internal_docs` is `true` and requests an authenticated hosted session when it is `false`.
`release_notes_markdown`	string or null	Full operator-facing release notes markdown for `genesis_version`, read from `config/genesis-docs-source/docs/Getting-Started/changelog/v<version>.mdx` (for example `v1.19.75.mdx` for Genesis release `1.19.75`). Rendered in the upgrade modal Release notes tab. Empty when no published page exists for the Genesis release (common on dev builds).
`release_notes_version_label`	string or null	Label of the release-notes document being shown (for example `v1.19.75`). Omitted when `release_notes_markdown` is empty.
`upgrade_summary_markdown`	string or null	Eve-generated personalized post-upgrade report when ready.
`upgrade_summary_thread_id`	string or null	Eve thread id for follow-up chat (`Discuss with Eve`).
`upgrade_summary_status`	string	`ready`, `generating`, or `unavailable`.
`upgrade_summary_error`	string or null	Short error hint when `upgrade_summary_status` is `unavailable`.
`llm_defaults_force_reset_applied`	boolean	Whether the one-time LLM defaults force-reset migration has run.
`llm_defaults_force_reset_providers`	string[]	Provider ids reset during that migration.

`POST /api/upgrade-summary/regenerate`

Clears the cached summary for the current runtime version and queues a fresh Eve post-upgrade-advisor run. Requires access_config_panel.

Response field	Type	Description
`success`	boolean	Whether the request completed.
`accepted`	boolean	Whether Genesis queued the background advisor job.

`POST /api/upgrade-summary/refresh-inventory`

Force-rebuilds the cached install inventory snapshot used by the advisor (bots, Apps, flows, blueprints, connections). Requires access_config_panel.

Response field	Type	Description
`success`	boolean	`true` when the snapshot rebuild completes.
`snapshot_path`	string	On-disk path to the cached inventory JSON.
`built_at`	string	ISO timestamp when the snapshot was built.
`bots`	integer	Bot count in the snapshot.
`apps`	integer	App count in the snapshot.
`flows`	integer	Flow count in the snapshot.
`blueprints`	integer	Blueprint count in the snapshot.
`connections`	integer	Connection count in the snapshot.
`errors`	string[]	Partial-failure messages when one or more inventory categories could not be collected.

Runtime health and observability endpoints

These routes are mounted under /api/health/... and back low-overhead runtime diagnostics used by Pulse and other operator tooling.

Method	Path	Description
`GET`	`/api/health/detailed`	Return the broader runtime snapshot, including a non-blocking `thread_service` summary. Requires `access_config_panel` when auth is enabled (open in no-auth dev mode). Anonymous callers receive `401`; callers without config-panel access receive `403` — there is no partial or redacted payload.
`GET`	`/api/health/thread-service/ready`	Tokenless readiness probe that returns only `enabled` and `active` from the non-blocking thread-service snapshot. Use for CI and ingress startup checks that must wait for the worker without config-panel credentials.
`GET`	`/api/health/thread-service`	Run a live `health()` RPC against the thread-service worker with a 10 second timeout. In auth-enabled deployments, this route requires the same config-panel access used for full thread-service details.
`GET`	`/api/health/threads`	Return live Python thread diagnostics with provenance-aware family summaries.
`GET`	`/api/health/server-panel-telemetry`	Return the cached Pulse Server runtime telemetry snapshot. Requires `access_config_panel` when auth is enabled (open in no-auth dev mode). Anonymous callers receive `401`.
`GET`	`/api/health/slots`	Return abridged, PII-free agent slot usage for authenticated callers. Identity fields are served only by `GET /api/admin/slots`. Anonymous callers receive `401` when auth is enabled.

`GET /api/health/detailed`

This route returns the broader detailed runtime snapshot used by operator tooling. Its nested thread_service block is intentionally non-blocking: Genesis reads in-memory metrics and worker process liveness without issuing a live worker RPC. The top-level snapshot also includes degraded and degraded_reason with the same semantics as GET /api/health. When no worse condition is already reported, a ready-but-degraded startup sets top-level status to "degraded". The errors.error_rate_per_minute value is calculated over at least one full minute after startup. During the first 60 seconds, Genesis uses a 60-second denominator so a short burst of startup errors does not appear as an inflated full-minute rate. The detailed health status uses this rate for its degraded and unhealthy thresholds, and the readiness probe uses it for its 50-errors- per-minute check. In auth-enabled deployments, callers need access_config_panel. Anonymous callers receive 401; callers without config-panel access receive 403 with detail Config panel access required. In no-auth dev mode the route is open.

`child_processes` field in `/api/health/detailed`

The detailed health response includes an in-memory snapshot of child-process supervision. supervised is true only when the supervision job is configured to run in a Databricks App: jobs.child_process_supervisor.enabled is enabled and jobs.child_process_supervisor.interval_seconds is positive. The children object is keyed by child name and reports state for children seen by a supervision pass.

Field	Type	Description
`supervised`	boolean	Whether child-process supervision is configured to run in this Databricks App.
`children`	object	Per-child restart snapshot. Each child has `status`, `restarts_in_window`, `total_restarts`, `last_exit_code`, `last_restart_at`, and `last_error`.
`children.{name}.status`	string	Latest supervision status: `healthy`, `not_started`, `restarted`, `busy`, `not_due`, `backing_off`, `restart_failed`, or `budget_exhausted`.
`children.{name}.restarts_in_window`	integer	Restarts currently counted in the configured restart window.
`children.{name}.total_restarts`	integer	Total restarts recorded in this process.
`children.{name}.last_exit_code`	integer or null	Exit code observed for the most recent dead-child check.
`children.{name}.last_restart_at`	string or null	ISO-8601 UTC timestamp of the most recent restart.
`children.{name}.last_error`	string or null	Most recent process-inspection or restart error.

The snapshot is process-local and performs no child-process RPC. Configure the job and restart budget in Advanced Settings — Child process supervisor.

Genesis no longer returns a filtered thread_service block for callers without config-panel access. Hard denial supersedes the legacy sensitive-field filtering path.

`thread_service` fields inside `/api/health/detailed`

Field	Type	Description
`enabled`	boolean	Whether thread-service diagnostics are enabled for the current runtime.
`active`	boolean	Whether the worker process is currently alive. This value comes from the local process snapshot, not a live worker RPC.
`worker_pid`	integer or null	Worker process id when full thread-service detail is visible.
`last_rpc_success_at`	float or null	Unix timestamp of the most recent successful thread-service RPC seen in in-memory metrics.
`rpc_metrics`	object	RPC metrics snapshot, including totals, rolling latency aggregates, and per-action counters.
`read_route_metrics`	object	Read-route metrics snapshot.
`write_route_metrics`	object	Write-route metrics snapshot.
`compression_metrics`	object	Compression metrics snapshot.
`boot_metrics`	object	Worker boot metrics snapshot.
`search_metrics`	object	Thread-search metrics snapshot.
`loaded_threads`	object	Approximate in-memory `BotOsThread` counts for the main process.
`error`	string or null	Snapshot error when Genesis cannot initialize the client or collect the thread-service health summary.

Selected nested `thread_service` metrics

`rpc_metrics.totals` fields

Field	Type	Description
`calls`	integer	Total thread-service RPC calls recorded in the current process.
`success`	integer	Successful RPC calls.
`errors`	integer	RPC calls that failed with a non-timeout error.
`timeouts`	integer	RPC calls that timed out.
`probe_timeouts`	integer	Timeout count recorded by probe-style calls.
`avg_elapsed_ms`	float or null	Average elapsed time across all RPC calls.
`avg_success_elapsed_ms`	float or null	Average elapsed time across successful RPC calls only.
`slow_calls`	integer	RPC calls whose elapsed time reached or exceeded 10 seconds (10,000 ms).
`very_slow_calls`	integer	RPC calls whose elapsed time reached or exceeded 30 seconds (30,000 ms).
`last_slow_action`	string or null	Most recent RPC action classified as slow or very slow.
`last_slow_elapsed_ms`	float or null	Elapsed time of the most recent slow or very slow RPC call.
`last_slow_at`	float or null	Unix timestamp of the most recent slow or very slow RPC call.

`rpc_metrics.rolling` fields

Field	Type	Description
`window_seconds`	integer	Rolling latency window size in seconds.
`sample_count`	integer	Total number of latency samples retained.
`window_sample_count`	integer	Number of latency samples currently inside the rolling window.
`recent_avg_elapsed_ms`	float or null	Average elapsed time across the retained recent RPC samples.
`window_avg_elapsed_ms`	float or null	Average elapsed time inside the active rolling window.
`recent_max_elapsed_ms`	float or null	Maximum elapsed time across the retained recent RPC samples.
`window_max_elapsed_ms`	float or null	Maximum elapsed time inside the active rolling window.

`rpc_metrics.actions` fields

Each key is an RPC action name (for example run_compression). Values are per-action counter buckets.

Field	Type	Description
`calls`	integer	Total RPC calls recorded for this action.
`slow_calls`	integer	Calls for this action whose elapsed time reached or exceeded 10 seconds (10,000 ms).
`very_slow_calls`	integer	Calls for this action whose elapsed time reached or exceeded 30 seconds (30,000 ms).

Pulse uses these per-action slow counters to attribute long run_compression work separately from read, write, and search RPC latency when deriving the Server tile severity.

`boot_metrics.state` fields

Field	Type	Description
`boot_count`	integer	Number of worker boot attempts recorded since process start.
`boot_failures`	integer	Number of recorded worker boot failures since process start.
`last_boot_started_at`	float or null	Unix timestamp when the most recent worker boot attempt started.
`last_boot_ready_at`	float or null	Unix timestamp when the most recent worker boot finished successfully.
`last_boot_elapsed_s`	float or null	Seconds taken by the most recent successful boot.
`last_boot_attempts`	integer or null	Number of internal attempts used by the most recent boot sequence.
`last_worker_pid`	integer or null	Worker pid recorded for the most recent boot attempt.
`last_boot_outcome`	string or null	Outcome of the most recent boot attempt, such as `ready`, `timeout`, `worker_died`, or `error`.
`last_boot_error`	string or null	Error summary for the most recent failed boot attempt.
`first_rpc_at`	float or null	Unix timestamp of the first successful RPC after the current worker booted.
`time_to_first_rpc_s`	float or null	Seconds from worker boot to the first successful RPC.

`search_metrics.totals` fields

Field	Type	Description
`calls`	integer	Total thread-search calls.
`success`	integer	Successful thread-search calls.
`errors`	integer	Thread-search calls that failed with a non-timeout error.
`timeouts`	integer	Thread-search calls that timed out.
`empty_results`	integer	Successful searches that returned no matches.
`avg_elapsed_ms`	float or null	Average elapsed time across all searches.
`avg_success_elapsed_ms`	float or null	Average elapsed time across successful searches only.
`success_rate`	float or null	Success ratio across all recorded searches.
`last_elapsed_ms`	float or null	Elapsed time of the most recent search call.
`last_match_count`	integer or null	Match count returned by the most recent successful search.
`last_backend`	string or null	Backend label used by the most recent successful search.
`last_error`	string or null	Error summary from the most recent failed search.
`last_search_at`	float or null	Unix timestamp of the most recent search call.
`last_success_at`	float or null	Unix timestamp of the most recent successful search call.
`last_error_at`	float or null	Unix timestamp of the most recent failed search call.

`loaded_threads` fields

Field	Type	Description
`total`	integer	Approximate number of currently loaded `BotOsThread` instances in memory.
`bot_sessions`	integer	Number of bot-session maps currently holding loaded threads.

`GET /api/health/threads`

This route does not accept query parameters.

Thread diagnostics response fields

Field	Type	Description
`success`	boolean	Whether the request completed successfully.
`total`	integer	Total Python threads in the current process.
`tracked_total`	integer	Total threads attributed to repo-owned code or registered pools.
`untracked_total`	integer	Total threads visible to Python that Genesis could not attribute.
`oldest_age_seconds`	float or null	Age of the oldest live thread using the best available reference time.
`oldest_tracked_age_seconds`	float or null	Age of the oldest tracked live thread.
`by_prefix`	object	Thread counts keyed by normalized thread family name.
`top_families`	object[]	Largest live thread families grouped by count, provenance, and oldest age.
`threads`	object[]	Full live thread list with best-effort provenance metadata.

`top_families[]` item fields

Field	Type	Description
`family`	string	Normalized thread family name.
`count`	integer	Live thread count for that family.
`tracked`	boolean	Whether the family is attributed to repo-owned code.
`creator_tag`	string or null	Best-effort module or subsystem tag.
`kind`	string or null	Thread kind such as `raw_thread` or `thread_pool`.
`source_file`	string or null	Repo-relative source file when available.
`max_age_seconds`	float or null	Oldest live thread age for that family.

`threads[]` item fields

Field	Type	Description
`name`	string	Thread name.
`family`	string	Normalized thread family name.
`ident`	integer or null	Python thread identifier.
`daemon`	boolean	Whether the thread is daemonized.
`native_id`	integer or null	Native OS thread id when available.
`tracked`	boolean	Whether Genesis attributed the thread to repo-owned code.
`creator_tag`	string or null	Best-effort module or subsystem tag.
`origin`	string or null	How Genesis attributed the thread.
`kind`	string or null	Thread kind such as `raw_thread` or `thread_pool`.
`source_file`	string or null	Repo-relative source file when available.
`source_function`	string or null	Best-effort source function when available.
`age_seconds`	float or null	Thread age in seconds.
`age_source`	string or null	Whether age is based on recorded start time or first observation.

`GET /api/health/thread-service/ready`

Tokenless operational readiness probe for the thread-service worker. Genesis reads the same non-blocking in-process snapshot used by the thread_service block in GET /api/health/detailed and returns only enabled and active — no live worker RPC. Use this from CI, ingress startup checks, or other automation that must wait for the external worker to come up without config-panel credentials. For full thread-service diagnostics, use GET /api/health/detailed (requires access_config_panel when auth is enabled). For a live health() round-trip, use GET /api/health/thread-service. In auth-enabled deployments, this route is tokenless (same treatment as GET /api/health, GET /api/health/live, and GET /api/health/ready).

Field	Type	Description
`enabled`	boolean	Whether thread-service diagnostics are enabled for the current runtime.
`active`	boolean	Whether the worker process is currently alive. This value comes from the local process snapshot, not a live worker RPC.

`GET /api/health/thread-service`

This route performs a live health() round-trip against the thread-service worker. Use it for deploy verification or on-demand stuck-worker debugging when you want a real IPC probe rather than the cheaper snapshot included in /api/health/detailed or GET /api/health/thread-service/ready. The timeout is fixed at 10.0 seconds and is returned as timeout_s.

Field	Type	Description
`ok`	boolean	Whether the live worker probe succeeded.
`worker_pid`	integer or null	Worker process id if Genesis can resolve the worker process before running the probe.
`timeout_s`	float	Probe timeout budget in seconds.
`status`	object	The live worker health payload on success. Genesis injects `worker_pid` into this object before returning it.
`error`	string	Error text on probe failure. Common values include `"timeout"` or an exception summary such as `RuntimeError: ...`.

In auth-enabled deployments, callers need config-panel access for this route. Without it, Genesis returns 403 Forbidden instead of a filtered response.

`GET /api/health/server-panel-telemetry`

This route returns the Pulse Server runtime snapshot. It is cache-backed by default and omits the heavier health block used by broader telemetry flows.

Field	In	Type	Default	Required	Description
`force_refresh`	query	boolean	`false`	No	Skip the short cache and build a fresh runtime snapshot.

When server telemetry is disabled, the response returns enabled=false, schema_version=1, and reason="disabled_by_env".

In auth-enabled deployments, callers need access_config_panel for this route. Anonymous callers receive 401; callers without config-panel access receive 403 with detail Config panel access required. In no-auth dev mode the route is open.

Server-panel telemetry top-level fields

Field	Type	Description
`enabled`	boolean	Whether server-panel telemetry is enabled for this runtime.
`schema_version`	integer	Telemetry payload version.
`captured_at`	string	ISO-8601 timestamp for the captured snapshot.
`captured_at_ts`	float	Unix timestamp used for the snapshot.
`config`	object	Snapshot configuration, including `interval_ms` and `top_n`.
`runtime`	object	Runtime-only telemetry block used by the Pulse Server view.

`runtime.threads` fields

Field	Type	Description
`total`	integer	Total live Python threads.
`tracked_total`	integer	Live threads attributed to repo-owned code or registered pools.
`untracked_total`	integer	Live threads visible to Python without provenance attribution.
`oldest_age_seconds`	float or null	Age of the oldest live thread in seconds.
`oldest_tracked_age_seconds`	float or null	Age of the oldest tracked live thread in seconds.
`top_prefixes`	object[]	Legacy family summary keyed by `prefix` and `count`.
`top_families`	object[]	Provenance-aware family summary keyed by `family`, `count`, `tracked`, `creator_tag`, `kind`, `source_file`, and `max_age_seconds`.
`growing_families`	object[]	Families whose live count increased since the previous server-panel snapshot. Each entry includes `family`, `count`, and `delta`.
`delta_window_seconds`	float or null	Seconds elapsed between the current thread comparison and the prior snapshot used to compute `growing_families`.

`runtime.async_dispatch` fields

The Pulse Server snapshot reports the event-loop-native prompt dispatcher under runtime.async_dispatch. It is the prompt dispatch path used when a bot has a registered WebSocket adapter; requests without one use the synchronous fallback described in Chat endpoints.

Field	Type	Description
`workers_total`	integer	Total per-thread async-dispatch workers currently tracked.
`workers_active`	integer	Workers currently processing a prompt.
`workers_idle`	integer	Tracked workers that are not currently processing a prompt.
`workers_with_pending`	integer	Workers with a newer prompt waiting for dispatch.
`active_tasks`	integer	Async-dispatch tasks currently active.
`dispatch_completed`	integer	Async-dispatch requests completed since the dispatcher was initialized.
`dispatch_errors`	integer	Async-dispatch requests that ended with an error since the dispatcher was initialized.

`GET /api/health/slots`

Return abridged agent slot usage for authenticated callers. This route intentionally omits user identity fields. For the full payload used by the Pulse CWA Monitor / Slots view, call GET /api/admin/slots instead. In auth-enabled deployments, anonymous callers receive 401. Tokenless load-balancer probes should use GET /api/health or GET /api/health/ready instead. Returns 503 when AgentSlotService is not initialized.

Slots response top-level fields (`/api/health/slots`)

Field	Type	Description
`abridged`	boolean	Always `true` on this route. Signals that identity fields were stripped.
`max_slots`	integer	Licensed concurrent agent slot limit for this runtime.
`acquired_slots`	object[]	Slots currently held (active work or cooldown).
`waiting_threads`	object[]	Threads queued for the next available slot.

`acquired_slots[]` fields (`/api/health/slots`)

Field	Type	Description
`bot_id`	string	Bot holding the slot.
`thread_id`	string	Thread id for the held slot.
`count`	integer	`0` when the slot is in cooldown after active work; greater than `0` when actively executing.
`acquired_at`	string or null	ISO-8601 timestamp when the slot was acquired.
`released_at`	string or null	ISO-8601 timestamp when active work finished and cooldown began.
`cooldown_type`	string or null	Cooldown category such as `chat` or `blueprint`.

This route does not return user_id, user_display_name, or thread_purpose.

`waiting_threads[]` fields (`/api/health/slots`)

Field	Type	Description
`bot_id`	string	Bot waiting for a slot.
`thread_id`	string	Thread id waiting in the queue.
`cooldown_type`	string or null	Cooldown category the waiter will use when a slot is granted.
`waiting_since`	string or null	ISO-8601 timestamp when the thread entered the wait queue.
`position`	integer	1-based queue position.

This route does not return user_id, user_display_name, or thread_name.

`GET /api/admin/slots`

Return full agent slot usage, including user identity fields, for operator tooling such as the Pulse CWA Monitor / Slots page. The operational shape matches GET /api/health/slots, but acquired and waiting entries also include identity metadata. In auth-enabled deployments, callers need access_config_panel. Without it, Genesis returns 403 Forbidden with detail Config panel access required. In no-auth dev mode the route is open. Returns 503 when AgentSlotService is not initialized.

Slots response top-level fields (`/api/admin/slots`)

Field	Type	Description
`max_slots`	integer	Licensed concurrent agent slot limit for this runtime.
`acquired_slots`	object[]	Slots currently held (active work or cooldown).
`waiting_threads`	object[]	Threads queued for the next available slot.

`acquired_slots[]` fields (`/api/admin/slots`)

Includes every field from the abridged /api/health/slots response plus:

Field	Type	Description
`thread_purpose`	string or null	Thread purpose label when recorded at slot acquisition.
`user_id`	string or null	User id associated with the slot.
`user_display_name`	string or null	Display name for the associated user when available.

`waiting_threads[]` fields (`/api/admin/slots`)

Includes every field from the abridged /api/health/slots response plus:

Field	Type	Description
`user_id`	string or null	User id associated with the waiting thread.
`user_display_name`	string or null	Display name for the associated user when available.
`thread_name`	string	Best-effort thread title or user-visible name; empty string when lookup fails.

Memory trace logging

Genesis emits periodic memory-trace log lines when the server starts with GENESIS_MEM_TRACE set to a truthy value (1, true, yes, or on). The monitor is off by default and imposes zero runtime cost when disabled. A dedicated daemon thread (MemoryMonitor) runs on the main Genesis process only (not the thread-service worker). It emits trace lines every 60 seconds at WARNING so they surface in SPCS log mirrors and in worker processes whose GENESIS logger level is WARNING.

Variable	Default	Description
`GENESIS_MEM_TRACE`	off	Enable the memory monitor and its 60s RSS/cgroup trace tick.
`GENESIS_MEM_TRACE_TRACEMALLOC`	off	When set to a truthy value alongside `GENESIS_MEM_TRACE`, also enable `tracemalloc` allocation tracing on the `MEM OS` line. Inflates RSS — use only for deliberate attribution sessions with memory headroom.

Process-level trace lines (every 60s):

MEM OS: — main-process RSS, Python block count, thread count, open-file count, and (on Linux) cgroup memory trajectory.
MEM_LEAK_SCAN / MEM_LEAK_SUSPECT — type-count leak heuristics every 10 minutes.

Per-microapp RSS attribution (every 60s, when GENESIS_MEM_TRACE is on): Microapp processes may run under a dedicated Linux user (microapp_<suffix> via sudo -u on SPCS). Their RSS is not included in the main MEM OS line. Instead, Genesis polls each running app’s PID, sums the RSS of that process and its descendants, and emits one line per app plus a summary:

Log prefix	Fields	Description
`MEM_APP`	`app_id`, `pid`, `rss_mb`, `rss_delta_mb`	Combined resident set size of the app PID and its descendants. `rss_delta_mb` is the change since the previous 60s tick (`0` on first sighting). Apps are sorted largest-first.
`MEM_APP_SUMMARY`	`n_apps`, `apps_total_mb`, `top_app`, `top_mb`	Roll-up across all running microapps on that tick.

RSS is read via psutil when permitted; on cross-user AccessDenied (typical for sudo -u apps on SPCS), Genesis falls back to the world-readable /proc/{pid}/statm resident-page count. Exited or unreadable processes are skipped without treating EPERM from os.kill(pid, 0) as dead. These lines appear in the Pulse log buffer and are downloadable via GET /api/logs and GET /api/logs/download. Filter with the log WebSocket search field (for example MEM_APP).

Scheduler and background job endpoints

These routes are mounted under /api/scheduler/.... The background-job routes below back Pulse -> Jobs rather than the prompt-job builder on the Scheduler page.

Method	Path	Description	Required permission
`GET`	`/api/scheduler/jobs`	Return the background-job inventory used by Pulse. Genesis merges `GenesisApp.BackgroundScheduler` jobs with FastAPI `AsyncIOScheduler` jobs and de-dupes name collisions in favor of the Genesis job.	`view_scheduler`
`POST`	`/api/scheduler/jobs/{job_name}/start`	Start a Genesis background job or resume a FastAPI `AsyncIOScheduler` job when no Genesis background job owns the same name.	`manage_scheduler`
`POST`	`/api/scheduler/jobs/{job_name}/stop`	Stop or pause a Genesis background job or pause a FastAPI `AsyncIOScheduler` job when no Genesis background job owns the same name.	`manage_scheduler`

GET /api/scheduler/jobs returns success and jobs. POST job-action responses return success and message.

Prompt-job expiration fields

The prompt-job routes under /api/scheduler/prompt-jobs expose the schedule’s expiration and indefinite-run intent. GET responses include these fields in each job, and POST create or PUT update requests pass the expiration values inside the trigger object:

Field	Type	Default	Description
`trigger_config`	object	`{}`	Structured trigger configuration, including expiration and perpetual metadata.
`end_date`	string or null	`null`	Schedule expiration time in ISO format.
`perpetual`	boolean	`false`	Whether indefinite scheduling was requested.
`perpetual_reason`	string or null	`null`	Audit reason for intentionally scheduling without expiration.

For recurring cron and interval schedules, use either a future end_date or perpetual: true with a non-empty perpetual_reason; do not send both. The same validation applies when updating an existing job, including an update that changes only the prompt or name. Invalid expiration input returns HTTP 400 with the validation message in the error response. Pause, resume, run-now, and delete operations do not require new expiration fields. GET /api/scheduler/prompt-jobs/history and DELETE /api/scheduler/prompt-jobs/history can return HTTP 503 while the scheduler restores run history after a restart. Retry after the restore completes.

Background job item fields

Field	Type	Description
`name`	string	Job identifier returned by the API and used by Pulse.
`status`	string	Job state such as `running` or `stopped`. FastAPI jobs report `stopped` when `next_run_time` is `null`. A `stopped` value alone does not distinguish an operator pause from intentional dormancy — see `status_reason`.
`status_reason`	string or null	When `status` is `stopped`, explains why the job is not running. Operator stops leave this `null`. Jobs paused for intentional dormancy set values prefixed with `dormant:` — for example `dormant:no_active_runtime_sessions` on `sandbox_monitor_job` when there are no active sandbox runtime sessions to watch. Cleared when the job is started or resumed.
`sleep_seconds`	integer or null	Genesis background-job interval in seconds when provided by the Genesis job definition.
`task_limit_minutes`	integer or null	Genesis background-job task time limit in minutes when provided by the Genesis job definition.

Notable FastAPI interval jobs surfaced by GET /api/scheduler/jobs include twin_scan_cost_sync (Twin Scan Cost Sync), which periodically syncs Twin scan LLM spend into SCAN_USAGE_FACTS for the Cost & Usage cube. Control it through App Config (not /api/config/user-config):

App Config path	Type	Default	Description
`jobs.twin_scan_cost_sync.enabled`	boolean	`true`	Enable or disable the Twin scan-cost sync job. On by default; each pass reads a bounded window that reaches back no further than the cost cutover.
`jobs.twin_scan_cost_sync.interval_seconds`	integer	`900`	Seconds between sync passes. Set to `0` or less to avoid registering the job.

agent_review_classifier (Agent Review Classifier) runs the scheduled turn-classifier pass when both agent_review.enabled and jobs.agent_review_classifier.enabled are true. When agent_review.steering_patterns.enabled is also true, each completed classifier tick runs a steering-pattern miner post-pass that proposes candidate learnings from recurring corrections (the post-pass is a no-op when either gate is off and never fails the classifier run). Control these settings through App Config (not /api/config/user-config): After classification, each scheduled tick also runs a settlement-only, database-only pass for threads with unsettled task facts that are now dormant. This closes a trailing task that was graded while its thread was still active; active threads remain unsettled until they meet the configured dormancy window. The pass makes no LLM call, and its attempts are separately bounded by jobs.agent_review_classifier.max_threads_per_run.

App Config path	Type	Default	Description
`agent_review.enabled`	boolean	`false`	Master switch for agent-review analysis (classifier routes, backfill, scorecard, learning APIs, and prompt injection). When `false`, analysis routes return `404` and the scheduled job is a no-op. Explicit message feedback remains available. Advisory-only — scores never gate agent actions.
`agent_review.model_tier`	string	`fast`	Model tier for turn classification. Allowed values: `nano`, `fast`, `main`, `frontier`.
`agent_review.steering_patterns.enabled`	boolean	`false`	Mine recurring steering-correction patterns into candidate learnings as a post-pass of the agent-review classifier job (requires `agent_review.enabled`).
`agent_review.steering_patterns.min_recurrence`	integer	`3`	Steering corrections sharing one `(bot, workflow type, anchor)` group required before a candidate learning is proposed. Minimum `1`.
`agent_review.steering_patterns.window_days`	integer	`30`	Lookback window in days for steering-pattern mining. Minimum `1`.
`agent_review.learning_deltas.horizon_days`	integer	`14`	Days before and after each adoption compared by the learning-delta report. Minimum `1`.
`agent_review.learning_deltas.min_tasks_per_window`	integer	`5`	Minimum settled tasks per window before a learning delta reports rates instead of `insufficient_data`. Minimum `1`.
`agent_review.feedback_to_agents.enabled`	boolean	`false`	Inject the filtered per-agent AGENT REVIEW NOTES block into prompts (behavioral steering patterns only). When `false`, prompts are byte-identical; agents can still call `consult_review_notes` when the tool group is assigned. Checked live per turn (no restart).
`jobs.agent_review_classifier.enabled`	boolean	`false`	Enable the scheduled classifier job (requires `agent_review.enabled`).
`jobs.agent_review_classifier.interval_minutes`	integer	`15`	Minutes between automatic classifier ticks.
`jobs.agent_review_classifier.dormant_after_minutes`	integer	`60`	Quiet time after which a thread’s ungraded span is classified and its trailing task settles.
`jobs.agent_review_classifier.min_new_turns_incremental`	integer	`8`	Ungraded user turns that trigger an incremental pass on a still-active thread.
`jobs.agent_review_classifier.scan_lookback_days`	integer	`7`	Only consider threads with activity within this many days during automatic scans. `0` scans all history.
`jobs.agent_review_classifier.min_assistant_messages`	integer	`3`	Minimum assistant messages required before a thread is classified.
`jobs.agent_review_classifier.max_threads_per_run`	integer	`20`	Maximum threads classified per scheduled tick. The same budget separately bounds settlement-only re-derivation attempts, which cost no model spend.

Internal scheduler subprocess endpoints

These routes are mounted under /api/internal/scheduler/... and are intended for the scheduler MCP subprocess to run dataset, dashboard, and Flow work inside the main FastAPI process. They are not part of the interactive client API.

Requests require an Authorization header with the internal bearer token: Bearer <internal-token> (the same token used by other /api/internal/... routes that accept the ephemeral internal MCP token).

Method	Path	Description
`POST`	`/api/internal/scheduler/datasets/{dataset_id}/refresh`	Refresh one dataset snapshot for a scheduled refresh job.
`POST`	`/api/internal/scheduler/dashboards/{dashboard_id}/refresh`	Refresh one dashboard for a scheduled refresh job.
`POST`	`/api/internal/scheduler/flows/{flow_id}/run`	Run one Flow with `trigger=schedule` for a scheduled Flow job.

`POST /api/internal/scheduler/flows/{flow_id}/run`

Field	In	Type	Default	Required	Description
`run_as_user_id`	body	string or null	`null`	No	User identity for connection secret resolution. When omitted, Genesis uses the Flow creator’s `created_by_user_id` when present.

Response model InternalFlowRunResponse:

Field	Type	Description
`success`	boolean	`true` only when the Flow run completed with status `completed`.
`run`	object or null	Terminal Flow run record when execution reached the runner.
`error`	string or null	Failure summary when `success` is `false`.
`operator_notified`	boolean	`true` only when Genesis demonstrably created an in-app operator notification for this terminal failure. Defaults to `false`. Omitted on successful runs.
`operator_notification_coverage`	string or null	How well the operator is covered for this run’s failure streak: `notified` (this run created a notification), `suppressed` (the operator was already told about this unbroken streak and the runner stayed quiet on purpose), or `not_covered` (nobody was told). The scheduler subprocess stands its generic job-failure alert down on `notified` or `suppressed`. `null` when omitted by an older backend — the scheduler falls back to `operator_notified` only.

Mission Value endpoints

These routes return an instance-wide report over persisted mission, TODO, and BlueprintRun history. A report uses a UTC half-open cohort (from_ts included, to_ts excluded), may cover at most 365 days, and refuses cohorts with more than 10,000 candidate projects. Aggregate metrics cover the complete selected cohort; limit and offset paginate only the mission drilldown. The operation performs multiple persistence reads per request.

Method	Path	Description	Required permission
`GET`	`/api/mission-value`	Return Mission Value metrics, work-type breakdown, quality counts, and paginated mission detail.	`access_pulse_panel` and `view_all_missions`
`PUT`	`/api/mission-value/baselines`	Replace the complete instance-wide manual-baseline value.	`access_config_panel`

`GET /api/mission-value` query fields

Field	Type	Default	Required	Description
`from_ts`	ISO-8601 datetime with UTC offset	none	Yes	Inclusive start of the reporting cohort.
`to_ts`	ISO-8601 datetime with UTC offset	none	Yes	Exclusive end of the reporting cohort. Must be later than `from_ts`; the range cannot exceed 365 days.
`work_type`	string or null	`null`	No	Optional normalized work-type filter. Supported namespaces are `blueprint:` and `project_type:`.
`limit`	integer	`50`	No	Number of mission detail rows to return, from `1` through `100`.
`offset`	integer	`0`	No	Number of observed mission detail rows to skip.

`GET /api/mission-value` response fields

Field	Type	Description
`success`	boolean	`true` when the report is returned.
`cohort`	object	Effective `from_ts`, `to_ts`, `as_of` timestamp, and normalized `work_type` filter.
`metrics`	object	Aggregate Mission Value measures for the selected cohort.
`quality`	object	Counts of `exact`, `estimated`, and `incomplete` observations.
`work_types`	object[]	Selected observed-mission counts, shares, classification source, exact counts, and baseline-covered exact counts by work type.
`missions`	object[]	Paginated observed mission detail.
`candidate_count` / `scanned_count`	integer	Number of distinct candidate projects collected and scanned.
`selected_count`	integer	Number of candidates remaining after the optional work-type filter.
`filtered_out_count`	integer	Candidates excluded by the work-type filter.
`observed_count` / `returned_count`	integer	Observed missions in the selected cohort and rows in this page.
`excluded_count`	integer	Candidates that did not produce an observed completed mission.
`truncated`	boolean	Whether the candidate scan was truncated; currently `false` for a report that completes.
`baselines`	object	Effective `mission_value.manual_baselines` value used for the report.

`metrics` fields

Field	Type	Description
`observed_completed`	integer	Successful missions with exact or coherently estimated timing.
`exact_count` / `exact_rate`	integer / number	Exact observations and their fraction of observed completed missions.
`roi_coverage_rate`	number	Fraction of observed completed missions that are exact and have a matching manual baseline.
`baseline_coverage_among_exact_rate`	number	Fraction of exact missions with a matching manual baseline.
`manual_total_seconds`	number	Sum of matching manual baselines for exact, baseline-covered missions.
`genesis_cycle_total_seconds`	integer	Additive recorded task work after attributable input-gate overlap is removed.
`genesis_lead_total_seconds`	integer	Elapsed time from accepted/start to successful output, including waits.
`human_wait_total_seconds`	integer	Union of BlueprintRun input gates and task awaiting-input intervals clipped to lead time.
`signed_saved_work_seconds`	number	Manual baseline minus Genesis cycle for exact, baseline-covered missions; negative values are retained.
`unclassified_count`	integer	Observed completed missions without a normalized work type.

Mission detail fields

Each missions[] row includes project_id, project_name, work_type, work_type_source, successful, quality, quality_reasons, started_at, output_at, cycle_seconds, lead_seconds, human_wait_seconds, manual_baseline_seconds, and saved_work_seconds. quality is exact, estimated, or incomplete; incomplete observations are counted in quality but are not included in observed_count or aggregate metrics.

`PUT /api/mission-value/baselines` request fields

The request replaces the whole value; it does not merge individual items.

Field	Type	Required	Description
`schema_version`	integer	Yes	Must be exactly `1`.
`items`	object[]	Yes	Baseline items with `work_type`, `display_name`, and positive numeric `manual_seconds`. Work types must use the `blueprint:` or `project_type:` namespace; normalized duplicates are rejected.

The response contains success and the canonical baselines object. If GENESIS__MISSION_VALUE__MANUAL_BASELINES is set, the replacement is refused with 409; malformed payloads return 400. Invalid cohort parameters and an oversized candidate cohort also return 400. Both routes return 403 when the caller lacks the required permission.

Agent review endpoints

These routes implement agent grading measurement: steering-turn classification, estimate-first backfill, scorecard queries, per-message expectation-met feedback, steering-pattern mining, learning-candidate disposition, adoption-ledger reads, and learning-delta reports. Classification and learning are advisory-only — nothing in these APIs consults a score to allow or deny an agent action. Classifier and backfill candidate scans include hidden threads. The usual eligibility filters still apply, so threads without human turns or with an autonomous origin are not sent for classification. Analysis routes are inert when agent_review.enabled is false (default): Genesis returns 404 for those routes as if the feature were absent. Explicit message feedback remains available while analysis is disabled, so deployments can collect user verdicts before enabling analysis. Scorecard reads and backfill estimate/start require access_pulse_panel when authentication is enabled.

Scorecard and backfill routes

Routes are mounted under /api/agent-review/....

Method	Path	Description	Required permission
`POST`	`/api/agent-review/backfill/estimate`	Count candidate threads and estimate classification cost for a window without LLM calls. Creates an `estimated` run row and returns `run_id`, `threads`, and `est_cost_usd`.	`access_pulse_panel`
`POST`	`/api/agent-review/backfill/{run_id}/start`	Atomically claim an estimated backfill run and process it asynchronously off the request. Returns `status: "running"` when the claim succeeds.	`access_pulse_panel`
`GET`	`/api/agent-review/runs`	List agent-review runs (automatic and backfill), newest first, with estimated vs actual cost.	`access_pulse_panel`
`GET`	`/api/agent-review/scorecard/filter-options`	Return bots, workflow types, and date bounds present in classifier rollups.	`access_pulse_panel`
`GET`	`/api/agent-review/scorecard/data`	Return time-bucketed scorecard series and workflow breakdown for one bot.	`access_pulse_panel`
`GET`	`/api/agent-review/weaknesses`	Return the longitudinal weakness ledger, including each row’s stored status and derived coaching display status.	`access_pulse_panel`
`GET`	`/api/agent-review/export/annual`	Generate a year-end grading sheet for one agent or the fleet. Malformed cycle evidence fails the export instead of rendering an empty cycle; overlapping stored cycle windows are called out in the sheet while summary totals count each covered day once.	`access_pulse_panel`

`GET /api/agent-review/export/annual`

Returns a Markdown (format=md, the default) or PDF (format=pdf) file download. Pass bot_id to generate one agent’s sheet; omit it for the fleet sheet. The annual summary totals are calculated from the union of the covered days in the stored cycle reports and daily rollups, so a day is counted once even when cycle windows overlap after a cycle-policy change. The per-cycle table still lists each stored report, so its rows can repeat covered days; when that happens, the sheet includes an overlap warning explaining the difference. Level-history and decision tables resolve human actor ids to the user’s display name, then email, and finally the raw id when lookup is unavailable. The system and scheduler actors are rendered verbatim. A failed user lookup does not fail the export. Malformed year or unsupported format values return the pinned contract error shape described below rather than a file download.

Agent-grading contract errors

Domain violations from cycle drafting, nomination decisions, and annual export use HTTP 400 or 409 responses with this additive shape:

{"detail": {"code": "<code>", "message": "<human-readable explanation>"}}

The machine-readable code remains stable. For example, stale_nomination means a nomination no longer targets the next level after an intervening level change; its message directs the caller to reject it or draft a new cycle. When an agent is demoted or reset, every still-provisional nomination for that agent is terminally marked rejected by system, with a reject event recorded for provenance. This system void does not block a new nomination for the same agent, target level, and cycle: Genesis files the next deterministic attempt id by appending #2, #3, and so on to the base nomination id. The voided rows remain in the append-only history. A nomination rejected by a human remains terminal for that cycle and cannot be re-nominated. Rejecting a stale nomination is also allowed and does not move the agent’s level fold. Weakness-ledger advancement is deduplicated by covered calendar day. A newly drafted cycle advances the ledger only for days not covered by an earlier stored cycle for that agent, so overlapping cycle windows do not recount the same corrections or bank clean days twice.

`POST /api/agent-review/backfill/estimate`

Field	In	Type	Default	Required	Description
`window_start`	body	datetime (ISO-8601)	none	Yes	Backfill window start (inclusive).
`window_end`	body	datetime (ISO-8601)	none	Yes	Backfill window end (exclusive). Must be after `window_start`.

Returns success, run_id, threads (candidate thread count), and est_cost_usd (estimated USD cost from prompt sizing and model pricing, no LLM calls).

`GET /api/agent-review/runs`

Field	In	Type	Default	Required	Description
`limit`	query	integer	`50`	No	Maximum runs to return. Minimum `1`, maximum `200`.

Returns success and runs (array of run objects).

`GET /api/agent-review/scorecard/data`

Field	In	Type	Default	Required	Description
`bot_id`	query	string	none	Yes	Agent to score.
`from_ts`	query	float	none	Yes	Range start as Unix seconds (UTC).
`to_ts`	query	float	none	Yes	Range end as Unix seconds (UTC).
`granularity`	query	string	`day`	No	Time bucket size. Allowed values: `day`, `week`.
`workflow_type`	query	string or null	`null`	No	Optional workflow filter. When omitted, Genesis aggregates all workflow types.

Returns success, bot_id, granularity, series, breakdown, and grading_policies_present. Rate fields in series and breakdown are fractions between 0 and 1 (the web client multiplies by 100 for display). Each series bucket includes bucket_ts (Unix seconds of the period start). First-shot rates come only from grading_policy='full' rollup rows; corrections_only rows never blend into a first-shot figure.

`GET /api/agent-review/weaknesses`

Field	In	Type	Default	Required	Description
`bot_id`	query	string or null	`null`	No	Optional agent filter.
`status`	query	string or null	`null`	No	Optional stored-status filter. Allowed values: `open`, `escalated`, `resolved`. When omitted, Genesis returns all stored statuses.

Returns weaknesses, ordered by stored status (escalated, open, resolved) and then last_seen descending within each status. Each weakness keeps its stored status; display_status is derived from the adoption join. The coaching_adoption_id field is the adoption behind that display status and is the identifier a client can use to focus the Agent Learning adoption ledger on the coaching that applies to the weakness. It is null when no coaching applies.

Weakness item fields

Field	Type	Description
`display_status`	string	Derived coaching status shown alongside the stored `status`; coaching does not change the stored status.
`coaching_adoption_id`	string or null	Adoption-ledger row behind `display_status`, for clients that link the coaching status to its adoption history; `null` when no coaching applies.

Field	Type	Description
`bots`	object[]	Selectable agents. Each entry has `bot_id` and `bot_name` (falls back to the id when the registry has no name).
`workflow_types`	string[]	Workflow types present in rollups.
`date_from`	string or null	Earliest rollup day (`YYYY-MM-DD`) when data exists.
`date_to`	string or null	Latest rollup day (`YYYY-MM-DD`) when data exists.

Scorecard series bucket fields

Field	Type	Description
`bucket`	string	Period start date (`YYYY-MM-DD`).
`bucket_ts`	integer	Unix seconds (UTC midnight) of the period start.
`tasks_total`	integer	Classified tasks in the bucket.
`first_shot_success_count`	integer	First-shot successes (from `full` policy rows only).
`steering_turns_total`	integer	Steering-turn count in the bucket.
`threads_classified`	integer	Threads with classifier rollups in the bucket.
`feedback_met`	integer	Expectation-met feedback count in the bucket.
`feedback_not_met`	integer	Expectation-not-met feedback count in the bucket.
`cost_usd`	float or null	Chat spend in USD for catalog-priced and estimated-price calls with a known cost. `null` when there are no such calls or chat cost data is unavailable.
`known_priced_total_usd`	float or null	Catalog-priced chat spend in USD for the bucket. `null` when there are no catalog-priced calls or chat cost data is unavailable.
`estimated_price`	object or null	Spend at an estimated price, separate from the catalog-priced total. Contains `usd` (float) and `request_count` (integer); `null` when chat cost data is unavailable.
`priced_call_count`	integer	Chat calls with catalog or estimated pricing and a known cost.
`unpriced_call_count`	integer	Chat calls classified as unpriced; these are excluded from `cost_usd`.
`unknown_price_call_count`	integer	Chat calls with unknown pricing classification or missing cost despite catalog or estimated pricing; these are excluded from `cost_usd`.
`latency_p50_ms`	float or null	Median assistant response latency in the bucket.
`latency_p95_ms`	float or null	95th-percentile assistant response latency in the bucket.
`tool_calls`	integer	Tool invocations in the bucket.
`tool_errors`	integer	Tool errors in the bucket.
`first_shot_rate`	float or null	`first_shot_success_count / full_tasks_total` when full-policy tasks exist; otherwise `null`.
`steering_per_task`	float or null	`steering_turns_total / tasks_total` when `tasks_total > 0`; otherwise `null`.
`tool_error_rate`	float or null	`tool_errors / tool_calls` when `tool_calls > 0`; otherwise `null`.

Scorecard breakdown row fields

Each row aggregates the whole requested range for one (workflow_type, grading_policy) pair. Rows are never blended across grading policies.

Field	Type	Description
`workflow_type`	string	Workflow label from classifier rollups.
`grading_policy`	string	Grading policy for the row (`full` or `corrections_only`).
`tasks_total`	integer	Tasks in the range for this workflow and policy.
`first_shot_success_count`	integer	First-shot successes (only incremented on `full` rows).
`steering_turns_total`	integer	Steering turns in the range.
`threads_classified`	integer	Threads classified in the range.
`first_shot_rate`	float or null	First-shot rate for `full` rows; `null` on `corrections_only` rows.
`steering_per_task`	float or null	Average steering turns per task when `tasks_total > 0`.

Agent review run fields

Field	Type	Description
`run_id`	string	Stable run identifier (for example `agent-review-auto-abc123` or `agent-review-backfill-def456`).
`mode`	string	`auto` for scheduled ticks or `backfill` for operator windows.
`window_start`	string or null	Backfill window start (ISO timestamp) when `mode` is `backfill`.
`window_end`	string or null	Backfill window end (ISO timestamp, exclusive) when `mode` is `backfill`.
`status`	string	Run lifecycle status such as `estimated`, `running`, `completed`, or `failed`.
`claimed_by`	string or null	Worker or API claim token when the run is active or was claimed.
`heartbeat_at`	string or null	Last heartbeat timestamp during processing.
`last_thread_checkpoint`	string or null	Last completed `thread_id` checkpoint for resumable backfills.
`threads_scanned`	integer or null	Threads inspected in the run.
`turns_classified`	integer or null	User turns classified in the run.
`est_cost_usd`	float or null	Estimated cost recorded at estimate time.
`actual_cost_usd`	float or null	Known-priced actual LLM cost from cost-cube rows tagged to the run. `0` with `actual_unpriced_call_count: 0` when the run made no classifier call. When `actual_unpriced_call_count` is greater than zero, the cost is partial and excludes calls with no price; it is `null` if no call was priced. Both cost fields are `null` when cost is unknowable: cost/usage tracking is off; the cube could not confirm its writes were committed during the run’s window — which includes a batch lost by any other writer in that window, since the cube records no per-write ownership; no cost row was recorded for the classifier calls; or the lookup failed.
`actual_unpriced_call_count`	integer or null	Calls with no known price, excluded from `actual_cost_usd`; `null` when the run cost is unknown.
`rubric_version`	string or null	Classifier rubric version used for the run.
`created_by`	string or null	Operator user id or `scheduler` for automatic runs.
`created_at`	string or null	Run creation timestamp.
`completed_at`	string or null	Run completion timestamp.

POST /api/agent-review/backfill/{run_id}/start returns 409 when the run is not claimable (already running or not in estimated status).

Learning routes

Routes are mounted under /api/agent-review/.... They require access_pulse_panel when authentication is enabled and return 404 when agent_review.enabled is false.

Method	Path	Description	Required permission
`GET`	`/api/agent-review/learning-candidates`	List mined steering-pattern candidates, ordered with multi-user patterns first (`distinct_user_count` DESC, `occurrences` DESC, `last_seen_ts` DESC).	`access_pulse_panel`
`POST`	`/api/agent-review/learning-candidates/{candidate_id}/accept`	Accept an open candidate as the statement the person read. The request is gated through the candidate’s Action Review item; anchored candidates write a team-visible `final` wiki learning, while unanchored candidates record adoption only.	`manage_agent_learning`
`POST`	`/api/agent-review/learning-candidates/{candidate_id}/dismiss`	Dismiss an open candidate (no wiki write, no adoption row).	`manage_agent_learning`
`GET`	`/api/agent-review/learning-deltas`	Return before/after intervention rates around each adoption (advisory only).	`access_pulse_panel`
`GET`	`/api/agent-review/adoptions`	List adoption-ledger rows, newest first.	`access_pulse_panel`

`GET /api/agent-review/learning-candidates`

Field	In	Type	Default	Required	Description
`bot_id`	query	string or null	`null`	No	Optional bot filter.
`status`	query	string or null	`null`	No	Optional status filter. Allowed values: `candidate`, `adopted`, `dismissed`. When omitted, Genesis returns all statuses.

Returns candidates (array of learning candidate items).

Learning candidate item fields

Field	Type	Description
`candidate_id`	string	Stable candidate identifier.
`bot_id`	string	Agent the pattern applies to.
`workflow_type`	string	Workflow label from classifier rollups.
`anchor_qn`	string or null	Context Graph qualified name when the pattern is anchored to a scanned asset; `null` for unanchored summaries.
`pattern_summary`	string	Human-readable summary of the recurring steering correction.
`occurrences`	integer	Times the pattern was observed in the mining window.
`distinct_user_count`	integer	Distinct users who steered on this pattern.
`first_seen_ts`	string	First observation timestamp (ISO-8601 UTC).
`last_seen_ts`	string	Most recent observation timestamp (ISO-8601 UTC).
`status`	string	`candidate`, `adopted`, or `dismissed`.
`evidence`	object[]	Supporting references. Each entry has `thread_id` and `message_id`.
`adopted_statement_id`	string or null	Wiki learning id when `status` is `adopted`; otherwise `null`.
`being_accepted`	boolean	`true` while an accept is in progress or its outcome is unsettled; the displayed `status` remains `candidate`. Accept and dismiss are refused while the hold is active.
`held_until`	string or null	ISO-8601 UTC time when the candidate’s own accept hold lapses, or `null` when the server cannot determine it. Action Review may keep the candidate locked after this time.

`POST /api/agent-review/learning-candidates/{candidate_id}/accept`

Request body:

Field	Type	Required	Description
`statement`	string	Yes	The candidate text rendered to and read by the person. Genesis refuses the accept if the candidate no longer has this exact text.

Genesis finds or creates the candidate’s Action Review item under the learning.adopt.v1 action family. The authenticated person decides and applies the item in this request; a policy-allowed item may be applied without a separate human review. The response returns candidate_id, status (adopted), statement_id (wiki learning id when the candidate was anchored; null for unanchored accept-as-summary), adoption_id, and action_review with the applied proposal_id and its final status. Returns 404 when the candidate does not exist. Returns 409 when the candidate is already adopted or dismissed, or when its text differs from the submitted statement. A changed candidate uses error code candidate_changed; nothing is published, so read the candidate again before retrying. While another accept holds the candidate, the response uses candidate_being_accepted and includes held_until; both accept and dismiss are refused. A declined or in-flight Action Review item is also reported as a conflict and includes its action_review details. If an accept may already have published the learning, the response uses 503 with code: "accept_outcome_uncertain", the server-selected next_step, proposal_id, and any anchor_qn or unlocks_at it can determine; do not retry until the named Action Review attempt settles. Returns 403 when policy denies the operation. When that attempt settles, Genesis reads an anchored page back by the exact candidate text and adopts it only when the matching learning landed during that attempt; an older matching learning does not get adopted for this accept and remains for a person to check.

`POST /api/agent-review/learning-candidates/{candidate_id}/dismiss`

Returns candidate_id and status (dismissed). Returns 404 when the candidate does not exist. Returns 409 when the candidate is already adopted or dismissed, while an accept hold uses candidate_being_accepted with held_until. If a prior accept may have written and its Action Review item is not settled, the response uses candidate_unsettled_in_action_review and includes the holding proposal_id; do not dismiss until that item is settled.

`GET /api/agent-review/learning-deltas`

Field	In	Type	Default	Required	Description
`bot_id`	query	string or null	`null`	No	Optional bot filter.
`horizon_days`	query	integer or null	`null`	No	Horizon override in days. Minimum `1`, maximum `365`. When omitted, Genesis uses the configured default (`agent_review.learning_deltas.horizon_days`, default `14`).

Returns deltas (array of learning delta items) and horizon_days (the effective horizon Genesis used for the comparison).

Learning delta item fields

Field	Type	Description
`adoption_id`	string	Adoption-ledger row identifier.
`source`	string	Adoption source. Allowed values: `h2_supersession`, `steering_pattern`, `manual`.
`bot_id`	string or null	Agent identifier when present on the adoption row.
`workflow_type`	string or null	Workflow label when present on the adoption row.
`anchor_qn`	string or null	Context Graph qualified name when the adoption is anchored.
`adopted_at`	string	Adoption pivot timestamp (ISO-8601 UTC).
`headline`	string	Operator-facing summary for the delta row.
`insufficient_data`	boolean	`true` when either window has fewer than `agent_review.learning_deltas.min_tasks_per_window` settled tasks.
`before`	object	Metrics for the window before `adopted_at` (see learning delta window fields).
`after`	object	Metrics for the window after `adopted_at` (see learning delta window fields).

Learning delta window fields

Field	Type	Description
`tasks_total`	integer	Settled tasks in the window.
`steering_per_task`	float or null	Average steering turns per task when `tasks_total` is sufficient; otherwise `null`.
`first_shot_rate`	float or null	First-shot success rate when `tasks_total` is sufficient; otherwise `null`.

`GET /api/agent-review/adoptions`

Field	In	Type	Default	Required	Description
`bot_id`	query	string or null	`null`	No	Optional bot filter.

Returns adoptions (array of adoption items), newest first.

Adoption item fields

Field	Type	Description
`adoption_id`	string	Stable adoption identifier.
`source`	string	Adoption source. Allowed values: `h2_supersession`, `steering_pattern`, `manual`.
`statement_id`	string or null	Wiki learning id when the adoption created or references a learning row.
`candidate_id`	string or null	Source learning candidate when the adoption came from steering-pattern disposition.
`bot_id`	string or null	Agent identifier when present on the adoption row.
`workflow_type`	string or null	Workflow label when present on the adoption row.
`anchor_qn`	string or null	Context Graph qualified name when the adoption is anchored.
`adopted_at`	string	Adoption pivot timestamp (ISO-8601 UTC).
`created_by`	string or null	Operator user id who accepted the candidate or recorded the adoption.

Expectation-met message feedback endpoints

These routes are mounted under /api/threads/{thread_id}/.... They persist per-user thumbs-up/thumbs-down style verdicts on assistant messages for scorecard hydration and operator review. Authorization is thread-participant based: Genesis derives bot_id server-side from the thread (never from the request) and applies the same thread-access check used by thread read routes. In authentication-disabled deployments, the resolved system_default_user is allowed consistently with those reads. Foreign threads return 403. These routes remain available when agent_review.enabled is false; the flag controls review analysis, not explicit user feedback.

Method	Path	Description	Auth behavior
`PUT`	`/api/threads/{thread_id}/messages/{message_id}/feedback`	Upsert the caller’s expectation-met verdict on one assistant message. A second `PUT` with the other verdict flips it.	Requires access to the target thread.
`DELETE`	`/api/threads/{thread_id}/messages/{message_id}/feedback`	Delete the caller’s verdict for the message.	Requires access to the target thread.
`GET`	`/api/threads/{thread_id}/feedback`	List the caller’s persisted verdicts for UI rehydration.	Requires access to the target thread.

For PUT, message_id must identify an assistant answer present in the target thread. Unknown ids and ids for user messages, tool requests, tool results, or system messages return 404; tool requests are not feedback targets even when they render as assistant prose. Genesis trims surrounding whitespace from the requested id before storing the verdict under the canonical id. DELETE applies the same trimming, so a caller can retract its existing verdict even if the message has since been removed from the thread.

`PUT /api/threads/{thread_id}/messages/{message_id}/feedback`

Field	In	Type	Default	Required	Description
`verdict`	body	string	none	Yes	Expectation verdict. Allowed values: `met`, `not_met`.
`reason`	body	string or null	`null`	No	Optional one-line reason.

Returns success and data (a message feedback item).

Message feedback item fields

Field	Type	Description
`thread_id`	string	Source thread identifier.
`message_id`	string	Assistant message identifier.
`bot_id`	string	Agent identifier derived from the thread.
`user_id`	string	User who submitted the feedback.
`verdict`	string	`met` or `not_met`.
`reason`	string or null	Optional reason text when provided.
`created_at`	string or null	First submission timestamp.
`updated_at`	string or null	Last update timestamp.

DELETE /api/threads/{thread_id}/messages/{message_id}/feedback returns success and deleted (true when a row was removed). GET /api/threads/{thread_id}/feedback returns success and items (array of message feedback items for the authenticated caller only).

User settings endpoints

These routes are mounted under /api/auth/settings and read or update the caller’s persisted users.settings JSON object. The web client uses them for per-user preferences such as the default landing page shown when opening Genesis or clicking the logo. When authentication is enabled, Genesis resolves settings for the authenticated user. When authentication is disabled, Genesis serves the persisted system_default_user row (resolved lazily on first read) so local and no-auth deployments can still store preferences.

Method	Path	Description	Auth behavior
`GET`	`/api/auth/settings`	Return the caller’s stored settings object.	Uses the authenticated user when auth is enabled; otherwise returns settings for the no-auth system user.
`PUT`	`/api/auth/settings`	Merge top-level settings keys into the caller’s stored settings.	Same identity resolution as `GET`. Returns `success: false` when the caller cannot be persisted (for example, an unpersisted regular user).

User settings request and response fields

`PUT /api/auth/settings`

Field	In	Type	Default	Required	Description
`settings`	body	object	none	Yes	Top-level settings keys to merge. Omitted sibling keys are preserved.

GET /api/auth/settings returns success and data (the settings object). PUT /api/auth/settings returns success and message.

Default landing page setting

The web client stores each user’s preferred landing page under default_landing_page. When the key is missing, unknown, or the settings request fails, the UI falls back to Launchpad (launchpad). Allowed default_landing_page values:

Value	Landing destination
`launchpad`	Launchpad (default)
`eveChat`	Eve chat
`agents`	Agents
`blueprints`	Blueprints
`missions`	Missions
`contextGraph`	Digital Twin / Context Graph
`docs`	Docs
`deploy`	Deploy
`data`	Data
`git`	Git
`apps`	Apps
`scheduler`	Scheduler
`flows`	Flows
`config`	Config
`pulse`	Pulse

Blueprint browser preferences setting

The web client stores each user’s Blueprint Library view mode and sort under blueprint_browser_preferences as an object merged through PUT /api/auth/settings.

Field	Type	Default	Description
`view_mode`	string	`tile`	Library layout: `list` or `tile`.
`sort_key`	string	`updated`	Sort column: `name`, `author`, `source`, `created`, or `updated`.
`sort_dir`	string	`desc`	Sort direction: `asc` or `desc`.

When the stored object is missing, corrupt, or contains unknown values, the web client falls back to tile view and Recently modified sort (updated, desc). Regex search mode is intentionally not persisted.

User settings example

Read the current settings:

curl "https://<genesis-host>/api/auth/settings" \
  -H "Authorization: Bearer <auth-token>"

Set the default landing page to Missions:

curl -X PUT "https://<genesis-host>/api/auth/settings" \
  -H "Authorization: Bearer <auth-token>" \
  -H "Content-Type: application/json" \
  -d '{"settings":{"default_landing_page":"missions"}}'

Personal access token endpoints

These routes are mounted under /api/auth/pats....

Personal access tokens (PATs) authenticate protected HTTP requests with Authorization: Bearer gp_.... Genesis treats the PAT as the token owner’s identity on those HTTP routes. WebSocket endpoints continue to use the auth-provider-specific bearer or query-token flows documented in their sections below.Genesis also accepts additional JWT issuers configured in auth.additional_issuers (a map keyed by a human-readable label; matching is on each entry’s issuer URL). Each entry requires issuer and jwks_url, with optional audience (defaults to auth.audience) and identity_source (sub, the default, or email). When identity_source is email, Genesis resolves the caller from the token’s verified email — used by OAuth-proxy identity tokens in dev import workflows. Unknown issuers are rejected; the token signature is always verified against the selected JWKS.

Method	Path	Description	Auth behavior
`POST`	`/api/auth/pats`	Create a PAT for the current Genesis caller identity.	With authentication enabled, requires the account’s own sign-in; PATs, machine tokens, GenesisApp tokens, sandbox thread tokens, and agent calls cannot mint PATs. With authentication disabled, the local operator can create one.
`GET`	`/api/auth/pats`	List PAT metadata for the current Genesis caller identity.	Returns only the caller’s PAT records.
`DELETE`	`/api/auth/pats/{pat_id}`	Revoke a PAT owned by the current caller.	Returns `403` when the caller does not own the PAT.
`GET`	`/api/auth/pats/admin`	List PAT metadata across all users.	Requires `manage_users`.
`DELETE`	`/api/auth/pats/admin/{pat_id}`	Revoke any user’s PAT.	Requires `manage_users`.

`POST /api/auth/pats`

Field	In	Type	Default	Required	Description
`name`	body	string	none	Yes	Human-readable token name. Minimum length `1`, maximum length `255`.
`scopes`	body	string[]	`["*"]`	No	Scope list stored with the PAT record.
`expires_in_days`	body	integer or null	`null`	No	Optional expiration period in days. Allowed range: `1` to `3650`.

With authentication enabled, the caller must be the person’s own sign-in, not a delegated or machine credential. Genesis returns 403 when the caller is an agent, system identity, app-only token, or another delegated credential. A PAT is always owned by the signed-in person; Prover approvals made with that PAT are attributed to the owner and labelled via personal access token.

PAT response fields

POST /api/auth/pats returns success, message, pat, and token. GET /api/auth/pats and GET /api/auth/pats/admin return success plus pats.

Shared PAT record fields

Field	Type	Description
`id`	string	PAT identifier such as `pat_<uuid>`.
`user_id`	string	Genesis user ID that owns the PAT.
`name`	string	Token name supplied at creation time.
`scopes`	string[]	Stored scope list. Wildcard tokens return `["*"]`.
`created_at`	string or null	ISO timestamp when Genesis created the PAT record.
`expires_at`	string or null	ISO timestamp when the PAT expires, or `null` when it does not expire.
`last_used_at`	string or null	ISO timestamp of the most recent accepted PAT use, when available.
`revoked`	boolean	Whether the PAT has been revoked.

Genesis returns the plaintext token value only from POST /api/auth/pats. Store it securely when created. Later list endpoints return metadata only.

PAT example

Create a PAT from an already authenticated HTTP client:

curl -X POST "https://<genesis-host>/api/auth/pats" \
  -H "Authorization: Bearer <existing-auth-token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"CLI automation","scopes":["*"],"expires_in_days":30}'

Use the returned token value on later protected HTTP requests:

curl "https://<genesis-host>/api/auth/pats" \
  -H "Authorization: Bearer <returned-pat-token>"

Common PAT status codes

Status	Meaning
`200`	Create, list, or revoke request completed successfully.
`401`	The caller was unauthenticated, or the presented PAT bearer token was invalid or expired.
`403`	The caller lacks `manage_users`, or attempted to revoke a PAT they do not own.
`404`	The requested `pat_id` was not found.

Authenticated coding-agent, data, and datasets endpoints

The routes below now explicitly reject unauthenticated callers when auth.enabled is true.

Coding agent session endpoints

These routes are mounted under both /api/cortex-code/... and /api/coding-agent/....

Method	Path	Description	Auth behavior
`GET`	`/api/cortex-code/sessions/by-thread/{thread_id}`	List running and recently completed coding-agent sessions for a thread. Also available at `/api/coding-agent/sessions/by-thread/{thread_id}`.	Requires authentication when auth is enabled.
`POST`	`/api/cortex-code/{session_handle}/take-control`	Transfer a coding-agent session to human control. Also available at `/api/coding-agent/{session_handle}/take-control`.	Requires authentication when auth is enabled and records the authenticated user as the controller.

`GET /api/cortex-code/sessions/by-thread/{thread_id}`

Field	In	Type	Default	Required	Description
`thread_id`	path	string	none	Yes	Thread identifier to resolve sessions for.
`bot_id`	query	string or null	`null`	No	Optional bot identifier used when thread-to-bot resolution is ambiguous. When you know the agent, pass the exact `bot_id` returned by `GET /api/bots`.

`POST /api/cortex-code/{session_handle}/take-control`

Field	In	Type	Default	Required	Description
`session_handle`	path	string	none	Yes	Coding-agent session handle to transfer to human control.
`user_id`	body	string or null	`null`	No	Optional caller identifier when auth is disabled. When auth is enabled, Genesis ignores this field and uses the authenticated user ID.
`user_name`	body	string or null	`null`	No	Optional caller display name when auth is disabled. When auth is enabled, Genesis prefers the authenticated display name and only falls back to this field if no authenticated display name is available.

Thread query-activity endpoint

Method	Path	Description	Auth behavior
`GET`	`/api/data/bots/{bot_id}/threads/{thread_id}/query-activity`	Return compact SQL execution activity for an authorized mission thread.	Requires thread ownership (or system-user access) and respects dataset authorization for linked query results.

`GET /api/data/bots/{bot_id}/threads/{thread_id}/query-activity`

Field	In	Type	Default	Required	Description
`bot_id`	path	string	none	Yes	Agent that owns the thread.
`thread_id`	path	string	none	Yes	Thread whose activity should be listed.
`through_timestamp`	query	number or null	`null`	No	Inclusive replay cutoff as a Unix timestamp in seconds. Omit for live missions.

The response is QueryActivityResponse: success plus data, an array of QueryActivityItem objects:

Field	Type	Description
`activity_id`	string	Stable activity identifier. Legacy rows may use `legacy-query:{query_id}`.
`query_id`	string or null	Stored query-result id when the caller can read the result; otherwise `null`.
`connection_id`	string	Connection the statement ran against.
`access_modes`	string[]	One or both of `read` and `write`.
`operation`	string or null	Normalized statement class such as `SELECT`, `INSERT`, `CREATE`, or `MERGE`.
`title`	string or null	Human label when available.
`has_result`	boolean	Whether a tabular query result is available for this activity.
`phase_metadata`	object or null	Blueprint phase attribution: `blueprint_name`, `phase_id`, optional `phase_name`.
`created_at`	string or null	UTC ISO-8601 execution time.

Genesis merges durable execution-activity rows with authorized legacy query-result and dataset-cache fallbacks. Partial source failures are logged and omitted independently so available rows still return.

Thread query-result endpoint

Method	Path	Description	Auth behavior
`GET`	`/api/data/threads/{thread_id}/query-results`	List stored query-result summaries for a thread.	Requires authentication when auth is enabled.

`GET /api/data/threads/{thread_id}/query-results`

Field	In	Type	Default	Required	Description
`thread_id`	path	string	none	Yes	Thread identifier whose stored query results should be listed.
`limit`	query	integer	`50`	No	Maximum number of results to return. Allowed range: `1` to `100`.
`offset`	query	integer	`0`	No	Number of results to skip. Minimum `0`.

Connection metadata browsing endpoints

These routes back the Data Explorer connection tree and other callers that need live database metadata (databases, schemas, tables, columns, and sample rows). They are mounted under /api/data/connections/....

Migration pipeline inspection and scope

These routes support the Launchpad pipeline branch of the database-migration journey. Pipeline inspection reads only the explicitly selected repository files at one immutable revision; it does not execute the pipeline or change the repository checkout. The returned source descriptor contains file paths, SHA-256 digests, byte sizes, and a source_checksum, but not source contents or credentials.

Method	Path	Description	Auth behavior
`POST`	`/api/data/migration/pipeline/inspect`	Inspect a selected pipeline entrypoint and dependency files and return their immutable source identity.	Requires authenticated access to the repository and `view_git`.
`POST`	`/api/data/connections/{connection_id}/migration-scope`	Finalize the selected objects, target namespace, naming policy, and optional pipeline selection into an immutable migration scope.	Requires access to the source and target connections.

`POST /api/data/migration/pipeline/inspect`

Field	In	Type	Default	Required	Description
`repo_id`	body	string	none	Yes	Repository identifier.
`revision`	body	40-character lowercase SHA-1 string or null	`null`	No	Revision to inspect. When omitted, Genesis resolves the repository revision used for the inspection.
`entrypoint`	body	string	none	Yes	Safe repository-relative file path that starts the pipeline.
`dependency_paths`	body	string[]	`[]`	No	Additional safe repository-relative files required by the entrypoint; at most 31 files may be selected.
`source_runtime`	body	`"python" \| "sql" \| "dbt" \| "unspecified"`	`"unspecified"`	No	Runtime hint used to validate the entrypoint suffix.

The inspection is bounded to 32 files, 256,000 bytes per file, and 1,000,000 bytes in total. The response has schema_version: 1, the resolved 40-character revision, the selected files, and source_checksum.

Migration producer discovery and plan proposal

These routes support the migration intake in Launchpad and chat. Producer discovery reads Context Graph lineage and source metadata; plan proposal also binds the choices to an immutable, checksummed scope record. Neither route runs pipeline code.

Method	Path	Description	Auth behavior
`POST`	`/api/data/connections/{connection_id}/migration-producers`	Find pipelines that write tables in the source database or selected schemas.	Requires access to the source connection.
`POST`	`/api/data/migration/plan-proposal`	Build a plan for source objects, target namespace, rebuild runtime, row keys, Prover checks, and bound scope.	Requires access to the source and, when supplied, target connections.

`POST /api/data/connections/{connection_id}/migration-producers`

Field	In	Type	Default	Required	Description
`connection_id`	path	string	none	Yes	Source connection identifier.
`database`	body	string or null	`null`	No	Source database; omission uses the connection’s database.
`schemas`	body	string[] or null	`null`	No	Optional schema filter; omission covers the database.

The response’s data includes source, lineage_available, pipelines, unproduced_tables, unproduced_count, and notes. When the Context Graph capability is unavailable, lineage_available is false; this is not a connection error.

`POST /api/data/migration/plan-proposal`

Field	In	Type	Default	Required	Description
`source_connection_id`	body	string	none	Yes	Source connection identifier.
`database`	body	string or null	`null`	No	Source database; omission uses the connection’s database.
`schemas`	body	string[] or null	`null`	No	Up to 32 source schemas to include.
`selected_pipeline_ids`	body	string[]	`[]`	No	Up to 64 pipeline ids selected from producer discovery; empty selects a data-only plan.
`code_location`	body	object or null	`null`	No	Optional selected pipeline-code location.
`target_connection_id`	body	string or null	`null`	No	Optional destination connection. Supply either this or `target_platform`.
`target_platform`	body	`"snowflake" \| "databricks" \| "other"` or null	`null`	No	Destination platform for a plan without a target connection. At least one of `target_connection_id` or `target_platform` is required.
`target_runtime`	body	string or null	`null`	No	Rebuild runtime. When a pipeline rebuild is planned, defaults to `dbt` for Snowflake or `declarative_pipeline` for Databricks; Databricks also supports `databricks_job`.
`target_database`	body	string or null	`null`	No	Optional target database or catalog.
`target_schema`	body	string or null	`null`	No	Optional target schema.
`naming`	body	object or null	`null`	No	Optional target naming policy.

The response’s data contains target_runtime, available runtime options, objects, target, row_keys, row_key_basis, prover_checks, pipelines, defaults_applied, notes, and the bound scope. The service reads current lineage, source inventory, primary keys, and candidate key-column nullability before saving that scope; chosen dbt projects can add one test-metadata read each. For the chat approval flow, see Migration intake tools.

Method	Path	Description	Auth behavior
`GET`	`/api/data/connections/{connection_id}/databases`	List databases accessible through the connection.	Requires access to the requested connection.
`GET`	`/api/data/connections/{connection_id}/databases/{database}/schemas`	List schemas in a database.	Requires access to the requested connection.
`GET`	`/api/data/connections/{connection_id}/databases/{database}/schemas/{schema}/tables`	List tables and views in a schema.	Requires access to the requested connection.
`GET`	`/api/data/connections/{connection_id}/databases/{database}/schemas/{schema}/tables/{table}/columns`	List columns for a table or view.	Requires access to the requested connection.
`GET`	`/api/data/connections/{connection_id}/databases/{database}/schemas/{schema}/tables/{table}/sample`	Return paginated sample rows from a table or view.	Requires access to the requested connection.

`GET /api/data/connections/{connection_id}/databases`

Field	In	Type	Default	Required	Description
`connection_id`	path	string	none	Yes	Database connection identifier (`type.name` or legacy bare name).
`use_cache`	query	boolean	`false`	No	When `true`, return a previously cached result immediately when one exists.

`GET /api/data/connections/{connection_id}/databases/{database}/schemas`

Field	In	Type	Default	Required	Description
`connection_id`	path	string	none	Yes	Database connection identifier (`type.name` or legacy bare name).
`database`	path	string	none	Yes	Database (catalog/project) name.
`use_cache`	query	boolean	`false`	No	When `true`, return a previously cached result immediately when one exists.

`GET /api/data/connections/{connection_id}/databases/{database}/schemas/{schema}/tables`

Field	In	Type	Default	Required	Description
`connection_id`	path	string	none	Yes	Database connection identifier (`type.name` or legacy bare name).
`database`	path	string	none	Yes	Database (catalog/project) name.
`schema`	path	string	none	Yes	Schema (dataset) name.
`use_cache`	query	boolean	`false`	No	When `true`, return a previously cached result immediately when one exists.

`GET /api/data/connections/{connection_id}/databases/{database}/schemas/{schema}/tables/{table}/columns`

Field	In	Type	Default	Required	Description
`connection_id`	path	string	none	Yes	Database connection identifier (`type.name` or legacy bare name).
`database`	path	string	none	Yes	Database (catalog/project) name.
`schema`	path	string	none	Yes	Schema (dataset) name.
`table`	path	string	none	Yes	Table or view name.

`GET /api/data/connections/{connection_id}/databases/{database}/schemas/{schema}/tables/{table}/sample`

Field	In	Type	Default	Required	Description
`connection_id`	path	string	none	Yes	Database connection identifier (`type.name` or legacy bare name).
`database`	path	string	none	Yes	Database (catalog/project) name.
`schema`	path	string	none	Yes	Schema (dataset) name.
`table`	path	string	none	Yes	Table or view name.
`limit`	query	integer	`100`	No	Maximum number of rows to return. Allowed range: `1` to `1000`.
`offset`	query	integer	`0`	No	Number of rows to skip. Minimum `0`.

List responses (databases, schemas, tables) include from_cache (boolean) to indicate whether the payload came from the in-process metadata cache. When these routes read a databricks_app_user connection in a Databricks App, a workspace-verified signed-in user’s metadata reads run as that user and bypass the process cache, so one user’s Unity Catalog visibility is never reused for another user. Other connection types and requests without a verified Databricks user are not switched to that user’s token. An empty databases, schemas, or tables array is a successful empty listing, not a connection failure. In particular, a Databricks catalog or database may return no enumerable rows even though the connection answered; callers should preserve the empty explorer state and use a known catalog or database name when they already have one. tables entries are objects with name (string) and type ("table" or "view"). columns entries include name, data_type, nullable, default, and description when the connector reports them. sample returns a data object with columns, rows, total_rows, limit, and offset. If a connector reports reconnect_required because its sign-in is missing or expired, these routes return HTTP 409 with error_code: "sign_in_expired" and a provider naming the platform that needs sign-in. Callers should prompt the user to sign in again rather than treating this as a server failure. SQL Server metadata browsing and query execution are also supported from a Databricks App through the bundled pymssql driver. Its integer DB-API type codes are normalized for column_metadata; pymssql’s BINARY code is reported as a string because the driver also uses it for types it does not identify, including date and time types. See SQL Server connections for TLS and connection-option behavior.

SQL Server CLR types. For SQL Server table samples, geography, geometry, and hierarchyid columns are returned as text so that one unsupported CLR column does not prevent the rest of the sample from loading. The column names remain unchanged. If column metadata cannot be read, the endpoint falls back to the standard SELECT * sample query.

BigQuery mapping. On BigQuery connections, Genesis maps the generic database/schema/table path segments to GoogleSQL objects:

Path segment	BigQuery object
`database`	Google Cloud project id bound to the connection
`schema`	BigQuery dataset
`table`	Base table or view inside the dataset

GET .../databases returns the connection’s bound project id (via SELECT @@project_id). GET .../schemas lists datasets from {project}.INFORMATION_SCHEMA.SCHEMATA. GET .../tables lists base tables and views from {project}.{dataset}.INFORMATION_SCHEMA.TABLES in one pass (table_type distinguishes views). GET .../columns reads {project}.{dataset}.INFORMATION_SCHEMA.COLUMNS.BigQuery metadata queries route through the shared DatabaseConnector executor (the same path used by query_database and the harvester) so service-account JSON is parsed into credentials_info and user-OAuth connections use a pre-authorized BigQuery client. Project and dataset identifiers are backtick-quoted in generated SQL so dashed project ids parse correctly. Table-preview requests may therefore use a hyphenated BigQuery project id (for example, genesis-471800) as the database value.

Ad-hoc query execution endpoints

Use these routes to execute SQL immediately, store page 1 of the result, and receive a new query_id for later pagination or refresh.

connection_id values on /api/data/... routes accept either the fully qualified type.name form (for example databricks.my_conn) or the bare name stored in legacy CUST_DB_CONNECTIONS (for example my_conn). When a type.name value does not match directly but the segment after the first dot matches a legacy row, Genesis resolves the request to that legacy connection_id before executing metadata or query operations.

Legacy compatibility aliases POST /api/query-results and POST /api/query forward to the same behavior as POST /api/data/query-results.

Method	Path	Description	Auth behavior
`POST`	`/api/data/query-results`	Execute an ad-hoc SQL query, store the first page, and return the stored query-result payload.	Requires access to the requested connection. Sandbox-thread and GenesisApp tokens receive `403` for writes; person and personal-token callers retain write access subject to other permissions.

`POST /api/data/query-results`

Field	In	Type	Default	Required	Description
`connection_id`	body	string	none	Yes	Database connection identifier (`type.name` or legacy bare name).
`query`	body	string	none	Yes	SQL query text. Maximum length `100000`.
`max_rows`	body	integer	`100`	No	Maximum number of rows to include in the stored first page. Allowed range: `1` to `10000`.
`thread_id`	body	string or null	`null`	No	Optional thread identifier to associate with the stored query result. Defaults to `adhoc` when omitted.
`bot_id`	body	string or null	`null`	No	Optional bot identifier to associate with the stored query result. Defaults to `system` when omitted.

POST /api/data/query-results returns the standard stored query-result payload in data plus these row-limit fields:

Field	Type	Description
`requested_max_rows`	integer	Echo of the requested `max_rows` value used for the stored first page.
`has_more`	boolean	Indicates the stored first page reached the requested row cap or that additional rows are available beyond the returned page.
`truncated`	boolean	Compatibility alias for `has_more`.

Genesis validates query-result SQL before it caches the first page. Submit a single SQL statement. Requests that contain multiple SQL statements or obviously concatenated or corrupted SQL return 400 Bad Request.

Newly stored query results are also indexed for find_past_queries(...) recall. This applies in both SQLAlchemy metadata deployments and legacy SQLite-backed metadata deployments; older legacy rows can be backfilled lazily the next time find_past_queries(...) runs.In SQLAlchemy metadata mode, stored query-result reads, writes, and refreshes use the metadata repository, including when the metadata backend is PostgreSQL.

Stored query-result endpoints

These routes are mounted under /api/data/query-results/....

When Genesis uses the datasets-backed query-results backend, stored query results backed by a query-result dataset enforce dataset authorization in addition to connection access rules. GET requests require dataset read access and POST .../refresh requires dataset manage access. App tokens may read only when the token grants dataset read; app tokens cannot refresh these datasets and receive 403 Forbidden.

AG Grid datasource routes such as /api/data-explorer/datasource, /api/data/query-results/{query_id}/datasource, and /api/datasets/{dataset_id}/datasource can return both sql and base_sql in the response body. sql is the wrapped SQL Genesis executed for paging, grouping, or pivoting. base_sql is the original SQL before SSRM wrapping when available. For Microsoft SQL Server connections, Genesis also preserves bracketed identifiers such as [database].[schema].[table] while rewriting paging to SQL Server syntax in sql; base_sql continues to reflect the original submitted query text when available. For Snowflake connections, Genesis parses base_sql with the Snowflake dialect before SSRM wrapping, so VARIANT path expressions such as column:path::TYPE in the original query are accepted rather than causing a parse error during server-side paging, grouping, or pivoting.

Method	Path	Description	Auth behavior
`GET`	`/api/data/query-results/{query_id}`	Return one stored query result page by ID.	Requires dataset `read` access for datasets-backed query-result datasets.
`POST`	`/api/data/query-results/{query_id}/refresh`	Re-run the stored query SQL and refresh the cached result in place.	Requires dataset `manage` access for datasets-backed query-result datasets.

`GET /api/data/query-results/{query_id}`

Field	In	Type	Default	Required	Description
`query_id`	path	string	none	Yes	Stored query-result identifier.
`page`	query	integer	`1`	No	Page number (1-indexed). Minimum `1`.
`page_size`	query	integer or null	`null`	No	Number of rows per page. Allowed range: `1` to `1000`.

When the stored query result is backed by the datasets query-results backend, the data object also includes:

Field	Type	Description
`has_more`	boolean	True when more rows are available beyond the requested page.
`truncated`	boolean	Compatibility alias for `has_more`.

For stored results, the response includes the stored first-page rows and its rows_per_page. When needs_re_execution is true, page 1 still contains the rows that were stored; clients can re-run the query to retrieve rows beyond that page. A result that cannot be replayed is returned with replayable: false, its stored total_rows, and no rows on later pages. If a connector detected dropped rows but could not observe their exact total, total_rows records a lower bound rather than presenting the stored page as complete. This endpoint returns 403 Forbidden when the caller lacks dataset read access to a datasets-backed query-result dataset, and 404 when the stored query result is not found or has expired.

`POST /api/data/query-results/{query_id}/refresh`

This endpoint does not document any request body fields.

Status	Meaning
`200`	Returns a refreshed `QueryResultResponse` payload.
`400`	The stored result is not replayable, or (for datasets-backed query-result datasets) its SQL is missing or malformed. Writes are not replayed because refresh would repeat the write; results computed from other saved results have no source SQL to replay. Genesis also rejects clearly corrupted SQL, including pagination text concatenated with another `SELECT` statement or multiple SQL statements submitted as a single query.
`403`	Caller lacks dataset `manage` access, or an app token attempted to refresh a datasets-backed query-result dataset.
`404`	Query result was not found.

Transition-contract endpoints

These routes back Data → Migration verification (/data/verify/). Browse, compile, and execute require view_connections. Ratify is the only authority-changing surface: it requires ratify_transition_contract, auth.enabled=true, a genuinely authenticated human caller (not a system or delegated identity), and a configured transition_contract.ratifier_private_key.

Method	Path	Description	Auth behavior
`GET`	`/api/transition_contract/rules`	List correspondence rules with derived status (`proposed`, `qualified`, `ratified`, `revoked`), qualifications, and bindings.	Requires `view_connections`.
`POST`	`/api/transition_contract/rules/{rule_hash}/ratify`	Approve a qualified rule: sign and append a transition binding.	Requires `ratify_transition_contract` and an authenticated human ratifier.
`GET`	`/api/transition_contract/objectives`	List stored transition objectives (verification requests).	Requires `view_connections`.
`GET`	`/api/transition_contract/contracts/{contract_hash}`	Return one compiled contract’s structured obligations.	Requires `view_connections`.
`GET`	`/api/transition_contract/contracts/{contract_hash}/dossier`	Return the rendered cutover dossier markdown for a contract.	Requires `view_connections`.
`GET`	`/api/transition_contract/runs`	List recent verification runs, newest first.	Requires `view_connections`.
`GET`	`/api/transition_contract/runs/{run_id}`	Return one run with status, summary, and capped evidence.	Requires `view_connections`.
`POST`	`/api/transition_contract/objectives/{objective_hash}/designate-keys`	Assert row-identity columns for source objects; creates a successor objective.	Requires `view_connections` and per-connection access to both estates named by the objective.
`POST`	`/api/transition_contract/compile`	Compile a stored objective into a governed contract.	Requires `view_connections`.
`POST`	`/api/transition_contract/execute`	Submit a compiled contract for verification; poll the run for results.	Requires `view_connections`. Records the authenticated user as `operator`.

`POST /api/transition_contract/rules/{rule_hash}/ratify`

Field	In	Type	Default	Required	Description
`rule_hash`	path	string	none	Yes	Immutable correspondence-rule artifact hash.
`transition_id`	body	string	none	Yes	Transition the binding licenses the rule for. Minimum length `1`.
`qualification_event_id`	body	string	none	Yes	Qualification event the binding attests to. Minimum length `1`.

Successful responses include event_id (registry event of the appended binding) and binding with rule_hash, qualification_event_id, transition_id, ratifier, ratified_at (ISO-8601), public_key_id, and signature (Ed25519 over the binding payload). The ratifier identity comes from the authenticated session, never from the request body.

Status	Meaning
`400`	Validation failure (for example rule not qualified for the transition).
`403`	Caller lacks `ratify_transition_contract`, auth is disabled, or the caller is not a genuinely authenticated human.
`404`	Rule or qualification event not found.
`409`	Duplicate binding for the same rule, transition, and qualification.
`503`	Ratifier signing key is missing or misconfigured.

`POST /api/transition_contract/objectives/{objective_hash}/designate-keys`

Assert which columns identify rows of one or more source objects. This is a human assertion of row identity — not a measurement from either estate — and it creates a successor objective rather than editing the one named in the path. Refresh the objectives list and compile from the returned objective_hash. view_connections is necessary but not sufficient: the service also requires per-connection access to both estates named by the objective (ownership, manage_all_connections, or a shared grant on each connection). Both source and target are checked.

Field	In	Type	Default	Required	Description
`objective_hash`	path	string	none	Yes	Parent transition objective artifact hash.
`key_designations`	body	array	none	Yes	Designations to apply; one entry per source object. Minimum length `1`, maximum `200`.
`key_designations[].source_object`	body	string	none	Yes	Source object the designated key applies to. Minimum length `1`, maximum `255`.
`key_designations[].columns`	body	string[]	none	Yes	Key columns in the order rows should be aligned. Minimum length `1`, maximum `8` columns per designation. Each column name must be non-empty and at most `255` characters.

Successful responses include objective_hash (successor carrying the designations), parent_objective_hash (the objective refined), and key_designations (the full designation set on the successor, including inherited ones). Compiled obligation frames expose row identity as key_column (legacy single-column field, null for composite keys), key_columns (composite-capable list), and key_source (declared from the source estate, or designated from this endpoint). Read identity through key_columns when present, falling back to key_column.

Status	Meaning
`400`	Validation failure (for example unknown source object, invalid column name, or estate characterization names no connection).
`403`	Caller lacks `view_connections`, or lacks per-connection access to either estate.
`404`	Objective not found.
`422`	Request body validation failure (for example empty `key_designations`, duplicate `source_object` in one request, or more than one designation for the same object).

`POST /api/transition_contract/compile`

Field	In	Type	Default	Required	Description
`objective_hash`	body	string	none	Yes	Stored transition objective artifact hash. Minimum length `1`.

Returns contract_hash, registry_snapshot_cut, and a one-line summary.

`POST /api/transition_contract/execute`

Field	In	Type	Default	Required	Description
`contract_hash`	body	string	none	Yes	Compiled contract artifact hash. Minimum length `1`.
`wait_seconds`	body	integer	`0`	No	Seconds to wait inline for a fast run before returning. Allowed range: `0` to `60`.

Returns run_id, status (running, succeeded, failed, or error), and run (full run record when the run finished within wait_seconds).

Measurement endpoints

These routes back Data → Migration verification measurement tabs (Baselines, Relationships, Compare, Qualifications). Every route below — including reads — requires manage_all_connections. Frozen records and qualification reports can carry per-column minimum and maximum values from customer estates; this is a data-disclosure gate, not a write gate. Agent measurement_tools apply the same permission inside the core. If a measurement tool returns refusal.kind: "fault", the service treats it as an internal measurement-service failure and returns HTTP 500. For a qualification-report read, it does not perform the normal missing-record check or convert the fault into a 404. The response is a generic server-error payload; the exception detail remains in the server log.

Method	Path	Description	Auth behavior
`GET`	`/api/transition_contract/measure/baselines`	List frozen estate records in registry order, each with its `provenance`. Optional query `limit` (default `100`, max `500`). Compare `total` with `shown` to detect truncation.	Requires `manage_all_connections`.
`GET`	`/api/transition_contract/measure/baselines/{frozen_contract_hash}`	Return one frozen record: contract, coverage, `reading_guide`, and provenance metadata.	Requires `manage_all_connections`.
`GET`	`/api/transition_contract/measure/runs/{run_id}`	Return one measurement run with coverage and `frozen_contract_hash` when present.	Requires `manage_all_connections`.
`GET`	`/api/transition_contract/measure/correspondences`	List stored declarations (relationships) between frozen records. Optional query `limit` (default `100`, max `500`). Response uses `data`, not `correspondences`; `unreadable` counts rows on this page that could not be read back.	Requires `manage_all_connections`.
`GET`	`/api/transition_contract/measure/correspondences/{correspondence_hash}`	Restate one declaration as `declared` sentences in reading order.	Requires `manage_all_connections`.
`POST`	`/api/transition_contract/measure/correspondences`	Store a declaration licensing comparisons between two frozen records.	Requires `manage_all_connections`. `declared_by` comes from the authenticated session — there is no request field for it.
`POST`	`/api/transition_contract/measure/compare`	Compare two frozen records under a stored declaration. Read `object_pairing` before the counts.	Requires `manage_all_connections`.
`GET`	`/api/transition_contract/measure/qualifications`	List qualification reports. Optional query `limit` (default `100`, max `500`). Response uses `data`.	Requires `manage_all_connections`.
`GET`	`/api/transition_contract/measure/qualifications/{report_hash}`	Return one qualification report (`report` body nested under `report_hash`).	Requires `manage_all_connections`.

`GET /api/transition_contract/measure/baselines`

List responses include records (not separate baselines / scratch_clones lists), run_index_limit, run_index_truncated (global — older measurement runs were not indexed), and provenance_index_complete (false when the clone/source lookup did not read every report). Each records[] row includes frozen_contract_hash, provenance (qualification_scratch_clone, qualification_source, named_by_measurement_run, or not_established), and optional summary fields (database, schemas, dialect, run_id, qualification_report_hash, and so on). Provenance is never a safety grade.

`POST /api/transition_contract/measure/correspondences`

Field	In	Type	Default	Required	Description
`source_contract_hash`	body	string	none	Yes	Frozen record of the source estate. Minimum length `1`.
`target_contract_hash`	body	string	none	Yes	Frozen record of the target estate. Minimum length `1`.
`relation`	body	string	none	Yes	`same_estate`, `loaded_from_at_or_after`, or `declared_equivalent`.
`evidence_kind`	body	string	none	Yes	`migration_run`, `load_log`, `change_feed`, `audit_record`, `ticket`, or `operator_attestation`.
`evidence_reference`	body	string	none	Yes	Something a reader could follow (run id, log location, ticket, and so on). Minimum length `1`.
`grade`	body	string	`unverified`	No	`unverified` licenses no comparison; `decided`, `exhaustive`, or `statistical` when evidence backs the claim.
`regions`	body	string[]	`[]`	No	Schema names this declaration covers. Empty licenses the whole estate and additionally requires `acknowledges_estate_wide`. Maximum `500` entries.
`object_renames`	body	object	`{}`	No	Map of source object name → target object name. Maximum `5000` entries.
`acknowledges_estate_wide`	body	boolean	`false`	No	Must be `true` when `regions` is empty.

Successful responses include correspondence_hash, declared_by (the authenticated session identity recorded on the declaration), and declared (sentences restated for the declarer to check). The request has no declared_by field; a caller cannot attribute the declaration to another person.

`POST /api/transition_contract/measure/compare`

Field	In	Type	Default	Required	Description
`source_contract_hash`	body	string	none	Yes	Source frozen record. Minimum length `1`.
`target_contract_hash`	body	string	none	Yes	Target frozen record. Minimum length `1`.
`correspondence_hash`	body	string	none	Yes	Stored declaration that licenses the comparison. Minimum length `1`.

Successful responses include counts, counts_by_object, counts_by_class, binding_failures, undischarged, and unresolved (integer counts, not lists), indeterminate_regions (strings), object_pairing, exemplars, exemplars_capped_at, coverage, reading_guide, and value_agreement_is_not_discharge.

Salesforce merge endpoints

These routes govern irreversible Salesforce Lead, Contact, and Account merges. They are compatibility aliases for the provider-neutral CRM merge endpoints with connection_type=salesforce and route new proposals through Action Review. Prefer the /api/crm/salesforce/merge/... paths for new integrations. Every route below — including reads — requires approve_agent_action. That permission is deliberately not named for merges: it grants the right to sign off on an action an agent cannot authorize for itself, and a CRM merge is the first of those rather than the only one. Preview responses carry record-level values from the customer’s Salesforce org, and stored approvals retain that preview verbatim. List and approve operations are additionally scoped to connections the caller can access. The approval routes are the authority-changing surfaces beyond the permission gate: they require auth.enabled=true and a genuinely authenticated human caller (not a system or delegated identity). Agents can preview, submit a proposal, and execute a merge through salesforce_connector, but they cannot approve an Action Review proposal on behalf of a human.

Method	Path	Description	Auth behavior
`POST`	`/api/salesforce/merge/preview`	Dry-run a merge: projection and digest, no writes.	Requires `approve_agent_action`.
`POST`	`/api/salesforce/merge/approvals`	Create an Action Review proposal from a server-side fresh preview.	Requires `approve_agent_action` and an authenticated requester identity.
`POST`	`/api/salesforce/merge/approvals/{approval_id}/approve`	Record a human approval.	Requires `approve_agent_action` and an authenticated human approver.
`POST`	`/api/salesforce/merge/approvals/{approval_id}/execute`	Execute one approved, unexpired, unclaimed merge.	Requires `approve_agent_action` and an authenticated human executor.
`GET`	`/api/salesforce/merge/approvals/{approval_id}`	Return one approval’s status, stored preview, and outcome.	Requires `approve_agent_action`.

Merge actions refuse when the target connection’s locator does not set merge_enabled to a truthy value, when merge_survivorship_policy is missing or invalid, or when Genesis cannot verify the Salesforce org id at authentication.

`POST /api/salesforce/merge/preview`

Field	In	Type	Default	Required	Description
`connection_name`	body	string	none	Yes	Salesforce connection name from Config -> Connections.
`object_name`	body	string	none	Yes	Mergeable object: `Lead`, `Contact`, or `Account`.
`survivor_id`	body	string	none	Yes	Record that survives the merge (15–18 characters).
`loser_ids`	body	string[]	none	Yes	Records deleted by the merge. Minimum length `1`, maximum `2`.

Successful responses include projection (canonical merge preview) and digest (sha256 of the projection, re-checked at approval creation and execution).

`POST /api/salesforce/merge/approvals`

Uses the same body fields as preview, plus:

Field	In	Type	Default	Required	Description
`ttl_seconds`	body	integer	`3600`	No	Approval lifetime in seconds. Must be greater than `0`. Capped by `salesforce.max_approval_ttl_seconds`.
`expected_digest`	body	string	none	No	Digest from the preview the caller saw. When provided, the server refuses with `409` if the recomputed digest differs.

Successful responses include approval_id, the effective Action Review status, digest, expires_at, and review_required. When review_required is true, a human decision is required before execution.

`POST /api/salesforce/merge/approvals/{approval_id}/approve`

Field	In	Type	Default	Required	Description
`approval_id`	path	string	none	Yes	Legacy approval id or Action Review proposal id. IDs beginning with `ap_` are routed through Action Review.

No request body. The approver identity comes from the authenticated session only. Successful responses include approval_id, status, and approved_by.

Status	Meaning
`403`	Caller lacks `approve_agent_action`, lacks access to the bound connection, auth is disabled, or the caller is not a genuinely authenticated human.
`404`	Approval not found.
`409`	Approval is not in a state that accepts approval.

`POST /api/salesforce/merge/approvals/{approval_id}/execute`

Field	In	Type	Default	Required	Description
`approval_id`	path	string	none	Yes	Approved legacy approval id or Action Review proposal id. IDs beginning with `ap_` are routed through Action Review.
`connection_name`	body	string	none	Yes	Salesforce connection to execute on for a legacy approval; compatibility input for an Action Review proposal.

Successful responses include approval_id, status (executed), and result with survivor_id, merged_ids, updated_related_ids, and success.

Status	Meaning
`400`	Validation failure, unverified org id, or survivorship policy error.
`403`	Caller lacks `approve_agent_action`, lacks access to the bound connection, auth is disabled, merge is disabled on the connection, or the caller is not a genuinely authenticated human.
`404`	Approval or connection not found.
`409`	Approval expired, already claimed, projection drift, or connection mismatch.
`503`	Salesforce API or auth failure.

`GET /api/salesforce/merge/approvals/{approval_id}`

Returns data with the approval row, including preview (stored canonical projection), execution_result when present, and status fields such as pending, approved, claimed, executed, failed, expired, or rejected.

CRM merge endpoints

Provider-neutral routes for irreversible CRM merges. Set connection_type to salesforce or hubspot. Every route below — including reads — requires approve_agent_action. That permission is deliberately not named for merges: it grants the right to sign off on an action an agent cannot authorize for itself, and a CRM merge is the first of those rather than the only one. Preview responses carry record-level values from the customer’s CRM org, and stored approvals retain that preview verbatim. List and approve operations are additionally scoped to connections the caller can access. The approval routes are the authority-changing surfaces beyond the permission gate: they require auth.enabled=true and a genuinely authenticated human caller (not a system or delegated identity). Agents can preview, submit a proposal, and execute a merge through salesforce_connector or hubspot_connector, but they cannot approve an Action Review proposal on behalf of a human.

Method	Path	Description	Auth behavior
`POST`	`/api/crm/{connection_type}/merge/preview`	Dry-run a merge: projection and digest, no writes.	Requires `approve_agent_action`.
`POST`	`/api/crm/{connection_type}/merge/approvals`	Create an Action Review proposal from a server-side fresh preview.	Requires `approve_agent_action` and an authenticated requester identity.
`GET`	`/api/crm/{connection_type}/merge/approvals`	List one provider’s legacy and Action Review approvals for human review.	Requires `approve_agent_action`.
`GET`	`/api/crm/merge/approvals`	List visible legacy and Action Review approvals across CRM providers for human review.	Requires `approve_agent_action`. Query `status` defaults to `pending` (`pending` or `approved`).
`POST`	`/api/crm/merge/approvals/batch-approve`	Approve the exact submitted CRM approvals sequentially.	Requires `approve_agent_action` and an authenticated human approver.
`POST`	`/api/crm/{connection_type}/merge/approvals/{approval_id}/approve`	Record a human approval.	Requires `approve_agent_action` and an authenticated human approver.
`POST`	`/api/crm/{connection_type}/merge/approvals/{approval_id}/execute`	Execute one approved, unexpired, unclaimed merge.	Requires `approve_agent_action` and an authenticated human executor.
`GET`	`/api/crm/{connection_type}/merge/approvals/{approval_id}`	Return one approval’s status, stored preview, and outcome.	Requires `approve_agent_action`.

Supported connection_type values: salesforce, hubspot. Merge actions refuse when the target connection’s locator does not set merge_enabled to a truthy value, when merge_survivorship_policy is missing or invalid, or when Genesis cannot verify the provider tenant identity at authentication (Salesforce org id or HubSpot portal id).

`POST /api/crm/{connection_type}/merge/preview`

Field	In	Type	Default	Required	Description
`connection_name`	body	string	none	Yes	CRM connection name from Config -> Connections.
`object_name`	body	string	none	Yes	Provider-supported CRM object type. Salesforce: `Lead`, `Contact`, or `Account`. HubSpot: `contacts` or `companies`.
`survivor_id`	body	string	none	Yes	Provider-designated primary input record. HubSpot may mint a different resulting record id; Salesforce preserves this id.
`loser_ids`	body	string[]	none	Yes	Other input records irreversibly combined with the primary record. Minimum length `1`, maximum `2`. HubSpot requires exactly one loser.

Successful responses include projection (canonical merge preview) and digest (sha256 of the projection, re-checked at approval creation and execution).

`POST /api/crm/{connection_type}/merge/approvals`

Uses the same body fields as preview, plus:

Field	In	Type	Default	Required	Description
`ttl_seconds`	body	integer	`3600`	No	Approval lifetime in seconds. Must be greater than `0`. Capped by `salesforce.max_approval_ttl_seconds` or `hubspot.max_approval_ttl_seconds`.
`expected_digest`	body	string	none	No	Digest from the preview the caller saw. When provided, the server refuses with `409` if the recomputed digest differs.

`GET /api/crm/{connection_type}/merge/approvals`

No request body. Returns data as a list of pending approval rows for the specified provider. Before selecting rows, Genesis performs a best-effort, provider-scoped recovery of stale claims left by an interrupted process. The recovery runs on demand when the approval ledger is read, at most once per cooldown window; idle instances do not run a recurring recovery job. Claims older than salesforce.merge_claim_stale_after_seconds or hubspot.merge_claim_stale_after_seconds (both default to 900 seconds) are marked failed with an unknown remote outcome rather than retried.

`GET /api/crm/merge/approvals`

Field	In	Type	Default	Required	Description
`status`	query	string	`pending`	No	`pending` or `approved`.

No request body. Returns data as a list of visible approval rows across all registered CRM providers and server_time (server clock used to evaluate expiry). Rows for connections the caller cannot access are omitted. Genesis attempts the same on-demand stale-claim recovery for every registered provider before selecting rows; a recovery failure for one provider does not prevent another provider’s attempt or the list response.

`POST /api/crm/merge/approvals/batch-approve`

Field	In	Type	Default	Required	Description
`approvals`	body	array	none	Yes	Exact approvals to process sequentially in submission order. Minimum length `1`, maximum `100`.

Each item in approvals:

Field	In	Type	Default	Required	Description
`approval_id`	body	string	none	Yes	Ledger id to approve. Minimum length `1`.
`connection_type`	body	string	none	Yes	CRM provider: `salesforce` or `hubspot`.

Successful responses include outcomes — one entry per submitted approval in submission order. Each outcome is either a success (approval_id, status, approved_by) or a failure (approval_id, error_code, message). error_code is one of bad_request, forbidden, not_found, conflict, service_unavailable, or internal.

`POST /api/crm/{connection_type}/merge/approvals/{approval_id}/approve`

Field	In	Type	Default	Required	Description
`approval_id`	path	string	none	Yes	Legacy approval id or Action Review proposal id. IDs beginning with `ap_` are routed through Action Review.

No request body. The approver identity comes from the authenticated session only. Successful responses include approval_id, status, and approved_by.

Status	Meaning
`403`	Caller lacks `approve_agent_action`, lacks access to the bound connection, auth is disabled, or the caller is not a genuinely authenticated human.
`404`	Approval not found.
`409`	Approval is not in a state that accepts approval.

`POST /api/crm/{connection_type}/merge/approvals/{approval_id}/execute`

Field	In	Type	Default	Required	Description
`approval_id`	path	string	none	Yes	Approved legacy approval id or Action Review proposal id. IDs beginning with `ap_` are routed through Action Review.
`connection_name`	body	string	none	Yes	CRM connection to execute on for a legacy approval; compatibility input for an Action Review proposal.

Successful responses include approval_id, status (executed), and result with survivor_id, resulting_record_id, merged_ids, updated_related_ids, warnings, and success. If the provider refuses the one merge request, the response records status: not_applied and preserves the provider’s error detail. If the request was sent but the outcome cannot be proved, the approval remains reconciliation_required; do not retry it, and inspect execution_result or the approval detail for the provider’s error when present.

Status	Meaning
`400`	Validation failure, unverified tenant id, or survivorship policy error.
`403`	Caller lacks `approve_agent_action`, lacks access to the bound connection, auth is disabled, merge is disabled on the connection, or the caller is not a genuinely authenticated human.
`404`	Approval or connection not found.
`409`	Approval expired, already claimed, projection drift, or connection mismatch.
`503`	CRM API or auth failure.

`GET /api/crm/{connection_type}/merge/approvals/{approval_id}`

Estate (source-contract) endpoints

These routes back the Estate workspace (named estates with scan timelines, source-estate characterization, contracts, jitter qualification, system-diff remediation, governance (Δ authoring, waivers, ranked findings, attestations), migration validation, the Genesis Knowledge System corpus, the estate ruling library (tier-3 ambiguity overlay), the Adjudication Court (ranked docket queue, attorney chat provenance, improvement-review queue, and human or headless decide/adopt), issue dossiers, and Π rule-review workflows). Submit-and-return routes stop accepting new flows once Genesis begins shutdown. If a run row was allocated before that refusal, Genesis closes it before returning the scheduling error; poll GET /api/estate/runs/{run_id} to see the terminal state rather than treating the request as an in-progress run. Estate review and approval reads are scoped to the caller’s estate visibility as well as view_connections. A comparison-scoped read treats an unknown or unreadable comparison as not found. Lists omit findings and approval records tied to comparisons the caller cannot see, and calculate any totals, waiver counts, or rule-usage counts after that visibility filter. This applies to the comparison review, attestation, waiver, export, correspondence-rule, finding-disposition, delta, ruling, and package reads below; approval work on a hidden comparison is not disclosed by a row or count. Browse, define and scan named estates, characterize, mine, compile, verify, jitter, system-diff run/read, on-demand fault-drill, fault-drill reads, and behavioral reads, knowledge corpus read/collect, Δ preview/propose, attestation read, witness drill-down, collaboration notes, comparison Human Review workflow persistence, reconciliation episodes (import/read, server-owned open/round/close lifecycle, live derivational open/round streaming from graded obligations, machine-channel issue replies and prover adjudication, human-court finding rulings, durable-finding cross-episode history, and the cross-run finding lifecycle ledger), programmatic Contract verification (POST /api/estate/verifications), and immune-arsenal ranking require view_connections. Agents may author and propose Δ artifacts through those routes; only ratification changes authority. Comparison Human Review is an annotation layer over a comparison: per-finding diagnosis, disposition, owner, workflow, and discussion remain available to view_connections reviewers. Review doors use one signer rule: with authentication enabled, a genuinely authenticated human signs and a caller-supplied name is refused; with authentication disabled, an allowed caller may submit and is recorded as the name in X-Genesis-Signed-As, disclosed as <name> (self-reported, auth disabled), or as local operator (auth disabled) when the header is absent. Finding and family disposition, remediation-request filing/dispatch, and collaboration notes are annotation acts over the findings ledger (nothing closes a finding — only re-verification does). They require ratify_source_contract (collaboration notes require only view_connections). With auth.enabled=true, a genuinely authenticated human is required; when auth is disabled, writes are permitted and attributed to local operator (auth disabled) so diagnosis and remediation surfaces stay usable on local stacks. Authority-changing surfaces — candidate adjudication, contract sealing, ruling-library settle / ratify / unsettle / answer (the tier-3 ambiguity overlay), Adjudication Court decide and adopt (POST /api/estate/court/dockets/{docket_id}/decide and .../adopt — each emits a ruling into the library) — require ratify_source_contract, auth.enabled=true, and a genuinely authenticated human caller (not a system or delegated identity). Π/Δ ratification, correspondence-rule review and revoke, and Π rule-review confirm/revoke use the signer rule above. Ruling-library and court reads (GET /api/estate/rulings, GET /api/estate/rulings/{ruling_id}, GET /api/estate/ruling-questions, GET /api/estate/court/dockets, GET /api/estate/court/dockets/{docket_id}, GET /api/estate/court/dockets/{docket_id}/audit, and GET /api/estate/improvement-docket) require only view_connections — agents and customers may browse the library and docket queues as living documentation. The Court panel shows the estate-scoped ambiguity queue separately from the all-estates improvement queue. Court attorney-chat recording (POST /api/estate/court/dockets/{docket_id}/chat) also requires only view_connections; attribution comes from the authenticated caller (auth-off callers are labeled local operator (auth disabled)). Spec-conformance compile, reading consult (POST /api/estate/spec-conformance/consult-reading), agentic spec-author seat (POST /api/estate/spec-conformance/author-seat), and grade (POST /api/estate/spec-conformance/compile, POST /api/estate/spec-conformance/grade, POST /api/estate/spec-conformance/grade-compiled, POST /api/estate/migration-envelope/grade), estate preflight (POST /api/estate/estates/{estate_id}/preflight), estate archive (POST /api/estate/estates/{estate_id}/archive), and stimulus runs (POST /api/estate/stimulus/run) also require ratify_source_contract — authoring or sealing the spec an envelope is graded against, commissioning an agent mission for readiness or behavioral verification, or injecting into clone estates is the same authority class — but are system-triggerable assessments with no genuine-human gate (a permitted service or agent caller may invoke them). The Estate nav is shown by default; it is hidden only when show_estate is explicitly false on GET /api/config/frontend (set AppConfig features.show_estate to false, or GENESIS__FEATURES__SHOW_ESTATE=false to force-lock).

Prover result visibility

view_connections is also the per-result visibility boundary for Prover data. A principal may see an estate only when they may see every connection in that estate; a comparison is visible only when they may see every connection behind both of its estates. This applies to agent tool calls as well as REST requests: an agent acts with the authenticated user’s connection reach and does not widen it. Direct connection scans without an estate are authorized from the connection recorded on the scan’s run. A result whose producing connection cannot be resolved is hidden rather than treated as public. List responses report filtering instead of silently presenting a partial board. The hidden field is a count of withheld rows: it is a total for estate, snapshot, ranked-finding, and unpaged result lists; it is per page for system-diff, findings, ledger, and comparison-event pages. For system-diff, findings, and comparison-event pages, has_more and next_cursor describe paging on the unfiltered keyset, so continue paging and sum per-page hidden values when a total is needed. The findings-ledger page instead applies visibility before cutting the page; its has_more and next_cursor walk only admitted rows, and hidden counts withheld rows in that page’s span. The findings-ledger summary applies the same visibility predicate inside its aggregation, so its open_total, by_state, by_layer, by_pair, and pair_unresolved values already describe only visible findings. Detail reads return 404 when the requested snapshot, estate, or comparison is hidden; a comparison requires both endpoint estates to be visible. The same visibility rule gates Prover approvals, run-level verdicts, and exception grants: comparison-scoped actions require the caller to be able to open that comparison. Consult ruling actions require the caller to be able to read the finding. A hidden subject returns the corresponding read’s 404, rather than disclosing whether an approval target exists. Write and submit routes apply the same check before writing or starting work. Estate archive and visibility changes, code-asset operations, drills, and artifact reproduction require the named estates to be visible; candidate adjudication requires visibility to the snapshot the candidate came from. Grades check their named snapshots, comparison, and estate; stimulus runs check their named snapshots and comparison. Boundary characterization and contract delta operations check the referenced boundary or contract. Run cancellation checks the run’s comparison, estate, and connection before it writes. Hidden or unresolved subjects answer as unknown (404), before the action proceeds. Spec-conformance prose compilation is the exception: a snapshot the caller cannot see is omitted from grounding, and the compiler proceeds without that snapshot’s inventory. This boundary also applies to routes and agent tools that resolve or act on comparison records: hidden comparisons and findings are treated like unknown ones. Family rollups for a comparison fold only findings the caller can see, so hidden members do not affect the returned counts or samples. For records that cannot be placed under a visible comparison or boundary, a principal with manage_all_connections may see the otherwise unplaced record; other principals continue to receive the hidden or unknown result. The same subject check now covers grading-run adjudication, stored adjudication reads, finding consultation, reconciliation episodes, and estate ruling and court tools. A run is visible through its comparison when it names one. Otherwise a recorded estate must be visible and a recorded connection must also be visible; with no estate, a recorded connection is checked on its own. A proceeding is visible through its comparison, or through every recorded conformance connection; an unplaced proceeding requires manage_all_connections. An episode without a comparison requires a visible estate and, when the estate’s recorded snapshots identify it, a visible connection; with no estate, its recorded connection is checked alone. Estate ruling and court records are available when a visible comparison touches the estate, or to a principal who can manage every connection. The same caller-specific rules also apply to court docket and audit reads, improvement-docket entries, transition detail, family and behavioral dossiers, proofless-grade review, reading-consult and seat status polls, and live run subscriptions. Lists and embedded rows are filtered to visible subjects; the endpoint descriptions below call out where filtering changes paging or returned counts. Hidden identifiers use the same unknown-style response as missing records, except where an endpoint documents an empty or otherwise safe result. Run feeds and polls use a caller-specific scope for every subject a run names: all recorded estates, its recorded connection, and every comparison in its summary must be visible. Run connection stamps and operator fallback are described in run ownership and connection stamps. A run naming none of those subjects is judged by its boundary: every snapshot stored under that boundary must be visible, or, when it has no snapshots, its registered connection must be visible; if neither snapshots nor a registered connection identify it, only a principal with manage_all_connections may see it. A run bound to nothing is visible to its recorded operator or user principal, or to a principal with manage_all_connections. GET /api/estate/runs and the active-run feed omit inaccessible runs before pagination and counts; polling one returns 404, indistinguishable from an unknown run. Comparison- and estate-scoped side reads also apply caller visibility before resolving or aggregating results: hidden subjects use each endpoint’s existing no-result response (404, null, an empty list, available: false, or unresolved_comparison on stimulus preflight), and family-member counts include only visible findings.

Prover listing response timings

The completed listing reads below return a Server-Timing response header. Timing is enabled automatically; there is no configuration key or request parameter. The header contains one member for each stage that ran, formatted as name;dur=<milliseconds> and optionally ;desc="<unit>=<count>", followed by total;dur=<milliseconds> for the read service’s recorded window. The window covers the service’s reads, resolutions, and projections, but not response encoding, middleware, network transfer, or client-side timing. An error response does not include a stage table. The stage vocabulary is route-specific:

Endpoint	Stages
`GET /api/estate/runs`	`feeds`, `spec_holds` (`hashes`), `project`
`GET /api/estate/system-diffs`	`feeds` (`comparisons`), `grades` (`graded`), `curate`, `readiness` (`featured`), `movements` (`approvals`), `rollups`, `untallied`, `page`
`GET /api/estate/findings`	`page`, and `consult` when `include_consult=true`
`GET /api/estate/findings/ledger/summary`	`summary` (`pairs`)
`GET /api/estate/findings/families`	`worklist` (`families`)
`GET /api/estate/knowledge/coverage`	`coverage`

The count description is omitted when a stage does not report a count; an omitted count does not mean zero.

Clarification review and reopened verdicts

In clarification responses, conversation_with identifies the signed-in person by email or display name rather than a bare user id; it is unnamed when no name can be resolved, unauthenticated when authentication is disabled, and absent when no person was present. Clarifications are append-only agent records that a sealed specification may cite. Review is a separate, after-reliance action: a person may ratify a recorded clarification before or after a seal cites it, but nothing waits for that review. Ratification changes its current status to ratified, sets provenance_kind to person, and names the reviewer. A person can overturn a clarification, changing its current status to overturned; the agent that recorded an agent-certified clarification can also withdraw it on the owner’s word, changing its status to withdrawn. Neither action deletes or mutates the record. Overturned and withdrawn clarifications are refused by later spec authoring, so new seals cannot rely on them. Agents withdraw through the withdraw_clarification tool; the review routes below remain person-only. When an agent records or withdraws a clarification through POST /api/tool_call, include agent_id to run under that agent persona. The stored recorder identity then names the agent that acted, rather than attributing the record only to the authenticated caller; see the tool_call request fields. For the record_clarification tool result fields and repeated-ruling behavior, see its tool reference. The review identity is resolved by the server, never accepted from the request body. With authentication enabled, the review routes require ratify_source_contract and a genuinely authenticated human; agent-delegated tokens and service accounts receive 403. With authentication disabled, the review actor is recorded as local operator (auth disabled). Agent-made clarification records separately expose conversation_with: the signed-in person whose conversation the turn was recorded in, or unauthenticated when authentication was disabled. The optional request body is { "note": "..." }; the note is stored on the review event. Unknown ids return 404, and a second review of an already reviewed clarification returns 409.

Method	Path	Description	Auth behavior
`GET`	`/api/estate/{estate_id}/clarifications`	List every clarification for the estate, oldest first, with `clarification_id`, `subject`, `statement`, `recorded_by_kind`, `recorded_by`, `conversation_with` (the person whose conversation an agent record was made in, or `unauthenticated` when auth was disabled), `status` (`recorded`, `ratified`, `overturned`, or `withdrawn`), `provenance_kind`, `reviewed_by`, `reviewed_at`, `label`, `cited_by` (spec hashes whose seal cites it), and `reopened` on overturned or withdrawn entries. `reopened` is the dependent snapshot captured immediately before retirement; current seal/run reopening is derived when those resources are read.	Requires `view_connections`; `404` when the estate is unknown or not visible.
`POST`	`/api/estate/clarifications/{clarification_id}/ratify`	Ratify one agent-certified clarification. The response returns its reviewed state without `cited_by`.	Requires `ratify_source_contract` and the human review rule above; `403`, `404`, or `409` as described.
`POST`	`/api/estate/clarifications/{clarification_id}/overturn`	Overturn one clarification as a person. The response returns its reviewed state and the dependents found just before the event was recorded; it does not delete the clarification or persist a reopen flag onto seals or runs.	Requires `ratify_source_contract` and the human review rule above; `403`, `404`, or `409` as described.

Every seal and run reads the current clarification state when requested. An overturn or withdrawal retires the clarification: a compiled-spec view exposes a reopened seal through who_decided.reopened, with the earliest cause at the top level and all causes in causes. A run that is a verdict over that seal exposes the same notice in reopened and projects outcome to not_verified, regardless of the stored outcome. This applies to GET /api/estate/runs, GET /api/estate/runs/{run_id}, and the run wake/read surfaces; the spec_author_seat run that produced the seal is excluded. Run listings and complete run reads include the common progress block, next_step sentence, and next call descriptor. next is {verb, args, why}; its verb is null when no call by the current caller moves the work along. See Prover run progress for their shared semantics and polling guidance. Every terminal run also carries outcome beside status in the envelope and listing row. outcome is one of PASS, FAIL, INDETERMINATE, not_verified, no_findings, or sealed; it is null while the run is non-terminal. status answers whether the process finished, while outcome answers what it decided. See The status is never the verdict for the meaning of each value and the fail-closed cases. For a grade, a not_verified verdict with a non-empty blocking list is published as FAIL, because the grade measured the migration and found a definite blocking result; an empty blocking list remains not_verified. The run envelope always includes report_this, a string or null. For terminal proof (prove) and grade (spec_conformance) runs, it is the sentence to report from the stored run summary: successful results state the verdict and obligation tally, name up to ten failing obligation ids (counting any remainder), and include available unmet scope, historized objects whose history was not tested, comparison counts, and full run, grade, comparison, and spec ids. A successful proof with no spec says that no obligation was checked. When a proof’s comparison ran under an assumption withdrawn for its estate pair, the sentence names each withdrawal (who withdrew it, when and why) and how many readings it moved, read from summary.comparison_counts.withdrawn_assumptions. A terminal proof or grade that did not succeed says it verified nothing and includes its stop_reason when available. The field is null while a run is live and for run types that grade nothing. See reporting a completed run for how agents use this sentence, including the row counts attached to named failed checks. See Prover run semantics. For repair-run settings as presented on run reads, see Prover run provenance. Each complete run’s envelope also includes grade_engine_version and reused_from_grade_version. grade_engine_version is the grading-code version recorded by the grade it carries, read from the grade summary (including summary.summary when a proof carries the grade there), or from row provenance when the grade has not written its summary yet. reused_from_grade_version names the version of a grade carried over rather than run for this answer: the grade submission reused, the proof reused, or a new proof reused its grade child. Both keys are always present; grade_engine_version is null when the run carries no grade or no version was recorded, and reused_from_grade_version is null when no grade was reused or its version was not recorded. For a reused verdict, grade_engine_version identifies the grader behind that verdict, not the serving build. Run envelopes also expose the same published and withheld headline fields on their summary object. Migration-validation run summaries include output_relations, mapping each output to the source and target relations recorded by its traces. A side is omitted when its trace records no relation for that output. Prover comparisons use this evidence to scope a rewritten-view license to the pair tested by the run; see fresh licensing evidence. For GET /api/estate/runs, shape=full and shape=card summaries add published and withheld headline fields for each comparison count present: unlicensed_published / withheld_unlicensed and indeterminate_published / withheld_indeterminate. The withheld fields are null when nothing was withheld. Summaries with no corresponding comparison count gain no fields, and shape=slim omits them. The server derives these fields for both older and newer stored summaries.

Method	Path	Description	Auth behavior
`GET`	`/api/estate/runs`	List estatechar runs, newest first. Optional queries are `run_type`, `estate_id`, `limit` (`1`–`1000`, default `50`), `cursor` (an opaque `next_cursor` from the previous response), and `shape` (`full`, `slim`, or `card`, default `full`). The response is a bounded, resumable page: `has_more` reports whether older runs exist and `next_cursor` is `null` on the last page. `estate_id` keeps only runs submitted under that estate or compared against it as the proof target, filtered before the page is cut; with it, `runs_without_estate` counts the runs (of `run_type`, when given) that carry neither a submitting nor target estate and so appear on no estate’s page, at the cost of one COUNT. Without `estate_id` it is `null`. List entries include run identity, status, liveness timestamps, pair/target identifiers, and summary scalars; heavy per-run evidence is omitted. `shape=slim` reduces `summary` to `spec_hash`, `spec_hash_basis`, `diff_hash`, `provenance.diff_hash`, and `artifacts.diff_hash`. `shape=card` keeps the listing scalars and small identity blocks but drops the per-run report documents (`items`, `adjudication`, `blind`, `canvas`, `drift`, `obligation_verdicts`, stimulus `steps`, `completion`, `batches`, `rounds`, and `platform_attribution`; `verdict` is also dropped except for its one-word `migration_validation` value). The platform accounting remains available in `classification.platform_licensed` and `classification.platform_rule_ids`. Strings in the card summary are capped at 2,000 characters; a capped value identifies its original length and points to `GET /api/estate/runs/{run_id}`. The card projection is persisted in `estate_char_runs.summary_card_json` when the run summary is written, so a current card row does not decode the full evidence document. Its `summary_shape` is `"slim"` when the real scalar columns answer a slim row, `"slim_json_fallback"` while an older slim row is being backfilled and on dialects without a JSON scalar accessor, `"card"` when the persisted card projection answers the row, `"card_from_document"` while startup backfill has not reached the row or its stored projection is from an older card rule, and `"full"` for the full projection. The backfill advances in batches at startup; rows still served from the document have the fallback marker and converge on a later startup. Fetch the complete run on demand with `GET /api/estate/runs/{run_id}`. Rows whose `diff_hash` belongs to a stimulus differential artifact carry `stimulus_evidence: true` so consumers can skip phantom comparison chapters. Every row also carries `spec_hash_resolvable` and `spec_hash_resolvable_basis`; when no `spec_hash` is named, the reachability value is `null`. The compiled-spec lookup is batched at 500 distinct hashes: it costs `ceil(distinct / 500)` indexed reads when rows cite hashes, and no read when none do. Shutdown and scheduling-refusal behavior for these runs is described in How a Run Works.	Requires `view_connections`.
`GET`	`/api/estate/runs/{run_id}`	Return one complete run row with its progress summary and evidence. The response includes `envelope`, the one poll shape for every estatechar run: `run_id`, `run_type`, lifecycle timestamps, `heartbeat_at`, `provenance`, `summary`, and `links.poll`. `links.detail` is the per-type poll path for `spec_author_reading_consult` (`/api/estate/spec-conformance/consult-reading/{run_id}`), and `spec_author_seat` (`/api/estate/spec-conformance/author-seat/{run_id}`); it is `null` for other run types. The envelope normalizes `status` to `queued`, `running`, `succeeded`, `failed`, `refused`, `cancelled`, or `superseded`; when a legacy or unknown stored spelling differs, the raw value remains available as `summary.raw_status`. The `provenance` block is stamped when the run is created and can include the served commit, package version, launch mode, operator, principal, connection, thread, mode, escalation mode, and constitution pin. For a run created before provenance stamping shipped, `provenance` contains `unavailable_reason: "run predates provenance stamping (#11545); it is not back-filled, because a back-filled block could not be told apart from one measured at create time"`; it is never back-filled. The legacy `data` projection is marked with `legacy: true` and `read_instead: "envelope"`; read `envelope` for new integrations. Use the `shape` query (`both`, `envelope`, `legacy`, or `report`; default `both`) to choose which representations are built: `both` returns both, `envelope` returns `data: null`, `legacy` returns `envelope: null`, and `report` returns the legacy report document without its raw payload blobs. The unrequested half is always `null`. Use `shape=envelope` when the legacy row is not needed; it skips copying, validating, and serializing the raw `data` projection, including heavy inlined summaries. Use `shape=report` when a single-run surface needs report documents such as `items`, `canvas`, or `drift` without per-object measurement blobs. `shape=legacy` also skips the compiled-spec lookup, so `spec_hash_resolvable` is not measured and its basis begins `this response did not read the compiled-spec store`. For `system_diff` runs, `summary.quiescence_reliance` is an object or `null`; when present it includes `basis`, `declared_by`, `quiet_since`, `note`, `relied_on_elements`, `unlicensed_elements`, and `refused_elements`. The bidirectional comparison also exposes the corresponding object at `summary.backward.quiescence_reliance`. When a compatible pair-scoped binding rule declares exactly one digest quantum, `summary.quantized_remeasure` records `minted`, `significant_digits`, `rule_id`, `source_columns`, and `target_columns`; it records `minted: false` with a reason when no quantum is declared or measurement versions are incompatible. When the whole-table digest cannot decide an object because a licensed or one-sided column guarantees a difference, `summary.comparable_digest_refold` discloses the best-effort live re-fold, including the number of objects asked for and successfully read on each side. A comparison submitted with `row_identity` also records its live per-key uniqueness probe in `summary.row_identity_evidence`; this evidence is execution-specific and is not stored on the content-addressed diff. The envelope always includes `spec_hash_resolvable` and `spec_hash_resolvable_basis`; these fields say whether the compiled spec named by the run can still be fetched from this instance, or why no measurement was made. Optional query `include_proceedings` (default `false`) adds the adjudication proceedings opened on this run: `proceedings` (addressing columns only — no materials and no verdicts), `proceedings_basis` (`measured` or `not_requested`), `proceedings_truncated`, and `proceedings_grading_run_id`. Off by default because this is the route the landing polls and a caller that draws no adjudication affordance should not pay a listing on every tick. Completing a proceeding writes the adjudication tables and not the run row, so `summary.adjudication.buckets` is a grade-time measurement and this is the pointer to what has ruled since. Without the query the four fields are `null` / `not_requested`, never `[]`: an empty list would claim a listing that was never made.	Requires `view_connections`; a `spec_author_seat` run additionally requires `ratify_source_contract`.
`GET`	`/api/estate/spec-conformance/run-for-diff/{diff_hash}`	Return the full `spec_conformance` / `spec_drill` run row whose envelope this comparison should open, or `data: null` when ungraded. Deterministic uncapped lookup by `diff_hash`: the newest specification’s authored grade outranks the platform envelope, and the newest authored grade wins whether verified or not. If that grade is not verified but an earlier grade of the same specification verified, the row includes `earlier_verified_grade`. Read-only, never mints a run.	Requires `view_connections`.
`GET`	`/api/estate/stimulus/run-for-diff/{diff_hash}`	Return the full `stimulus` run row that stimulated this comparison, or `data: null` when never stimulated. Deterministic uncapped lookup by `diff_hash` — read-only, never mints a run. Includes `summary.steps` ledger, `rounds`, and terminal verdict for the comparison-surface Stimulus chapter.	Requires `view_connections`.
`GET`	`/api/estate/runs/{run_id}/flow`	Return the flow view for one `spec_conformance` grade: each ordered output, its spec lineage and source inputs, and the grade’s verdict. Optional query `shape` is `full` (default) or `summary`; every response identifies its shape in `flow_shape`. The full response includes `items`, `checks`, `source.tables`, and `target.tables`, with snapshot `dialect` and `database` captions (or `null` when identity is unavailable). `shape=summary` returns the run and spec identifiers, snapshot IDs, `flow_version`, `layout`, `identity_overlap`, `unaccounted_columns`, `counts`, and `flow_shape`, omitting those four detail blocks. Both shapes read and verify the compiled spec, read both snapshot column inventories (including a JSON decode per object row), parse each compared column’s SQL to tally item states, and trace each projection of every check’s source SQL to identify the source columns it reads; summary skips the snapshot-identity read and transfer of item and table lists. Open this on demand, not on a poll. The full response’s items carry `locus`, `lineage` (`declared`, `derived`, `not_declared`, or `model`), `inputs`, comparison `references`, `obligation_ids`, `state`, and `basis`; table and column records include their state/tone. Item states include `pass`, `fail`, `missing`, `undecided`, `unverified`, `unread`, and `model`; `unverified` means the grade attributed no spec check to the structural item, while `undecided` means its attributed checks reached no verdict. A check merely reading or keying on the item’s column does not confirm it. A check-only read of a scoped input is shown as a comparison reference rather than an unread input; a failing check marks a projected source column `wrong` only when its compared projection differs. For target items, a failed check’s differing columns are matched to its `target_sql` projection aliases, not the underlying target column names; when multiple projections reach one item, the worst effect wins. An unqualified table name resolves to a target table only when its object name is unique in the target inventory; if multiple target tables share that name, a failure through the name is held on each candidate rather than assigned to one. A failed check is placed only when its affected projection is fully traceable; otherwise affected items remain `undecided`. Each side’s SQL is parsed using the engine recorded for that side in the grade; if the grade names no engine, the flow uses Databricks, while a named engine without a registered dialect is parsed as ANSI. A source table outside an item’s declared inputs is also a comparison reference, not lineage. Target columns in ordered tables with no matching item are `unordered`, except columns the grade identifies in `unaccounted_columns`, which are `unaccounted` and pending a person’s decision, and columns the spec’s sealed `target_model` declares (the same declaration the grade reads them as accounted for by), which get an item of their own (`model_only: true`) in state `model` (green, “derived by the target model”) with lineage `model` and, as `inputs`, the source columns the model carries into them (none for a column the load derives, such as a load-metadata column); such an item is held undecided by a failed check the flow cannot place, like any other item of its table, and by any check that failed on its table, on the table or on any of its columns; a spec item on such a column that declares no inputs and that no check reaches takes the model’s lineage and inputs and keeps its own state (one that declares its own inputs keeps them); a column a check decides keeps the check’s lineage; a column the grade lists in `unaccounted_columns` gets no model item; a qualified model object names only that table, a bare one every table of that name; target content outside the spec’s outputs is `not_involved`. `counts.target_unverified` counts ordered target columns in the `unverified` state, `counts.target_unaccounted` counts the pending unaccounted columns separately, and `counts.target_model_derived` counts the `model` columns. A source column read only through the target model’s lineage is never `used`: it reads `model` (carried by the target model, gray), or `wrong` when a failed check names it (for these columns only, a failed `SELECT *` check names columns through its differing columns; no other source reading changes); its strand into the target-model item is drawn neutral; `counts.source_model_carried` counts the `model` source columns. Source columns distinguish `used`, `wrong`, `expected_unread`, and `unused`, as well as `reference` and `out_of_scope`. `layout` is `flow` when identity overlap is unknown or below `0.5`, otherwise `venn`; overlap is `matched` facts divided by all classified facts (`matched`, `spec_licensed`, `platform_licensed`, `drift`, and `indeterminate`), or `null` when unavailable. A grade that carried no specification (graded against its platform move alone, stated by `specification_attached: false` or a `no_specification` verdict) returns `200` with `flow_shape: "no_spec"`, a one-line `reason`, and the run, spec and snapshot identifiers alone, whichever `shape` was requested; it reads no compiled spec and no column inventory, because no spec item orders any column and there is nothing to trace. Requires `view_connections` and visibility to both snapshots. `404` for an unknown run or an invisible snapshot; `400` when the run is not a spec grade, when a grade that names a real spec cannot find that spec on this server, or when a compared snapshot is not held on this server.	Requires `view_connections`.
`GET`	`/api/estate/active-runs`	Live feed: in-flight runs plus the most-recently-finished ones.	Requires `view_connections`.
`GET`	`/api/estate/overview`	Cross-estate rollup: plane coverage plus per-contract deviation, attestation, and jitter counts in one call.	Requires `view_connections`.
`GET`	`/api/estate/transitions`	Transition portfolio: one row per migration effort, newest first, with derived generation count and the current generation label. Optional query `status` filters by `active` or `closed`; no default row limit is applied.	Requires `view_connections`.
`GET`	`/api/estate/transitions/{transition_ref}`	Return one transition by opaque id or readable slug, including its comparison-track edges, complete generation lineage, current-generation pins, and derived station/edge/spec counts.	Requires `view_connections`. `404` when neither the id nor slug matches.
`POST`	`/api/estate/runs/{run_id}/cancel`	Cancel a non-terminal run. The request requires a nonblank `reason` of at most 4,000 characters; blank or over-long reasons return `400`. Unknown runs and runs bound to an estate, comparison, or connection the caller cannot see return `404`; already-terminal runs return `409`. Visibility is checked before cancellation writes. Success returns the ordinary run envelope. For a spec-author seat, the driver also requests a hard-stop of the seat’s turn; a warehouse SQL statement that turn is polling is cancelled on a best-effort basis. See Databricks SQL cancellation.	Requires `ratify_source_contract`.
`POST`	`/api/estate/transitions`	Create a transition. The request supplies `name`, URL-safe lowercase-hyphenated `slug`, and optional `owner`; the authenticated caller is recorded as `created_by`.	Requires `ratify_source_contract`. `400` for validation errors; `409` when the slug already exists.
`POST`	`/api/estate/transitions/{transition_ref}/generations/{generation_number}/close`	Close one generation, pinning the supplied citations and recording the authenticated caller as `closed_by`. A closed generation is append-only and cannot be closed again.	Requires `ratify_source_contract`. `400` for invalid citations; `404` for an unknown transition or generation; `409` when the generation is already closed or a pin conflicts.
`POST`	`/api/estate/transitions/seed/etfjpx`	Seed the recorded ETFJPX transition lineage for deployments that do not have it. The operation is idempotent and returns `created: false` without changing data when the transition already exists.	Requires `ratify_source_contract`. `400` when the recorded lineage cannot be written.
`GET`	`/api/estate/discover-schemas`	List selectable (non-system) schemas of a database for the scan form’s schema multi-select. Best-effort: discovery failures return `schemas: []` and `error` (not HTTP 500) so the form falls back to free-text entry.	Requires `view_connections`.
`GET`	`/api/estate/estates`	List named estates with a scan rollup (`scan_count` + `latest_scan`) for the landing. Each row carries `archived` (landing SOURCES visibility hide; see `PATCH .../archived`). Lifecycle-archived estates are excluded unless `include_archived=true`, which returns them with `active: false` so callers can distinguish an archived estate’s leftover snapshots from an unregistered boundary. The response also includes `hidden`, the number of estates withheld by connection visibility.	Requires `view_connections`.
`POST`	`/api/estate/estates`	Define (Add / craft) a named estate: validate every member connection is reachable and the name is unique, then save. Accepts a crafted multi-member estate (`members` across one or more connections, plus optional `code_assets`) or the flat single-member shim. Nothing is scanned yet — scanning is a separate event. Duplicate name → `409`; overlap on any database is allowed.	Requires `view_connections`. Records the authenticated user as `operator`.
`GET`	`/api/estate/target-candidates`	Comparison target picker: estate definitions eligible as targets (scanned or not), each with scan state and a compared-before badge for the given source estate. Utility/clone estates carry `kind="utility"`. Optional query `source_estate_id`.	Requires `view_connections`.
`GET`	`/api/estate/bot-git-repos`	List local Genesis git repos available to attach as estate code (ETL) assets (ISS6 picker) — each `{repo_id, path, branch, remote_url}`. Only git-mode repos the operator may view are returned.	Requires `view_connections`.
`GET`	`/api/estate/estates/{estate_id}`	One named estate with its full scan timeline (newest first).	Requires `view_connections`.
`PATCH`	`/api/estate/estates/{estate_id}`	Edit a named estate (rename / `kind` / schema scope / `status`, or a full `members[]` + `code_assets[]` replacement that re-validates every member). Rename clash or an edit that moves the estate onto the exact scope of another live operator-registered estate → `409`; an edit that leaves its scope unchanged is allowed. `status='archived'` is not accepted — use `POST .../archive`.	Requires `view_connections`. Records the authenticated user as `operator` on member replacement.
`POST`	`/api/estate/estates/{estate_id}/archive`	Archive (soft-delete) a named estate: sets `active=0, status='archived'` so the row survives for scan history but drops off landing cards, target candidates, and comparison participants. Idempotent — re-archiving returns `already_archived=true`. Distinct from the landing visibility hide (`PATCH .../archived`).	Requires `ratify_source_contract`. Records the authenticated user as `operator`.
`PATCH`	`/api/estate/estates/{estate_id}/archived`	Set/unset the landing SOURCES grid visibility hide: `archived=true` hides the source card (reversible); never changes `active`/`status` or retires target-candidate or comparison surfaces. Durable replacement for the former per-browser localStorage filter.	Requires `view_connections`. Records the authenticated user as `operator`.
`POST`	`/api/estate/estates/{estate_id}/validate`	Re-run the define-time reachability pre-flight for every member connection and store the fresh validation report on the estate (`validated` when all reachable, `partial` when any is not).	Requires `view_connections`. Records the authenticated user as `operator`.
`POST`	`/api/estate/estates/{estate_id}/preflight`	Run estate-setup PREFLIGHT readiness (agent ACCESS, ETL understanding, CLONABILITY) as a submit-and-poll run; returns `run_id` and `status: "running"` immediately. Follow `GET /api/estate/runs/{run_id}` or `GET /api/estate/estates/{estate_id}/preflight/latest`.	Requires `ratify_source_contract`. Records the authenticated user as `operator`.
`GET`	`/api/estate/estates/{estate_id}/preflight/latest`	Return the estate’s latest preflight readiness view (`ready`, per-check lights, run id/status), or `data: null` when never run. Read-only — never mints a run.	Requires `view_connections`.
`POST`	`/api/estate/estates/{estate_id}/code-assets/clone`	Clone the estate’s attached git code (ETL) assets, and capture the `revision` of its Databricks notebooks and jobs (`captured` count), and persist the clone ref (NN4). Best-effort per asset; query `force=true` re-clones already-cloned assets.	Requires `view_connections`. Records the authenticated user as `operator`.
`POST`	`/api/estate/estates/{estate_id}/code-assets/lineage`	Derive dbt transform lineage from the estate’s cloned code assets and reconcile it against the latest scanned snapshot (NN4). Best-effort per asset; query `force=true` re-derives assets that already have lineage.	Requires `view_connections`.
`POST`	`/api/estate/estates/{estate_id}/artifact-reproduction`	Run one declared SQL artifact in a utility estate, characterize its output, and compare it with a live relation. Returns `reproduces`, `does_not_reproduce`, or `unmeasured`; this operation executes customer code and writes to the utility estate.	Requires `view_connections`.
`POST`	`/api/estate/estates/{estate_id}/scan`	Trigger a scan (or re-scan) of a named estate (submit-and-return): returns `run_id`, `scan_id`, `estate_id`, and `status: "running"` immediately. Every scan is a new run + timeline event that plays live over `/api/ws/estate/live`. The static fault-drill coverage meter does not chain on every scan unless `estate_char.fault_drill.run_on_scan_default` is `true` (schema default `false`); use `POST .../fault-drill` to run it deliberately.	Requires `view_connections`. Records the authenticated user as `operator`.
`POST`	`/api/estate/estates/{estate_id}/fault-drill`	Run the static fault-drill coverage meter on the estate’s latest contract on demand (submit-and-return): scores catch rate against a synthetic copy of the stored characterization — works for any dialect (unlike `/harden`, whose live cloner is postgres-only). Returns `run_id` and `status: "running"` immediately; follow live over `/api/ws/estate/live` on the `drill` phase. `409` if a drill is already running. Drills are capped by `estate_char.fault_drill.max_drills` (schema default `250`).	Requires `view_connections`. Records the authenticated user as `operator`.
`POST`	`/api/estate/estates/{estate_id}/harden`	Harden the estate’s latest contract on demand (submit-and-return): runs only the source-hardening chain against the most recent snapshot + contract — never a re-scan. Returns `run_id` and `status: "running"`; follow live over `/api/ws/estate/live`. `409` if a hardening round is already running.	Requires `view_connections`. Records the authenticated user as `operator`.
`POST`	`/api/estate/estates/{estate_id}/spec-drill`	Run a sealed-spec conformance drill on demand (submit-and-return): seals a fresh spec, migrates a throwaway clone, and grades the Prover’s blind diff against the sealed spec end to end. Returns `run_id` and `status: "running"` immediately; the graded run-view is persisted for the theater report. `400` when the estate source is not `postgres` (live cloner is postgres-only today); `409` if a drill is already running.	Requires `view_connections`. Records the authenticated user as `operator`.
`GET`	`/api/estate/estates/{estate_id}/scans`	One estate’s scan timeline (dated events, newest first). Each row includes `binding`: `bound` when a scan event names the estate, or `inferred_from_boundary` when the registered connection, database, and optional schema scope matches a stored snapshot without a binding event; inferred rows disclose `binding_basis` and return `null` for scan-only fields.	Requires `view_connections`.
`POST`	`/api/estate/characterize`	Submit a source-estate scan (submit-and-return): returns `run_id` and `status: "running"` immediately while the scan and chained contract compile run in the background. The static fault-drill coverage meter chains only when `estate_char.fault_drill.run_on_scan_default` is `true` (schema default `false`). Follow live progress over `/api/ws/estate/live` or poll `GET /api/estate/runs/{run_id}`.	Requires `view_connections`. Records the authenticated user as `operator`.
`GET`	`/api/estate/snapshots`	List stored characterization snapshots. Optional query `boundary_hash`. Without `boundary_hash`, every snapshot is returned (no server-side cap); boundary-scoped calls use the default page size. The response also includes `hidden`, the number of snapshots withheld by connection visibility.	Requires `view_connections`.
`POST`	`/api/estate/snapshots/{snapshot_id}/recharacterize`	Re-characterize under the exact boundary a stored snapshot was taken with (submit-and-return): returns `run_id` and `status: "running"` immediately; follow live over `/api/ws/estate/live`. The caller must be able to see the snapshot’s estate or direct connection.	Requires `view_connections`. Records the authenticated user as both `viewer` and `operator`; an unknown or unauthorized snapshot is deliberately indistinguishable.
`GET`	`/api/estate/snapshots/{snapshot_id}`	Return one snapshot with its per-object rows. Optional query `shape` is `full` (default) or `inventory`; every response names the selected shape in `data.snapshot_shape`. `full` includes the complete characterization document as `data.payload` plus per-object rows. `inventory` returns snapshot identity, object rows, and `data.columns` (object name to column names), without `payload`; use it for views that draw the snapshot’s objects and columns but do not need measured values. The full document may be large (40 MB for one measured Databricks snapshot); `full` decodes and re-encodes it.	Requires `view_connections`.
`GET`	`/api/estate/snapshots/{snapshot_id}/objects/{object_name}`	Per-object characterization view (measurements, digest tree, QN).	Requires `view_connections`.
`POST`	`/api/estate/mine`	Mine candidate rules from a stored snapshot into the review queue. The authenticated caller is recorded as the run operator; see run ownership and connection stamps.	Requires `view_connections`.
`GET`	`/api/estate/snapshots/{snapshot_id}/candidates`	Rule review queue with suggested dispositions. Optional query `status`.	Requires `view_connections`.
`POST`	`/api/estate/candidates/{candidate_id}/adjudicate`	Apply one human D/P/V decision (`accept_fact`, `endorse_policy`, or `reject`).	Requires `ratify_source_contract` and an authenticated human adjudicator.
`POST`	`/api/estate/compile`	Compile adjudicated candidates into a draft frozen source contract.	Requires `view_connections`.
`GET`	`/api/estate/contracts`	List stored source contracts (draft and sealed) compiled from snapshots the caller may see, newest first (no server-side cap). Optional query `status`; hidden contracts are omitted.	Requires `view_connections`.
`GET`	`/api/estate/contracts/{contract_id}`	Return one source contract with obligations and seal status. Unknown contracts and contracts compiled from a hidden snapshot both return `404`.	Requires `view_connections`.
`POST`	`/api/estate/contracts/{contract_id}/seal`	Seal a draft source contract (the Def 4.9 freeze gate).	Requires `ratify_source_contract` and an authenticated human sealer. `404` when the contract is unknown or compiled from a hidden snapshot.
`GET`	`/api/estate/contracts/{contract_id}/ledger`	Return the contract’s hash-chained evidence ledger in seq order; empty for a contract compiled from a snapshot the caller may not see.	Requires `view_connections`.
`POST`	`/api/estate/contracts/{contract_id}/verify`	Re-verify a contract against a fresh characterization of its estate.	Requires `view_connections`. `404` when the contract is unknown or compiled from a hidden snapshot. Records the authenticated user as `operator`.
`POST`	`/api/estate/jitter`	Run a mutation-qualification campaign against a stored contract.	Requires `view_connections`. `404` when the contract is unknown or compiled from a hidden snapshot.
`GET`	`/api/estate/contracts/{contract_id}/jitter`	List jitter campaigns for a contract compiled from a visible snapshot, newest first; empty for a hidden contract.	Requires `view_connections`.
`GET`	`/api/estate/jitter/{campaign_id}`	Return one jitter qualification report (kill rate, survivors). Unknown campaigns and campaigns on a hidden contract both return `404`.	Requires `view_connections`.
`GET`	`/api/estate/contracts/{contract_id}/deviations`	Continuous-assurance deviation triage rows for a sealed contract; empty for a hidden contract. Optional query `status`.	Requires `view_connections`.
`POST`	`/api/estate/planes/access/characterize`	Characterize the security plane: roles and table grants as access ceilings.	Requires `view_connections`. Records the authenticated user as `operator`.
`POST`	`/api/estate/planes/logic/characterize`	Characterize the logic plane from a dbt manifest (compiled-SQL identities).	Requires `view_connections`. Records the authenticated user as `operator`.
`POST`	`/api/estate/planes/consumption/characterize`	Characterize the consumption plane: view identities and pinned replays.	Requires `view_connections`. Records the authenticated user as `operator`.
`GET`	`/api/estate/planes/{plane}/latest`	Latest stored snapshot of one non-data plane for a boundary. Query `boundary_hash` required.	Requires `view_connections`.
`GET`	`/api/estate/execution-profiles`	Registered execution profiles (estates known to migration validation).	Requires `view_connections`.
`POST`	`/api/estate/consumer-queries`	Register one reviewed consumer read path for consumption coverage.	Requires `view_connections`. Records the authenticated user as `operator`.
`GET`	`/api/estate/consumer-queries`	Registered consumer queries for a boundary. Query `boundary_hash` required.	Requires `view_connections`.
`POST`	`/api/estate/jitter/clone`	Run the empirical clone-mutation campaign (real faults on a real clone).	Requires `view_connections`. `404` when the contract is unknown or compiled from a hidden snapshot. Records the authenticated user as `operator`.
`GET`	`/api/estate/contracts/{contract_id}/edge-report`	Latest edge-qualification report (just-inside/just-outside fixtures); `404` when there is none or the contract is hidden.	Requires `view_connections`.
`POST`	`/api/estate/contracts/{contract_id}/attestation`	Export the portable attestation (bundle, coverage, and ledger head). Refuses while the transition has structural residue, unlicensed open behavioral findings, or unverified behavioral coverage unless `allow_open_residue=true` (mints a QUALIFIED attestation embedding every disclosure).	Requires `view_connections`. `404` when the contract is unknown or compiled from a hidden snapshot. Records the authenticated user as `operator`.
`POST`	`/api/estate/comparisons/{diff_hash}/proof-report`	Download the comparison’s signed proof report as PDF (default) or Markdown (`format=md`). First download may mint a signed statement; unchanged downloads reuse it. Returns its id in `X-Attestation-Id`; `409` with `payload.reasons` when the report is not ready or another export is in progress.	Requires `view_connections`.
`GET`	`/api/estate/attestation/public-key`	Return the install’s Ed25519 verification key as base64 raw bytes and PEM, its key id, and whether this caller can set up signing (`can_set_up`). Callers with `manage_secrets` also receive signing-key source diagnostics.	Requires `view_connections`.
`POST`	`/api/estate/attestation/signing-key/test`	Test signing by signing a throwaway statement and verifying it; stores nothing and returns no key material.	Requires `manage_secrets`.
`POST`	`/api/estate/attestation/signing-key`	Generate and store an install-wide report-signing key; returns its id and public key only. Does not replace or rotate a key; `409` when one is configured or another setup wins concurrently.	Requires `manage_secrets`.
`GET`	`/api/estate/attestations/{attestation_id}`	Return one stored attestation document.	Requires `view_connections`.
`GET`	`/api/estate/contracts/{contract_id}/attestations`	Attestation rows for one contract, newest first (lifecycle included).	Requires `view_connections`.
`GET`	`/api/estate/attestations/{attestation_id}/report`	Attestation viewer: grade × plane coverage, waivers, ledger linkage.	Requires `view_connections`.
`POST`	`/api/estate/attestations/{attestation_id}/verify`	Verifier-side check of a signed attestation (signature + re-derivation).	Requires `view_connections`.
`POST`	`/api/estate/proofs`	Submit one Prover run for a source/target pair, optionally attaching a sealed spec so the run creates and owns both the comparison and grade. Returns the proof envelope and child run ids as they are created. Optional `wait_seconds` can return a terminal result or a `202` handle when the bounded wait expires.	Requires `view_connections`; attaching `spec_hash` also requires `ratify_source_contract`.
`POST`	`/api/estate/system-diffs`	Submit a live mediated system diff (submit-and-return): returns `run_id`, `status: "running"`, and `pair_fingerprint` immediately while the diff runs in the background. Follow live progress over `/api/ws/estate/live?run_id=` or `?pair=` (using the returned `pair_fingerprint`), or poll `GET /api/estate/runs/{run_id}`.	Requires `view_connections`. Records the authenticated user as `operator`.
`GET`	`/api/estate/system-diffs`	Mediated-diff summaries (verdict counts only), newest first (no server-side cap); each row includes resolved source/target estate identity, `provenance` (`"real"` or `"synthetic"` — see field table below), pair identity (`pair_key`, `is_latest_for_pair`, `is_latest_for_pair_basis`, `pair_run_count`), and optional highlight display metadata for curated migration targets. Comparisons whose source or target estate is archived are excluded unless `include_archived=true` (nothing is deleted from the store). Stimulus differential evidence diffs carry `provenance: "synthetic"` and `stimulus_evidence: true` and are never `is_latest_for_pair` — the featured card stays on the comparison they measured.	Requires `view_connections`.
`GET`	`/api/estate/stimulus/preflight`	Side-effect-free feasibility check for a stimulus run against a comparison: resolves the pair (`diff_hash` or a snapshot pair) and reports whether a run is `possible`, whether it `requires_override` (live non-clone estate — inject-in-place confirmation), whether the pair has a provable ETL (`etl_provable` — required for the default `genesis-agent` executor), and named `reasons` — without allocating a run or commissioning an agent. The compare / escalation dialogs call this on open.	Requires `view_connections`.
`POST`	`/api/estate/stimulus/run`	Run the both-sides STIMULUS behavioral beat against a comparison (submit-and-return): AI-designed synthetic edge batch injected into source + target clones, ETL re-run on both sides, then deterministic differential comparison. Optional `rounds` (server-clamped to `[1, 5]`) and `start_tier` (`nominal`, `boundary`, or `adversarial`) control the escalation ladder. Returns `run_id`, `status`, and `executor` immediately; follow `/api/ws/estate/live?run_id=`. `409` if a stimulus run is already in progress (single-flight).	Requires `ratify_source_contract`. Records the authenticated user as `operator`.
`GET`	`/api/estate/system-diffs/{diff_hash}`	One classified mediated diff; optional query `shape=scope` omits the element document when the caller needs only comparison identity and counts, while `verdict` filters `payload.elements` in the default `full` shape.	Requires `view_connections`.
`GET`	`/api/estate/system-diffs/{diff_hash}/assumptions`	List the assumptions available to the comparison’s estate pair, including each assumption’s current `withdrawn` state and withdrawal record. This includes rule-borne assumptions and, when this comparison relied on them, the target platform’s identifier-case and engine-collation licenses.	Requires `view_connections`; `404` when the comparison is unknown or not visible.
`POST`	`/api/estate/system-diffs/{diff_hash}/assumptions/{assumption_id}/withdraw`	Withdraw one assumption for the comparison’s estate pair. Later comparisons stop applying that assumption: rule-borne readings return as findings, identifier names are no longer paired by the platform fold, and text minimums and maximums abstain when collation ordering is withdrawn. Stored comparisons retain their verdicts, while dependent sign-offs read reopened.	Requires `view_connections`; `400` when the assumption is not available for this comparison, `404` when the comparison is unknown or not visible, and `409` when it is already withdrawn.
`POST`	`/api/estate/system-diffs/{diff_hash}/assumptions/{assumption_id}/restore`	Restore one withdrawn assumption for the comparison’s estate pair. A person may restore any withdrawal; an agent can restore only an agent withdrawal through the agent tool.	Requires `ratify_source_contract`; `400`, `404`, and `409` have the same meanings as the withdrawal route.
`GET`	`/api/estate/system-diffs/{diff_hash}/families/{family_signature}/members`	Every ledger member of one finding family behind a diff, with evidence (paginated). The family rollup carries only a small sample; page with `offset`/`limit` to reach the full member set (`limit` is clamped to the configured page size). Optional query `status` (default `open`).	Requires `view_connections`.
`POST`	`/api/estate/migration-envelope/grade`	Grade a platform-only migration envelope against a real comparison (submit-and-return): seals an empty platform-clause-only spec and grades the pair’s persisted comparison. Returns `run_id`, `status`, and `sealed_spec` immediately; follow live over `/api/ws/estate/live?run_id=` or poll `GET /api/estate/runs/{run_id}`. When `diff_hash` names a comparison that already has an envelope run, returns the existing run (`status: "finished"`, `reused: true`) instead of minting a duplicate, so a repeated submission is safe. Viewing a comparison never calls this route; a grade starts only from an explicit request.	Requires `ratify_source_contract`.
`POST`	`/api/estate/spec-conformance/compile`	Compile pasted prose (migration doc, PRD, ticket, or a few sentences) into structured, editable spec items plus inline ambiguity/assumption/unmapped notes. Nothing is sealed or graded — items feed the seal+grade flow after human review.	Requires `ratify_source_contract`.
`POST`	`/api/estate/spec-conformance/author-seat`	Submit a ticket to the agentic spec-author seat on a hidden chat thread (submit-and-return): returns `run_id`, `thread_id`, `status: "authoring"`, and the effective `mode`, `interpretation_policy`, and `authoring_tooling` while the seat works in the background. The seat uses the supplied `connection_id`, authors through its `register_*` tools, and seals through `finalize_spec`; poll the run or `GET .../author-seat/{run_id}` for `authoring`, `sealed`, `sealed_partial`, `refused`, or `failed`, with `spec_hash` on either seal status. Optional `wait_seconds` returns `200` if the run terminalizes during the bounded wait, or `202` with the same handle and `wait.expired: true` when the seat continues authoring.	Requires `ratify_source_contract`. Records the authenticated user as `operator`.
`GET`	`/api/estate/spec-conformance/author-seat/{run_id}`	Poll one agentic spec-author seat run: `authoring`, `sealed` or `sealed_partial` with `spec_hash` and `compiled_spec_url`, `refused`, `failed`, or `error`, plus authored counts, findings, and open questions.	Requires `ratify_source_contract`.
`POST`	`/api/estate/spec-conformance/grade-compiled`	Grade a registered sealed compiled artifact against two live connections and the source/target snapshots, persist one `spec_conformance` run, and return durable `#N` finding ids plus obligation and structural verdicts. The same request key and `round_n` reuse a finished run; a concurrent in-flight request returns `409`.	Requires `ratify_source_contract`. Records the authenticated user as `operator`.
`POST`	`/api/estate/spec-conformance/compiled`	Register an externally sealed compiled artifact so it can be read by `spec_hash`. The server recomputes the content hash and seal; the claimed hash must match exactly. Registration is idempotent, and content `findings` are advisory.	Requires `ratify_source_contract`. Records the authenticated user as `registered_by`.
`GET`	`/api/estate/spec-conformance/compiled/{spec_hash}`	Read a sealed compiled derivational artifact by content hash — seal-verified (`artifact`, `seal`, `provenance`, repair `lineage`). Refused when the stored artifact is unsealed or its seal does not verify (tamper).	Requires `ratify_source_contract`.
`POST`	`/api/estate/spec-conformance/compiled/{spec_hash}/qualify`	Deterministically qualify bare relation names in a sealed compiled spec against a named connection, without invoking an author or creating a run; returns a new child `spec_hash` and the changed-field receipt.	Requires `ratify_source_contract`. Records the authenticated user as `operator`.
`POST`	`/api/estate/spec-conformance/consult-reading`	Submit a matches-neither reading consult (submit-and-return): the blind author adjudicates whether `candidate_reading` is an honest reading of sealed prose for `ambiguity_group`. Supply exactly one prose source — `compiled_spec_hash` (loads authoritative instruction from provenance) or raw `prose` (offline replay). Returns `run_id` and `status: "running"` immediately. Poll `GET .../consult-reading/{run_id}` for `verdict` (`licensed` or `rejected`) and `rationale`.	Requires `ratify_source_contract`. Records the authenticated user as `operator`.
`GET`	`/api/estate/spec-conformance/consult-reading/{run_id}`	Poll one reading-consult run: `status`, `verdict`, `rationale`, `ambiguity_group`, and terminal `error` when failed.	Requires `ratify_source_contract`.
`POST`	`/api/estate/verifications`	Run a `system_diff` Contract against its pre-registered `source` / `target` connections, or verify a sealed compiled derivational artifact by `compiled_spec_hash` (one comparison per obligation with caller-supplied connection bindings injected). Returns the whole verification result — verdict, counts, localized `mismatched_keys`, and `aggregate_failures` value-pair evidence the chat `verify_against_contract` finished path drops. The comparison runs under the authenticated caller’s identity (connection RBAC applies), never a body-supplied bot. Unregistered endpoint connections are refused before any query is issued.	Requires `view_connections`.
`GET`	`/api/estate/fault-drill-coverage`	Latest fault-drill coverage report for a snapshot’s sealed contract (drills, per-class coverage, blind spots). `available: false` when no report has been produced yet — run `POST /api/estate/estates/{estate_id}/fault-drill` (or a scan with `estate_char.fault_drill.run_on_scan_default=true`, or `POST .../harden`) to generate one. Query `snapshot_id` required.	Requires `view_connections`.
`GET`	`/api/estate/behavioral`	Legacy trajectory-campaign detail for a component pair: the per-step agree/diverge outcomes of whichever campaign ran most recently on this engine pair. `available: false` when the pair has no trajectory-campaign run. A component pair is not a comparison, so nothing rendered on one comparison may source from here — see the diff-scoped `/api/estate/behavioral/steps-for-diff/{diff_hash}` and `/api/estate/behavioral/chip-for-diff/{diff_hash}`. Query `component_pair` required.	Requires `view_connections`.
`GET`	`/api/estate/behavioral/steps-for-diff/{diff_hash}`	Diff-scoped per-step behavioral outcomes for a comparison: the trajectory campaign run against this diff and its per-step agree/diverge verdicts, which back the comparison’s behavioral markers. `available: false` when no campaign was run against this comparison (UI renders no markers). Read-only.	Requires `view_connections`.
`GET`	`/api/estate/behavioral/chip-for-diff/{diff_hash}`	Diff-scoped, verdict-backed behavioral chip for a comparison. Resolves the stimulus run that stimulated this diff; `verified` is true only for a finished verdict (`spec_graded` / `baseline_subtracted`) with `unlicensed_count == 0`. `available: false` when never stimulated (UI renders no chip). Read-only.	Requires `view_connections`.
`GET`	`/api/estate/comparison-events`	Comparison events (A vs B at time t), newest first. Each event carries identity, verdict counts, finding counts, and the systemic-family rollup — not per-finding rows (drill down with `GET /api/estate/comparison-events/{diff_hash}/findings`). Optional query `component_pair`; `limit` defaults to `25` and is clamped to `1`–`20,000`. The response reports whether more events remain and includes an exact total only when the page is complete.	Requires `view_connections`.
`GET`	`/api/estate/comparison-events/{diff_hash}/findings`	One page of the findings a comparison event exhibited: event role (`opened` / `recurred` / `closed`), decoded evidence, family coordinates, and top-level reading fields in `view=rows`. Paged with `offset`/`limit`, narrowable to one `family_signature` or `settlement_basis`, and selectable as `view=keys` for naming fields only; `view=index` returns the element → finding-key join alone (complete, never paged). Empty page for an unknown diff hash (not an error).	Requires `view_connections`.
`GET`	`/api/estate/findings`	Bounded, resumable findings-ledger pages for the remediation loop. Optional query `component_pair`; `status` defaults to `open` (pass `all` for open and closed). Rows include systemic-family annotations when present. `limit` defaults to `150` and is clamped by response shape; pass `next_cursor` back as `cursor` until `has_more` is `false`.	Requires `view_connections`.
`GET`	`/api/estate/findings/dispositions`	Page the per-finding diagnosis state, including the recorded verdict, note, actor, and comparison filters. Returns filtered totals and counts by disposition before paging.	Requires `view_connections`.
`GET`	`/api/estate/findings/ranked`	Deviation-ranked findings with blast radius and plane annotations. Optional query `component_pair`; `status` defaults to `open` (pass `all` for open and closed). Evidence is omitted unless `include_evidence=true`.	Requires `view_connections`.
`GET`	`/api/estate/findings/ledger`	Bounded, resumable pages of the OPEN cross-run finding lifecycle ledger. Repeatable `diff_hash` or `run_id` scopes the read to one comparison; `include_lineage` defaults to `false`; `limit` defaults to `150` and is clamped to `1`–`250`; pass `next_cursor` back as `cursor` until `has_more` is `false`. Resolved findings are omitted — reach them through `GET /api/estate/findings/{finding_id}/history`.	Requires `view_connections`.
`GET`	`/api/estate/findings/ledger/summary`	Counts for the open cross-run finding ledger without returning rows: estate-wide totals, state and layer counts, per-estate-pair counts, and unresolved-pair counts.	Requires `view_connections`.
`GET`	`/api/estate/findings/{finding_id}/history`	One finding’s folded lifecycle state plus tamper-evident case history (opened rX, resolved rY, reopened rZ), keyed by its durable `#N`. The lifecycle state and case history are a pure fold over the append-only event log and cannot disagree with the ledger’s current state. `rests_on_reopened_seal` is not part of that fold: it is derived when the history is read, from the run that last saw the finding and the current state of the rulings its seal cites, as on the ledger row.	Requires `view_connections`. `404` when no finding carries that number; `422` when `finding_id` is not an integer.
`POST`	`/api/estate/findings/{finding_key}/disposition`	Attach one human diagnosis to an open finding.	Requires `ratify_source_contract`. With auth enabled, requires a genuinely authenticated human; auth-off callers are attributed as `local operator (auth disabled)`.
`GET`	`/api/estate/findings/families`	Systemic-family rollup of findings on comparisons the caller may see (alert-flood collapse); hidden findings are excluded before family membership, counts, and samples are computed. Optional query `component_pair`; `status` defaults to `open` (pass `all` for open and closed). `with_deferrals=true` badges only deferrals on visible pairs or unpaired notes authored by the caller.	Requires `view_connections`.
`POST`	`/api/estate/findings/families/{family_signature}/disposition`	Attach one human diagnosis to every open member of a systemic family.	Requires `ratify_source_contract`. With auth enabled, requires a genuinely authenticated human; auth-off callers are attributed as `local operator (auth disabled)`.
`POST`	`/api/estate/comparison-events/{diff_hash}/disposition-packages`	Stage an agent-proposed batch of finding diagnoses for human approval; staging applies nothing and returns a Human Review link.	Requires `view_connections`.
`GET`	`/api/estate/comparison-events/{diff_hash}/disposition-packages`	List staged disposition packages for one comparison, newest first, with summary counts and whether the caller can sign each package.	Requires `view_connections`.
`GET`	`/api/estate/signoffs/waiting`	Read open disposition packages and rule reviews for several visible comparisons in one request, for the Prover landing worklist.	Requires `view_connections`.
`GET`	`/api/estate/disposition-packages/mine`	List the caller’s most recent standing sign-offs across comparisons. The response reports when the bounded view may omit older signatures.	Requires `view_connections`.
`GET`	`/api/estate/comparison-events/{diff_hash}/disposition-packages/{package_id}`	Return one staged disposition package with each proposal joined to the finding’s current evidence and per-item review state.	Requires `view_connections`.
`GET`	`/api/estate/comparison-events/{diff_hash}/disposition-packages/{package_id}/record`	Read only the package’s title, signer record, and owning or historical Action Review request; omits per-item review data and viewer verdicts.	Requires `view_connections`.
`GET`	`/api/estate/comparison-events/{diff_hash}/disposition-packages/{package_id}/promotion-preview`	Preview the rules package approval would create, including unavailable promotion reasons; writes nothing. Repeat `finding_key` to preview selected items.	Requires `view_connections`.
`POST`	`/api/estate/comparison-events/{diff_hash}/disposition-packages/{package_id}/approve`	Apply selected package approvals or amendments and record selected rejections; unnamed items remain undecided. Refused for a package an agent or service staged, which is decided as a whole through Action Review.	Requires `ratify_source_contract` and an authenticated human. `403` when the proposer attempts approval; `409` when an item moved after staging.
`POST`	`/api/estate/comparison-events/{diff_hash}/disposition-packages/{package_id}/unsign`	Retract the caller’s signature from selected package items, returning them to the undiagnosed set while preserving the decision history.	Requires `ratify_source_contract` and the same signing identity that decided at least one named item.
`POST`	`/api/estate/comparison-events/{diff_hash}/disposition-packages/{package_id}/retract`	Withdraw an open package before any item is ruled on. The proposer can withdraw only their own package.	Requires `view_connections`.
`GET`	`/api/estate/comparisons/{diff_hash}/review/bundles`	List standing one-signature bundles for a comparison, including their recorded scope, proposer identity, approval link, and whether the evidence-gap population moved.	Requires `view_connections`.
`POST`	`/api/estate/comparisons/{diff_hash}/review/bundles`	Stage one agent-proposed bundle across correspondence rules, disposition packages, and evidence-gap packages. Staging applies nothing.	Requires `view_connections`.
`POST`	`/api/estate/comparisons/{diff_hash}/review/bundles/{bundle_id}/approve`	Settle every member named by one bundle in one transaction, or write nothing if any member no longer binds. Bundles carrying disposition packages or an agent-routed rules-only bundle are refused because they need a composite Action Review authorization.	Requires `view_connections`; bundles carrying correspondence rules also require `ratify_source_contract`.
`GET`	`/api/estate/remediation-requests`	Filed defect remediation requests, newest first. Optional query `pair_fingerprint`, `family_signature`, `status`.	Requires `view_connections`.
`POST`	`/api/estate/remediation-requests`	File a defect remediation request (content-addressed, idempotent).	Requires `ratify_source_contract`. With auth enabled, requires a genuinely authenticated human; auth-off callers are attributed as `local operator (auth disabled)`.
`POST`	`/api/estate/remediation-requests/{request_id}/dispatch`	Advance a remediation request to `dispatched` (human-only).	Requires `ratify_source_contract`. With auth enabled, requires a genuinely authenticated human; auth-off callers are attributed as `local operator (auth disabled)`.
`GET`	`/api/estate/notes`	Collaboration notes on one target (family/object/rule), oldest first. Returns notes on visible estate pairs and notes without a pair that the caller authored. Query `target_kind` and `target_ref` required; optional `pair_fingerprint`.	Requires `view_connections`.
`POST`	`/api/estate/notes`	Append one collaboration note to a family/object/rule (human-only).	Requires `view_connections`. With auth enabled, requires a genuinely authenticated human; auth-off callers are attributed as `local operator (auth disabled)`.
`GET`	`/api/estate/comparisons/{diff_hash}/review`	Every reviewer decision recorded against one comparison: run-level verdict plus per-finding review state folded from the append-only event log. When a verdict is no longer valid for the selected conformance population (re-grade, incomplete worklist, or unresolved blockers), the folded `decision` is returned as `awaiting_review` even though the event log still carries the prior approval.	Requires `view_connections`.
`GET`	`/api/estate/comparisons/{diff_hash}/history`	List the comparison’s newest recorded runs, review actions, and requirements registrations, with actor attribution and conversation links only when the caller may open them. Returns at most 200 entries and a `truncated` indicator.	Requires `view_connections`. Unknown and hidden comparisons both return `404`.
`GET`	`/api/estate/comparisons/{diff_hash}/attestation`	Return the newest attestation whose signed transition binds this comparison, or `attestation: null` when none does. This is a two-read summary, not a signature check or bundle re-derivation.	Requires `view_connections`. `404` when the comparison is unknown.
`GET`	`/api/estate/comparisons/{diff_hash}/review/population`	One page of the selected conformance run’s complete Human Review worklist: exact `total_count` / `unresolved_count`, population coordinates (`run_id`, `population_hash`), and independently reviewable blocker identities. Paged with `offset`/`limit`.	Requires `view_connections`.
`GET`	`/api/estate/grades/{run_id}/review/population`	One page of a grade that read no comparison: its failed checks as Human Review blockers, plus `comparison_made: false`, the proofless disclosure, and the refusal explaining why no approval can stand.	Requires `view_connections`. `404` when the run is not a comparison-less grade.
`GET`	`/api/estate/comparisons/{diff_hash}/witnesses`	The witness document for one review-population member, addressed by its `comparison`, `object` (object name), and optional `column` coordinates. Pass `refresh=true` to bypass the persisted sample cache and re-run the live cross-estate probe. Optional query `timeout_seconds` (default `30`).	Requires `view_connections`. `404` when the comparison is hidden or no finding was minted at the locus; `409` when multiple visible entity-scoped findings share it. Read-only.
`POST`	`/api/estate/comparisons/{diff_hash}/review/finding`	Record one change to a finding’s review state (`diagnosis`, `disposition`, `workflow`, `owner`, `exception_approved`). Patch semantics — only set fields are applied; omitted fields are left alone. Optional `run_id` + `population_hash` bind a one-time exception to the population the reviewer saw. Returns the whole folded state so concurrent reviewers see each other’s writes.	Requires `view_connections`, and granting an exception additionally requires a genuinely authenticated human on an auth-enabled stack. Author is taken from the request context, never the body; auth-off callers are attributed as `local operator (auth disabled)`.
`POST`	`/api/estate/grades/{run_id}/review/finding`	Record one ruling on a failed check in a comparison-less grade and return the refreshed proofless review page. Uses the same patch fields and exception identity rule as the comparison finding route; no run-level approval is available.	Requires `view_connections`; granting an exception additionally requires a genuinely authenticated human on an auth-enabled stack. Uses the same run-visibility rule as the review-page read; `404` when the run is not a comparison-less grade or is hidden; `409` when the expected grade or population changed.
`POST`	`/api/estate/comparisons/{diff_hash}/review/findings/bulk`	Apply one review-state adjudication to multiple findings atomically. The same explicitly-set patch fields and optional shared comment are applied to every named finding, or the request is refused before any event is written.	Requires `view_connections`, and granting an exception (`exception_approved: true`) additionally requires a genuinely authenticated human on an auth-enabled stack — the same rule as the single-finding route, so batching cannot be used to step around it. `403` otherwise.
`POST`	`/api/estate/comparisons/{diff_hash}/review/comment`	Append one line to a finding’s review discussion. Comments are append-only. Returns the whole folded state.	Requires `view_connections`. Author from request context; auth-off callers attributed as `local operator (auth disabled)`.
`POST`	`/api/estate/comparisons/{diff_hash}/review/decision`	Record the run-level review verdict for this comparison. Refuses `approved` / `approved_with_exceptions` when the selected population is incomplete, still has unresolved blockers, or no longer matches optional `run_id` / `population_hash` optimistic-concurrency coordinates. Returns the whole folded state.	Requires `view_connections`, and recording ANY verdict additionally requires a genuinely authenticated human on an auth-enabled stack (`403` otherwise). Author from request context; auth-off callers attributed as `local operator (auth disabled)`. `409` when approval preconditions fail.
`POST`	`/api/estate/comparisons/{diff_hash}/review/propose-rule`	Draft a reusable Π rule from a finding’s first-hand evidence and record the proposal in the Π review worklist at `pending_review` (never auto-ratified). Returns the whole folded comparison state plus `proposed_rule_id`.	Requires `view_connections`. Author from request context; auth-off callers attributed as `local operator (auth disabled)`.
`POST`	`/api/estate/comparisons/{diff_hash}/review/propose-cluster-rule`	Propose ONE reusable ruling for a same-cause cluster: a single-column Π rule per member, drafted from each member’s own evidence, in one transaction. Rules that fold the same way share a mechanism, so the Π worklist asks the cluster as one question, signed once. Every unowned member is recorded as owned by the caller, and the ruling is recorded with its members and owner (`cluster_rulings` on the review read). Returns the folded comparison state plus `proposed_rule_ids`.	Requires `view_connections`. Author and owner from request context.
`POST`	`/api/estate/episodes/import`	Import one bench loop-gate artifact bundle as a reconciliation episode (numbered issues, append-only journal, durable-ledger upserts). Idempotent per `(scope_key, source_run_id)` — re-importing the same bundle returns the existing episode untouched. Importing a new episode terminally supersedes any prior open episode for the same scope. Malformed bundles and licensing-doctrine violations (the implementer never licenses) return `400` with nothing persisted.	Requires `view_connections`. An episode is the record of an agent-to-agent conversation, not an authority change.
`POST`	`/api/estate/episodes/open`	Open a reconciliation episode from a dirty finished `spec_conformance` run: the server derives scope from the run (estate/connection plus the view’s spec name), allocates issue numbers (`numbering: "server"`), and derives implementer-actionable findings from the run view. Party identities default from `estate_char.episodes.implementer_id` / `prover_id` when omitted. Idempotent per opening run; terminally supersedes any prior open episode for the same scope. Refuses clean, unfinished, unknown, or non-conformance runs (`400`/`404`) with nothing persisted.	Requires `view_connections`. An episode is the record of an agent-to-agent conversation, not an authority change.
`POST`	`/api/estate/episodes/open-live`	Open a live derivational/bench reconciliation episode before round 1 from graded obligations the orchestrator supplies directly (each `verify_against_contract` verdict the loop gate collected), instead of deriving issues from a finished conformance run view. Party identities default from `estate_char.episodes.implementer_id` / `prover_id` when omitted. Every opened issue is plain `open` (never pre-licensed). Refuses a clean grade or an empty findings list (`400`/`422`) with nothing persisted. Eve replies, prover adjudication, and close reuse the existing episode machine-channel routes.	Requires `view_connections`. An episode is the record of an agent-to-agent conversation, not an authority change.
`POST`	`/api/estate/episodes/{episode_id}/rounds`	Append one full re-grade round to an open episode; the server derives still-failing findings from the grade run’s view under the episode’s scope and computes the differential.	Requires `view_connections`. `404` when the episode or grade run is unknown or not visible to the caller; `400` when the grade run has not finished; `409` when the episode is not open.
`POST`	`/api/estate/episodes/{episode_id}/rounds/live`	Append one live re-grade round from the orchestrator’s current still-failing obligations (the round’s grade-vector / findings delta) rather than a finished conformance grade run. The server re-derives issues under the episode’s scope and computes the resolved/carried/new differential. An empty `findings` list is accepted — it resolves every open issue. No grade run is folded here; a Gap-A verification run is persisted and inspectable on its own.	Requires `view_connections`. `404` when the episode is unknown or not visible to the caller; `400` when the findings are refused; `409` when the episode is not open.
`POST`	`/api/estate/episodes/{episode_id}/close`	Record the orchestrator’s terminal decision (`resolved`, `disputed`, or `abandoned` — `superseded` is never set here; only a newer open episode sets it).	Requires `view_connections`. `404` when the episode is unknown or not visible to the caller; `409` when the episode is not open.
`POST`	`/api/estate/episodes/{episode_id}/issues/{issue_number}/respond`	The implementer’s machine-channel reply for one issue (`fixed`, `explanation`, or `fixed_note`). `actor_id` is verified against the episode’s registered implementer — identity refusals return `403`.	Requires `view_connections`. `404` when the episode is unknown or not visible to the caller; `409` when episode state forbids the reply.
`POST`	`/api/estate/episodes/{episode_id}/issues/{issue_number}/adjudicate`	The prover’s independent verdict on one issue (`agree`, `withdraw`, or `dispute`). Only the episode’s registered prover may adjudicate; licensing-doctrine violations return `403`.	Requires `view_connections`. `404` when the episode is unknown or not visible to the caller; `409` when the issue is already settled — except a `withdraw` repeating a withdrawal this same prover already recorded, which returns `200` with the episode unchanged, `idempotent_repeat: true` and `repeat_unrecorded`.
`POST`	`/api/estate/findings/{finding_key}/ruling`	The human court’s ruling on a contested finding (`license`, `uphold`, `withdraw`), plus `reconfirm_license`, which records no disposition and answers the migration question a pinned license carries. The deciding human comes from the request context, never the body; auth-off callers are attributed as `local operator (auth disabled)`.	Requires `view_connections`. `404` when the finding is unknown or its episode state forbids the ruling; `409` when a `reconfirm_license` names a finding that is not a pinned standing license, or when its evidence moved under the caller.
`GET`	`/api/estate/episodes`	List reconciliation episodes, newest first (episode rows only — no issues or journal). Optional query `spec_family`, `estate_id`, `status`; `limit` defaults to `50`.	Requires `view_connections`.
`GET`	`/api/estate/episodes/{episode_id}`	One episode with its numbered issues (including prior-ledger-status snapshots) and append-only event journal.	Requires `view_connections`. `404` when unknown.
`GET`	`/api/estate/findings/{finding_key}/episodes`	A durable finding’s ledger row plus every episode sighting of that finding, newest episode first. Drives the cross-episode render (`ledger.reopen_count`, per-sighting episode linkage).	Requires `view_connections`. `404` when the finding is unknown (no ledger row and no sightings).
`GET`	`/api/estate/findings/{finding_key}/witnesses`	The rows behind one finding: violating rows or side-by-side aligned samples, plus full queries-run disclosure. Samples are served from a persisted cache; pass `refresh=true` to bypass and re-run the live cross-estate probe. Optional query `timeout_seconds` (default `30`).	Requires `view_connections`. Read-only.
`GET`	`/api/estate/findings/families/{family_signature}/witnesses`	Witness views for a sample (open-first, at most 3 members) of one systemic finding family. Each member’s samples are served from a persisted cache; pass `refresh=true` to bypass and re-run the live probe for every sampled member. Optional query `timeout_seconds` (default `30`).	Requires `view_connections`. Read-only.
`GET`	`/api/estate/dossier`	Render a complete, self-contained Markdown issue dossier for one post-judgment divergence (for copy/download). Query `kind` (`family` or `behavioral`) plus the kind-specific keys below. Family dossiers are served from a persisted cache when warm; pass `refresh=true` to bypass and re-assemble from live state. Returns `kind`, `title`, `summary`, `markdown`, `filename`, `cached`, and `cached_at`.	Requires `view_connections`.
`GET`	`/api/estate/arsenal/ranking`	Corpus-ranked immune-arsenal selection for a pair (operator_ui-redacted attack chips). Query `component_pair` required; optional `migrator_id`, `contract_id`, `pair_fingerprint`, `top_k`.	Requires `view_connections`.
`GET`	`/api/estate/correspondence-rules`	Π correspondence-rule registry (provenance tier + qualification). Optional query `component_pair`, `status`.	Requires `view_connections`.
`GET`	`/api/estate/correspondence-rules/pack-availability`	Shipped Π pack rules for a pair vs how many are already proposed (drives the comparison-surface propose affordance). Query `component_pair` required.	Requires `view_connections`.
`GET`	`/api/estate/correspondence-rules/pack-consent`	Read a pair’s shipped Π rules with vendor and effective consent tiers, pair adoption state, directional loss notes, and non-adoptable measurement templates. Optional query `component_pair`, `diff_hash`.	Requires `view_connections`.
`POST`	`/api/estate/correspondence-rules/adopt`	Adopt named checkbox-tier shipped Π rules for the estate pair resolved from a stored comparison. Each rule is re-qualified against that pair before binding.	Requires `ratify_source_contract` and an authenticated human.
`POST`	`/api/estate/correspondence-rules/accept-defaults`	Accept a comparison’s pending platform-default Π rules under ONE signature. Each named rule is re-qualified against the comparison’s estate pair and bound independently; every rule that bound is recorded in a single `platform_defaults_accepted` review event, and the comparison is re-submitted so the new licensing reaches its numbers (best-effort, and reconciled on the next diff-scoped `GET /api/estate/rule-reviews`).	Requires `ratify_source_contract` and an authenticated human.
`POST`	`/api/estate/correspondence-rules/propose`	Seed + qualify a pair’s shipped Π pack so its rules reach the ratification worklist (eligible, not binding). Mirrors `propose_correspondence_rules`.	Requires `view_connections`. Proposer from request context (audit only). `400` when the pair ships no pack.
`POST`	`/api/estate/correspondence-rules/{rule_id}/withdraw`	Remove one proposal from one comparison’s worklist without rejecting or revoking the rule globally. The server admits only a recorded foreign origin, an absent object in the comparison boundary, or the caller’s own proposal, and journals the actor, reason, and ground.	Requires `view_connections`. `400` for invalid input, `403` when no objective withdrawal ground is satisfied, `404` when the comparison or rule is unknown.
`POST`	`/api/estate/correspondence-rules/{rule_id}/qualify`	Qualify one proposed Π rule against the reviewed comparison’s pair: evaluate edge fixtures and record configured-pair field-survival evidence so the rule becomes ratifiable.	Requires `ratify_source_contract` and an authenticated human ratifier.
`POST`	`/api/estate/correspondence-rules/{rule_id}/request-approval`	Ask Action Review to approve one agent- or service-proposed rule; returns the existing request when one already holds the rule.	Requires `ratify_source_contract`. `409` when the rule signs off directly or belongs to an open package.
`POST`	`/api/estate/correspondence-rules/{rule_id}/ratify`	Ratify one qualified rule that uses the direct sign-off route (binding from now on; refuses unqualified rules and rules that require Action Review).	Requires `ratify_source_contract` and an authenticated human ratifier.
`POST`	`/api/estate/correspondence-rules/{rule_id}/reject`	Reject one proposed Π rule the ratifier declines (retires it from the pending-review worklist). A ratified rule is revoked, not rejected — the store refuses that (`400`).	Requires `ratify_source_contract` and an authenticated human ratifier.
`POST`	`/api/estate/correspondence-rules/{rule_id}/revoke`	Revoke a ratified Π rule (human-only; stops future licensing). Requires a `reason`; optionally records a `superseded_by` rule that absorbs it. Historical diffs that cite the rule keep their verdicts.	Requires `ratify_source_contract` and an authenticated human revoker.
`GET`	`/api/estate/rule-reviews`	Π rules for the operator ratification-review worklist (each with `review_status` and `viewer_signs_as`, the identity this caller would ratify as, or `null` when they may read but not sign; `usage` is `null` until merged from `rule-usage`; plus `mechanism_signature`, `mechanism_label`, `scope`, and `default_refusal` — the shared fold rules are grouped by for batch consent, that fold in plain words, whether the rule is `site`-scoped or `pair`-generic, and why a rule must not be offered as a pre-ticked platform default). Optional query `component_pair`, `source` (dialect), `review_status` (for example `pending_review`).	Requires `view_connections`.
`GET`	`/api/estate/rule-reviews/by-comparison`	Return the rule-review worklist for several comparisons in one request. Pass comma-separated `diff_hash` values in the query; response data is keyed by hash, and an unknown hash is absent from the map. This batch read does not run the single-comparison consent read-repair.	Requires `view_connections`.
`GET`	`/api/estate/rule-usage`	Per-rule usage keyed by `rule_id` (`licensed_count`, `comparison_count`) — the deferred second half of the ratifications worklist.	Requires `view_connections`.
`GET`	`/api/estate/rule-reviews/{rule_id}`	One rule’s review dossier: payload, edge fixtures, provenance, qualification, field events, usage, sign-off route, and bundle hold; also includes the `mechanism_signature` / `mechanism_label` / `scope` triple the sign-off dialog renders the rule itself from.	Requires `view_connections`.
`POST`	`/api/estate/rule-reviews/{rule_id}/confirm`	Confirm a ratified Π rule after review (human-only; rule stays binding).	Requires `ratify_source_contract` and an authenticated human reviewer.
`POST`	`/api/estate/rule-reviews/{rule_id}/revoke`	Revoke a ratified Π rule after review (human-only; stops future licensing).	Requires `ratify_source_contract` and an authenticated human reviewer.
`GET`	`/api/estate/waivers`	Durable-waiver ledger: owner, expiry, scope, and expiring-soon alerts. Optional query `expiring_within_days` (default `14`).	Requires `view_connections`.
`POST`	`/api/estate/deltas/preview`	Dry-compile a draft Δ: footprint, issues, touched obligations. Persists nothing.	Requires `view_connections`.
`POST`	`/api/estate/deltas`	Register one Δ proposal (ratification stays a separate human gate).	Requires `view_connections`. Records the authenticated user as `operator`.
`GET`	`/api/estate/deltas`	Δ (intended-changes) artifacts with typed operations.	Requires `view_connections`.
`POST`	`/api/estate/deltas/{delta_hash}/ratify`	Ratify one Δ (human-only; the empty delta is explicitly ratifiable).	Requires `ratify_source_contract` and an authenticated human ratifier.
`GET`	`/api/estate/knowledge`	List knowledge atoms (`operator_ui`-redacted). Optional filters: `component_pair`, `migrator_id`, `source_platform`, `target_platform`, `phenomenon_kind`, `provenance`, `disclosure`, `signal`; `include_superseded` (default `false`); `limit` omitted by default → every matching atom is returned (pass `limit` to page down).	Requires `view_connections`.
`GET`	`/api/estate/knowledge/coverage`	Corpus-wide coverage map: persisted vs harvestable atoms, the gap, and per-source counts.	Requires `view_connections`.
`GET`	`/api/estate/knowledge/comparison`	Per-comparison view: atoms this pair contributed plus atoms informing its instruments. Query `component_pair` required; optional `migrator_id`.	Requires `view_connections`.
`POST`	`/api/estate/knowledge/collect`	Run one idempotent knowledge sweep — mint atoms the corpus now implies.	Requires `view_connections`. Records the authenticated user as `operator`.
`GET`	`/api/estate/knowledge-dossiers`	Browse the cross-estate knowledge moat — one summary per deduped failure pattern, most-recently-seen first. Optional query facets: `comparison`, `source_engine`, `target_engine`, `verdict`, `status`, `cross_signature`. Each row carries `seen_count` / `seen_refs` for cross-estate recurrence; Markdown bodies are omitted from the list.	Requires `view_connections`.
`GET`	`/api/estate/knowledge-dossiers/{dossier_id}`	One knowledge dossier with both rendered Markdown views: `estate_view_md` (full estate-specific write-up) and `redacted_view_md` (safe-to-share pattern document). `resolution_md` is present only later in the lifecycle.	Requires `view_connections`.
`GET`	`/api/estate/rulings`	Browse the estate ruling library (settled ambiguity-class conventions). Optional filters: `scope_level`, `scope_id`, `estate_id`, `state`, `class_id`, `provisional`. Returns fold rows only — provenance chains read through `GET .../rulings/{ruling_id}`.	Requires `view_connections`.
`GET`	`/api/estate/rulings/{ruling_id}`	One ruling with its full provenance chain (`ruling_events` log).	Requires `view_connections`. `404` when unknown.
`POST`	`/api/estate/rulings/settle`	A human directly settles one `(class_id, jurisdiction)` slot; the licensor is the authenticated caller, never the body. Sub-estate jurisdiction components without an `estate_id` are refused at the store.	Requires `ratify_source_contract` and an authenticated human decider. `400` on vocabulary / state errors; `403` on identity or licensing-doctrine violations.
`POST`	`/api/estate/rulings/{ruling_id}/ratify`	Confirm a provisional direction (the RATIFY gate); stamps the ratifier.	Requires `ratify_source_contract` and an authenticated human ratifier. `404` when the ruling id is unknown; `400` when the ruling is not ratifiable; `403` on identity refusals.
`POST`	`/api/estate/rulings/{ruling_id}/unsettle`	Withdraw a direction — the slot reverts to escalate via supersession (the withdrawn direction stays reconstructable; nothing is deleted). Optional `note` in the body.	Requires `ratify_source_contract` and an authenticated human decider. `404` when the ruling id is unknown; `400` when state forbids unsettle; `403` on identity refusals.
`GET`	`/api/estate/ruling-questions`	Pending build-time clarifications an agent filed mid-build (the answer worklist). Optional query `status`, `estate_id`.	Requires `view_connections`.
`POST`	`/api/estate/ruling-questions/{question_id}/answer`	A human answers a build-time question — settling the slot and closing the loop. The decider is the authenticated caller, never the body.	Requires `ratify_source_contract` and an authenticated human decider. `404` when the question is unknown; `400` when state forbids answer; `403` on identity refusals.
`GET`	`/api/estate/court/dockets`	The ranked Adjudication Court queue for an estate — dockets awaiting a decision, ordered by materiality.	Requires `view_connections`. Query `estate_id` required.
`GET`	`/api/estate/court/dockets/{docket_id}`	One docket’s full package (neutral question, instances, prior elections) plus its court record (attorney-chat provenance).	Requires `view_connections`. Query `estate_id` required. `404` when the docket is not in the estate’s current queue.
`GET`	`/api/estate/court/dockets/{docket_id}/audit`	One docket’s audit status in its estate (`open`, `provisional`, or `settled`). The docket supplies the class being audited; an optional `class_id` must match that docket.	Requires `view_connections`. Query `estate_id` required; `class_id` is optional.
`POST`	`/api/estate/court/dockets/{docket_id}/decide`	A human decides a docket — emits a settled ruling into the estate ruling library; the licensor is the authenticated caller, never the body.	Requires `ratify_source_contract` and an authenticated human decider. `400` on vocabulary / state errors; `403` on identity or licensing-doctrine violations; `404` when the docket is unknown.
`POST`	`/api/estate/court/dockets/{docket_id}/adopt`	A human adopts another jurisdiction’s ruling for this docket’s estate. The adopter is the authenticated caller, never the body.	Requires `ratify_source_contract` and an authenticated human decider. `403` on identity or licensing-doctrine violations; `404` when the docket or source ruling is unknown; `400` on other state errors.
`POST`	`/api/estate/court/dockets/{docket_id}/chat`	Record one exchange in a docket’s attorney chat (the court record / provenance).	Requires `view_connections`. Author from request context; auth-off callers attributed as `local operator (auth disabled)`. `400` on court-record errors.
`GET`	`/api/estate/improvement-docket`	List candidate improvements awaiting human review across all estates. Optional query filters: `diff_hash`, `adjudication_id`, and `status` (`open`, `accepted`, or `rejected`). Open entries are listed first, then newest first within each status.	Requires `view_connections`.
`POST`	`/api/estate/improvement-docket/{docket_entry_id}/accept`	Accept one candidate improvement. The human decision records the entry and mints the finding-wide `waived` licence when every element of that finding has been accepted.	Requires `ratify_source_contract` and an authenticated human reviewer. `400` when the entry cannot be accepted; `403` on identity or permission refusal; `404` when the entry is unknown; `409` (`action_review_required`) when an agent filed it.
`POST`	`/api/estate/improvement-docket/{docket_entry_id}/request-approval`	Ask Action Review to accept every open element of an agent-filed entry’s finding. Declining the request rejects nothing.	Requires `ratify_source_contract` and an authenticated human. `404` when the entry is unknown; `409` when it is decided, names no finding, or is accepted directly.
`POST`	`/api/estate/improvement-docket/{docket_entry_id}/reject`	Reject one candidate improvement, recording the human decision without minting a licence or changing the finding disposition.	Requires `ratify_source_contract` and an authenticated human reviewer. `400` when the entry cannot be rejected; `403` on identity or permission refusal; `404` when the entry is unknown.

For POST /api/estate/spec-conformance/author-seat, repository and chat-upload asset forms, including the ref requirement, are documented in the author_spec tool reference. Terminal writes are conditional: once a run row has a terminal status, a later completion does not replace its status, finished_at, or terminal summary. This preserves a stale-run reconcile, refusal, failure, or cancellation when work finishes after the row was closed. The late arrival is retained in the row’s summary instead: summary.late_completions is an oldest-first list capped at 20 entries, and summary.late_completion_count counts every late arrival without that cap. Each list entry contains status_attempted, an ISO-8601 UTC at timestamp, a basis describing the terminal state that won, and the attempted summary_attempted document (or null). An at-least-once retry with the same terminal status and summary is treated as already recorded and is not added again. Heartbeat updates after a row is terminal are ignored. The run envelope also declares these values as late_completions and late_completion_count, always present even when they are an empty list and 0, so clients can distinguish “no late completion” from an older server that does not expose the fields. The run’s own summary remains authoritative: these envelope fields report what a refused terminal writer attempted, not a replacement verdict. All run-envelope timestamps (started_at, finished_at, heartbeat_at, provenance stamped_at, and late-completion at) are ISO-8601 strings with an explicit timezone offset when the stored value is a valid ISO timestamp. A malformed stored timestamp is served verbatim and logged at WARNING rather than being assigned an invented offset. When stale-run reconciliation reaps a still-running row, it preserves the driver’s existing summary and adds the liveness account under summary.reaper. That block includes reaped_at and a basis naming the measured liveness evidence and the estate_char.reconcile.stale_after_seconds threshold that was applied; the existing top-level error and error_type remain available for readers that already use them. If the stored summary is not a JSON object, the raw value is retained in summary.reaper.unparsed_summary rather than discarded. The reaper only closes a row that is still running when it writes, so a completion that wins the race is not rewritten as abandoned.

Readiness checklist conversation provenance

POST /api/estate/readiness and GET /api/estate/readiness/{readiness_id} include these fields in data:

Field	Type	Description
`recorded_in_thread`	string or null	Conversation that first recorded the answers, or `null` when no conversation was recorded.
`same_conversation`	boolean or null	Whether the recorded conversation matches the reader’s. HTTP requests have no conversation context, so this is `null` for these routes.
`conversation_note`	string or null	Confirmation warning when the record is known to come from another conversation. HTTP requests have no reader conversation to compare, so this is `null` for these routes.

These fields describe provenance, not answer content; an identical submission from a later conversation keeps the first record’s recorded_in_thread.

Transition surface

A transition groups comparison tracks into one migration effort and exposes its history through a portfolio and a detail view. transition_ref accepts either the opaque transition_id or the stable lowercase-hyphenated slug.

`GET /api/estate/transitions`

The portfolio returns one data item per transition, ordered newest first. Use the optional status query to filter by active or closed; the endpoint does not apply a default limit.

Field	Type	Description
`transition_id`	string	Opaque transition identifier.
`name`	string	Display name.
`slug`	string	Stable URL segment.
`owner`	string or null	Accountable owner, when set.
`status`	string	`active` or `closed`.
`created_at`	datetime or null	Creation timestamp.
`generation_count`	integer	Number of generations in the lineage.
`current_generation_label`	string or null	Label of the open generation, or `null` when all generations are closed.

`GET /api/estate/transitions/{transition_ref}`

The detail response contains data with the transition’s edges, all generations in oldest-first order, pins for the current generation, and derived counts. Edges are included only when every named estate is visible (an edge naming no estate is shown only to a principal with manage_all_connections). Pinned comparisons and runs are included only when the caller may see them. edge_count and station_count are calculated from the visible edges; station_count counts distinct estates touched by those edges. sealed_spec_count counts distinct sealed specifications cited by the current generation. Each edges item includes track_id, position, source_role, target_role, the source and target estate identifiers and dialects, the track status, and the mediation set: platform_pack, schema_spec_hash, or both. When both are present, they describe one hop that changes platform and schema; they are not two separate edges. Each generations item includes:

Field	Type	Description
`generation_id`	string	Opaque generation identifier.
`generation_number`	integer	Lineage number within the transition.
`label`	string	Customer-facing generation label.
`kind`	string	`native` for a product-owned generation or `archived` for a pre-existing record.
`is_current`	boolean	`true` exactly when `closed_at` is `null`.
`external_url`	string or null	Archived generation’s committed board URL; `null` for native generations.
`external_commit`	string or null	Commit pinning an archived board URL; `null` for native generations.
`seeded_from_generation_id`	string or null	Prior generation from which this generation was seeded, when applicable.
`closed_at`	datetime or null	Closing timestamp; `null` while open.
`closed_by`	string or null	Authenticated closing identity, when closed in the product.

The current_generation_pins items contain pin_kind, subject, pin_ref, and an optional label. Valid pin_kind values are spec_seal, effective_view, diff_of_record, run_of_record, register_commit, closing_record, and archived_board.

`POST /api/estate/transitions`

Field	In	Type	Default	Required	Description
`name`	body	string	none	Yes	Display name, 1–255 characters.
`slug`	body	string	none	Yes	Stable URL segment, 1–128 characters matching `^[a-z0-9]+(?:-[a-z0-9]+)*$`.
`owner`	body	string or null	`null`	No	Accountable owner, up to 255 characters.

The creating identity is taken from the authenticated request context, not from the body. The response returns the newly created transition detail.

`POST /api/estate/transitions/{transition_ref}/generations/{generation_number}/close`

This endpoint closes the named generation and returns its data record. Closing is append-only: the request records closed_at and the authenticated caller as closed_by, and a second close of the same generation returns 409.

Field	In	Type	Default	Required	Description
`transition_ref`	path	string	none	Yes	Transition id or slug.
`generation_number`	path	integer	none	Yes	Generation to close.
`pins`	body	object[]	`[]`	No	Citations to freeze with the closing record.

Each pins item has the following fields:

Field	Type	Description
`pin_kind`	string	One of the seven pin kinds listed above.
`subject`	string	Component the citation is about, 1–255 characters.
`pin_ref`	string	Hash, id, commit, or URL being cited, 1–512 characters.
`label`	string or null	Optional display label, up to 255 characters.

Pins on a closed generation cannot be added or changed later. A missing transition or generation returns 404; malformed citations return 400; a conflicting or already-closed record returns 409.

`POST /api/estate/transitions/seed/etfjpx`

Seeds the recorded ETFJPX on Databricks lineage. The first call creates one transition with three comparison edges and three generations (V17, V18, and Transition v1); V17 and V18 are archived committed-board records, while Transition v1 is the current native generation. A repeat call is safe and returns the existing detail with created: false; a first successful call returns created: true.

`POST /api/estate/characterize`

Field	In	Type	Default	Required	Description
`connection_ref`	body	string	none	Yes	Saved connection reference. Minimum length `1`, maximum `255`.
`dialect`	body	string	none	Yes	Source dialect: `bigquery`, `clickhouse`, `databricks`, `duckdb`, `mssql`, `palantir_foundry`, `postgres`, `postgresql`, `redshift`, `risingwave`, `snowflake`, `sqlite`, `sqlserver`, or `trino`.
`database`	body	string	none	Yes	Database name. Minimum length `1`, maximum `255`.
`schemas`	body	string[] or null	`null`	No	Schema names to include. Omit or pass `null`/an empty list for full-source scope — every schema in the database is scanned minus recorded `excluded_schemas` (and engine-system schemas). Pass a non-empty list only to pin a deliberate subset. Maximum `100` entries; each name must be non-empty.
`excluded_objects`	body	string[]	`[]`	No	Fully qualified objects to exclude. Maximum `1000` entries.
`objects`	body	string[] or null	`null`	No	Optional object-level scope. Omit or pass `null`/an empty list to scan every object in the in-scope schemas. Pass a non-empty list of schema-qualified names (`schema.object`) to characterize exactly those objects. Maximum `1000` entries; names must be resolvable and are matched case-insensitively.
`allow_absent_scope`	body	boolean	`false`	No	Declare that the pinned `objects` may not exist yet because a build creates them. Requires a non-empty `objects` list; missing pinned names are recorded in the run summary instead of failing the scan. It does not permit an empty visible estate.
`absent_scope_basis`	body	string or null	`null`	No	Why the pinned objects may be absent: `relocation` for a decision-10 relocation whose round-0 target has not received the declared relations, or `frozen_build_did_not_produce` when the build under measurement failed before producing them. A target scan with `allow_absent_scope: true` must name one of these causes; a source scan may omit it.
`build_evidence`	body	object or null	`null`	No	Required only with `absent_scope_basis: "frozen_build_did_not_produce"`. Provide `armed_by` (non-blank string), `build_rc` (non-zero scalar integer), `error_summary` (non-blank string), `before_side_measured: true`, and `measured_at` (ISO-8601 timestamp with a UTC offset). Rejected with any other basis.
`role`	body	string	`"source"`	No	Sandbox-glob side: `"source"` (default) applies the recorded `excluded_schemas` sandbox glob (`_eval`, `_stim`); `"target"` keeps every non-system schema so a target-only sandbox-looking schema is characterized, not silently dropped. Use `"target"` when characterizing a migration target.
`as_of_window_rules`	body	object[]	`[]`	No	Optional locked as-of windows (DEM1-2b). Maximum `1000` entries. Each rule pins one wall-clock object to a fixed timestamp range on `anchor_column` so a later comparison yields a real in-window verdict instead of a time-dependent abstention. Each item requires `object_name` (string), `anchor_column` (string), and at least one of `lower_bound` or `upper_bound` (ISO date/timestamp strings; either bound may be omitted). Rules are validated at the HTTP boundary and stamped onto the observation boundary (they participate in the boundary hash).
`provenance_assertions`	body	object[]	`[]`	No	Optional proposals for provenance relationships the schema does not declare. Maximum `100` entries. Each item requires `source_object` (`schema.object`), `source_column`, and `dependent_columns` (objects with `object_name` and `column`); `note` is optional. The authenticated caller is stamped server-side as the asserting person.

The optional Idempotency-Key request header names the submission when a caller needs to distinguish an intentional repeat from an accidental duplicate. While an identical characterization is queued or running, Genesis returns the existing run_id with reused: true and reused_basis instead of starting a second scan. A distinct header value forks the submission identity and permits a second concurrent scan on purpose. A repeat after the first scan finishes always starts a new scan because characterization measures the estate at an instant; failed or cancelled runs likewise do not satisfy a repeat. A new scan returns reused: false and reused_basis: null. The caller’s resolved identity governs interrupted characterization resume; see Prover identity and resume isolation for the boundary. For dialect: "palantir_foundry", database is the Foundry space RID or display name, and schemas contains folder paths relative to that space (or folder RIDs). Dataset objects are addressed by their Foundry dataset RID rather than display name; the catalog provider resolves those RIDs and the measurement queries run through Foundry’s Spark SQL surface. Omit schemas for the full-source scope. See Palantir Foundry integration for connection setup and Genesis Prover for the measurement model. Each as_of_window_rules item is a strict pass-through of the estatechar AsOfWindowRule shape — only object_name, anchor_column, lower_bound, and upper_bound are accepted. Bounds must be fixed ISO date or timestamp literals (not wall-clock functions such as current_date); when both bounds are present, lower_bound must not be after upper_bound. A malformed rule (missing bounds, non-ISO literal, reversed bounds, or unknown key) returns 422 before the background scan starts. Each provenance_assertions item is a proposal, not a client-supplied attribution or license. The server ignores attribution fields, stamps the authenticated caller, and verifies the source column against the live catalog during the scan. A proposal cannot override an existing declared foreign-key origin; a malformed wire shape returns 422, while a proposal rejected by the shared provenance rules returns 400 before a run is created. Each assertion adds one catalog query during the scan, and a catalog contradiction fails the scan rather than silently applying the relationship. For object-level scope, each name must be schema-qualified and spelled as the catalog spells it, except that matching ignores letter case. Blank names, unqualified names, and names with empty or edge-whitespace components return 422 before the background scan starts. If a non-empty objects list includes an object that is not present in the catalog or is not visible to the scanning role, the run fails instead of silently characterizing a smaller scope. Set allow_absent_scope when an additive greenfield spec intentionally names relations that the build will create: names absent from a visible catalog are then reported in the completed run’s summary.scoped_absent, alongside summary.catalog_rows_seen, rather than failing the run. For a builder-created target schema, when the characterization also took a whole-database listing, the completed summary includes summary.listing_rows_seen and its corresponding summary.listing_provenance so the row count remains attributable to that listing. These fields are omitted when no listing was taken. The premise still requires the object pin and a visible catalog; an empty estate remains an error. For a target scan, allow_absent_scope: true without absent_scope_basis returns 422 rather than creating a snapshot. Use absent_scope_basis: "relocation" when the target is the not-yet-moved round-0 side of a declared relocation, or "frozen_build_did_not_produce" with its complete build_evidence when the build failed before producing the declared relations. The declared basis is content-addressed with the observation boundary and is carried into proof summaries so an element over a relation measured absent can be identified as unbuilt rather than as a failed read. See Prover run results for how proofs present that distinction. Submit-and-return: the response returns immediately with run_id, top-level status: "running", and data containing { "success": true, "run_id": "...", "status": "running" }. The scan and chained contract compile run as a background task; snapshot and contract fields land later via the runs/snapshots feed. On source scans, the static fault-drill coverage meter runs on the same background run only when estate_char.fault_drill.run_on_scan_default is true (schema default false); otherwise the terminal summary carries fault_drill_skipped and operators use POST /api/estate/estates/{estate_id}/fault-drill to drill deliberately. Follow progress live over /api/ws/estate/live?run_id=<run_id> or poll GET /api/estate/runs/{run_id}.

`GET /api/estate/discover-schemas`

Field	In	Type	Default	Required	Description
`connection_ref`	query	string	none	Yes	Saved connection reference.
`dialect`	query	string	none	Yes	Source dialect: `postgres`, `snowflake`, `databricks`, `palantir_foundry`, or `sqlite`.
`database`	query	string	none	Yes	Database whose selectable schemas to list. For `sqlite`, the value is a logical file label; discovery uses the databases attached to the connection instead.

Successful responses include schemas (sorted list of selectable non-system schema names; engine-system schemas such as information_schema, pg_catalog, ClickHouse system, or SQLite temp are excluded per dialect, matching full-source characterization scope) and error (null on success, or a human-readable message when discovery could not run). For SQLite, the returned schema names are the databases attached to the connection; the per-connection temp database is excluded because its objects are non-durable. Discovery opens the saved connection as the authenticated human caller, not as a bot identity. A personal connection therefore works when that caller owns it and can read it; the route does not substitute a bot identity for the authenticated owner. Discovery is best-effort: a bad connection, unsupported dialect, or query failure returns schemas: [] with error set (not HTTP 500) so the scan form can fall back to free-text schema entry instead of blocking a characterize request.

`GET /api/estate/estates`

Field	In	Type	Default	Required	Description
`include_archived`	query	boolean	`false`	No	When `true`, include soft-deleted (archived) estates. Each archived row carries `active: false` so callers can tell an archived estate’s leftover snapshots from an unregistered boundary.

Successful responses include data as a list of named estates, each with a scan rollup (scan_count, latest_scan) for the landing. scanned_snapshot_ids lists every snapshot bound by that estate’s scans, sorted; it is [] when none of its scans bound a snapshot. Every row also carries archived (boolean, default false) — the landing SOURCES grid visibility hide, distinct from lifecycle archive (active: false, status: 'archived'). Each row carries origin_label: null for an estate registered by an operator, or a sentence identifying a startup-backfill estate whose id begins estate_bf_. Set or clear the visibility hide with PATCH /api/estate/estates/{estate_id}/archived.

`POST /api/estate/estates`

Two request shapes are accepted (both role-agnostic):

Crafted / multi-member — pass members (one or more (connection, database, schema-scope) rows, possibly across several connections) and optionally code_assets (git ETL repos).
Flat single-member shim — pass connection_ref, dialect, and database at the top level (plus optional schemas / excluded_objects) and omit members. Normalized into a one-element member list.

Field	In	Type	Default	Required	Description
`name`	body	string	none	Yes	Operator-facing estate name. Minimum length `1`, maximum `512`. Must be unique (case-insensitive) among live estates; archiving an estate frees its name for reuse.
`members`	body	object[]	none	No*	Crafted estate members. Maximum `50` entries. Each member requires `connection_ref`, `dialect` (one of `bigquery`, `clickhouse`, `databricks`, `duckdb`, `mssql`, `palantir_foundry`, `postgres`, `postgresql`, `redshift`, `risingwave`, `snowflake`, `sqlite`, `sqlserver`, or `trino`), and `database`; optional `schemas` (omit/`null`/empty = full-source scope for that member; maximum `100` non-empty names) and `excluded_objects` (maximum `1000` entries). Required when the flat shim is not used.
`code_assets`	body	object[]	`[]`	No	Attached code (ETL) assets. Maximum `50` entries. An item’s `kind` is `git` (default), `databricks_notebook` or `databricks_job`; a field that belongs to another kind is refused. A `git` item requires `connection_ref`, `url`, or `bot_git_repo` (id of a local Genesis bot-git repo — ISS6 picker; resolved without a network clone), with optional `ref` (branch/tag/sha) and `subdir` (path inside the repo, e.g. the dbt project dir); its clone ref and resolved commit are filled server-side on clone. A `databricks_notebook` item requires `connection_ref` and an absolute `workspace_path`; a `databricks_job` item requires `connection_ref` and `job_id`. A Databricks item’s `revision` (source or settings SHA-256) is captured by `POST /api/estate/estates/{estate_id}/code-assets/clone`. Server-filled fields are never supplied by the caller.
`connection_ref`	body	string	none	No*	Flat shim: saved connection reference. Minimum length `1`, maximum `255`. Required with `dialect` and `database` when `members` is omitted.
`dialect`	body	string	none	No*	Flat shim: source dialect: `bigquery`, `clickhouse`, `databricks`, `duckdb`, `mssql`, `palantir_foundry`, `postgres`, `postgresql`, `redshift`, `risingwave`, `snowflake`, `sqlite`, `sqlserver`, or `trino`.
`database`	body	string	none	No*	Flat shim: database name. Minimum length `1`, maximum `255`.
`schemas`	body	string[] or null	`null`	No	Flat shim: schema names to include. Omit or pass `null`/an empty list for full-source scope. Maximum `100` entries; each name must be non-empty.
`excluded_objects`	body	string[]	`[]`	No	Flat shim: fully qualified objects to exclude. Maximum `1000` entries.
`kind`	body	string	`"normal"`	No	`"normal"` or `"utility"` (utility/clone estates tuck behind a toggle in the target picker).
`role`	body	string	`"source"`	No	Estate default only (`"source"` or `"target"`). Kept for the scan gate; a crafted estate is selectable as SOURCE or TARGET at comparison time.
`source_only`	body	boolean	`false`	No	Declares that no transform of ours produces the estate’s data (a raw source). Its preflight readiness has no ETL light and names the omitted check under `not_applicable`, so it can read ready with no code assets. A declaration about the ETL check only; it does not restrict the estate’s role or comparison side.

* Provide a non-empty members list or all three flat shim fields (connection_ref, dialect, database). Registration is idempotent by scope. If an active estate visible to the caller already covers exactly the requested member scope — the same connection, database, schema list, and excluded objects for every member — the endpoint returns that estate unchanged with data.reused: true; it does not validate, save, or start a preflight for this request. The existing estate’s name, role, kind, source_only, and code assets win, so callers should use the returned estate_id or update that estate explicitly. A different schema list or database is a different scope. If the matching estate is not visible to the caller, the endpoint returns 409 without naming it or creating a second estate. A newly created estate returns data.reused: false. At backend startup, Genesis runs an idempotent backfill for legacy duplicate scopes. It considers live, non-platform estates created strictly before September 24, 2026 at 06:26:26 UTC with the same stored connection, dialect, database, schema pin, and excluded objects. The oldest registration (created_at, then estate id) remains live; younger matches are archived, not deleted. Include archived rows with GET /api/estate/estates?include_archived=true. For a new estate, define-time validation runs before save: every member connection is checked. All reachable → status: "validated"; any unreachable → status: "partial" with each error recorded. Nothing is scanned yet — call POST /api/estate/estates/{estate_id}/scan separately. Overlap on any underlying database is allowed when the scope differs. When another estate already fronts the same physical (dialect, database) boundary, the save still succeeds but data includes siblings_over_same_database (an empty list when none exist) and siblings_basis. The disclosure is not a refusal: use the returned estate_id to address the intended estate explicitly, or archive an accidental duplicate. The registration response also includes data.same_source_estates and data.same_source_basis. On SQLite, these identify every other live, operator-registered estate using the same connection’s file, regardless of its registered database name; on other dialects, the source is the connection and database. These estates remain separate and their proof histories are not merged or refused. When another estate reads the source, each entry in same_source_estates contains estate_id, name, connection_ref, database, and a proof_history object with proved and latest_proof_run_id. The registering estate’s data.proof_history has the same shape. The latest run is the newest prove or standalone system_diff proof; latest_proof_run_id is null when none exists. If no other live estate reads the source, same_source_estates is empty and data.proof_history is null. same_source_basis summarizes which estates have proof history. On SQLite, finding these estates costs one narrowed estates query; when any others are found, the response also reads proof history for each one and for the registering estate (two indexed run reads per estate). When estate_char.preflight.enabled and estate_char.preflight.auto_on_save are both true (schema defaults), Genesis also fires a non-blocking post-save preflight run in the background after create — the save response returns immediately while readiness lights accrue in the live feed and GET /api/estate/estates/{estate_id}/preflight/latest. Successful responses include estate_id and data with the persisted estate (payload.connections holds the full member list; denormalized card columns reflect the primary member — members[0]). The operator identity is taken from the authenticated session, never from the request body. The response also always includes data.unpinned_code_assets (string[]) naming attached assets that have not been cloned or had a Databricks revision captured, and data.source_only_suggestion (object or null). The suggestion is present only for a newly registered role: "source" with no code assets and source_only still false; it gives the update_estate(..., source_only=true) call for raw data. Attaching no code is not inferred to mean raw data.

Status	Meaning
`409`	An estate with the same name already exists over another scope; a matching scope exists but is not visible to the caller; or all claim slots for the scope are exhausted. A visible matching scope is returned with `data.reused: true` instead.

`PATCH /api/estate/estates/{estate_id}`

Two mutation modes coexist (only passed fields change):

Scope-only edit (legacy): pass schemas / excluded_objects to re-pin the first connection’s scope in place.
Full members[] + code_assets[] replacement (ISS8): pass members to add / remove / edit sources wholesale — every member is re-validated, payload.connections and payload.validation are rebuilt atomically, and denormalized card columns follow members[0]. When members is passed, scope-only fields are ignored. Pass code_assets to replace attached ETL repos ([] clears them). Estate edit payloads typically omit server-generated clone metadata; Genesis preserves a stored clone when the incoming asset omits clone and source identity is unchanged (first non-blank of bot_git_repo, url, or connection_ref, plus trimmed ref and subdir — whitespace-only edits on those fields do not count as a change). Changing the source drops the stored clone; an incoming asset that explicitly includes clone is written as-is. Omit members to leave existing connections untouched.

Field	In	Type	Default	Required	Description
`estate_id`	path	string	none	Yes	Named estate id.
`name`	body	string	none	No	New operator-facing name. Minimum length `1`, maximum `512`.
`kind`	body	string	none	No	`"normal"` or `"utility"`.
`status`	body	string	none	No	`draft`, `validated`, or `partial`. Archiving is not settable here — call `POST /api/estate/estates/{estate_id}/archive`. When `members` is replaced and `status` is omitted, Genesis recomputes `validated` when all members are reachable or `partial` otherwise.
`schemas`	body	string[]	none	No	Scope-only: re-pin the first connection’s schema scope (must name at least one schema). Omit to leave scope unchanged. Ignored when `members` is passed. Maximum `100` entries.
`excluded_objects`	body	string[]	none	No	Scope-only: updated excluded-object list for the first connection. Ignored when `members` is passed. Maximum `1000` entries.
`members`	body	object[]	none	No	Full replacement: one or more `(connection, database, schema-scope)` rows (maximum `50`). Each member requires `connection_ref`, `dialect` (one of `bigquery`, `clickhouse`, `databricks`, `duckdb`, `mssql`, `palantir_foundry`, `postgres`, `postgresql`, `redshift`, `risingwave`, `snowflake`, `sqlite`, `sqlserver`, or `trino`), and `database`; optional `schemas` (omit/`null`/empty = full-source scope; maximum `100` non-empty names) and `excluded_objects` (maximum `1000` entries). Must contain at least one member — an empty `members[]` is rejected (`400`).
`code_assets`	body	object[]	none	No	Full replacement of attached git code (ETL) assets (maximum `50`). Each item requires `connection_ref`, `url`, or `bot_git_repo`; optional `kind` (`"git"`, default `"git"`), `ref`, and `subdir`. Pass `[]` to clear all code assets. Server-generated `clone` (resolved repo path + commit from `POST .../code-assets/clone`) is server-owned — omit it on edit. When an incoming item omits `clone`, Genesis copies the stored `clone` only if source identity matches (first non-blank of `bot_git_repo`, `url`, or `connection_ref`, plus trimmed `ref` and `subdir`); identity changes drop the clone. Items that explicitly include `clone` use the resolved payload as written. A code asset’s `kind` is `git` (default) or, for a transform that lives in a Databricks workspace, `databricks_notebook` (`connection_ref` + absolute `workspace_path`) or `databricks_job` (`connection_ref` + `job_id`); a field of another kind is refused. A Databricks asset’s `revision` (source or settings SHA-256) is captured by `POST /api/estate/estates/{estate_id}/code-assets/clone`, never supplied.
`source_only`	body	boolean	none	No	Set or clear the source-only mark. Omit to leave it unchanged.

Status	Meaning
`400`	Validation failure (for example empty `members[]`, invalid member / code-asset shape, or `status='archived'` — use `POST .../archive` instead).
`404`	Unknown estate.
`409`	Rename clashes with another estate’s name.

When estate_char.preflight.enabled and estate_char.preflight.auto_on_save are both true (schema defaults), Genesis also fires a non-blocking post-save preflight run in the background after a member or code-asset replacement — the patch response returns immediately while readiness lights accrue in the live feed and GET /api/estate/estates/{estate_id}/preflight/latest. The patch response also always includes data.unpinned_code_assets and data.source_only_suggestion with the same meanings as the registration response. Because an edit has no registration role, source_only_suggestion is null on edits; use update_estate(source_only=true) explicitly when the estate is raw.

`POST /api/estate/estates/{estate_id}/archive`

Field	In	Type	Default	Required	Description
`estate_id`	path	string	none	Yes	Named estate to archive (soft-delete).

Archive is the estate lifecycle’s delete: the row is never hard-removed (scan timelines, snapshots, and comparisons still reference it). Genesis sets active=0 and status='archived', which drops the estate from GET /api/estate/estates (unless include_archived=true), target-candidate pickers, and GET /api/estate/system-diffs (unless include_archived=true) — archiving an estate retires its comparisons from the live grid. Re-archiving an already-archived estate is idempotent — HTTP 200 with already_archived=true and no second state change. This is not the landing SOURCES visibility hide — use PATCH .../archived for a reversible card hide that leaves active/status untouched. Successful responses include estate_id, archived (always true on success), already_archived, and data with the persisted estate row.

Status	Meaning
`403`	Caller lacks `ratify_source_contract`.
`404`	Unknown estate.

`PATCH /api/estate/estates/{estate_id}/archived`

Set or clear the landing SOURCES grid visibility hide on a named estate. Two distinct “archive” concepts exist:

Lifecycle archive (POST .../archive): soft DELETE — sets active=0 and status='archived', requires ratify_source_contract, and retires everything downstream (landing cards, target candidates, comparison participants).
Landing visibility hide (this route): cosmetic and reversible — archived=true hides the source card from the landing’s default SOURCES view; archived=false restores it. Never changes active or status; the estate stays a live target candidate and comparison participant.

Field	In	Type	Default	Required	Description
`estate_id`	path	string	none	Yes	Named estate id.
`archived`	body	boolean	none	Yes	`true` hides the source from the landing SOURCES grid; `false` restores it.

Successful responses include estate_id, success, and data with the persisted estate row (including top-level archived).

Status	Meaning
`403`	Caller lacks `view_connections`.
`404`	Unknown estate.

`POST /api/estate/estates/{estate_id}/validate`

Field	In	Type	Default	Required	Description
`estate_id`	path	string	none	Yes	Named estate to re-validate.

Re-runs the define-time reachability pre-flight for every member connection in payload.connections, stores the fresh validation report on the estate, and updates status to validated when all members are reachable or partial when any is not. Each member connection is checked as the authenticated human caller. A personal connection is valid when that caller owns and can read it; the validation request does not fall back to a bot identity. Successful responses include data with ok (all members reachable), connections (per-member reachability results), and validated_at.

Status	Meaning
`404`	Unknown estate.

`POST /api/estate/estates/{estate_id}/preflight`

Field	In	Type	Default	Required	Description
`estate_id`	path	string	none	Yes	Named estate to preflight.
`persist_clones`	body	boolean or null	`null`	No	Override `estate_char.preflight.persist_clones`: when `true`, the CLONABILITY check leaves the Postgres scratch schema it provisions registered instead of dropping it. Omit to use the configured default (`false`).

Submit-and-return: runs three business-readable readiness checks — agent ACCESS (deterministic reachability for every member connection), ETL understanding (agentic, read-only — the agent locates and reads registered code_assets and returns a run plan; no writes; estates with no code assets fail immediately with no agent turn), and CLONABILITY (lightweight provision-then-teardown for Postgres members). A source-only estate omits ETL entirely and reports it under data.not_applicable, so an estate with no code assets can be ready. The response returns immediately with run_id, top-level status: "running", and data. The ETL check commissions a bounded agent turn on a visible, thread-linked thread; if that turn reaches estate_char.preflight.etl_timeout_seconds (default 600 seconds), the ETL light reports a timeout and names that setting instead of judging a partial reply as malformed. Follow GET /api/estate/runs/{run_id}, GET /api/estate/estates/{estate_id}/preflight/latest, or /api/ws/estate/live?run_id=.

Status	Meaning
`400`	Preflight is disabled (`estate_char.preflight.enabled=false`).
`404`	Unknown estate.

`GET /api/estate/estates/{estate_id}/preflight/latest`

Field	In	Type	Default	Required	Description
`estate_id`	path	string	none	Yes	Named estate whose latest readiness view to return.

Read-only: returns the latest preflight readiness view without minting a run. Successful responses include data with ready (all checks green), ordered per-check lights (pending / running / passed / failed, each with a business diagnosis and optional agent thread link), not_applicable (for example, the ETL check and its source-only basis), run_id, and run_status. When the estate has never been preflighted, data is null (not HTTP 404).

Status	Meaning
`404`	Unknown estate.

`POST /api/estate/estates/{estate_id}/code-assets/clone`

Field	In	Type	Default	Required	Description
`estate_id`	path	string	none	Yes	Estate whose attached code assets to clone.
`force`	query	boolean	`false`	No	When `true`, re-clone git assets or recapture Databricks revisions that already have server-owned state.

Clones git assets and persists their resolved clone slots; for Databricks asset shapes, revision capture, identity resolution, and failure behavior, see Estate registration and code assets. Successful responses include data with cloned / captured / skipped / failed counts, updated code_assets, and the updated estate.

Status	Meaning
`404`	Unknown estate.

`POST /api/estate/estates/{estate_id}/code-assets/lineage`

Field	In	Type	Default	Required	Description
`estate_id`	path	string	none	Yes	Estate whose cloned code assets to derive lineage from.
`force`	query	boolean	`false`	No	When `true`, re-derive lineage for assets that already have a `lineage` slot.

Derives dbt transform lineage from the estate’s cloned code assets (manifest-free parser) and reconciles parsed models against the estate’s latest scanned snapshot. Best-effort per asset; fills each asset’s lineage slot. Successful responses include data with derived / models / matched counts, updated code_assets, and the updated estate.

Status	Meaning
`404`	Unknown estate.

`POST /api/estate/estates/{estate_id}/artifact-reproduction`

This route implements the reproduce_artifact tool. It executes the declared artifact and writes to the named utility estate; the artifact must already be present in the source estate’s derived lineage.

Field	In	Type	Default	Required	Description
`estate_id`	path	string	none	Yes	Estate whose derived lineage supplies the declared artifact and whose relation is being verified.
`utility_estate_id`	body	string	none	Yes	Scratch estate registered with `kind="utility"`; a live estate is refused.
`artifact`	body	string	none	Yes	Declared artifact id in the form `<asset>:<file path in the clone>`. Clone the asset and derive its lineage first.
`relation`	body	string	none	Yes	Live relation to compare with the artifact’s reproduced output.
`confirm_relation`	body	string or null	`null`	No	Must echo `relation` on a non-local engine. Without it, nothing runs and nothing is spent. Not needed for sqlite, duckdb, or postgres.

The response is wrapped in data; see the reproduce_artifact tool contract for verdict semantics and optional evidence fields.

Status	Meaning
`400`	The request is invalid, the artifact is not declared in derived lineage, the destination is not a utility estate, confirmation is missing on a metered engine, or the artifact contains a statement that would escape the scratch schema.
`404`	Unknown source or utility estate, or unknown declared artifact / relation.

`GET /api/estate/target-candidates`

Field	In	Type	Default	Required	Description
`source_estate_id`	query	string	none	No	When set, each candidate row includes a `compared_before` badge and `last_verdict` for the `(source_estate_id, target_estate_id)` pair.

Each row includes estate_id, name, dialect, database, kind, scanned, last_scan_at, object_count, scan_count, compared_before, and last_verdict (when applicable). When a finished scan exists, object_count is resolved from the latest snapshot’s identity fields; the endpoint does not load the full characterization document just to render this count. A last_verdict for the latest forward comparison can also expose its measured unlicensed, published published_unlicensed, and withheld_unlicensed / withheld_indeterminate counts; the withheld fields are null when the minting run withheld nothing or its withholding is unavailable.

`POST /api/estate/estates/{estate_id}/scan`

Field	In	Type	Default	Required	Description
`estate_id`	path	string	none	Yes	Named estate to scan or re-scan.

Submit-and-return: the response returns immediately with run_id, scan_id, estate_id, top-level status: "running", and data. Every scan is a new run and timeline event — never a replay of a finished recording. On source scans, the static fault-drill coverage meter chains on the same run only when estate_char.fault_drill.run_on_scan_default is true (schema default false); otherwise use POST /api/estate/estates/{estate_id}/fault-drill to run it on demand. Follow progress live over /api/ws/estate/live?run_id=<run_id> or poll GET /api/estate/runs/{run_id}.

Status	Meaning
`404`	Unknown or archived estate.

`POST /api/estate/estates/{estate_id}/fault-drill`

Field	In	Type	Default	Required	Description
`estate_id`	path	string	none	Yes	Named estate whose latest contract to fault-drill.

Submit-and-return: runs only the static fault-drill coverage meter against the estate’s most recent snapshot + compiled contract — never a re-scan and never the adversarial hardening chain. The drill scores the contract’s catch rate against a synthetic copy of the stored characterization, so it works for any dialect (unlike POST .../harden or POST .../spec-drill, whose live cloners are postgres-only today). The response returns immediately with run_id, estate_id, top-level status: "running", and data. Follow the drill phase live over /api/ws/estate/live?run_id=<run_id> or poll GET /api/estate/runs/{run_id}. When the estate has no finished scan or no compiled contract yet, the run still finishes cleanly with fault_drill_skipped in the summary (not an error). Drills per run are capped by estate_char.fault_drill.max_drills (schema default 250; set 0 for no cap).

Status	Meaning
`404`	Unknown or archived estate.
`409`	A fault drill is already running for this estate.

`POST /api/estate/estates/{estate_id}/harden`

Field	In	Type	Default	Required	Description
`estate_id`	path	string	none	Yes	Named estate whose latest contract to harden.

Submit-and-return: runs only the source-hardening chain (fault drill + adversarial self-drill + harden/recompile + learnings) against the estate’s most recent snapshot + contract — never a re-scan. The response returns immediately with run_id, estate_id, top-level status: "running", and data. Follow the drill phase live over /api/ws/estate/live?run_id=<run_id>.

Status	Meaning
`404`	Unknown or archived estate.
`409`	A hardening round is already running for this estate.

`GET /api/estate/bot-git-repos`

No request body or query parameters. Successful responses include data: a list of local Genesis git repos attachable as estate code assets, each with repo_id, path, branch, and remote_url. Only git-mode repos the operator may view (via the platform’s RBAC-aware git list_repos action) are returned.

`POST /api/estate/estates/{estate_id}/spec-drill`

Field	In	Type	Default	Required	Description
`estate_id`	path	string	none	Yes	Estate the drill run is attached to.

Submit-and-return: seals a fresh spec, has a separate agent migrate a throwaway clone, then grades the Prover’s blind diff against the sealed spec end to end. The response returns immediately with run_id, estate_id, top-level status: "running", and data; the graded run-view is persisted into the run summary when the drill finishes. For a Databricks drill whose teardown keeps its lease, the terminal run summary also includes drill_lease_kept with the operator’s DROP SCHEMA instruction. Databricks provisioning runs roughly 140 warehouse statements (70 per catalog) plus the lease; teardown runs about six statements. Follow live over /api/ws/estate/live?run_id=<run_id> or poll GET /api/estate/runs/{run_id}.

Status	Meaning
`400`	Estate source is not admitted. PostgreSQL is supported; Databricks requires `estate_char.self_drill.databricks_enabled` to be `true` and `estate_char.self_drill.databricks_base_catalog`, `estate_char.self_drill.databricks_work_catalog`, and `estate_char.self_drill.databricks_connection_id` to be set. When Databricks is enabled but one or more settings are unset, the response names each missing setting.
`404`	Unknown or archived estate.
`409`	A spec drill is already running for this estate.

`POST /api/estate/migration-envelope/grade`

Field	In	Type	Default	Required	Description
`source_snapshot_id`	body	string	none	Yes	Source characterization snapshot id. Minimum length `1`, maximum `255`.
`target_snapshot_id`	body	string	none	Yes	Target characterization snapshot id. Minimum length `1`, maximum `255`.
`source_engine`	body	string	none	Yes	Source estate engine: `postgres`, `sqlite`, `duckdb`, `snowflake`, `databricks`, or `clickhouse`.
`target_engine`	body	string	none	Yes	Target estate engine (same vocabulary as `source_engine`).
`spec_name`	body	string	`"migration plan — platform move only"`	No	Operator-facing spec name. Minimum length `1`, maximum `255`.
`provenance_note`	body	string	`"migration plan — platform move only"`	No	Provenance note stored on the sealed envelope. Maximum length `2048`.
`diff_hash`	body	string or null	`null`	No	Persisted mediated-diff id to grade. Omit to use the latest forward diff for the pair. When set and a conformance run already exists for this diff, the existing run is returned instead of minting a duplicate.
`estate_id`	body	string or null	`null`	No	Optional named-estate id for theater routing.

Submit-and-return: seals an empty, platform-clause-only spec (“move source_engine → target_engine, change nothing”) and grades the pair’s persisted comparison against it. The response returns immediately with run_id, status, sealed_spec (spec_hash, sealed_at, spec_name, source_engine, target_engine, n_items), and data. Follow live over /api/ws/estate/live?run_id=<run_id> or poll GET /api/estate/runs/{run_id}. Idempotent when diff_hash is set: legacy callers that omit transport identity reuse any existing materialized envelope run for the named comparison and receive its run_id with status: "finished" and data.reused: true. Identity-aware callers reuse only an existing viable run with the same snapshot pair, engines, authored envelope fields, estate scope, and bot-plus-authenticated-human identity; a different owner or binding claims a separate run. No new grading task is spawned for a reused run.

Status	Meaning
`400`	Validation failure.
`404`	Either snapshot, the named `diff_hash`, or the named `estate_id` is unknown or not visible to the caller. Unknown and hidden subjects answer alike. Grading errors (a pair with no persisted/computable diff) surface on the run row’s terminal status, not the submit response.

`POST /api/estate/spec-conformance/compile`

Field	In	Type	Default	Required	Description
`text`	body	string	none	Yes	Pasted prose to compile (migration doc, PRD, ticket, or a few sentences). Minimum length `1`, maximum `32768`.
`component_pair`	body	string or null	`null`	No	Optional comparison context (for example `src_snap->tgt_snap` or a “source → target” label) to help resolve loci and engines. Maximum length `255`.
`source_snapshot_id`	body	string or null	`null`	No	Comparison source snapshot id. When set (with `target_snapshot_id`), the compiler is grounded in each side’s real schema/object/column inventory so loci resolve against objects that exist. Best-effort — a missing, unloadable, or caller-invisible snapshot is ignored and the compile runs ungrounded for that side. Maximum length `255`.
`target_snapshot_id`	body	string or null	`null`	No	Comparison target snapshot id. Same grounding behavior as `source_snapshot_id`. Maximum length `255`.

Compiles free prose into structured, editable spec items by driving a nested claude CLI subprocess (not the resolved default LLM via litellm.acompletion) over the closed change-kind vocabulary (add_column, drop_column, rename_column, type_change, transform_values, add_table, drop_table, add_derived_mart, modify_etl_derivation, drop_constraint). Out-of-vocabulary kinds are dropped and reported in notes, never smuggled into the editor. The production spec-linter runs over the result. Nothing is sealed or graded — the items feed the unchanged seal+grade flow after human correction. Successful responses include items (same shape as the manual spec editor: spec_id, locus, change_kind, change_expectation, description, expected_effect, propagates_to, new_locus, expected_type, and, when declared, expected_type_family, expected_scale, and type_license) and notes (advisory findings with item_index, kind, and message). change_expectation is must_differ when the target is supposed to change at the locus, or must_match when it is supposed to retain the locus unchanged; the structural tier refuses to score an item that omits it rather than guessing. expected_type_family accepts numeric, text, date, timestamp, temporal, boolean, or binary; expected_scale is a non-negative integer scale for numeric declarations. A type declaration’s type_license is "ticket" when the ticket states or entails the type, or "inferred" when the author selected it by convention. This tag controls mismatch severity: ticket-licensed mismatches produce a repair directive, while author-inferred mismatches produce an informational note. Each note kind is one of ambiguity (a lint finding — a malformed item that would be unadjudicable), assumption (a choice the compiler made from under-specified prose), or unmapped_text (prose the compiler could not turn into a structured change). item_index is null for whole-document notes. On compile failure the response is a clean error with a distinct error_type and a short human error message — never a partial spec, never raw provider or agent text:

Status	`error_type`	Meaning
`400`	`compiler_unreadable`	The model reply could not be parsed into spec items.
`502`	`compiler_error`	The compiler agent failed (timeout, subprocess error, or other agent fault).
`503`	`compiler_unauthenticated`	The compiler agent is not authenticated — an administrator must connect its credentials.
`422`	—	Malformed request (for example empty or whitespace-only `text`).

Failure bodies have the shape { "success": false, "error": "<human message>", "error_type": "<type>" } (omitted for 422).

`POST /api/estate/spec-conformance/grade`

Author, seal, and grade a change-item spec against the source and target snapshots. The endpoint returns immediately with a run_id and status: "running"; poll GET /api/estate/runs/{run_id} or follow /api/ws/estate/live?run_id=<run_id> for the finished run view. The grade reads its snapshot bindings as the authenticated human caller, not as a bot identity. A personal connection therefore works when that caller owns and can read it; the request does not substitute a bot identity for the authenticated owner.

Field	In	Type	Default	Required	Description
`source_snapshot_id`	body	string	none	Yes	Source characterization snapshot id.
`target_snapshot_id`	body	string	none	Yes	Target characterization snapshot id.
`spec_name`	body	string	none	Yes	Operator-facing name for the sealed spec.
`engine`	body	string	none	Yes	Source engine: `postgres`, `sqlite`, `duckdb`, `snowflake`, `databricks`, or `clickhouse`.
`items`	body	object[]	`[]`	No	Authored change items. Each item uses the `spec_id`, `locus`, `change_kind`, `change_expectation`, `description`, `expected_effect`, `propagates_to`, `new_locus`, and `expected_type` fields; it may also declare `expected_type_family`, `expected_scale`, and `type_license`. `change_expectation` is `must_differ` for a change specification or `must_match` for a lift-and-shift or landing hop.
`source_ref`	body	string or null	`null`	No	Optional source reference; defaults to `source_snapshot_id`.
`clone_ref`	body	string or null	`null`	No	Optional target/clone reference; defaults to `target_snapshot_id`.
`target_engine`	body	string or null	`null`	No	Target engine; defaults to `engine`.
`diff_hash`	body	string or null	`null`	No	Persisted mediated-diff id. Omit to resolve the comparison from the snapshot pair.
`estate_id`	body	string or null	`null`	No	Optional named-estate id for theater routing.
`item_verdicts`	body	object[] or null	`null`	No	Optional externally graded value-obligation outcomes. Supplying them adds the verdict overlay to the run view and reconciles unlicensed failures into the findings ledger; omitting them preserves the pre-verdict run shape.
`verdict_coverage`	body	object or null	`null`	No	Coverage counters from the grading engine, passed through unchanged in the run view. Closure is qualified by the loci carrying determinate (`pass` or `fail`) item verdicts; `unverified` and omitted items are not treated as re-verified.

Each item_verdicts entry contains item_id, locus, verdict (pass, fail, or unverified), licensed, obligation_ids, and obligations. Each nested obligation contains obligation_id, the same three-way verdict, licensed, title, optional kind, and an optional election record. The structural attribution still determines where a result appears; the value-obligation verdict determines its status. An obligation marked fail with licensed: true does not become a finding, and unverified items are not treated as successful re-verification. Successful responses include run_id, status, sealed_spec, and data. Graded comparison results identify the comparison engine in comparison_engine_version; it is the recorded version for the comparison, or null when the comparison predates engine recording. When an item declares expected_type_family or expected_scale, grading compares the target column’s type family (and numeric scale when declared) rather than its backend-specific type spelling. Ticket-licensed mismatches fail the structural item and produce a repair directive; author-inferred mismatches remain informational notes. Items without these fields retain existence-only grading. The completed run view can include obligation_verdicts with source, coverage, and normalized items, plus the type_family block when the family tier graded one or more declarations; matched spec rows can also expose verdict, verdict_licensed, verdict_obligation_ids, and verdict_obligations. The verdict also reports items_matched_in_scope, the requested changes the oracle matched by place and shape, and retains confirmed_changes as a deprecated count that also includes clauses confirmed by checks. After obligation verdicts are applied, items_passing counts confirmed rows with a pass verdict, including confirmed removals and items whose only failing check is an accepted difference. It remains null until checks are applied and on a structural-only grade. When the summary has an item list, conformance.items_unconfirmed counts requested changes whose item verdict is fail or unverified; a shape=card run row retains this count under conformance when it drops the items list.

`POST /api/estate/spec-conformance/grade-compiled`

title (body, string or null, maximum length 200) is the grade’s business title — for example Foundry aviation: raw → ontology rebuild (spec-mediated) — stamped on the run’s provenance.title and shown as the comparison’s headline in the dashboard, above its technical source → target label. Omitting it, or sending a blank one, is deprecated: the request is still admitted, and the response carries Deprecation: true and a Warning header saying the title will be required. The agent tools prove, compare and grade already refuse an untitled call. Grade a registered, seal-verified compiled artifact against a live estate and persist the result. The endpoint runs the artifact’s obligations against the two registered connections and its structural items against the mediated diff for the source and target snapshots. Unlike POST /api/estate/verifications with compiled_spec_hash, this endpoint persists one spec_conformance run and returns the durable #N identifiers of findings it minted. Register an external artifact first with POST /api/estate/spec-conformance/compiled; the artifact is never re-compiled here. This is a synchronous, warehouse-bound operation: one comparison runs per obligation, with a query on each side for keyed obligations and one count for an invariant, followed by grain probes as needed and structural grading. A real artifact may take minutes, and the work is dispatched off the API event loop. The route requires ratify_source_contract and records the authenticated caller as the run’s operator; it does not accept an operator identity in the request body. Before the service can inspect or reuse a prior result, both submitted connections must be registered and authorized for the exact bot-and-human transport identity. A revoked caller receives the same disclosure-safe 400 as an unknown or unregistered connection, without the prior run being named. When diff_hash names a comparison from a retired diff engine, structural grading recomputes it under the current engine on the same stored snapshots and checks the snapshots’ measurement-library versions. The run provenance identifies both comparisons under comparison_recomputed_under_engine; a snapshot that another measurement library took, or a comparison the recompute cannot reproduce, is refused with 409. The Prover overview describes the recompute and refusal conditions. A type_mapping that can carry fractional values into a scale-zero numeric type is conditional: only a source column measured with zero fractional values is licensed. For each such candidate column, grading reads the live source (not the comparison’s source snapshot), with one full counting scan per source relation containing candidates. A failed or unavailable measurement does not license the mapping. When measured, run provenance includes whole_numbers_read with read_at, columns, compared_source_snapshot_id, and basis so the live-source reading is distinguishable from the comparison snapshot. For how derived_checked affects structural findings, see the [Prover mapping guide] (/docs/Genesis-Prover/Overview#declared-target-mappings-and-data-vault-shapes).

Field	In	Type	Default	Required	Description
`compiled_spec_hash`	body	string or null	`null`	Conditional	Content hash of one sealed compiled artifact to grade. Supply this or `compiled_spec_hashes`, never both.
`compiled_spec_hashes`	body	string[]	`[]`	Conditional	Two or more sealed compiled-spec hashes to grade as one result. Supply this or `compiled_spec_hash`, never both.
`source_connection_id`	body	string	none	Yes	Registered source connection injected into every obligation; it must be authorized for the submitting bot-and-human identity.
`target_connection_id`	body	string	none	Yes	Registered target connection injected into every obligation; it must be authorized for the submitting bot-and-human identity.
`source_snapshot_id`	body	string or null	`null`	Conditional	Baseline (delivered) snapshot the structural tier is graded from; required when `tiers` includes `structural`.
`target_snapshot_id`	body	string or null	`null`	Conditional	Build snapshot the structural tier is graded against; required when `tiers` includes `structural`.
`title`	body	string or null	`null`	No	Business title shown as the comparison headline and stamped at creation in `provenance.title`. Maximum length `200`; surrounding whitespace is stripped and blank becomes `null`. Omitted or blank remains admitted during the deprecation period and adds `Deprecation: true` and `Warning` response headers.
`source_db_type`	body	string or null	`null`	No	Optional source engine; resolved from the registered connection when omitted.
`target_db_type`	body	string or null	`null`	No	Optional target engine; resolved from the registered connection when omitted.
`source_catalog`	body	string or null	`null`	No	Catalog (database) for the baseline side, bound as the session catalog for its reads. Omit to use the database the source snapshot characterized when the engine binds a catalog (Databricks, Snowflake); otherwise the source connection’s default. On an engine that does not bind a session catalog, an explicit value is accepted only when it matches the database recorded by `source_snapshot_id`; that names the connection itself and binds no catalog. Any other explicit value, or an explicit value when the snapshot records no database, returns `400` before grading.
`target_catalog`	body	string or null	`null`	No	Catalog (database) for the graded side. Omit to use the database the target snapshot characterized when the engine binds a catalog (Databricks, Snowflake); otherwise the target connection’s default. On an engine that does not bind a session catalog, an explicit value is accepted only when it matches the database recorded by `target_snapshot_id`; that names the connection itself and binds no catalog. Any other explicit value, or an explicit value when the snapshot records no database, returns `400` before grading. The catalog is part of the request identity as resolved, so omitting it and naming that same database are one request. When supplied, it also enables attribution of a deliverable written as `target_catalog.schema.table` (or `target_catalog.schema.table.column`) to the matching structural item; the catalog must match the graded side’s leading qualifier case-insensitively.
`invariant_side`	body	`source` or `target`	`source`	No	Fallback estate for single-relation `invariant` obligations that declare no `invariant_side` of their own; one that does is graded on the side it declares. Keyed obligations always compare source and target.
`tiers`	body	string[]	`["derivational", "structural"]`	No	Grade `derivational` obligations against the two live connections, `structural` items against the snapshot pair, or both. Use `["derivational"]` to grade obligations without a comparison or snapshot pair. When `check_ids` is supplied and `tiers` is omitted, defaults to `["derivational"]`.
`check_ids`	body	string[] or null	`null`	No	Grade only the named check (obligation) ids as a partial grade. Supply 1–500 non-empty ids, each 1–255 characters; omit or pass `null` to grade every check. Unknown ids return `400` and name the valid ids. A partial grade runs on the live connections only and reads no comparison: it cannot include the `structural` tier or `diff_hash` (either is refused with `400`).
`diff_hash`	body	string or null	`null`	No	Persisted mediated diff for the structural tier. Omit to use the latest forward diff for the pair, or compute one when none exists. Only the structural tier reads it, so supplying it while `tiers` omits `structural` is refused rather than ignored — `400` on this route, mapped from the admission rule the service owns.
`estate_id`	body	string or null	`null`	No	Optional named estate for run provenance and theater routing.
`round_n`	body	integer	`0`	No	Grading round and part of the idempotency identity; must be between `0` and `500`, inclusive.
`estate_coordinate`	body	string or null	`null`	No	Caller-supplied coordinate for the estate measured at grade time. It is part of the idempotency identity but is not sent to a query: the same coordinate reuses the round’s run, while a different coordinate grades the round again. Omit it to preserve the pre-existing round identity. Maximum length `255`.
`run_label`	body	string or null	`null`	No	Human label recorded in run provenance; not part of the idempotency identity.
`task_id`	body	string or null	`null`	No	Caller task id recorded in run provenance; not part of the idempotency identity.

When compiled_spec_hashes is supplied, the service grades the named specs as one set for a table specified in parts. The set must contain at least two distinct hashes; a one-member set is rejected, and the schema rejects an empty list or a request that supplies both forms. The set has its own spec_hash, derived from its member hashes in any order, while spec_hashes lists the sorted members in the response, submit handle, and reused result. Each member is loaded and seal-verified; the set itself has no seal. Set attribution is ownership-based: a column belongs to every member whose structural item covers it or whose declared target_model mapping carries it. A column covered by more than one member is listed in spec_set.overlaps. A column covered by no member is the only column-level drift in a set grade; its reason says not covered by any spec in this set and it remains for adjudication rather than receiving the single-spec implementer_error lean. Object-level differences retain their ordinary grading behavior. Every member’s obligations run, and each obligation is attributed only to its own member’s items. An obligation’s member is the spec that sealed it, unless it names an owning_relation — the one table it is about, which its SQL reads — that exactly one member owns (a scope entry expecting same, changed or new of it, a structural item on it, or a declared mapping into it). Then it is that member’s. A check spanning two tables, sealed by the spec that holds the other table only as context, uses this to belong to the spec that owns it; with no owner or several, it stays with the spec that sealed it. If members claim different values for the same column’s change kind, new locus, expected type family or scale, or change expectation, the result records a spec_ambiguity finding against the conflicting specs and leaves neither claim graded. Conflicting scope expectations leave the object out of the merged scope. These conflicts appear in spec_set.conflicts; SQL obligations are not compared for conflicts. The run view also includes spec_set.item_owners, declared_columns, and the member hashes used for each overlap or conflict. The warehouse work is the sum of running each member’s obligations. The request identity includes the sealed spec, both connections, both snapshots, resolved engines, catalogs as resolved, invariant_side, diff_hash, estate_id, estate_coordinate, round_n, and tiers. On Databricks or Snowflake, an omitted catalog resolves from its side’s named snapshot database, so omitting it and naming that same database are one request; naming a different catalog is a different request. The snapshot pair and diff_hash are hashed as omitted unless tiers includes structural, because only that tier reads them: the same derivational-only grade submitted once bare and once carrying a comparison it never uses is one request, not two. That is why supplying a diff_hash without the structural tier is refused rather than dropped — a grade that ignored it would name no comparison, which the adjudicator refuses permanently, and a re-submission adding the diff_hash alone would hash to the same identity and return that same run as reused. The rule is decided ONCE, at the service admission boundary, for every caller; this route’s 400 is a mapping of that verdict, and a caller invoking the service directly receives the raised error with no status code. The refusal text is the same at both. Adding the tier does mint a new run, because tiers is unconditionally part of the identity. When supplied, estate_coordinate likewise distinguishes a repeat measured against a changed estate from the earlier run. run_label and task_id are excluded, but the exact bot-and-human transport identity is retained in the request key. An identical authorized request from that same identity resolves to the same run; a different credential scope gets a distinct request identity and cannot receive the earlier caller’s run. A finished run is returned with reused: true; a run still in progress is not returned as a verdict and instead produces 409 with the run id to follow. Errored runs do not satisfy a repeat, so the next identical request can grade the round again. The claim is atomic within one backend process; stale abandoned runs are released by the periodic stale-run reconcile. For catalog-qualified deliverables, target_catalog is used on both sides of value obligation attribution: a target reference such as target_catalog.schema.table can match the structural locus for that object, and a column-grain reference can include the column as the fourth segment. The completed run normalizes a matching locus to schema.table or schema.table.column; a different catalog is not attributed to the graded item. Catalog binding is decided once during grade admission. For an engine that cannot bind a session catalog, naming the database recorded by that side’s snapshot identifies the connection and proceeds without a catalog; naming any other database, or naming one when the snapshot records none, returns 400 with no obligations graded. Omit the field when the connection’s own database should be used. This same rule applies to the catalog fields on POST /api/estate/verifications when compiled_spec_hash is supplied. The completed grade summary makes measurement coverage explicit. obligation_verdicts contains items for obligations claimed by structural items and unattributed for every obligation that claims none. Failed or unverified obligations in either holder are included in the persisted finding population sent to the Adjudicator; reading items alone can omit failures. Each obligation verdict also carries requirement_source, either the declared {kind, citation} provenance or null when the seal has no readable declaration. This is display context only and does not affect grading. It also contains unverified, a list of every obligation that did not reach PASS or FAIL, with its obligation_id, title, relation, and error. relation is the declared locus for an invariant and null for comparison obligations, so an errored invariant still names the relation it governs. An errored entry can also include errored_sql: source_sql_sha256 and source_sql_chars, and/or target_sql_sha256 and target_sql_chars for the statements declared by the seal. These pointers identify sealed SQL without including its text in the run record; use the run’s sealed-spec hash to read the artifact. If source_read records a landed-copy substitution, errored_sql still hashes the sealed statement, while source_read.statement describes the rewrite. Each entry in data.obligations also carries the same relation and its own error when the instrument failed. When no declared obligation reached a verdict, the conformance block sets no_drift, drift_count, and verified to null and adds a drift_basis explaining that no measurement was made. Partial grades measure the decided obligations and use drift_basis to name the errored remainder. The coverage block also reports nothing_to_check for obligations whose checks measured an empty population and items_nothing_to_check for structural items whose attached obligations all had that outcome. These counts are separate from decided, errored, and unmeasured obligations: an empty check is neither a pass nor a check that could not run. For the obligation_verdicts.clauses_not_checked interpretation against the seal’s clause_gate, including the case where a commissioned document has no clauses, see how the Prover grade reports unchecked clauses. The run envelope also exposes the same obligation totals as summary.obligation_counts: obligation_count, passed, failed, errored, unmeasured, and nothing_to_check, plus failing_obligation_ids (all failing ids, not capped at ten), obligations_at, and detail_path (the run-detail path). The count is absent when the run recorded no obligation coverage. summary.items remains the structural tier’s spec-item list and can be empty on a derivational-only grade; use summary.obligation_counts to tell what obligations were measured. The obligations_at paths point to records under summary.obligation_verdicts.items[].obligations and summary.obligation_verdicts.unattributed. For a multi-tier grade, wall_seconds includes the earlier derivational work as well as the structural tier, so it reports the run’s elapsed time rather than only the final tier’s duration. When structural items failed, summary.obligation_counts.failed_items groups the failing spec-item count by the checks that failed them. It has count and by_check; each entry names an obligation_id and the number of items it failed. An item failed by more than one check is counted under each, so per-check counts can sum to more than count. The grouped counts also appear in the grade headline. When more than six checks failed items, the headline names the five largest groups and points to verdict.failed_items for the remaining groups. An absent failed_items means the summary did not record this grouping. The structural conformance block’s derived_checked, derived_unchecked, and derived_unchecked_reasons are null when the comparison reported no derived target whose whole-table digest it skipped; derived_basis explains that no split applied. When there is a split, the lists and reason map are populated and derived_basis is null. A run view rebuilt from a stored summary that recorded no classification also returns null for these fields, but derived_basis says the split was not recorded. For a committed fork, summary.readings_not_taken lists the rival obligation ids whose FAILED readings were not taken by the build. The rival is marked licensed and counted with the passes only when exactly one committed lean identifies the fork’s taken reading and every fork member is decided; the election record names reading_taken, taken_by, reading_not_taken, taken_verdict, and the committed_lean_held basis. When the leaned reading itself fails (taken_verdict: "fail"), it stays the fork’s one failure at its own row count, and the failing rivals are still reported as readings not taken rather than as failures, since a rival differs from the taken reading by design on every build. An uncommitted fork, an undecided member, conflicting committed leans, or a failed leaned reading beside a passing rival (the build took the rival) leaves the readings graded as-is. For a by-reference grade, spec_hash is the submitted compiled_spec_hash and projected_spec_hash is the separate, unregistered seal of the structural projection created for that run. Direct-envelope and derivational-only grades report projected_spec_hash: null; use spec_hash_basis and projected_spec_hash_basis to interpret those values. Runs created before these fields were introduced are not back-filled. For the series state machine, open-demotion behavior, attribution rules, and unmeasured cases, see How agents drive the Prover. This endpoint persists the resulting obligation_pass_to_fail_ids, obligation_regressions, obligation_regressions_basis, and obligation_regressions_unmeasured fields in data.summary; a tier that cannot be measured is omitted from certification rather than reported as a clean empty list. The findings tier carries its own findings_regressions_basis because this product path does not have per-round finding verdict vectors for the same comparison. The same summary carries structural_observed_at, structural_observed_through, obligations_read_at, obligations_read_through, and vintage_basis. The first pair is the structural snapshot interval; the second is the sequential live-read interval. Fields are null when their tier did not contribute a reading. The closed vintage_basis values are single_tier, same_vintage, blended, and vintage_unknown; see how a run reports observation vintage for their interpretation and the zero-obligation behavior. A blended grade also carries vintage_between_reads, {status, source, target}, whose status is observed_changed when write history shows a newer data write, confirmed_unchanged when every table’s history confirms no write, or not_confirmable when an estate has no history Prover reads or its history could not be reread. For what not_confirmable does and does not establish, and when the caveat says nothing was seen to change, see how a run reports observation vintage. The grade’s vintage_caveat names changed tables or gives the reason confirmation was unavailable, and is null when the grade is confirmed unchanged. vintage_between_reads is null for every other basis. GET /api/estate/spec-conformance/run-for-diff/{diff_hash} returns the grade’s vintage_caveat and vintage_between_reads beside data. Successful responses include:

Field	Type	Description
`run_id`	string	Persisted `spec_conformance` run id.
`reused`	boolean	`true` when an identical finished run is returned instead of re-grading.
`reused_basis`	string or null	Why a reused run matched: the explanation names whether the request identity included the `estate_coordinate` measured by this request. `null` when `reused` is `false`, because the grade ran rather than being reused.
`reused_from_grade_version`	string or null	On a reused answer, the grading-code version recorded by the run whose verdict was returned. A repeat after the grader changes is graded again because that version is part of the request identity. `null` when `reused` is `false`, or when the reused run recorded no version.
`approval_carried`	object or null	Set when a retired-engine comparison was recomputed and its recorded approval still applies: the approved review population is unchanged, the spec hashes match when both are available, and no exception was granted on the retired comparison. Carries `decision`, `decided_by`, `decided_at`, `approved_run_id`, `carried_to_run_id`, `population_hash`, and a sentence beginning `approval carried to run <id>`. `null` when no approval was carried.
`approval_superseded`	object or null	Set when this grade replaced the population bound to a recorded approval without carrying it. Carries `decision`, `decided_by`, `decided_at`, `approved_run_id`, `superseded_by_run_id`, and a sentence beginning `approval superseded by run <id>`; on a retired-engine recompute it also includes `changed` with the comparison, reading counts, review populations, exception count, and `spec` (`approved` and `graded` spec hashes when available). When both hashes are available, a different spec hash supersedes the approval even when the review population is unchanged. The approval no longer stands and the comparison awaits review again. `null` when no approval was superseded.
`status`	string or null	Run status, normally `finished` for a completed response.
`spec_hash`	string	The sealed compiled artifact that was graded, or the set identity derived from member hashes for a set grade.
`spec_hashes`	string[]	Sorted member hashes for a set grade; `[]` for a single-spec grade.
`request_key`	string	The 64-character idempotency identity for this request.
`findings`	array	All durable findings from the obligation and type-family ledgers. Each entry includes `finding_id` (the `#N`, nullable for legacy rows), `finding_key`, `object_name`, `column`, `status`, `streak`, `prior_state`, `spec_item_id`, `title`, `kind`, `finding_class`, and failing `obligation_ids` when applicable.
`data.summary`	object	Persisted graded-run summary, including obligation verdict coverage, obligation regression data and basis fields when applicable, and both the obligation and type-family finding ledgers. The conformance verdict also carries `requested_changes` and `confirmed_changes`; exact item-count meanings and the added `items_matched_in_scope` / `items_passing` fields are documented in the grade response. A structural set grade also adds `spec_set_reading`, the review-card wording for the set. For a structural grade, `conformance.drift_count` remains the measured drift count; `conformance.published_drift` is the count published as unexplained drift, and `conformance.withheld_drift` is the count withheld because the target shape was undeclared, or `null` when nothing was withheld. The conformance block also carries `conformance.withheld_indeterminate`; see withheld readings in the Prover review. The summary also carries `scope_surplus` and `scope_unclaimed` for target objects no scope entry names, and `scope_unclaimed_absent` for unnamed source objects absent from the target under any declared scope. `scope_unaccounted_columns` lists new target `object.column` values awaiting a person’s decision; `scope_unaccounted_limits` explains when the source-column reading for a built table is limited; `scope_unaccounted_readings` lists the exact unlicensed column readings withdrawn from drift while that decision waits. See scope verdicts for their grade and review semantics.
`data.summary.schema_map_unpaired`	object or null	Present when a carried scope entry is unpaired because no `schema_map` addresses its source schema. Lists `source_schemas`, `target_schemas`, `source_objects`, and `target_objects`; target objects it accounts for are excluded from `scope_surplus`. In the same summary, scope verdicts carry `cause` (`scope_entry_unresolved`, `schema_map_undeclared`, or `null`). See scope verdicts for the grouped grade and review behavior.
`data.obligations`	array	Per-obligation verification summaries, including `obligation_id`, `kind`, `title`, `verdict`, localized evidence, and errors when applicable. `spec_item_ids` lists the sealed structural item ids declared for the check, de-duplicated in declaration order, or `[]` when none were declared. Errored rows may include `cause` (`spec_as_written` or `instrument`), and every row carries its `degeneracy` reading with status, findings, and basis. A keyed obligation can also include `missing_target_columns` when its error is measured as a missing target column, and `missing_declared_columns` when those columns are declared by `target_model`; see the verification response contract.
`data.probe_records`	array	Grain-probe quarantine records from the obligation fan-out pass.

An unclaimed failed obligation check normally creates a durable finding at its declared relation, even when no structural item claims it. If it has recorded table reads and every read is qualified to a database other than the graded catalog, it remains a review blocker but does not mint a finding; that is an authoring fault, not a target-build defect. For a compiled grade, data.summary.spec_seal_state is full or partial. A partial grade also carries data.summary.open_clause_count and data.summary.open_clauses; each entry has clause, text, reason, remedy (actor, kind, statement, options, measured_candidate), evidence (measurements with sql and result), and depends_on. data.summary.verdict.open_clauses is the count. When the grade would otherwise be verified or verified_with_indeterminate, the partial seal sets its status to verified_with_indeterminate and verified to false. Its headline uses Partially specified · N clauses open (singular clause at 1), not Verified wording. A grade submitted with check_ids has data.summary.spec_seal_state: "subset", plus data.summary.graded_check_ids and data.summary.spec_check_count. Its headline identifies the selection as Partial grade · N of M checks; passing checks remain amber at best, never Verified. It does not replace the comparison’s or spec’s latest grade and cannot be approved. The Prover guide describes how to use the result. When a stored grade has no spec_seal_state, the reader uses its provenance.grade_engine_version when that value is dotted unsigned ASCII digits: a version older than the partial-seal reader is read as full, regardless of grade time. For a missing or unreadable version, a known grade time before 2026-10-14T05:00:00+00:00 is read as full; without a grade time, a missing version is full and an unreadable version is unknown. Other missing-state grades are unknown, not Verified. For a set grade that includes the structural tier, data.summary.spec_set_reading is the card-ready reading of the set. It contains headline, members, overlaps, conflicts, not_covered_by_any_spec, and not_covered_count. members identifies each spec_hash as Spec 1, Spec 2, and so on, and includes that member’s seal when the run provenance has one. Each overlap gives its locus, the covering spec_hashes, and a reading such as <locus> is covered by 2 specs. Each conflict includes both claims in first and second, the locus and field, and a reading that says neither claim is graded until the specs agree. Each uncovered difference gives its locus, comparison, and a neutral reading that it is not covered by any spec in the set; not_covered_count is the exact count when the stored summary provides it. This block is absent for a single-spec grade and for a derivational-only set grade.

Status	Meaning
`400`	The artifact is unsealed or tampered, a connection is unregistered, the artifact declares nothing to grade, a seal cites a clarification that was overturned by a person or withdrawn by its recording agent, or request binding values are invalid.
`404`	The compiled spec is unknown, or the snapshot pair has no gradeable comparison.
`409`	An identical request is already grading this round; follow the run id in the error.

For the non-persisting, submit-and-return alternative, see POST /api/estate/verifications with compiled_spec_hash.

`POST /api/estate/adjudication/runs/{run_id}/adjudicate`

Send one readable Prover subject to the independent Adjudicator for attribution. The path accepts a spec_conformance, spec_drill, or system_diff run, and a prove run handle resolves to the grade when one exists or to its comparison otherwise. A no-spec proof therefore reaches judgment through its comparison’s own elements rather than through an empty grading envelope. The server assembles the subject from persisted findings and comparison materials; callers do not supply or rewrite the findings. The route requires ratify_source_contract and records the authenticated caller as the invoker. The response returns immediately for a fresh proceeding with status: "running"; poll the returned adjudication_id using get_adjudication_run for the verdicts. A repeat with the same (run_id, round_n) normally returns the existing proceeding with reused: true and its recorded verdicts, without commissioning another bot turn. This deduplication is per backend process, not an exactly-once guarantee. A fresh proceeding needs an LLM provider — the seat is a bot turn — and without one the route answers 503 with details: "llm_provider_not_configured", naming the cause, the remedy (Settings > AI Providers) and what still works; a repeat over a round that already has a proceeding is a read and answers 200 regardless. A provider that is configured but does not answer a readiness check (an expired login, an unreachable endpoint, a spent quota) is refused the same way with details: "llm_provider_unreachable", plus cause (login_expired, unreachable, rate_limited or provider_error) and operator_detail, the provider’s own error for an operator. Nothing is started. If an earlier stalled Adjudicator turn could not be stopped, a new proceeding over the same comparison is refused with 400 while that turn is still in the runtime. Each replacement request and reconcile sweep asks the runtime to stop it again; a replacement can open once a stop request is accepted or the turn leaves the runtime. For a grading subject, adjudication reads the run’s persisted durable finding population, including open rows from both the obligation and type_family ledgers. For a comparison subject, it reads the comparison’s classified elements, retaining unlicensed, indeterminate, and errored members and counting match and licensed elements in its composition. When a subject has no findings, no proceeding is opened and the response explains why in no_findings_basis; a no_findings status alone is not evidence that the run was clean. clean_run means the recorded Human Review blocker population was complete and empty, review_blockers_only means blockers remain but none is a durable finding for this seat, blockers_unmeasured means the blocker count could not be read or the population was incomplete without finding a blocker, and clean_comparison means the comparison census contains only matches and licensed differences. For the blocker worklist and its measurements, use GET /api/estate/comparisons/{diff_hash}/review/population.

Field	In	Type	Default	Required	Description
`run_id`	path	string	none	Yes	Persisted `spec_conformance`, `spec_drill`, `system_diff`, or `prove` run handle whose readable subject is sent to the Adjudicator. A `prove` handle resolves to its grade when present, otherwise its comparison.
`round_n`	body	integer	`0`	No	If omitted, joins a proceeding already running for this run under any round; if none is running, uses round `0`. Name a round to open or read that specific `(run_id, round_n)` proceeding, independently of other running rounds. Must be between `0` and `500`, inclusive.
`mode`	body	`silent` or `active` or null	`null`	No	Optional override of the configured adjudicator mode. Omit to use the operator-configured default. `silent` records verdicts only; in `active`, `target_defect` and pocket `candidate_improvement` verdicts are sent back immediately under the Adjudicator’s name, while `spec_defect`, `platform`, and `instrument_defect` verdicts are staged for human approval. The mode does not filter findings.
`doctrine_addendum`	body	string or null	`null`	No	Doctrine block appended to the pinned Adjudicator constitution, never substituted for it. Use it for proceeding-specific conditions the product doctrine cannot state. Maximum length `20000`; the server records the SHA-256 digest of the rendered bytes.
`doctrine_sha256`	body	string or null	`null`	No	SHA-256 digest that `doctrine_addendum` must produce. A mismatch is refused rather than reconciled. When supplied, it must match `^[0-9a-f]{64}$`; lowercase hexadecimal is required, so uppercase hexadecimal is rejected with `422`.
`verdict_ids`	body	string[] or null	`null`	No	Read back only these verdicts, by `verdict_id`. Narrows the proceeding before the page is cut, so it filters the ruling rather than the page. Maximum `200` ids.
`outcome`	body	string or null	`null`	No	Read back only verdicts carrying this outcome. The value must be one of the recorded outcomes; an unknown one is refused with `400` rather than filtered to nothing.
`verdict_offset`	body	integer	`0`	No	Where the verdict page starts. Advance by the `next_offset` the previous page reported, never by the limit you asked for. Must be `0` or greater.
`verdict_limit`	body	integer or null	`null`	No	How many verdicts the page may carry. A page, not a filter: a verdict past it is absent from the page, not from the proceeding. Between `1` and `500`; omit to read the whole narrowed set.

A verdict may carry the instrument_defect outcome; see False alarm (Prover) for its user-facing label and behavior. Successful responses include:

Field	Type	Description
`success`	boolean	Request success status, inherited from the shared response base. Documented because the endpoint serializes it: a field a caller receives and the reference omits is a contract they cannot discover.
`run_id`	string	The persisted grading run that was adjudicated.
`adjudication_id`	string or null	Proceeding id; `null` when the run persisted no findings.
`progress`	object	Nine-key progress block: `phase`, `phase_basis`, `source_message_count`, `last_activity`, `write_version`, `unavailable_reason`, `streaming`, `last_chunk_at`, and `stream_chunk_count`. It is present on every response, including `no_findings`; counters are `null` when no seat thread was measured, and `streaming` is `null` when this response could not decide stream liveness. Snowflake Cortex completions are included in the stream readings while chunks arrive.
`next_step`	string	Plain-language action for this proceeding status. Re-call this endpoint with the same `run_id` and the returned `round_n` to poll a running proceeding; do not poll `adjudication_id` at the generic run route.
`reused`	boolean	`true` when this `(run_id, round_n)` resolved to an existing proceeding.
`mode`	string	Mode used by the proceeding: `silent` or `active`.
`requested_mode`	string or null	The mode THIS request named, on a `reused` response. Reuse is keyed on `(run_id, round_n)` alone, so a repeat naming a mode the existing proceeding does not have is accepted and NOT applied. `null` when the request named no mode, and on a freshly opened proceeding, which gets the mode it asked for.
`mode_basis`	string or null	Why `mode` is not the mode THIS request named — and that mode decides whether verdicts are staged as a disposition package for approval. Non-null only when something was dropped: a `reused` response whose request named a mode the existing proceeding does not have. `null` whenever nothing was dropped — a freshly opened proceeding, and equally a reused one whose request named no mode or named the mode already on the record.
`status`	string	`running`, `completed`, `failed`, or `no_findings`.
`finished_at`	string or null	When this proceeding reached a terminal status — tz-aware ISO-8601, the same spelling the run envelope uses. `status` and `progress` both say THAT a proceeding is terminal and neither says when; the proceeding record carries the moment, so without this field two reads of one proceeding answer “has it finished” differently. `null` while it is running and on a `no_findings` response, where nothing finished.
`started_at`	string or null	When this proceeding’s record was opened — tz-aware ISO-8601, the same spelling as `finished_at`. Set on a freshly opened proceeding and on every re-read of one, so a caller can say when a seat began as well as when it ended. `null` only on a `no_findings` response, where nothing was opened.
`no_findings_basis`	string or null	Why the subject had no adjudicable findings on a `no_findings` response: `clean_run`, `review_blockers_only`, `blockers_unmeasured`, or `clean_comparison`. `null` for every other status.
`round_n`	integer	Round of the proceeding that answered. When the request omitted `round_n`, this may be a running round other than `0`; use the returned value to poll that proceeding.
`thread_id`	string or null	Visible Adjudicator triage thread, when a proceeding was opened.
`finding_count`	integer	Number of persisted findings sent for adjudication.
`tier0_flagged_count`	integer	Number of findings pre-flagged as likely instrument artifacts.
`declared_target`	object	Build target named by the proceeding’s materials, with `catalog` and optional `dialect`; `{}` when the materials named no target estate.
`composition`	object or null	Five-way comparison census with `match`, `licensed`, `unlicensed`, `indeterminate`, `errored`, and `total` counts. Present for a comparison subject; `null` for a grading-run subject because its population is the durable ledger, not the comparison element census.
`routing_verb_schema_version`	string	Which routing-verb vocabulary the `routing_verb` on each verdict belongs to. A consumer that does not recognise this value must REFUSE those verbs rather than map one to the nearest slot it has. Its ABSENCE identifies a response predating the vocabulary, so key on absent-vs-present rather than on a value being lower.
`verdicts`	array	Recorded verdicts when reusing a completed proceeding; empty while a fresh proceeding is `running`. Each verdict includes the durable `finding_id` (`#N`, nullable for legacy findings), `finding_key`, `object`, `column`, `outcome`, `confidence`, `rationale`, `receipts`, optional `provisional_position`, `license_refs`, `improvement`, `reason`, `departs_from`, `escalated`, `destination`, `destination_label`, `routing_verb`, `charges_a_defect`, and `may_stage_builder_work`. `object` and `column` are projected from the briefed finding resolved by `finding_key`; both are `null` when no briefed finding resolved, and `column` is also `null` for a table-level finding. `license_refs` identifies register entries backing a `stands` verdict; `improvement` carries a candidate-improvement docket entry, including its `pocket` or `blocking` mode; `departs_from` is the earlier ruling on the same finding this verdict overturned (`verdict_id`, `outcome`, `adjudication_id` and the seat’s `why`), or `null` when it overturned none; `destination` is `build`, `spec`, `not_an_issue`, or `null` — null means the verdict is intentionally UNROUTED rather than unclassified: `unprovable` routes nowhere by design (the instrument failed, so charging anyone would be a lie), and an outcome outside the vocabulary is left unrouted rather than defaulted into `not_an_issue`, which is the one destination where nobody would look at it again. `destination_label` is its plain-English name and is null with it; `routing_verb` is the additive vocabulary answering whose problem the ruling says it is, derived from `outcome` and not yet authoritative (`destination` still routes). `charges_a_defect` and `may_stage_builder_work` are the two facts the verb drops, derived from the same `outcome` and carried on every verdict including the ones that carry no verb: the projection onto `routing_verb` is many-to-one, so a consumer COUNTING the verb counts rulings that charge nobody as defects. Read `charges_a_defect` rather than re-deriving it from `outcome`, which restates a mapping this API owns and this field already answers. Which vocabulary a token belongs to is `routing_verb_schema_version` on THIS response — the fuller `routing.verb_vocabulary` block rides the adjudication seat’s materials payload and no HTTP route serves it, so a consumer here cannot read a version from there.
`verdict_page`	object or null	What `verdicts` is a page of, on a reused proceeding: `total` (verdicts in the narrowed set), `returned` (this page) and `next_offset` (`null` when there is no more). Read `total` rather than `finding_count` for the verdict set’s denominator — `finding_count` is the proceeding’s population and a narrowed readback is not a page of it. `null` on a fresh open and on `no_findings`, where no readback happened.
`verdict_selection`	object or null	What this readback asked for: `verdict_ids`, `outcomes`, `offset` and `limit`. Echoed because a caller cannot tell a complete readback from a narrowed one by looking at the rows. `null` wherever `verdict_page` is.

Status	Meaning
`400`	The named run is unreadable, has no subject, its findings cannot be identified, `outcome` names no recorded verdict outcome, the supplied doctrine digest does not match the addendum bytes, the assembled briefing exceeds the thread message limit, or an unstopped stalled turn still holds the comparison. Nothing is started.
`404`	No persisted run carries `run_id`.
`503`	A fresh proceeding was requested, but the Adjudicator seat cannot be commissioned. With no LLM provider configured the response uses `details: "llm_provider_not_configured"`; configure a provider under Settings > AI Providers. With a configured provider that does not answer, it uses `details: "llm_provider_unreachable"` and adds `cause` (`login_expired` — an operator re-authenticates the provider — `unreachable`, `rate_limited` or `provider_error`) and `operator_detail`. Nothing is started. A repeat over a round that already has a proceeding is a read and remains `200`.
`422`	`round_n`, `mode`, `doctrine_addendum`, `doctrine_sha256`, `verdict_ids`, `verdict_offset`, or `verdict_limit` fails request-schema validation. A `verdict_limit` of `0` and a negative `verdict_offset` are refused here rather than clamped.

`POST /api/estate/spec-conformance/author-seat`

Field	In	Type	Default	Required	Description
`ticket_text`	body	string	`""`	No	Requirements under the older field name; send this or `requirements`. If both are non-blank, their text must match. Maximum length `65536` (`2048 * 32`).
`requirements`	body	string	`""`	No	What the business asked for: ticket and requirement-document text. Send this or `ticket_text`; if both are non-blank, their text must match. At least one must be non-blank. Maximum length `65536` (`2048 * 32`).
`context`	body	string or null	`null`	No	Optional operator background, such as how the build ran, what was reloaded, or what an earlier run found. The seat receives it in a separate block; it is not a requirement and cannot support a graded obligation by itself. A `written_by` mechanism is accepted only when the requirements name it. Maximum length `65536` (`2048 * 32`).
`connection_id`	body	string	none	Yes	Connection the seat may inspect and pass to every `register_*` call. Minimum length `1`; maximum length `255`.
`spec_name`	body	string	none	Yes	Name for the authored compiled spec. Minimum length `1`; maximum length `255`.
`mode`	body	string or null	`null`	No	Per-run escalation mode: `human` or `autonomous`. When omitted, uses `estate_char.spec_author.escalation_mode`. `human` reports unsettled questions for a person; `autonomous` forks and continues without waiting for one.
`interpretation_policy`	body	string or null	`null`	No	Per-run interpretation policy: `lean`, the only policy, which commits to the most likely reading, forks with a lean and flags the assumption. `open` is retired and refused with `422`, naming the retirement; a spec sealed under `open` is repaired under `lean`. Recorded on the run and on its seal. Any other value is refused with `422`.
`authoring_tooling`	body	string or null	`null`	No	Per-run authoring tooling: `registrar`, or `classic` only to repair a spec sealed with it. When omitted, uses `estate_char.spec_author.authoring_tooling` (always `registrar`). For submit-time inheritance from a named repair prior and the effective value returned in the handle, see the `author_spec` contract. `classic` is retired for new specs: it requires `repair_of`, and without it the submit is refused with `422` before anything starts. A classic round that loads no prior spec is also refused at finalization (`classic_tooling_retired`). `registrar` adds the Registrar’s tools (`spec_author_registrar_tools`) alongside the seat’s default groups on the run’s thread. A fresh round can seal from any phase once every phase check passes; registrations close completed phases, and the seal records a checkpoint for each phase. A repair round skips the phases. The Registrar group remains through the seal’s closing turn and is withdrawn when the run becomes terminal. See the Registrar tool reference for phase details and lifecycle. Recorded on the run and on its seal. An explicitly named mismatch is refused at finalization. Any other value is refused with `422`.
`repair_of`	body	string or null	`null`	No	The `spec_hash` of the seal this run repairs, for a repair of any tooling. When the run names no catalogs, the seat reads in that seal’s catalogs from its first statement, and it seeds from that seal alone. A hash no spec is sealed under is refused with `422` and no run or thread is created. Required with `authoring_tooling: "classic"`, where it must name a classic seal.
`resubmission_of`	body	string or null	`null`	No	Optional run id of the earlier spec-author seat run this request resubmits. With `target_model` omitted, its accepted mapping is carried unchanged; `data.target_model_carried_from` names the run whose seat registered it. Maximum length `255`.
`max_finalize_rounds`	body	integer	`3`	No	Maximum finalize-and-correct rounds. Bounded `1`..`5`.
`estate_id`	body	string or null	`null`	No	Optional named-estate id for run provenance. Maximum length `255`.
`source_estate_basis`	body	object or null	`null`	No	Optional operator declaration that a `SUBSTITUTE` connection is this run’s source of truth. When supplied, both `connection_id` and `reason` are required.
`source_catalog`	body	string or null	`null`	No	Catalog (database) bound to every statement the seat sends except a registration check for an invariant declaring `invariant_side: "target"` when source and target are separate catalogs of this connection; also used for source relation columns at the seal. Omit it to use the connection’s own catalog.
`target_catalog`	body	string or null	`null`	No	Catalog (database) the seal reads the target side in: target relation columns, and the target-engine prepare of every target-side check. When source and target are separate catalogs of this connection, a registration check for an invariant declaring `invariant_side: "target"` resolves here, not in `source_catalog`; other registration checks use `source_catalog`. Omit it to use the connection’s own catalog. With `target_connection_id` it is a catalog of that connection, admitted by that connection’s engine, and only the target-engine prepare reads it.
`target_connection_id`	body	string or null	`null`	No	The registered connection the target is on, when it is not `connection_id` (a migration to another engine). The seal prepares every target-side check on that connection’s engine, reading no row, and refuses a check the engine rejects. It must be usable by the authenticated user and, for a relayed request, the agent. Omit it when the target is on `connection_id`. Minimum length `1`; maximum length `255`.
`target_column_types`	body	object[] or null	`null`	No	Optional caller assertions for target columns. Each object requires string fields `relation`, `column`, `native_type`, `source_clause_ref`, and `provenance`. See the `author_spec` contract for how the run handles these assertions.
`target_type_dispositions`	body	object[] or null	`null`	No	Optional storage choices for declared target TIME columns. Each object requires `relation`, `column`, `physical_type`, `encoding_rule`, and `clarification_id` as non-blank strings. See the `author_spec` contract for the exact person-ratified statement format and seal behavior.
`assets`	body	object[] or null	`null`	No	Caller-declared assets handed to the seat. Each item has `name`, optional `provenance` (`canonical` or `hypothetical`), and `basis`; an absent or unrecognized label is unlabelled and refuses the submit. An asset may also carry its document as exactly one of `content` (up to `2,097,152` characters, stored exactly as sent), `repository` (`{bot_git_repo, ref, path}` in a local bot-git repo, read at submit), or `upload` (`{file_id}` for a file attached to the chat, using the File ID or Git Path shown by its attachment notice). A `repository` asset with `bot_git_repo: "uploads"` and the notice path is also treated as an upload when no local bot-git repository named `uploads` exists; otherwise it is read from that repository. Uploads use the `uploads` repository’s read grant. The document is stored with the run and the seat reads it itself. Asset names must be unique. Maximum `50` assets.
`clarification_ids`	body	string[] or null	`null`	No	Clarification record ids the caller explicitly asks the seat to rely on. Every id must be recorded against `estate_id`, which is required when ids are supplied; who recorded each one is read from its record and sealed into provenance. Unknown or cross-estate ids refuse the submit before a run starts. On a repair (`repair_of`), still-standing rulings cited or used to answer questions in the prior’s sealed lineage are also carried automatically for that estate; retired or other-estate rulings are not carried. Maximum `50` caller-supplied ids.
`target_model`	body	object or null	`null`	No	The proposer’s source-to-target mapping (the version-2 `target_model` schema): the target tables each source table is split or merged into, the target tables derived (by joins or rollups) from source tables, and for a Data Vault its hubs, links and satellites. It must be one object, never a list; a list is rejected with `422`. A mapping that does not parse refuses the submit before a run starts. The seat checks it against the source, registers it as the spec’s `target_model` with the obligations it renders, and ends the run unsealed with its findings when it does not hold; it never writes a mapping itself. When a reference misses a hub’s declared key, the refusal findings can include source measurements showing repeated key values, row and distinct-value counts, or `NULL` rows when the source is readable. See the `author_spec` contract for the proposer-facing behavior.
`wait_seconds`	query	number or null	`null`	No	Optional bounded wait. Values below `0` are rejected; values above `estate_char.api.max_wait_seconds` are clamped and the applied ceiling is reported in `wait.ceiling_seconds`. The seat continues in the background when the wait expires.

source_estate_basis has the shape { "connection_id": string, "reason": string }; both fields are non-empty and required when the object is present. On Snowflake, an unbindable catalog name is refused before the authoring run is created; the author_spec contract documents the accepted identifier forms. source_catalog and target_catalog can place both estates on one connection as separate catalogs. In that placement, source_catalog binds seat statements except the registration check for an invariant declaring invariant_side: "target"; target_catalog binds that check along with target-side reads and preparation. The seat’s ad-hoc _query_database reads use the target catalog only when every schema named by the query exists there and at least one is absent from the source catalog; otherwise they use the source catalog. See the author_spec catalog-binding guidance for the full behavior. A successful target-catalog check is recorded as resolution_target_catalog, not as source observation evidence. When target_connection_id names another connection, target_catalog belongs to that connection and is used only for target-engine preparation. Omitted catalogs use the applicable connection’s own catalog. A named catalog on an engine that cannot bind session catalogs returns 400 and no run is created. target_connection_id must name exactly one registered connection that the caller may use. An unregistered or ambiguous reference returns 400, a connection the caller may not use returns 403, and an unreadable connection store returns 503; none creates a run. The connection is kept on the run row, and the seal reads it from there. The seat run is asynchronous by default: the response returns a handle with data containing run_id, thread_id, status: "authoring", mode, interpretation_policy, and authoring_tooling, plus the common run envelope. The hidden thread is retained as the run’s audit transcript. The seat’s status is derived from that thread and the compiled-spec store. The seat’s data.status uses one word per run: authoring while the stored run is queued or running, sealed for stored succeeded, and refused, failed, or cancelled for those stored terminal statuses. The common envelope beside it keeps the stored spelling and exposes it as summary.raw_status when that spelling differs from the normalized run vocabulary. sealed is returned only when spec_hash names a registered compiled artifact. A sealed response includes compiled_spec_url for GET /api/estate/spec-conformance/compiled/{spec_hash}; a refused response indicates the seat returned spec_hash=NONE; malformed or unregistered seals are failed. When a conversation resubmission omits target_model and the pre-check carries a mapping registered by an earlier round, the submit handle includes data.target_model_carried_from, the run id of a round whose seat registered that mapping. The author_spec contract documents which rounds are eligible when a commission’s estate_id changes and when an omitted mapping is refused before a run. resubmission_of explicitly names an earlier run and replaces the conversation lookup; it allows an HTTP caller, which has no authoring conversation, to carry a mapping. The named run must be a spec-author seat run even when target_model or repair_of is supplied. If target_model is omitted, a mapping is carried only when the named run’s seat registered it (or it carried a mapping registered by an earlier seat); a named run with no mapping carries none. The seat checks the carried mapping against this request’s source; the named run’s spec_name, connection, and estate do not have to match. A supplied target_model is used as sent, and with repair_of the repaired seal’s mapping is used; in either case the named run is checked for seat type only. An unknown run and one the caller may not see both return 404 Unknown run; a non-seat run or an unregistered proposed mapping returns 400 naming resubmission_of. These refusals create no run. At finalization, the seat compares every relation-observation receipt’s connection with the requested connection_id. A receipt from another connection is refused as re_anchored unless source_estate_basis explicitly names that substitute and explains why it is accepted as the source. An accepted substitution is recorded in the sealed artifact and finalize result as re_anchored_from; ordinary seals expose the declared source and the reason no substitution was recorded. See relation observation evidence for the receipt and seal fields. When assets is supplied, the response’s data.intake reports the caller’s inventory before the seat derives any obligation. Every named asset must be labelled canonical or hypothetical; the seat never supplies or corrects a label. A bundle containing a hypothetical asset runs a findings pass and does not seal (data.intake.phase is findings). Submit the resolved bundle again with all assets canonical to author and seal it. Intake and sealed assets also carry server-stamped asserted_by and label; see the author_spec tool contract for the attribution semantics. Document-carrying intake and sealed assets also carry the document pin: source, chars, content_sha256, and the storage metadata needed to identify the bytes actually read. The document itself is not in the summary or brief; the seat reads it with read_spec_asset. Omitting assets, or sending an empty list, is the no-separate-assets case and authors normally. Before creating the run, the route refuses a ticket and its document assets when their combined numbered items and table rows exceed the seat’s registration capacity: 100 clauses per accounting call times estate_char.spec_author.max_registration_calls (default 200). This returns 422 and no run handle. If a pinned document later cannot be read during finalization, the run ends refused with the recorded rule asset_documents_unreadable; see the author_spec tool contract for the refusal details. When clarification_ids is supplied, each record must exist and belong to estate_id; otherwise the request is refused with no authoring run. The seat records the ids and their stored provenance in the sealed specification; see the clarification tool contract for the recording rules. On a repair, inherited ruling ids are listed separately in the run summary as clarifications_carried_from_lineage; the caller’s clarification_ids remain the explicit submit-time list. The summary also records earlier_owner_rule_offers and exact repeated offers withheld from the owner in owner_rule_offers_already_made. The seat’s repair brief behavior and when earlier questions or checks may be raised again are described in the author_spec contract. target_type_dispositions is validated at submit: a disposition for an undeclared, duplicate, non-TIME, or time-zone-bearing column returns 422 before a run starts. For a Databricks or unidentified target, the asynchronous seal refuses with target_time_encoding_unratified if a declared TIME column lacks a matching disposition ratified by a signed-in person for the same estate and exact storage choice. The current accepted disposition is STRING encoded as HH:mm:ss; choosing native TIME as the disposition’s physical type is not accepted yet, and a time-zone offset cannot be represented by this encoding. Each disposition that reaches ratification validation causes two clarification-store reads at seal. See the author_spec contract for the statement format and caller workflow. With wait_seconds, the route returns 200 if the seat terminalizes during the wait. If the wait expires first, it returns 202 with the same handle, status: "authoring", and wait.expired: true; the seat is not cancelled and the caller should poll on. The generic GET /api/estate/runs/{run_id} route is the common poll surface, while the seat-specific status route exposes the seat’s counts, findings, and open questions. If the seat’s thread and completion make no progress for the configured estate_char.spec_author.no_progress_seconds bound, the driver ends the run with terminal status: "error" and summary.error_type: "run_stalled". The response’s next action says to start the run again after checking work already committed. The driver reads activity from the runtime that dispatched the turn, not only from the completion stream; an unreadable runtime view does not declare a stall. Before writing the terminal row, it asks that runtime’s hard-stop to stop the turn and retries a refused request according to the configured stop policy. The summary says whether the stop was taken or the requests ran out; anything written afterward is recorded as a late completion beside the terminal row. If all stop requests are refused, the process keeps asking on reconcile sweeps and replacement submissions; a new run for the same operator and connection is refused with 409 until a stop is accepted or the turn leaves the runtime. A poll that cannot read the thread counters or the owning runtime does not declare a stall. Before creating the run, the route checks that the configured model provider answers. If no provider is configured, it returns 503 with details: "llm_provider_not_configured". If a configured provider does not answer, it returns 503 with details: "llm_provider_unreachable", cause (login_expired, unreachable, rate_limited, or provider_error), and operator_detail; no run or thread is created. The readiness probe is shared across model-backed seats according to llm.provider_preflight_ttl_seconds.

Status	Meaning
`200`	The request completed, or the requested wait observed a terminal seat result.
`202`	The requested wait expired before terminalization; the same run handle is returned and the seat continues authoring.
`400`	The run could not be created, for example because the seat thread could not be created, the named `resubmission_of` run is not a seat run, or it proposed a mapping no seat registered.
`404`	`resubmission_of` names an unknown run or one the caller may not see; both return `Unknown run`.
`403`	A repository asset names a local bot-git repository the submitting operator may not read.
`409`	An unstoppable stalled seat turn still holds this operator and connection; the request asks the runtime to stop it again, but no replacement run is created.
`503`	The spec-author seat cannot be commissioned because no model provider is configured (`details: "llm_provider_not_configured"`) or the configured provider did not answer (`details: "llm_provider_unreachable"` with `cause` and `operator_detail`). No run or thread is created.
`422`	Request validation failure, such as missing or conflicting requirements text (`ticket_text` and `requirements` differ), invalid `mode`, an out-of-range `max_finalize_rounds` or `wait_seconds`, a `target_model` supplied as a list, or an omitted mapping when the newest prior proposal was not registered by a seat (on a conversation resubmission without `repair_of`). A ticket and document bundle that exceeds the seat’s registration capacity also returns `422`. These submit refusals create no run or thread.

`GET /api/estate/spec-conformance/compiled/{spec_hash}/substrate`

Read only the SUBSTRATE section of a seal-verified compiled spec. This is the customer’s stated requirement for how the change must be built; it states no obligation and is not graded. The response’s data contains spec_hash, declared, and clauses. declared: false means the ticket stated no substrate, so clauses is empty for that reason.

Status	Meaning
`400`	The artifact is unsealed or its seal does not verify.
`404`	Unknown compiled spec hash.

`POST /api/estate/spec-conformance/compiled/{spec_hash}/self-certification`

Record the building agent’s self-certification against the sealed substrate. This is a statement, never a proof: nothing measures it and no Prover verdict reads it. The response is labelled kind: "self_certification" and is_proof: false.

Field	In	Type	Default	Required	Description
`spec_hash`	path	string	none	Yes	Sealed compiled-spec hash whose substrate is being certified.
`build_ref`	body	string	none	Yes	What was built, such as a git SHA, job run id, dbt invocation, or notebook path. Maximum length `2048`.
`agent`	body	string	none	Yes	Agent certifying its own work. Maximum length `255`.
`compliance`	body	`yes`, `no`, or `partial`	none	Yes	The agent’s overall statement of compliance.
`clauses`	body	object[]	`[]`	No	Per-clause statements. Each object has `clause` (the sealed clause verbatim, `1`..`2048` characters), `did` (what the agent did and its evidence, `1`..`2048` characters), and `complied` (boolean). Maximum `25` clauses.

When the spec declares no substrate, the statement is recorded as the builder’s substrate declaration instead: the clauses are the builder’s own (what it built on and where it departed), and the response is labelled kind: "substrate_declaration" and anchored: false — it is not certified against anything the spec stated, and the spec does not gain a substrate. A statement against a declared substrate is labelled kind: "self_certification" and anchored: true. The request is refused with 400 when a clause is not present in a declared sealed section, when a declaration names no clause, or when a clause is submitted twice. An identical statement is idempotent: the response returns the same certification_id and created: false on a retry. A new statement is appended rather than replacing an earlier one.

`GET /api/estate/spec-conformance/compiled/{spec_hash}/self-certification`

Return every self-certification for the hash, newest first. The response is labelled as a self-certification and never as a verdict. An empty certifications list means nobody has certified against the spec; it is not a finding or a non-compliance result. Each row carries kind and anchored as above, so a builder’s declaration on a spec with no substrate never reads as a certification against it.

Status	Meaning
`200`	The list was read, including when no certification exists for the hash.

`GET /api/estate/spec-conformance/author-seat/{run_id}`

Field	In	Type	Default	Required	Description
`run_id`	path	string	none	Yes	Seat run id returned by `POST .../author-seat`.

The response’s data contains run_id, thread_id, status, mode, and the authored counts (structural, obligations, settlements, and finalize_rounds) when available. On a terminal run, finalize_rounds remains the seat’s own count from its RESULT line, while finalize_round_history carries the finalize attempts recorded on the run row, including each attempt’s status, findings, and refusal rules. result_line_disagreed names finalize_rounds when the seat’s count differs from the number of recorded attempts, even when no artifact was sealed; the count remains the seat’s self-report, so the marker does not decide which side is wrong. The terminal summary also retains authoring_effort, with the run’s authoring cost and counts by kind. It also includes findings and open_questions; each open-question entry carries its number, text, status (open, answered, or proceeded), owner_answered, and the current resolution label and metadata. summary.open_questions contains questions put to the owner; migration-default questions that were held back are retained separately as summary.migration_default_questions, an array of {question, property} objects. The field is omitted when empty. See [resolve_open_question] (/docs/Genbot-Toolkit/Additional-Tool-Groups#resolve_open_question) for how that field distinguishes an open or agent-closed question from an agent-recorded answer. A full or partial sealed result includes spec_hash and compiled_spec_url. When a sealed seat still has an open question, the common run envelope’s next names resolve_open_question with the next question number instead of handing off directly to prove; after all questions are resolved, next hands off to prove. Statuses are authoring, sealed, sealed_partial, refused, failed, or error. For status: "error" with summary.error_type: "run_stalled", use the next action to start a new run; the original turn may still write a late completion because it was not interrupted. The common envelope’s summary.seat_settings_defaulted lists authoring settings left unset; summary.seat_settings_inherited records inherited settings and catalogs. See the author_spec contract for submit-time tooling inheritance and the load_prior_spec reference for catalog inheritance. The terminal summary also retains Registrar activity under registrar_phases and registrar_withdrawn_obligations, including ruled withdrawals, so polling the run preserves checkpoints and withdrawals recorded during authoring. Its registrar_phases.checkpoints list is newest first in the run summary, marked by registrar_phases.checkpoint_order: "newest_first"; the seal’s checkpoint record remains oldest first. This ordering also applies when a run ends without a seal. If an oversized response is shortened by dropping trailing list elements, this order keeps the final review rather than only the earliest draft checkpoints. The terminal summary also includes sealed_obligations, a mapping from each sealed obligation_id to its kind. It is placed first in the summary so a byte-offset fallback retains it unless the mapping itself does not fit. When the sealed artifact has a clause-accounting ledger, clause_dispositions counts its entries by accounted_by value: obligation, accepted_difference, not_applicable, and open. The three closed-disposition counts are present, including zeroes; open is present when any clause is open. clause_dispositions is omitted when the seal has no ledger. Each sealed run also reports spec_seal_state (full or partial) and open_clause_count, measured from the artifact (0 for a full seal, null when a partial seal’s coverage block cannot be read). For a partial seal, open_clause_remedies lists each open clause’s clause, reason, remedy actor, and remedy statement as remedy; it is null if the block cannot be read. result_line_disagreed names open_clauses when the seat omits the required partial-seal count or reports a count that differs from the artifact. On a repair, the summary can also include clarifications_carried_from_lineage, earlier_owner_rule_offers, and owner_rule_offers_already_made; the first distinguishes inherited rulings from ids supplied by the caller. The run’s provenance.seat_settings_defaulted also records which settings the deployment default decided. Every read of the run — the envelope, the data half, each run-list row and the seat status view — shows a provenance setting the round inherited as the inherited value, and neither seat_settings_defaulted list names a setting once it has been inherited.

Status	Meaning
`404`	Unknown seat run id or a run the caller may not see.

The questions are resolved through the prover_tools resolve_open_question tool, not this status route. Supply either a clarification recorded with record_clarification or an explicit reason for proceeding without an answer; the resolution is append-only and the latest one for a question is the current state. The same open_questions view is included when reading the compiled spec that the seat sealed.

`POST /api/estate/spec-conformance/compiled`

Field	In	Type	Default	Required	Description
`spec_hash`	body	string	none	Yes	Claimed content identity. Must be exactly 64 lowercase hexadecimal characters and must match the hash recomputed from the supplied artifact content.
`artifact`	body	object or null	`null`	No*	The parsed four-key compiled artifact: `spec_name`, `structural_items`, `obligations`, and `notes`. It is passed through unchanged; preserve its key order because the canonical content hash uses the supplied order.
`artifact_text`	body	string or null	`null`	No*	The sealed artifact’s exact text, including indentation and the trailing newline. It is hashed as supplied, so use this when the file was read but no `file_ref` is available. Maximum length `8000000`.
`file_ref`	body	string or null	`null`	No*	Reference to an uploaded sealed artifact in the Genesis file store. The server reads its bytes exactly, avoiding model re-typing drift. Maximum length `2048`.
`provenance`	body	object or null	`null`	No	Authoring metadata recorded beside the artifact and excluded from the content hash.
`parent_spec_hash`	body	string or null	`null`	No	Hash of the spec this artifact was repaired from, when continuing a lineage. Must be a 64-character lowercase hexadecimal hash when supplied. Naming it also puts the registration under the coverage gate described below.
`round_n`	body	integer or null	`null`	No	Repair round within the lineage. Omit it — the server allocates the next round for the declared parent inside the transaction that stores the row. Send a value only to reproduce a specific historical one; must be between `0` and `1000`, inclusive. Within one lineage `round_n` is an identity: a round already held by different content on the declared parent is refused `400`. Across lineages `spec_hash` remains the only identity.
`coverage_drop_basis`	body	string or null	`null`	No	Why this reseal deliberately asserts less than the parent it names. Required to register one that drops an obligation or a structural item; recorded with the gate’s own measurement in a schema-owned field of the stored row, never in `provenance`. Maximum length `4000`.

* Supply exactly one artifact form: artifact, artifact_text, or file_ref. Supplying none or more than one returns 422. Use this endpoint when an agent or other authoring process sealed the artifact outside the Genesis server. Prefer file_ref when the sealed file is uploaded; otherwise send its exact text as artifact_text. Use the parsed artifact only for content assembled as an object. Do not send a seal: the server derives the seal from the artifact, verifies the claimed spec_hash, validates the artifact shape, and then stores it so GET /api/estate/spec-conformance/compiled/{spec_hash} can serve the seal-verified view. The authenticated caller is recorded as registered_by in provenance, together with the registration timestamp. Successful responses include data with registered: true, the spec_hash, already_registered, advisory findings, and content_sha256 plus content_sha256_basis. When the artifact’s model lists unassessed tables, findings also include unassessed_but_assessed if its scope, structural items, or obligations assess one, or unassessed_without_scope if the spec declares no scope. These findings report contradictions in externally sealed artifacts but do not block registration. For byte forms, content_sha256 is the digest of the bytes supplied and the basis says whether they are the sealed bytes or a different serialization that canonicalizes to the sealed content. For the parsed-object form, it is null with a basis stating that no caller-supplied bytes were measured. Re-posting an already stored hash writes nothing and returns already_registered: true; findings do not block registration. That no-op is on the CONTENT only: because nothing is written, the coverage in such a response is measured against the stored row’s OWN parent and carries a coverage_basis saying so, rather than against the parent_spec_hash the repeat supplied — which the store would not have honoured. coverage and coverage_drop_basis are the gate’s own record and are stored in a schema-owned field of the row, never inside provenance: a caller-supplied value under either name is stripped at the write, on every path. The separation is what makes the legacy answer sound — provenance is a free-form namespace the caller fills, and filled it under the previous contract too, so a key sitting in it says nothing about whether the gate ran. A repeat that declares a different parent_spec_hash than the stored row is refused 400 rather than answered, since re-posting identical content cannot move stored lineage. COVERAGE is the one thing that does block, and only when parent_spec_hash names a spec this deployment holds: the response then carries a coverage block measuring this artifact against that parent (obligations and structural_items each as before/after, dropped_obligation_ids, added_obligation_ids, dropped_structural_ids, per-kind counts, and shrank), and a reseal that asserts LESS is refused 400 unless coverage_drop_basis states why. An absent coverage block means nothing was measured — read coverage_basis for which case — and never that a parent was declared and nothing was dropped. Every response carries a coverage_basis, including a first registration that declared no parent, which reports no_parent_declared and no coverage: an original is a state the answer names, not one a caller infers from a missing key. The other bases are not_measured_at_registration (a parented row admitted before the gate existed), parent_unavailable (measured once, its parent has since left the store), read_not_taken (this request wrote nothing, so the answer describes the row that persisted) and measured_against_unmeasured_parent (measured against a parent whose own lineage never was). Rows admitted before this gate existed have one stated policy that every read path obeys: re-posting such a row is idempotent success carrying coverage_basis: not_measured_at_registration and no coverage, because a measurement taken now is not the registration-time state the gate attests, and it is not refused even when the parent it names has since left the store — reading a record back is the documented way to see it. A NEW reseal whose parent is one of those rows IS measured against the content the store holds, is still refused 400 if it asserts less, and reports coverage_basis: measured_against_unmeasured_parent, since the diff is true about that one link and claims nothing about the chain above it. A row the gate DID measure whose parent has since left the store reads back with coverage_basis: parent_unavailable, which is a different fact from never having been measured. Declaring a parent_spec_hash this deployment does not hold is refused 400, because the coverage it claims cannot be measured — register the parent first, or drop the field. A mismatch names the claimed hash, the supplied-byte hash when available, and the canonical content hash, with the byte form to use instead of retyping the artifact.

Status	Meaning
`400`	The claimed hash does not match the artifact, or the artifact cannot be canonicalized or read as a compiled spec.
`422`	Request validation failure, such as an invalid hash format, no or multiple artifact forms, or a `round_n` outside `0`–`1000`.

On Snowflake, registration claims both the content hash and the (parent_spec_hash, round_n) repair-round slot in the write. Concurrent different artifacts cannot both register under the same parent and round; the losing request is refused as a round conflict. Re-posting the same stored content under its existing lineage remains idempotent and returns already_registered: true.

`GET /api/estate/spec-conformance/compiled/{spec_hash}`

Field	In	Type	Default	Required	Description
`spec_hash`	path	string	none	Yes	Content hash of the sealed compiled derivational artifact.

Successful responses include data with the seal-verified artifact view: artifact (obligations and metadata), seal, provenance (including retained instruction_text and, when ticket prose was submitted, instruction_text_submitted_by, canonical spec_files ([{name, markdown}]), spec_files_sha256 integrity hash, target_manifest when present, seat_settings_defaulted when recorded, and the stored clarification and asset provenance), who_decided (the clarification reliance sentence, each clarification with who recorded it, each asset with who asserted its label, and the ticket-prose byline), open_questions (the numbered questions the sealing seat reported, each with its current status, resolution metadata, and display label), and repair lineage (round_n, parent_spec_hash, and related fields). A seal made before clarification provenance was recorded reports clarification provenance unknown. Compiled artifacts include artifact.notes.doctrine_version set to 2026-08-29.grain, identifying the compile doctrine used. Numeric implied-domain misses with a resolvable relation are added as deterministic mandatory invariants for non_negative (min: 0), percentage (min: 0, max: 100), and ratio (min: 0, max: 1); label_set domains remain author-resolved because their allowed values must come from the prose or schema. Axis coverage is checked after cross-family assembly: a cited settlement whose settled_group exactly matches the detected axis id settles that axis even when its resolving sentence does not meet token-overlap coverage, and artifact.notes.ambiguity_axes carries each axis disposition. When the soft fork budget is exceeded, excess ambiguity groups are demoted to plain obligations and retain their underlying checks rather than dropping alternate readings.

Status	Meaning
`400`	The stored artifact is unsealed or its seal does not verify (tamper) — it cannot be trusted.
`404`	Unknown compiled spec hash.

The open_questions entries use the same shape as the author-seat response above, including owner_answered. offered_not_adopted lists checks the sealing seat offered the owner as stated rules that this sealed artifact does not carry. Each entry has obligation_id, statement, seat_run_id, and the server-owned label explaining that the check is not graded. A check appears once by obligation id; registered obligations in artifact are the adopted checks. This list is visible context only and is not part of grading. The read includes it with the seal by default; the service’s artifact-only path can omit both this list and open_questions.

`POST /api/estate/spec-conformance/compiled/{spec_hash}/qualify`

Field	In	Type	Default	Required	Description
`spec_hash`	path	string	none	Yes	Parent compiled spec hash to qualify.
`connection_id`	body	string	none	Yes	Estate whose catalog and default schema resolve bare relation names. Minimum length `1`, maximum `255`.

Submit-and-return: loads the parent seal-verified artifact, qualifies bare relation names against the named connection using the same normalization as the spec-author finalize path, and registers a new sealed child chained with parent_spec_hash and an incremented round_n. This operation is synchronous because qualification is deterministic; it does not invoke an author, create a run, or create a thread. The successful response returns data with the new spec_hash, parent_spec_hash, qualified (one from/to receipt per changed relation field), author_invoked: false, and the normal registration result. Only relation fields may change. The operation refuses with 400 when nothing needed qualifying, the pass would change any other field or remove an item, the qualified artifact fails the seal gate, the parent is tampered or unsealed, or the connection cannot resolve the names. An unknown parent returns 404; an invalid connection_id returns 422. Use this endpoint for deterministic name qualification instead of a model-backed repair round.

Status	Meaning
`400`	The parent is not seal-verified, qualification is refused, no relation needs qualifying, or the qualified artifact does not pass the seal gate.
`404`	Unknown parent compiled spec hash.
`422`	Request validation failure, such as an empty or overlong `connection_id`.

`POST /api/estate/spec-conformance/compiled/{spec_hash}/declare-shape`

Declare the migration shape for a sealed specification whose structural items do not yet say whether their loci should change or remain identical. This is a synchronous derivation: it does not invoke an author, create a run, or query a warehouse. It returns a new child spec_hash chained to the supplied parent; grade that child instead of the parent.

Field	In	Type	Default	Required	Description
`spec_hash`	path	string	none	Yes	Parent sealed compiled-spec hash.
`change_expectation`	body	string	none	Yes	`must_differ` when the target must differ from the source at each locus; `must_match` when the target must contain each locus unchanged.
`item_expectations`	body	object	`{}`	No	Optional `spec_id` to shape map for layered moves. Overrides `change_expectation` for named items only.

The declaration is written onto every structural item. The response’s data includes the new spec_hash, parent_spec_hash, declared receipt, author_invoked: false, and the normal registration result. A must_match declaration is refused for a drop item, an override is refused when its spec_id is not present, and a specification with no structural tier cannot be re-sealed.

Status	Meaning
`400`	The parent is tampered, already carries a readable shape, has no structural tier, or the declaration is otherwise refused.
`404`	Unknown parent compiled spec hash.
`422`	`change_expectation` or an override is outside `must_differ` and `must_match`.

`POST /api/estate/spec-conformance/consult-reading`

Field	In	Type	Default	Required	Description
`compiled_spec_hash`	body	string or null	`null`	No*	Content hash of a sealed compiled derivational artifact. When supplied, the server loads the authoritative instruction text from the artifact’s `provenance.instruction_text` — drift-proof against the stored sealed prose. Maximum length `255`.
`prose`	body	string or null	`null`	No*	Raw prose for offline replay when no compiled row exists. Maximum length `32768` (`2048 * 16`). Must be non-empty when supplied.
`ambiguity_group`	body	string	none	Yes	Label identifying the ambiguity group under review. Minimum length `1`, maximum `255`.
`candidate_reading`	body	string	none	Yes	The implementer’s proposed reading to adjudicate against the prose. Minimum length `1`, maximum `8192` (`2048 * 4`).

* Supply exactly one prose source: compiled_spec_hash or prose. Supplying neither or both returns 422. When compiled_spec_hash is supplied but the artifact did not retain instruction_text, pass raw prose instead (400). Submit-and-return: the response returns immediately with data containing { "run_id": "...", "status": "running" }. The blind author sees only the resolved prose, the ambiguity-group label, and the candidate reading — never the implementer’s artifact, tests, or verifier content. Poll GET /api/estate/spec-conformance/consult-reading/{run_id} for terminal status. On completion, verdict is licensed (the reading is defensible from the prose and may join the ambiguity group as an election) or rejected (not defensible; malformed model responses are coerced to rejected). The consult identity is the authenticated caller, never a body-supplied bot.

Status	Meaning
`400`	Neither prose source supplied (service layer), the compiled spec did not retain instruction text, or validation failure.
`404`	Unknown `compiled_spec_hash`.
`422`	Malformed request (no prose source, both prose sources, or empty fields).

`GET /api/estate/spec-conformance/consult-reading/{run_id}`

Field	In	Type	Default	Required	Description
`run_id`	path	string	none	Yes	Reading-consult run id returned by `POST .../consult-reading`.

Successful responses include data with the persisted run row:

Field	Type	Description
`run_id`	string	Run id.
`status`	string	Run status (`running`, `finished`, `error`, and so on).
`verdict`	string or null	`licensed` or `rejected` on completion; `null` while running.
`rationale`	string or null	One-line author explanation of the verdict.
`ambiguity_group`	string or null	The ambiguity group submitted with the consult.
`error`	string or null	Terminal error message when the run failed.

Status	Meaning
`404`	Unknown reading-consult run id or a run the caller may not see.

`GET /api/estate/spec-conformance/run-for-diff/{diff_hash}`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Content-addressed mediated-diff id for the comparison whose envelope run to resolve.
`include_proceedings`	query	boolean	`false`	No	Add the adjudication proceedings opened on the resolved grade. Off by default: the listing is a second store read this route otherwise never makes.

Deterministic, uncapped lookup of the spec_conformance or spec_drill run whose envelope this comparison should open. The newest specification’s authored grades (target_items > 0) rank ahead of the platform-only migration envelope (target_items == 0); within a tier, the newest grade by parsed started_at wins whether or not it verified (spec_conformance before spec_drill when start times tie). A newer unverified grade therefore replaces an earlier verified grade for display. When the selected grade is not verified but an earlier grade with the same spec_hash verified, its run row includes earlier_verified_grade with that earlier run’s run_id and started_at; the most recent such verified grade is named. The field is absent when the selected grade verified or no earlier verified grade of the same spec exists. A still-running grade is the fallback when no finished viable run exists. Successful responses include data with the full run row (summary, canvas, provenance) when a viable grading run exists, or data: null when the comparison is ungraded — the common case, not an error. Read-only: never mints a run or fires a grade. Use this when the recency-shaped GET /api/estate/runs feed may have dropped an older envelope run for a specific comparison. With include_proceedings=true the response also carries proceedings (addressing columns only — no materials and no verdicts; read one in full through the adjudication routes), proceedings_basis, proceedings_truncated, and proceedings_grading_run_id. proceedings_basis separates three facts an empty list alone cannot: measured (this comparison’s grade WAS listed and held these), no_grade (nothing was listed because no grading run resolves for the comparison at all), and not_requested. They prescribe different next moves. Both halves come off ONE resolution — the uncapped run-feed scan this route already pays — so asking here costs one prefix listing over the proceedings table rather than a second scan.

`GET /api/estate/stimulus/run-for-diff/{diff_hash}`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Content-addressed mediated-diff id for the comparison whose stimulus run to resolve.

Deterministic, uncapped lookup of the stimulus run that stimulated this comparison. Successful responses include data with the full run row (summary.steps ledger, rounds, completion/outcome, and terminal verdict) when a stimulus run references the diff, or data: null when the comparison was never stimulated — the common case, not an error. Read-only: never mints a run. Use this when the recency-shaped GET /api/estate/runs feed may have dropped an older stimulus run for a specific comparison; the comparison-surface Stimulus chapter renders per-round beats directly from this row.

`GET /api/estate/knowledge-dossiers`

Field	In	Type	Default	Required	Description
`comparison`	query	string or null	`null`	No	Filter by comparison class (difference class).
`source_engine`	query	string or null	`null`	No	Filter by source engine in the engine-pair.
`target_engine`	query	string or null	`null`	No	Filter by target engine in the engine-pair.
`verdict`	query	string or null	`null`	No	Filter by verdict: `matched`, `licensed`, `unlicensed`, or `indeterminate`.
`status`	query	string or null	`null`	No	Filter by lifecycle status: `open`, `licensed`, `platform_accepted`, or `resolved`.
`cross_signature`	query	string or null	`null`	No	Exact `cross_family_signature` match.

Every facet is optional; results are deduped failure patterns, most-recently-seen first. List rows include title and meaning (plain-language labels), engine-pair fields, verdict, status, seen_count, and seen_refs — not the Markdown bodies.

`GET /api/estate/knowledge-dossiers/{dossier_id}`

Field	In	Type	Default	Required	Description
`dossier_id`	path	string	none	Yes	Stable dossier id (equal to `cross_family_signature`).

Successful responses include data with both rendered Markdown views: estate_view_md (full estate-specific write-up) and redacted_view_md (redacted, safe-to-share pattern document). resolution_md — how the pattern was resolved / licensed / accepted — is present only later in the lifecycle.

Status	Meaning
`404`	No such knowledge dossier.

`GET /api/estate/rulings`

Field	In	Type	Default	Required	Description
`scope_level`	query	string or null	`null`	No	Filter by scope level.
`scope_id`	query	string or null	`null`	No	Filter by scope id.
`estate_id`	query	string or null	`null`	No	Filter by estate id.
`state`	query	string or null	`null`	No	Filter by ruling state.
`class_id`	query	string or null	`null`	No	Filter by ambiguity class id.
`provisional`	query	boolean or null	`null`	No	When set, filter to provisional (`true`) or ratified (`false`) directions.

Successful responses include data as a list of ruling fold rows (direction, licensor, flags, scope coordinates) for findings the caller may see. The provenance chain is omitted — read it through GET /api/estate/rulings/{ruling_id}.

`GET /api/estate/rulings/{ruling_id}`

Field	In	Type	Default	Required	Description
`ruling_id`	path	string	none	Yes	Content-addressed ruling slot id.

Successful responses include data with the fold row plus its full events provenance chain.

Status	Meaning
`404`	Unknown ruling id, or a ruling decided on a finding the caller cannot see.

`POST /api/estate/rulings/settle`

Field	In	Type	Default	Required	Description
`class_id`	body	string	none	Yes	Ambiguity class id. Minimum length `1`, maximum `64`.
`estate_id`	body	string or null	`null`	No	Estate id for the jurisdiction. Maximum length `255`.
`domain`	body	string or null	`null`	No	Optional jurisdiction component (most-specific-wins below `estate_id`). Maximum length `255`.
`mart_family`	body	string or null	`null`	No	Optional jurisdiction component. Maximum length `255`.
`metric_family`	body	string or null	`null`	No	Optional jurisdiction component. Maximum length `255`.
`direction`	body	string	none	Yes	Direction token from the class vocabulary (or `other` with a descriptive `direction_label`). Minimum length `1`.
`direction_label`	body	string	none	Yes	Human-readable label for the chosen direction. Minimum length `1`.
`note`	body	string or null	`null`	No	Optional operator note.
`source_finding_key`	body	string or null	`null`	No	Optional finding key linking the settlement to evidence. Maximum length `64`.

Jurisdiction components below estate_id are optional (most-specific-wins); a sub-estate component without an estate_id is refused at the store seam. The licensor identity is taken from the authenticated session, never from the request body (there is deliberately no decided_by field). Successful responses include data with the ruling fold row plus its provenance chain.

Status	Meaning
`400`	Unknown class id, retired class, direction outside the class vocabulary, or other store state error.
`403`	Caller lacks `ratify_source_contract`, auth is disabled, the caller is not a genuinely authenticated human, or a licensing-doctrine / identity-binding refusal.
`404`	Unscoped jurisdiction or other store refusal mapped to not-found.

`POST /api/estate/rulings/{ruling_id}/ratify`

Field	In	Type	Default	Required	Description
`ruling_id`	path	string	none	Yes	Provisional ruling to ratify.

The ratifier identity is taken from the authenticated session, never from the request body. Successful responses include data with the ruling fold row plus its provenance chain.

Status	Meaning
`403`	Caller lacks `ratify_source_contract`, auth is disabled, the caller is not a genuinely authenticated human, or an identity-binding refusal.
`404`	Unknown ruling id.
`400`	The ruling is not a provisional settled direction (state forbids ratify).

`POST /api/estate/rulings/{ruling_id}/unsettle`

Field	In	Type	Default	Required	Description
`ruling_id`	path	string	none	Yes	Settled ruling to withdraw.
`note`	body	string or null	`null`	No	Optional operator note explaining the withdrawal.

Withdrawal is supersession, not delete — the slot reverts to escalate and the withdrawn direction stays reconstructable from the event log. The decider identity is taken from the authenticated session, never from the request body. Successful responses include data with the ruling fold row plus its provenance chain.

Status	Meaning
`403`	Caller lacks `ratify_source_contract`, auth is disabled, the caller is not a genuinely authenticated human, or an identity-binding refusal.
`404`	Unknown ruling id.
`400`	State forbids unsettle (for example a closed question or non-settled direction).

`GET /api/estate/ruling-questions`

Field	In	Type	Default	Required	Description
`status`	query	string or null	`null`	No	Filter by question status (for example `open` or `answered`).
`estate_id`	query	string or null	`null`	No	Filter by estate id.

Successful responses include data as a list of ruling-question rows (build-time clarifications filed mid-build). Only questions the caller may see are returned: questions about estates no visible comparison touches, and installation-wide questions, are omitted except to a principal with manage_all_connections.

`POST /api/estate/ruling-questions/{question_id}/answer`

Field	In	Type	Default	Required	Description
`question_id`	path	string	none	Yes	Open ruling question to answer.
`direction`	body	string	none	Yes	Direction token settling the slot. Minimum length `1`.
`direction_label`	body	string	none	Yes	Human-readable label for the chosen direction. Minimum length `1`.
`note`	body	string or null	`null`	No	Optional operator note.

Answering settles the underlying (class_id, jurisdiction) slot and closes the question. The decider identity is taken from the authenticated session, never from the request body. Successful responses include data with question (the closed question row) and ruling (the settled ruling).

Status	Meaning
`403`	Caller lacks `ratify_source_contract`, auth is disabled, the caller is not a genuinely authenticated human, or an identity-binding refusal.
`404`	Unknown question id.
`400`	State forbids answer (for example the question is already closed).

`GET /api/estate/court/dockets`

Field	In	Type	Default	Required	Description
`estate_id`	query	string	none	Yes	Estate whose ranked court queue to return.

Successful responses include data as a list of docket fold rows (docket_id, class_id, neutral_question, materiality fields, and related metadata), ranked by materiality. An estate the caller may not see returns an empty list; same-class rulings from other estates are included only when visible to the caller.

`GET /api/estate/court/dockets/{docket_id}`

Field	In	Type	Default	Required	Description
`docket_id`	path	string	none	Yes	Docket id from the court queue.
`estate_id`	query	string	none	Yes	Estate the docket belongs to.

Successful responses include data with docket (the prepared package, with same-class rulings from other estates limited to those the caller may see) and court_record (attorney-chat exchanges recorded as ruling provenance). A caller who cannot see the requested estate receives the same 404 as for an unknown docket.

Status	Meaning
`404`	Unknown docket id for the given estate.

`GET /api/estate/court/dockets/{docket_id}/audit`

Field	In	Type	Default	Required	Description
`docket_id`	path	string	none	Yes	Docket id (scopes the audit lookup).
`estate_id`	query	string	none	Yes	Estate id.
`class_id`	query	string	none	No	Optional ambiguity class id. When supplied, it must be the class carried by the docket; omit it to use the docket’s class.

Successful responses include data with docket_id, class_id (which can be null when the docket carries no class), status (open, provisional, or settled), and ruling (the settled ruling when present, otherwise null). A docket with no attached class is reported as open without a ruling. The path docket is the scope of the lookup: the endpoint does not audit an unrelated class from the query. It returns 404 when the estate has no such docket, the caller cannot see the estate, or a supplied class_id does not match the docket’s own class. A settled ruling the caller cannot see is reported as status: "open" with ruling: null.

`POST /api/estate/court/dockets/{docket_id}/decide`

Field	In	Type	Default	Required	Description
`docket_id`	path	string	none	Yes	Docket to decide.
`estate_id`	query	string	none	Yes	Estate the docket belongs to.
`direction`	body	string	none	Yes	Direction token from the class vocabulary. Minimum length `1`.
`direction_label`	body	string	none	Yes	Human-readable label for the chosen direction. Minimum length `1`.
`note`	body	string or null	`null`	No	Optional operator note.

The deciding human is the authenticated caller — never the body (there is deliberately no decided_by field). A successful decision emits a ruling into the estate ruling library and binds it to the docket’s court record. Successful responses include data with docket_id, provisional, and ruling (the emitted ruling fold row).

Status	Meaning
`400`	Vocabulary / state error (for example an out-of-vocabulary direction or a docket that cannot accept a decision).
`403`	Caller lacks `ratify_source_contract`, auth is disabled, the caller is not a genuinely authenticated human, or a licensing-doctrine / identity-binding refusal.
`404`	Unknown docket id for the given estate.

`POST /api/estate/court/dockets/{docket_id}/adopt`

Field	In	Type	Default	Required	Description
`docket_id`	path	string	none	Yes	Docket to adopt a ruling for.
`estate_id`	query	string	none	Yes	Estate the docket belongs to.
`source_ruling_id`	body	string	none	Yes	Ruling id from another jurisdiction to adopt. Minimum length `1`, maximum `64`.
`note`	body	string or null	`null`	No	Optional operator note.

The adopter identity is taken from the authenticated session, never from the request body. Successful responses include data with docket_id, provisional (false), and ruling (the emitted ruling).

Status	Meaning
`403`	Caller lacks `ratify_source_contract`, auth is disabled, the caller is not a genuinely authenticated human, or a licensing-doctrine / identity-binding refusal.
`404`	Unknown docket id or unknown `source_ruling_id`.
`400`	Other state or vocabulary errors.

`POST /api/estate/court/dockets/{docket_id}/chat`

Field	In	Type	Default	Required	Description
`docket_id`	path	string	none	Yes	Docket whose court record to append to.
`estate_id`	query	string	none	Yes	Estate the docket belongs to.
`message`	body	string	none	Yes	Exchange text. Minimum length `1`.
`role`	body	string	`"decider"`	No	Speaker role: `decider` or `attorney`.

Records one exchange in the docket’s attorney chat (the court record). Attribution comes from the authenticated caller; auth-off callers are labeled local operator (auth disabled). Successful responses include data with exchange (the recorded row) and court_record (the full running record).

Status	Meaning
`400`	Court-record error (for example an invalid role or message).

`GET /api/estate/improvement-docket`

The improvement docket is the second kind of queue shown in the Court panel. It contains candidate_improvement deviations held for human review, across all estates; unlike the estate-scoped ambiguity queue, these entries have no materiality ranking or estate_id filter. The list includes only entries raised by comparisons the caller may see, with visibility applied before pagination.

Field	In	Type	Default	Required	Description
`diff_hash`	query	string or null	`null`	No	Filter by the comparison that first raised the docket entry. This is provenance, not the set of deviations observed by a later run.
`adjudication_id`	query	string or null	`null`	No	Filter by the adjudication proceeding that raised the entry.
`status`	query	string or null	`null`	No	Filter by `open`, `accepted`, or `rejected`.

Successful responses include data as a list of entries with docket_entry_id, finding_key, element_ref, status, source (adjudicator or builder), mode (pocket or blocking), the build and declared behaviour, clause_ref, value and risk assessments, proposed or recorded waiver_owner and waiver_expires_at (null when no terms were recorded), review fields, and action_review: the entry’s finding’s current Action Review request (proposal_id, status, live, decided_by_label, decision_reason, url), or null when the finding was never asked for. A declined request stays listed with its reason until the finding is asked for again. Entries are ordered with open work first, then newest first within each status. The Court panel displays open entries in an Improvement docket (all estates) section.

`POST /api/estate/improvement-docket/{docket_entry_id}/accept`

Field	In	Type	Default	Required	Description
`docket_entry_id`	path	string	none	Yes	Docket entry to accept.
`note`	body	string or null	`null`	No	Optional note from the human reviewer.
`waiver_expires_at`	body	string or null	`null`	For success	Future ISO-8601 date-time when the waiver stops allowing the finding. Required for acceptance.
`waiver_owner`	body	string or null	`null`	No	Person responsible for the waiver; defaults to the authenticated reviewer.

The reviewer identity is taken from the authenticated session, never from the request body. Accepting is the licensing act and requires a future expiry; for an otherwise acceptable entry, a missing, unreadable, or passed expiry returns 400 without writing the acceptance. The entry is recorded as accepted, and the finding-wide waived licence is written only when every element of the finding has been accepted. Until that point, an accepted element’s register_entry_id remains null; when the last element settles, all element rows receive the finding’s disposition:<finding_key> register entry id. Successful responses include data with the updated docket entry.

Status	Meaning
`400`	The entry cannot be accepted, including an entry with no finding to license or a finding whose prior human disposition cannot be converted.
`403`	Caller lacks `ratify_source_contract`, auth is disabled, or the caller is not a genuinely authenticated human reviewer.
`404`	Unknown docket entry id.
`409`	`code: action_review_required` — an agent filed the entry (`source` is `adjudicator` or `builder`), so it is accepted only through Action Review. Use `request-approval`. Rejecting it stays available here.

`POST /api/estate/improvement-docket/{docket_entry_id}/request-approval`

Field	In	Type	Default	Required	Description
`docket_entry_id`	path	string	none	Yes	An open docket entry an agent filed.
`waiver_expires_at`	body	string or null	`null`	No	Future ISO-8601 date-time for the waiver. If omitted, the request uses the filing agent’s proposed expiry; if none is available, request creation is refused.
`waiver_owner`	body	string or null	`null`	No	Person responsible for the waiver. When naming an expiry, defaults to the authenticated requester.

Asks Action Review to accept every open element of the entry’s finding in one request of type prover.decide_improvement_docket_entry.v1. The agent that filed the entry stays its proposer; the authenticated human caller is the requester and may approve the request. The agent’s filing now attempts to open this request automatically; use this endpoint for a person’s ask when automatic opening failed or an earlier request ended. The request seals its waiver owner and future expiry for approval; if the filing supplied no usable expiry, provide one here. A new request expires after seven days. Its sealed request names each open element, the finding’s current disposition, and the licence approving installs (waived, citable as disposition:<finding_key>). When another element of the finding was already rejected, the request says instead that no licence will be installed, because a finding is licensed only when every element is accepted. Approving accepts every element in one transaction and settles the licence once every element of the finding is accepted. Declining closes the request with its reason and rejects nothing: the elements stay open and unlicensed, and the finding can be asked for again. The request is withdrawn if an element is edited or decided elsewhere, or the finding’s disposition moves, before it is approved. Successful responses include finding_key, proposal_id, status, url, and replayed (true when a request still asking for the finding answered instead of a new one being made).

Status	Meaning
`403`	Caller lacks `ratify_source_contract`, auth is disabled, or the caller is not a genuinely authenticated human.
`404`	Unknown docket entry id.
`409`	`code: docket_entry_decided` (the entry is already decided), `docket_entry_has_no_finding` (it can only be rejected), `docket_decides_directly` (it is accepted on the `accept` endpoint), `docket_request_already_asking` (a request is already waiting with its sealed terms), or `action_review_request_refused` (the request could not be derived, including when no usable future waiver expiry is available).
`503`	Action Review wiring is unavailable.

`POST /api/estate/improvement-docket/{docket_entry_id}/reject`

Field	In	Type	Default	Required	Description
`docket_entry_id`	path	string	none	Yes	Docket entry to reject.
`note`	body	string or null	`null`	No	Optional note from the human reviewer.

The reviewer identity is taken from the authenticated session, never from the request body. Rejecting closes the entry as rejected and writes neither a licence nor a finding disposition. Successful responses include data with the updated docket entry.

Status	Meaning
`400`	The entry cannot be rejected in its current state.
`403`	Caller lacks `ratify_source_contract`, auth is disabled, or the caller is not a genuinely authenticated human reviewer.
`404`	Unknown docket entry id.

`POST /api/estate/snapshots/{snapshot_id}/recharacterize`

Field	In	Type	Default	Required	Description
`snapshot_id`	path	string	none	Yes	Snapshot whose boundary to re-characterize under.

Submit-and-return: the response returns immediately with run_id, top-level status: "running", and data containing { "success": true, "run_id": "...", "status": "running" }. The snapshot is authorized before its boundary is read or a run is created. Follow progress live over /api/ws/estate/live?run_id=<run_id> or poll GET /api/estate/runs/{run_id}. Re-characterization applies the same caller-scoped resume rule; see Prover identity and resume isolation.

Status	Meaning
`404`	Snapshot is unknown or exists but is not visible to the caller; both cases use the same response.

`POST /api/estate/candidates/{candidate_id}/adjudicate`

Field	In	Type	Default	Required	Description
`candidate_id`	path	string	none	Yes	Candidate rule id from the review queue.
`disposition`	body	string	none	Yes	One of `accept_fact`, `endorse_policy`, or `reject`.

Successful responses include candidate_id and disposition. The adjudicator identity is taken from the authenticated session, never from the request body.

Status	Meaning
`400`	Unknown `disposition` value.
`403`	Caller lacks `ratify_source_contract`, auth is disabled, or the caller is not a genuinely authenticated human.
`404`	Candidate not found, or mined from a snapshot the caller cannot see. Both cases answer alike.

`POST /api/estate/contracts/{contract_id}/seal`

Field	In	Type	Default	Required	Description
`contract_id`	path	string	none	Yes	Draft source contract id to seal.

Successful responses include contract_id and sealed_by (authenticated human). The sealer identity is taken from the authenticated session, never from the request body.

Status	Meaning
`400`	Contract is already sealed.
`403`	Caller lacks `ratify_source_contract`, auth is disabled, or the caller is not a genuinely authenticated human.
`404`	Contract not found.

`GET /api/estate/overview`

This endpoint does not document any request body or query fields. Successful responses include data with a cross-estate rollup computed in one call (so the GUI does not fan out per-scope or per-contract requests):

Field	Type	Description
`plane_coverage`	object	Map of `boundary_hash` → list of characterized plane names (`access`, `logic`, `consumption`, and so on).
`deviation_counts`	object	Map of `contract_hash` → map of deviation `status` → count.
`attestation_counts`	object	Map of `contract_hash` → total attestation row count.
`jitter_latest`	object	Map of `contract_hash` → latest jitter campaign stats (`campaign_id`, `kill_rate`, `mutant_count`, `killed_count`, `survivor_count`, `created_at`).

`POST /api/estate/jitter/clone`

Field	In	Type	Default	Required	Description
`contract_id`	body	string	none	Yes	Sealed contract to qualify with clone mutations.
`max_mutants`	body	integer	`12`	No	Maximum mutants to run. Allowed range: `1` to `50`.

Returns run_id (poll via GET /api/estate/runs/{run_id}) and a data summary.

`POST /api/estate/proofs`

Submit the Prover’s single comparison trigger for a characterized source and target pair. The comparison always runs. If spec_hash is supplied, the same proof then grades that sealed specification against the comparison it just created; callers do not need to submit a comparison first or pass its id to a second request. The proof envelope owns the child runs and records their ids in summary.comparison_run_id and summary.grade_run_id. title (body, string or null, maximum length 200) is the proof’s business title — for example Foundry aviation: raw → ontology rebuild (spec-mediated) — stamped on the proof and child runs’ provenance.title and shown as the comparison’s headline in the dashboard, above its technical source → target label. Omitting it, or sending a blank one, is deprecated: the request is still admitted, and the response carries Deprecation: true and a Warning header saying the title will be required. The agent tools prove, compare and grade already refuse an untitled call. The title is a display label, not part of request identity; when an existing proof answers the submission, its original title remains on the stored comparison. For the title shown in a no-spec response answered by a spec-titled comparison, see the system-diff reuse behavior. A new proof submitted without spec_hash uses the no-spec title rule described for system diffs. The estate reads run as the authenticated human who submitted the proof, not as the bot acting for that human. This matters for personal connections: the connection must be readable by that submitting identity. The proof still records the bot as the acting principal where the run contract needs it, so access identity and actor identity remain distinct. For a graded proof on completely enumerated snapshots, Genesis checks whether the sealed scope can be paired before submitting the run. When a carried same or changed entry names no object in either snapshot, or a source object is under a schema absent from the target and neither schema_map nor object_map addresses it, the request is refused with no proof submitted. Correct an unresolved scope name and reseal the spec, or declare the mapping and submit again. A target_model or a ratified addressing rule for the pair can supply the addressing instead; the scope verdict guide describes how the same missing-map cause appears in a completed grade. The proof envelope also preserves the pair it certifies as source_snapshot_id and target_snapshot_id, and carries the comparison verdict counts at summary.comparison_counts. On the undeclared-target-shape path, the unlicensed and indeterminate values count published readings. withheld_unlicensed and withheld_indeterminate report the corresponding readings measured but withheld from published findings; errored reads remain measured in errored_reads. Read these fields from the proof itself when presenting the result; they remain available after the child comparison run is complete. For a proof submitted by Foundry migration verification with a translated pipeline’s lineage record, summary.comparison_counts.indeterminate_causes can include non_reproducible_by_construction. This cause identifies readings of columns recorded as freshly randomized on every run; the lineage record is supplied internally from the translated script, not as a POST /api/estate/proofs request field. See the Prover comparison guide for the comparison behavior. summary.comparison_counts carries the four assumption disclosure fields described in the Prover comparison guide, including the post-assumption residual counts. It also carries withdrawn_assumptions: the assumptions withdrawn for the estate pair when the comparison ran, each with id, statement, withdrawn_by, withdrawn_by_kind, withdrawn_at, reason, named_in_would_be_licensed_by, findings_returned and readings_made_indeterminate. It is [] when nothing was withdrawn and null for a comparison recorded before the list existed. A withdrawn target-platform fold returns its missing and surplus findings tagged with that platform license, so its findings_returned is counted; other non-rule withdrawals that license no named finding retain null. The block also carries unwitnessed_by_identity with findings, objects, and sentence. It counts unlicensed findings for which no witness row can be localized because their objects have no declared row identity. sentence is the user-ready consequence and remedy; it is null when no findings are affected. The whole block is null for comparisons recorded before this disclosure existed. When the target is shaped like a Data Vault but the sealed spec omitted target_model, the proof summary also carries summary.undeclared_target_shape. It identifies the detected shape, the model to declare, and the number of readings withheld from published findings. The same key carries guidance for a non-vault pair whose objects are unpaired on both sides: it names those objects, shows shared columns as an observation, and gives an empty mapping skeleton. Read this guidance before reporting comparison counts; it is absent when there is no undeclared correspondence to explain. The proof summary may also carry summary.unaccounted_sources; its field semantics are defined in the Prover mapping guide. It may carry summary.unassessed_sources when the sealed mapping lists source tables the owner left unassessed. The object contains objects (the source-table names), count, missing (unlicensed table-level object_missing readings on those tables), basis (the owner’s ruling), and statement (a reader-facing explanation). These readings remain recorded but are not counted as findings about the build. See the [Prover mapping guide] (/docs/Genesis-Prover/Overview#declared-target-mappings-and-data-vault-shapes) for when a table may be left unassessed. A graded proof with spec_hash and no relocation premise also records summary.proof_addressing; see re-proving a spec for its fields and inheritance rules. The sealed artifact may also contain the optional top-level target_model block. It is read only after the artifact seal is verified, so it is not an additional request field and cannot be supplied separately. In schema_version: "2", its derived entries name computed targets, their source objects, required columns, derivation text, and optional grain; a mapping may contain derived targets without any splits. See Declared target mappings for the optional unassessed field and how declared mappings change pairing; a spec without the block retains ordinary one-to-one comparison. When a sealed spec declares target_model, a comparison made without that model and later named by a grade is recomputed under the model before grading. The finished grade’s provenance carries comparison_recomputed_under_spec with the replaced comparison hash, the target_model_hash, and the declaring spec hash. This adds a full comparison of both estates; a pinned comparison carrying a caller-declared row identity cannot be recomputed and returns 409, directing the caller to use POST /api/estate/proofs with the spec and row identity together. The recomputed comparison’s title comes from the grade run when recorded; otherwise, the replaced comparison’s title is inherited only when it was recorded for the same spec. See the Prover guide for title inheritance and the no-title behavior. This is an asynchronous, warehouse-bound operation: comparison-only proofs read both characterized estates, and graded proofs also read both estates for the obligations. The response returns one proof run_id; poll GET /api/estate/runs/{run_id} or envelope.links.poll. A repeated request for the same pair, addressing, column_map, spec, and round_n reuses a finished result only while the pair’s licensing is unchanged. If a correspondence-rule binding changes or a bound rule is re-qualified after the held proof started, Genesis recomputes the proof instead of returning the held result. An identical request whose grade is still in flight is superseded and names the run holding the answer. A grade that declines a seal or tier rolls up to refused, which is a terminal system decision rather than a crash. Proof reuse is also scoped to the exact acting bot and authenticated human that submitted the request. A repeat from a different bot or user starts a separate proof instead of disclosing the earlier proof result, even when every estate and proof field matches. The optional Idempotency-Key header is part of the proof identity. The proof forwards round_n to its comparison, but deliberately does not forward that header: a submission id scopes the proof, not the measurement. If the comparison is already held for the pair, the proof summary reports comparison_reused: true and comparison_reused_basis says that the id was scoped to the proof and the held comparison answered it. Change round_n when the measurement itself must run again.

Field	In	Type	Default	Required	Description
`source_snapshot_id`	body	string or null	`null`	Conditional	Exact source characterization snapshot. Provide it or `source_boundary_hash`; when both are supplied, the snapshot id wins. Maximum length `255`.
`target_snapshot_id`	body	string or null	`null`	Conditional	Exact target characterization snapshot. Provide it or `target_boundary_hash`; when both are supplied, the snapshot id wins. Maximum length `255`.
`source_boundary_hash`	body	string or null	`null`	Conditional	Source boundary hash whose latest snapshot is used when `source_snapshot_id` is omitted. Maximum length `255`.
`target_boundary_hash`	body	string or null	`null`	Conditional	Target boundary hash whose latest snapshot is used when `target_snapshot_id` is omitted. Maximum length `255`.
`title`	body	string or null	`null`	No	Business title shown as the comparison headline and stamped at creation in `provenance.title`. Maximum length `200`; surrounding whitespace is stripped and blank becomes `null`. Omitted or blank remains admitted during the deprecation period and adds `Deprecation: true` and `Warning` response headers.
`schema_map`	body	object or null	`null`	No	Maps source schema names to target schema names for a whole-schema relocation. A source object that a declared target model answers as input-only (loaded by the build but carried into no target object) does not need a schema-map entry solely to account for that input.
`object_map`	body	object or null	`null`	No	Per-object rename overrides, keyed and valued as `schema.object`. A value may be a one-element array, equivalent to the bare target name. An array naming several targets is rejected during comparison resolution because the addressing map is one-to-one; it is never silently reduced to one target.
`column_map`	body	object or null	`null`	No	Uses the same declared column-rename map as `POST /api/estate/system-diffs`; see that field for its shape and pairing rules. An entry that pairs nothing on the snapshots returns a proof run with status `refused` and `stop_reason: addressing_unresolvable` before a comparison run starts. A declared map is part of proof identity and is forwarded to the comparison.
`row_identity`	body	object or null	`null`	No	Caller-declared row identity in source coordinates: map each schema-qualified source object to one or more key terms, such as `{"PUBLIC.ORDERS": ["ORDER_ID"]}`. A term is a column name, `{"coalesce": ["col_a", "col_b", ...]}` for the first non-NULL value in order, or `{"concat": [<part>, <part>, ...], "sep": "<text>"}` for two or more distinct parts joined into one key position (`sep` is optional and defaults to empty text). A concat part is a column name or a coalesce term; text, integer, exact decimal, date, and UUID parts are rendered consistently, while float, timestamp, boolean, and binary parts are refused. If any concat part is NULL, the concatenated key is NULL. For example, `{"PUBLIC.CLAIMS": {"source": [{"concat": [{"coalesce": ["ICN_ADJ", "ICN_ORIG"]}, "LINE_NUM_ORIG"], "sep": "\|"}], "target": ["CLAIM_ITEM_ID"]}}`. Composite keys are positional. For a key column renamed across the migration, use the per-side form; the two lists must have equal length. When `target_model` splits a source object into several images, use `{"source": [...], "target": [...], "image": "schema.image"}` to name the one image whose columns the target terms name. The comparison refuses an image that is not declared for that split, or an `image` on an object the model does not split; see the Prover guide for how image-scoped keys affect findings and witnesses. The flat list is shorthand for the same terms on both sides. The proof admits the run, then the comparison probes each declared key on both sides; an unusable or unresolvable key refuses the pair rather than returning a submit-time `400`. If the probe cannot read a side as the submitting identity, the refusal keeps that declaration and reports it in `summary.unverifiable_objects` (`object`, `side`, `cause`); a key read successfully but found unusable is listed in `summary.unusable_objects` and omitted from the remedial `next` call. Omit the field to use only the engine-declared basis.
`declared_relations`	body	array of strings or null	`null`	No	Relocation premise (decision 10): schema-qualified relation names in target coordinates, where the relations must end up. The pair binds at the first repair round whose target holds every declared relation; later rounds reuse that bound target. Requires explicit `round_n`, `source_snapshot_id`, and `target_snapshot_id`; names must be resolvable catalog names, with only letter case ignored.
`case_insensitive_object_names`	body	boolean or null	`null`	No	Per-comparison case-folding override. `null` uses `estate_char.comparison.case_insensitive_object_names`.
`change_expectation`	body	`must_match`, `must_differ`, or null	`null`	No	Caller-declared migration shape when no spec is attached: `must_match` means a lift-and-shift, so a clean comparison can be answered as `propose`; `must_differ` means the target should change, but licenses nothing without a spec and a clean comparison still points to `author_spec`. The proof records the declaration as `summary.declared_change_expectation`, attributed to the calling identity. With `spec_hash`, it must match the shape every structural item in the sealed spec declares or the request returns `422`.
`estate_id`	body	string or null	`null`	No	Optional named estate for run provenance and review-theater routing. Maximum length `255`.
`spec_hash`	body	string or null	`null`	No	Sealed compiled-spec hash to grade. Supplying it requires both connection ids and `ratify_source_contract`.
`source_connection_id`	body	string or null	`null`	Conditional	Registered source connection used by the grade; required with `spec_hash`.
`target_connection_id`	body	string or null	`null`	Conditional	Registered target connection used by the grade; required with `spec_hash`.
`invariant_side`	body	`source` or `target`	`source`	No	Fallback estate for single-relation invariant obligations that declare no `invariant_side` of their own.
`source_catalog`	body	string or null	`null`	No	Catalog the grade’s source reads resolve in; requires `spec_hash` (refused without it). Omit to use the database the source snapshot characterized when the engine binds a catalog (Databricks, Snowflake); otherwise the connection’s default.
`target_catalog`	body	string or null	`null`	No	Catalog the grade’s target reads resolve in, target-side invariants included; requires `spec_hash`. Omit to use the database the target snapshot characterized when the engine binds a catalog; otherwise the connection’s default.
`round_n`	body	integer	`0`	No	Repair round, bounded `0`..`500`, and part of proof idempotency.
`tiers`	body	array of strings or null	`null`	No	Grade tiers to run when `spec_hash` is supplied; omit to run every gradeable tier.
`wait_seconds`	query	number or null	`null`	No	Non-negative bounded wait. Values above `estate_char.api.max_wait_seconds` are clamped and reported in `wait.ceiling_seconds`; the proof continues after expiry.

For the spec_hash-specific omission behavior of row_identity and case_insensitive_object_names, see re-proving a spec. When declared_relations is supplied, the names are the relocation destination, not a second object map. The first round whose target snapshot holds every declared relation binds the proof to that target; later rounds compare against the same bound snapshot instead of taking a new one. A round where a declared relation is still absent is a normal failed proof naming the missing relations, not a hold. Because the binding is defined by round order and a fixed target snapshot, this mode requires an explicit round_n and both snapshot ids; boundary hashes alone are rejected for the relocation premise. The source must also hold the declared relations, or a greenfield sealed spec must declare them in its structural-item loci; the target must not have held them in the pre-build baseline. See Relocation proofs bind once for the evidence rules. The prior-binding read uses an indexed key for this relocation premise rather than scanning unrelated proof history. It examines at most 200 rounds for the premise; that window is scoped to the premise, not to all runs on the instance, so a repair loop should remain below 200 rounds for the baseline binding to remain in the lookup window. When row_identity is supplied, its shape is validated when the proof is submitted, but the live key probe belongs to the comparison that the proof commissions. A key that is absent, non-unique, or NULL-bearing on either side refuses that pair and identifies the side, key, and duplicate count; the proof is not silently retried as an identity-free comparison. A verified declaration is recorded as the pair’s row_identity_basis, contributes separately to summary.row_identity_evidence, and controls witness localization. It does not change column comparison semantics: those remain order-independent value-multiset digests. The response includes success, run_id, status, envelope, wait, reused, and superseded_by. The common envelope is the canonical poll shape; its summary also carries proof loop fields such as round_label, rounds_used, regressions, findings, unmeasured, unmeasured_elements, and stop_reason. unmeasured is the obligation population; unmeasured_elements is the separate comparison-element population whose reads did not happen. Each unmeasured_elements entry includes element_id, comparison, object_name, optional source and target columns or target object, an optional coded cause, and the read basis. unmeasured_elements_basis explains whether the list is a measured empty list or an unmeasured population. stop_reason is a classifier token, not prose; stop_reason_detail carries the human-readable explanation. Every proof summary keeps these keys present while running, using null plus a basis when the value is not measurable yet. The submit response also copies reused onto envelope.reused; it is true when an existing proof answered the submission and false when a new proof was started. A polled envelope has reused: null, because a stored run cannot know which caller submitted the request. Terminal statuses are succeeded, failed, refused, cancelled, and superseded. When change_expectation is supplied without spec_hash, summary.declared_change_expectation carries the declaration’s change_expectation, declared_by, basis, and meaning. A must_match declaration changes the clean no-spec next call to propose, because the unchanged target answers the declared lift-and-shift premise; a must_differ declaration does not license an empty difference set, so the clean no-spec next remains author_spec. If a supplied declaration disagrees with the sealed spec’s item shapes, the request returns 422 instead of grading it. With spec_hash, meaning names the attached spec: its items say which differences are intended, and the one-word declaration licenses nothing beyond them. In run classifications, classification.model_licensed is the subset of classification.platform_licensed accounted for by the declared target model rather than by a ratified platform rule. Relocation summaries expose premise_basis and the missing-relations basis; see Relocation proofs bind once for their values and refusal behavior. With wait_seconds, the route returns 200 if the proof terminalizes during the wait. If the wait expires first, it returns 202 with the same handle and wait.expired: true; the proof is not cancelled. Validation failures, including a missing side, an invalid round, or a spec without both connection ids, return 422. An unknown snapshot or boundary returns 404; an identical proof already being created can return 409. Before scheduling work, a graded proof validates the sealed artifact and its connections. An unknown spec_hash returns 404 with not_found; a malformed spec_hash returns 400 with validation; and an unregistered source_connection_id or target_connection_id returns 200 with a terminal refused proof run. The refusal summary has stop_reason: "connection_not_registered" and puts the human-readable explanation in stop_reason_detail; it lists the sides and ids in summary.unregistered_connections. No comparison or grade is created for that refusal. After registering the missing connection, submit the same request again. When tiers is supplied with spec_hash but does not include "structural", the proof is refused before either estate is opened. A proof always creates a comparison and grades by that comparison’s diff_hash; only the structural tier reads that hash. The response is 200 with a terminal refused proof run whose summary has stop_reason: "grade_reads_no_comparison", stop_reason_detail, and requested_tiers; no comparison child or grade child is created. Add "structural" to tiers to grade the comparison, or omit spec_hash to run the comparison alone. Both this refusal and an unregistered-connection refusal carry request_key: null, so they are terminal outcomes rather than idempotency answers for a later corrected submission. When the sealed spec declares a target_model, the proof and comparison summaries expose target_model_hash; the comparison also exposes split_key_evidence. The model-aware element and finding semantics are defined in Declared Data Vault target shapes. The comparison may publish an indeterminate column_content_digest finding with cause="object_unmeasured" when a requested column checksum could not be read; see the Prover comparison guide for the reporting conditions. A proof failure is classified separately from a grade-child failure. A proof that cannot be scheduled, or whose comparison or relocation orchestration raises, uses stop_reason: "proof_faulted". When the grade child reaches a terminal non-success, the proof carries the corresponding reason: grade_died for failed, grade_declined for refused, grade_claimed for superseded, and cancelled for cancelled. The detail is the grade’s recorded error when one exists; otherwise it explains the terminal status. These tokens let callers group terminal proofs without inspecting the child run. If the server loop stops during proof admission, the service returns an unavailable response rather than parking a proof that cannot run. A stop detected before hand-off means that nothing was admitted and the request can be retried after the replacement server is serving. A stop detected after hand-off is indeterminate: a store write may already be in flight. Once the server is serving, resubmit the identical request with the same client_request_id (or the same pair and round_n when no request id was supplied). Admission checks that request key and returns the run if one was created, rather than starting a second proof run.

`POST /api/estate/system-diffs`

title (body, string or null, maximum length 200) is the comparison’s business title — for example Foundry aviation: raw → ontology rebuild (spec-mediated) — stamped on the run’s provenance.title and shown as the comparison’s headline in the dashboard, above its technical source → target label. Omitting it, or sending a blank one, is deprecated: the request is still admitted, and the response carries Deprecation: true and a Warning header saying the title will be required. The agent tools prove, compare and grade already refuse an untitled call. For a newly created no-spec comparison, a closing parenthetical that names a spec, such as (spec X), is omitted from the stamped title because the comparison was not graded against that spec. If nothing remains, the comparison is untitled; when inherit_pair_title is enabled, it can inherit the pair’s eligible title instead. Live re-reads performed by a comparison use the authenticated submitter’s connection access, not the agent identity that may have commissioned the run. The agent remains in the run’s provenance; a personal connection must be readable by the submitting user.

Field	In	Type	Default	Required	Description
`source_snapshot_id`	body	string or null	`null`	Conditional	Exact characterization snapshot for the source side. Maximum length `255`.
`target_snapshot_id`	body	string or null	`null`	Conditional	Exact characterization snapshot for the target side. Maximum length `255`.
`source_boundary_hash`	body	string or null	`null`	Conditional	Source boundary hash; resolves to that boundary’s latest snapshot. Maximum length `255`.
`target_boundary_hash`	body	string or null	`null`	Conditional	Target boundary hash; resolves to that boundary’s latest snapshot. Maximum length `255`.
`title`	body	string or null	`null`	No	Business title shown as the comparison headline and stamped at creation in `provenance.title`. Maximum length `200`; surrounding whitespace is stripped and blank becomes `null`. Omitted or blank remains admitted during the deprecation period and adds `Deprecation: true` and `Warning` response headers.
`delta_hash`	body	string or null	`null`	No	Stored Δ (intended-changes) artifact; omit for the empty delta (faithful migration). Maximum length `255`.
`schema_map`	body	object or null	`null`	No	Schema addressing map (ν): source schema name → target schema name for renames. Every key must name a schema in the source snapshot and every value a schema in the target snapshot; otherwise the request returns `400` naming the invalid entry.
`object_map`	body	object or null	`null`	No	Object addressing map (ν): source object → target object for renames, written as `schema.object`. Each key must resolve to one source object and each value to one target object. A bare name is accepted only when unique on that side; unresolved or ambiguous entries return `400` naming the entry. A one-element array is equivalent to its single target name. An array naming several targets is rejected with `400` because ν carries one image per source object; it is never resolved to one of them. The map is normalized to schema-qualified names before the run.
`column_map`	body	object or null	`null`	No	Declared column renames in source coordinates, keyed by source `schema.object` like `object_map` (or a bare object name only when unique), with `{source_column: target_column}` pairs; for example, `{"MAIN.FLIGHTS": {"flight_id": "flightId"}}`. The target column is resolved on that source object’s image after the delta’s object move and the schema/object maps. Column names must match exactly. A declared pair produces a licensed `column_renamed` and its content is compared; without a declaration, the rename remains `column_missing` plus `column_surplus`. An entry that pairs nothing is rejected with `400` before a run is created, naming the problems, including absent columns, self-maps, duplicate target columns, a target already paired by name, or a rename already made by the delta.
`case_insensitive_object_names`	body	boolean or null	`null`	No	Per-comparison opt-in for case-insensitive catalog correspondence across objects, columns, and declared-key members. Omit (`null`) to defer to the instance-wide `estate_char.comparison.case_insensitive_object_names` setting; `true` or `false` overrides this policy for the comparison only. Use `true` for cross-engine pairs whose target folds identifier case on create (for example MSSQL → Snowflake or Postgres → Databricks); leave `false` or omit for same-engine pairs. A binding addressing rule can independently supply an explicit fold even when this option is `false`; fold collisions now fail closed, so rerunning such an affected comparison can change findings, match counts, and its hash. Existing callers that already pass `true` will now stop receiving case-only column and declared-key findings as well as object findings. To retain the earlier object-only result when no binding fold applies, pass `false`, provide explicit `object_map` correspondence, and rerun; stored prior diffs are unchanged.
`declared_quiescent`	body	boolean	`false`	No	Operator attestation that both systems were static (frozen — no writes in flight) across this comparison. When `true`, a content/row digest on an `append_only`/`mutable` object decides instead of abstaining under observation skew, and the attestation is recorded on the decided element’s `relied_on` (basis `declared_quiescent`, the attester, the note). Mirrors the stimulus differential’s quiescence declaration. Default `false` keeps a comparison abstaining honestly.
`quiescence_note`	body	string or null	`null`	No	Free-text who/why for the static attestation (for example, `static demo fixture — attested by operator session`), recorded on decided elements’ `relied_on` for audit. Ignored unless `declared_quiescent` is `true`. Maximum length `2048`.
`row_identity`	body	object or null	`null`	No	Caller-declared row identity in source coordinates: map each schema-qualified source object (`schema.object`) to one or more key terms. A term is a column name, `{"nullif": ["column", "<text>"]}` to read that exact text as NULL, `{"coalesce": ["col_a", "col_b", ...]}` for the first non-NULL of at least two distinct operands, or `{"concat": [<part>, <part>, ...], "sep": "<text>"}` joining two or more distinct parts into one key position (`sep` is optional and defaults to empty text). A `nullif` term may stand alone, inside `coalesce`, or as a `concat` part; a concat part is a column, `nullif`, or `coalesce` term. Text, integer, exact decimal, date, and UUID parts are rendered consistently, while float, timestamp, boolean, and binary parts are refused. If any key term evaluates to NULL, the key is NULL. For example, `{"schema.claims": {"source": [{"coalesce": [{"nullif": ["icn_adj", ""]}, "icn_orig"]}], "target": ["claim_id"]}}`. Composite keys are positional; each object must be declared once and each key term once. A renamed key column can use the per-side form; the two lists are paired positionally and must have equal length. When the sealed `target_model` declares a derived target, put its row key on that target’s driving input (the first item in `sources`), with source terms named on the input and target terms named on the derived target; see the Prover guide for columns compared during witness localization. For a split legacy object, name the one image in the per-side form, for example `{"source": ["legacy_id"], "target": ["hub_id"], "image": "MAIN.HUB_CUSTOMER"}`; target terms name that image’s columns. The image must be one the sealed model declares for the split; see the Prover guide for image-scoped findings and witness behavior. Genesis probes every declared key for uniqueness, NULL-bearing rows, and presence on both sides before creating a run; a failed or unresolvable declaration returns `400` naming the side, key, and duplicate count, and no run is created. An empty object is invalid; omit the field to use only the engine-declared basis.

The result may include an unlicensed addressing_incoherence finding for columns whose names look like convention-only renames. It is a suggestion, not a pairing; the Prover comparison guide describes when it appears and how column_map resolves it. Each side must be identified by exactly one of *_snapshot_id or *_boundary_hash (a snapshot id wins when both are given). If a boundary hash is used but no characterization snapshot exists for that boundary, the request fails with 400. Submit-and-return (like POST /api/estate/characterize): the response returns immediately with run_id, top-level status: "running", and data containing run_id, status, pair_fingerprint, component_pair, source_snapshot_id, and target_snapshot_id. The mediated diff (forward + backward, content comparison, findings reconciliation) runs as a background task. The returned pair_fingerprint is the scope-independent identity of the resolved snapshot pair used for live event routing; after the pair’s scope changes, it can differ from the observed <source_boundary_hash>-><target_boundary_hash> pair. If no snapshot-pair identity is available, it falls back to that boundary-hash pair. Follow progress live over /api/ws/estate/live?run_id=<run_id> or /api/ws/estate/live?pair=<pair_fingerprint>, or poll GET /api/estate/runs/{run_id}. The optional Idempotency-Key request header is part of the submission identity. An identical comparison submission is answered by the run that already owns it: reused: true and reused_basis identify that run, whether it is still queued/running or has finished. An in-flight response has no diff_hash yet, so poll its run_id; a finished response includes the existing result. A failed or cancelled comparison releases the identity for a later retry, while a new submission returns reused: false. A distinct header value makes a distinct question, but it does not bypass the one-comparison-per-pair resource guard: while another question on the same pair is running, the request can still return 409. When a no-spec submission reuses a comparison whose title was recorded under a spec, the response’s provenance.title omits its closing parenthetical. This changes only the returned copy; the stored comparison title remains unchanged in the listing and on the proof that graded it under that spec. The completed comparison records diff_engine_version and diff_engine_digest. A pinned retired-engine comparison returns 409; reuse and recomputation semantics are defined in the [Prover comparison guide] (/docs/Genesis-Prover/Overview#2-comparison-the-system-diff). After the comparison reaches a terminal state, its run summary includes auto_envelope. This object reports materialized, status, run_id, and basis: materialized: true means this comparison minted an envelope or an earlier run already owns one, materialized: false means the envelope attempt failed, and null means the comparison was not measured for envelope creation (for example, the feature was disabled or the run was a stimulus differential). The per-diff hook is enabled by estate_char.comparison.auto_envelope, whose default is true; when it creates an envelope it runs a second spec_conformance grade, and it is idempotent for a given diff_hash. A normal skipped or disabled result does not fail the comparison. An identical comparison submission — the same resolved pair, addressing maps and case-folding policy, column_map, delta_hash, row_identity, quiescence attestation, round_label, and client request id when supplied — is answered by the run that already holds it instead of starting another run. The response sets reused: true both at the top level and on envelope.reused, returns the existing run_id, and reports that run’s status. A queued or running reuse has no diff_hash yet; poll the run before reading the comparison. A failed or cancelled comparison is not reused, so retrying after one of those statuses starts a new run. New submissions set reused: false; the response envelope is the row created for that run. Comparison reuse is scoped to the exact acting bot and authenticated human as well as the comparison inputs. A caller with a different identity receives a new comparison rather than the existing run’s result. A completed comparison is also not reused when a correspondence-rule binding for its pair moved at or after the run’s started_at. Ratification, pair-scoped review, or revocation records that change the binding clock therefore make a repeat submit a new comparison instead of returning the older result (for example, an earlier object_missing + object_surplus rename pair). The new run is what can report the ratified rule as object_relocated. A finished migration behavior proof for the same database-and-connection sides also ages a completed comparison; a run against another database on either connection does not. See Genesis Prover for how the run profiles identify those sides. If such a proof finished at or after the comparison started, an identical repeat recomputes instead of reusing the older comparison. Whether an individual rewritten view is licensed depends on a proof of its specific view pair, as described in fresh licensing evidence. When schema_map or object_map is supplied, Genesis resolves it against both snapshot inventories before creating the run. A completed run summary discloses the binding with schema_map_keys_submitted, schema_map_keys_bound, schema_map_keys_unbound, object_map_keys_submitted, object_map_keys_bound, and object_map_keys_unbound. These fields show which submitted keys matched the source inventory; an empty map binds nothing and is reported with zero counts. Invalid or ambiguous map entries are rejected with 400 at submission rather than producing a run whose intended pairs all appear missing or surplus. A source object declared by the target model as input-only is answered by that model, including when the build loads it into no target object, so it does not require a schema-map entry merely to avoid an unbound-schema refusal. When row_identity is supplied, its live uniqueness probe runs on both sides under the same snapshot addressing and any ratified delta used by the comparison. A verified declaration becomes the pair’s row_identity_basis and selects the key used to localize witness rows; it does not change the column comparison, which remains an order-independent value-multiset digest. For agent, headless, or stored re-run paths that perform the probe inside the diff, a key that is not unique, contains NULLs, is absent, or cannot be resolved withholds that pair behind an indeterminate row-identity element rather than silently falling back to digest-only localization. The API submission path rejects the same failure with 400 before creating a run. Probe counts are kept separately in the run’s summary.row_identity_evidence and are attributed to that run. For a pair whose binding rules declare exactly one digest quantum, the system diff re-measures approximate columns on each side when measurement versions are compatible. The re-measure is best effort: if no quantum is declared, versions are incompatible, or a side cannot be read, the comparison uses the exact snapshot digests instead. Inspect summary.quantized_remeasure on the completed run to see whether the quantum was minted, its significant_digits and rule_id, and the re-measured column count for each side. The completed summary’s findings object also reports closed_by_license separately from closed_by_reverification; a licensed difference closes under licensed_by_rule because the rule allows it, not because a repair was verified. The whole-table content digest is folded over the licensed-comparable columns. When a licensed column, or a column held by only one side, would make the whole-table digest differ by construction, the diff performs a best-effort live re-fold over the comparable columns for that object instead of treating the digest as actionable drift. This re-fold is automatic, pair-scoped, and only runs for objects the initial diff cannot decide from its snapshots; it uses one live table scan per requested object and falls back to abstention if either side cannot be read. Inspect summary.comparable_digest_refold for folded, objects_asked, objects_folded, source_objects_read, target_objects_read, failures, and errored_reads. folded is true only when every asked object folded on both sides and no read errored. failures is always present; each entry identifies the object, its sqlstate when supplied by the driver, whether the failure is retryable, and a basis. A retryable transport failure receives one bounded retry; an engine refusal is reported without retrying. A locus the comparison could not decide — an indeterminate element — closes nothing. Its open finding stays open and its lifecycle entry records coverage_qualifier: "indeterminate", kept distinct from not_exercised (the run never reached the locus) and from resolved_verified (the run swept it and found nothing). Older lifecycle events written with "undecided" are read back as "indeterminate"; the stored history is not rewritten. An abstention is not a re-verification, so it never appears in finding_counts.closed. If a comparable re-read errors, the affected element uses verdict errored and cause comparable_fold_errored; it is not counted as indeterminate, and the comparison summary reports errored_reads separately with clean: false. This means the comparison is unmeasured for that element rather than evidence of drift. Two additional causes are intentionally indeterminate rather than unlicensed: cross_representation_precision_unverified means boundary values agree to float precision but an exact numeric side may contain unobserved digits, while outside_characterized_scope means a target object lies outside the characterized source boundary and the source scan never measured the surface being compared. Completed mediated-diff payloads also include verdict_bases, a compact map of the verdict meanings and named causes present in that diff; use it when relaying why a comparison is indeterminate rather than treating all abstentions as the same. Live events stream in order: phase("diff") → family_found → element_verdict → phase("fold") → summary → done.

Status	Meaning
`400`	Validation failure (for example neither snapshot id nor boundary hash for a side, no snapshot for a boundary hash, or a schema/object map entry that is unresolved or ambiguous).
`404`	Unknown `source_snapshot_id` or `target_snapshot_id`.
`409`	A different comparison question is already running for the same source/target pair, or two identical submissions raced before either run row existed; wait for the existing pair run and retry if necessary.

`GET /api/estate/system-diffs`

Field	In	Type	Default	Required	Description
`include_archived`	query	boolean	`false`	No	When `true`, include comparisons whose source or target estate is archived. Nothing is deleted from the store; archived comparisons are omitted by default because archiving an estate retires its comparisons from the live grid.
`limit`	query	integer or null	none	No	Optional response page size between `1` and `1000`. There is deliberately no default: the landing needs the complete set to derive one featured card per physical boundary pair.
`cursor`	query	string or null	none	No	Opaque `next_cursor` from the previous response. Pass it back unchanged to continue with older comparisons.

Successful responses include data as mediated-diff summaries (verdict counts only, no payload), newest first. next_cursor and has_more are always present; they are null and false when the request is the unbounded whole-board read. When limit is provided, has_more reports whether an older page exists and next_cursor resumes after the last returned row. The bound limits the response page, not the database reads used to curate pair identity and featured runs. The response also includes hidden, counting withheld comparison cards rather than withheld runs: one per estate pair (per scan scope when both endpoints belong to one estate), however many runs were withheld. A card does not count as hidden if the caller can still see a run for it. This is separate from has_more, which reports older rows available through pagination. The count can include pairs the Prover grid itself omits under sandbox or utility estates. Each row is enriched for the comparison list:

Field	Type	Description
`direction`	string	Comparison orientation (`forward` or `backward`).
`source_estate_id` / `target_estate_id`	string or null	Resolved estate that owns each snapshot (`null` when the endpoint cannot be bound to an estate).
`retired_by_archive`	boolean	`true` when either endpoint’s estate is archived.
`pair_key`	string	Stable source→target BOUNDARY-pair identity (re-scans mint new snapshot ids but stay on the same pair). Keyed on the physical boundary, so an operator-registered estate, the boot backfill’s `estate_bf_` twin over the same database, and snapshots no scan bound to either all land on one pair. Where several registrations answer for one database the fold does not apply and each stays its own pair.
`is_latest_for_pair`	boolean	`true` for the pair’s forward comparison answered by the most recently started `prove` or `system_diff` run — the card the grid leads with. A run counts whether it minted the comparison or reused it, so a re-prove can make an existing comparison latest. If a proof run names a comparison, only proof runs determine its recency; otherwise a standalone `system_diff` run can determine it. When no run names a comparison, its creation time is used. Exactly one eligible forward comparison per BOUNDARY pair carries the flag: the newest by instant, with `diff_hash` breaking a tie. Stimulus differentials (`stimulus_evidence: true`) are skipped; if every forward comparison for a pair is stimulus evidence, none are featured.
`is_latest_for_pair_basis`	string	Which rule resolved each side of the pair the flag was judged in, as `"<source>=><target>"`. Each half is `boundary_group` (the boundary’s group representative), `estate` (the bound estate row itself), `database` (an unbound snapshot over a database several registrations answer for) or `snapshot` (nothing known about the endpoint). Present with a value on every row.
`pair_run_count`	integer	Number of forward runs for this pair (older runs stay addressable via `?diff=<hash>`).
`source_engine` / `source_database` / `target_engine` / `target_database`	string or null	Resolved snapshot engines and databases.
`display_name` / `highlight_rank` / `is_highlight`	string, integer, or boolean	Present when the forward migration target is a curated highlight whose source is the `estatebench` oracle with a `postgres` or `postgresql` dialect. A target name alone is not sufficient; comparisons from another source carry `null` / `null` / `false`.
`provenance`	string	`"real"` or `"synthetic"`. Classifies whether the comparison is a genuine migration (`"real"`) or a source-hardening artifact (`"synthetic"`). Classification is durable-first, then name fallbacks; ambiguous or unknown endpoints default to `"real"`. Durable signals (either endpoint): estate `kind="utility"` or `payload.synthetic=true`. Name fallbacks (when no durable signal): curated adversarial/sabotage highlight targets; drill-clone database name patterns (for example `-source-<hash>` / `-target-<hash>`, `selfdrill.`, sandbox names); or a legacy base-registration scratch estate whose display name* matches `source registration` / `target registration` (estates registered before `payload.synthetic` stamping — new registrations carry the durable flag and do not rely on this fallback). Stimulus differential evidence is always forced to `"synthetic"`.
`stimulus_evidence`	boolean	`true` on stimulus differential evidence diffs (Protocol V2 s4). These rows are excluded from the `is_latest_for_pair` pick so a stimulus run cannot displace the comparison it measured.
`published_unlicensed_count` / `published_indeterminate_count`	integer or null	Counts published by the minting run. They exclude readings withheld for an undeclared target shape; `null` means the run’s withholding could not be read.
`title`	string or null	Business title recorded on the comparison’s minting run, or `null` when that run has no title. The Prover landing and review use it as the headline; untitled comparisons retain the technical source → target label.
`withheld_unlicensed` / `withheld_indeterminate`	integer or null	Counts measured but withheld by the minting run for an undeclared target shape; `null` means nothing was withheld or the withholding could not be read.
`errored_reads`	null	Always `null` in the comparison list because the list resolves rows in SQL without decoding each stored element document. Read `GET /api/estate/system-diffs/{diff_hash}` for the count.
`clean`	null	Always `null` in the comparison list. The list cannot certify cleanliness without reading the elements, and deriving it from only `unlicensed_count` and `indeterminate_count` could report a false green when errored reads are present.
`tallies_basis`	string	Explains why the list does not measure `errored_reads` or `clean`; use the single-diff route for those values.
`ruling_rollup`	object or absent	Server-resolved ruling residue and Human Review settlement for the comparison. Includes `person_ruled`, `instrument_void`, `behavioral_open`, `grade_run_id`, `review_decision`, and optional `review_readiness`; see the field details below. Absent when the enrichment reads fail.

ruling_rollup contains integer counts for the featured comparison’s settled residue and the pair’s open behavioral catches, plus the current Human Review settlement state for the comparison:

Field	Description
`ruling_rollup.person_ruled`	Open findings in the featured comparison settled by a person’s recorded ruling.
`ruling_rollup.instrument_void`	Open findings in the featured comparison settled as instrument-invalid.
`ruling_rollup.behavioral_open`	Open stimulus-layer findings across the comparison’s pair; these remain open because a ruling does not settle them.
`ruling_rollup.grade_run_id`	The sealed-spec grading run used to resolve the settled buckets, or `null` when the comparison is ungraded.
`ruling_rollup.review_decision`	The Human Review run decision that currently settles the comparison outside the finding ledger: `"approved"` or `"approved_with_exceptions"`. Before the listing returns a recorded decision, it revalidates that decision against the selected comparison’s element-bound review population. `null` when no current, population-matched settling decision accounts for the comparison, including when no completed conformance run is available for that population.
`ruling_rollup.review_readiness`	Object or `null` describing the selected run’s complete review population. It contains `population_complete` (boolean), `remaining_count` (integer), `recorded_exceptions` (integer), `person_accepted_differences` (integer or `null`), `nothing_compared` (boolean), and `person_acceptance` (object or `null`). `person_accepted_differences` counts the `unexpected_change` members a person accepted — by a ruling that is not settled as a false alarm, or by a one-time exception bound to this population — that each represent one diff element; each member counts once, and scope-surplus members, undecided (evidence) members, members of a partially false-alarmed ruling group, and exceptions naming a finding the population does not carry are excluded. It is `0` when a complete population has no such rulings and `null` when the population is incomplete. When `population_complete` is `true`, `remaining_count` is `0`, and `nothing_compared` is `false`, the run is fully accounted for and the comparison can read settled without a recorded `review_decision`. A comparison that matched nothing cannot read settled, even with no remaining members. `person_acceptance`, when non-null, has the `accepted_by_person` outcome described by the comparison review response and means verified people’s standing approvals cover every item that kept this comparison off Verified; no run decision is required, and the machine grade remains unchanged. See the comparison review response for the complete conditions and fields. `spec_grade`, when present, is the spec grade standing for a reshaped build whose tables paired none; it is the same object the review population carries, and a verified one is what the review page’s approval rule reads in place of the empty pairing. `null` means readiness was unavailable or no applicable run/population was resolved; it does not mean the population is complete. An older server may omit `person_accepted_differences`.
`ruling_rollup.source_moved_since_approval`	Object or absent. When present, discloses whether the source estate has CHANGED since the snapshot the standing approval was recorded against. It includes `count` (later readings whose measured content differs from the bound one), `readings_since` (later readings of any kind), `basis`, `approved_snapshot_id`, `latest_snapshot_id`, `latest_at`, `latest_changed_snapshot_id`, and `latest_changed_at`; `count` and `readings_since` are numeric only for `basis` `measured`, `no_newer_snapshot` or `no_content_change`. The disclosure does not withdraw the approval.
`ruling_rollup.target_moved_since_approval`	Object or absent. The same disclosure for the target estate. A missing field means the batched movement read was unavailable, not that the estate is unchanged.

For person_accepted_differences, only a person’s ruling or a population-bound one-time exception counts as person-settled. A finding claimed through attributed_to or rule_ids is grade-licensed, not person-settled, only when the grade re-sorted counts; a finding marked unaccounted remains outside that license. The rollup is an enrichment, not a reason to omit the comparison. If its supporting reads fail, the row is returned without ruling_rollup so clients can show an unresolved ruling state rather than treating missing data as zero. The readiness result is computed from the complete, element-bound Human Review population; it is not a count inferred by subtracting ledger totals from an element count. Only featured (is_latest_for_pair) comparison cards receive this optional readiness evaluation and the approval-movement disclosures. If the movement read fails, those fields are omitted rather than reported as a clean zero. For a comparison with a recorded settling decision, the listing uses the same population resolution as the Human Review read before reporting review_decision. This keeps the card’s approval state and the review page’s approval state aligned: an incomplete or unavailable comparison population cannot make an approval appear to stand on the card when the review read has withdrawn it. Individual diff detail (GET /api/estate/system-diffs/{diff_hash}) and dossier readers are unchanged — they still see full history regardless of archive state.

`GET /api/estate/comparisons/{diff_hash}/export`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Content-addressed comparison id to export.

Requires view_connections. The response’s data is a portable bundle with an envelope (bundle_type, bundle_version, contract, exported_at, source_server, connection_refs, estate_ids, and adjudications_excluded) and a tables map containing the comparison and the rows needed to render its card: its run family, snapshots and measured objects, estates and scans, review events, exhibited findings, the adjudication proceedings that ruled on those findings with their verdicts, compiled specs, and cited correspondence rules. Connection values are references only. Stored JSON is scanned and credential-shaped fields are replaced before export. The bundle preserves the comparison’s diff_hash; it is not a re-run and does not need the source or target database credentials. An unknown comparison returns 404. Only a terminal adjudication travels. A proceeding still running on this server is left out and named in envelope.adjudications_excluded with basis excluded_by_design, because nothing on the receiving server would ever finish it and that server’s own reconcile sweep would terminalize it as failed. bundle_version is 2; an importer that reads a different version refuses the bundle on the envelope rather than applying the sections it recognises. This is an expensive read: about two dozen indexed store reads plus JSON decoding for the returned payloads, which can be several megabytes for a real comparison.

`POST /api/estate/comparisons/import/validate`

Field	In	Type	Default	Required	Description
`bundle`	body	object	none	Yes	Bundle returned by the export endpoint, passed verbatim.
`on_conflict`	body	enum	`refuse`	No	`refuse`, `skip`, or `replace`; controls how existing rows are handled in the plan.

Requires ratify_source_contract. This side-effect-free endpoint reports what the bundle would create or collide with, the estate ids it would adopt rather than twin, the durable finding numbers it would remap, blockers, and which referenced connections are registered on this deployment. A collision is disqualifying only when on_conflict is refuse; a missing connection is reported but does not prevent the imported card from being read. A blocker — a unique value a different row on this deployment already owns, checked against every uniqueness constraint the tables declare rather than against the row identity alone — is disqualifying under every mode, so valid is false whenever one is present. blocking_count is the exact total; blockers is a bounded sample of it, because one blocker is enough to refuse and every row of a large bundle can collide. Validation performs indexed existence reads and writes nothing. A malformed or unreadable bundle returns 400.

`POST /api/estate/comparisons/import`

Field	In	Type	Default	Required	Description
`bundle`	body	object	none	Yes	Bundle returned by the export endpoint, passed verbatim.
`on_conflict`	body	enum	`refuse`	No	`refuse` stops on the first existing row; `skip` leaves existing rows alone; `replace` overwrites comparison-owned rows.

Requires ratify_source_contract. The import writes the bundle in one transaction; it does not re-characterize either estate or re-decide the review. The original review author and timestamp remain on the imported review events, while the importing caller is recorded separately as imported_from. Estates already present for the same database boundary are adopted, not duplicated, and the response includes the source-to-target estate_id_map. A finding’s durable number (durable_id, the #N a report cites) is a per-instance sequence under a unique index, not a portable identity, so it is remapped on import — the target’s own number where the target already holds the finding by finding_key, a freshly minted one otherwise — and the response includes the source-to-target durable_id_map. The finding lifecycle events that join on that number are remapped with it. The response reports per-table created, skipped, and replaced counts, imported_from, durable_id_map, and no_op (true when nothing was written, such as a repeat import). An import collision under refuse returns 409; an invalid bundle, an invalid mode, or a uniqueness value a different row already owns returns 400. The operation can read and write tens of thousands of rows for a real comparison; it decides every row before writing any, so a refusal writes nothing at all, and any later failure rolls back all writes. It owns its transaction and commits it while holding the process-wide durable-number mint lock, so no other allocator can take the same numbers between the allocation and the commit — and a concurrent findings reconcile waits for the length of the import.

`GET /api/estate/system-diffs/{diff_hash}`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Content-addressed mediated-diff id.
`shape`	query	string	`full`	No	`full` returns the decoded element document and derived `errored_reads` / `clean` values. `scope` returns comparison identity and stored counts without reading or returning `payload`; `verdict` cannot be combined with `scope`.
`verdict`	query	string	none	No	Filter `payload.elements` to one verdict: `match`, `licensed`, `unlicensed`, or `indeterminate`. Omit to return all elements.

Successful full responses include data with diff metadata and payload.elements (each element carries comparison, verdict, and object/column context). When present, payload.row_identity_basis discloses the identity basis for each object pair; it is separate from the run’s live uniqueness evidence. List summaries from GET /api/estate/system-diffs omit payload and expose verdict counts plus comparison-list enrichment: direction, resolved source_estate_id / target_estate_id, retired_by_archive, pair_key / is_latest_for_pair / is_latest_for_pair_basis / pair_run_count, source_engine / source_database / target_engine / target_database, and when the forward migration target is a curated highlight from the estatebench oracle (postgres or postgresql source dialect), display_name, highlight_rank, and is_highlight. A customer proof from another source does not receive a curated label even if its target database name matches a curated target. full and scope detail responses also include source_estate_id, target_estate_id, and retired_by_archive, resolved using the same endpoint-estate rules as the comparison list but without reading the whole list. Producing these fields costs one batched snapshot-identity read, one estate-list read including archived rows, and two indexed scan-timeline reads. See the [comparison list contract] (/docs/Genesis-API/API-Reference#get-api-estate-system-diffs) for field meanings. Detail responses also include errored_reads, the number of persisted elements whose verdict is errored, and clean, which is true only when no persisted element is unlicensed, indeterminate, or errored. On a comparison with undeclared_target_shape guidance, the published unlicensed and indeterminate counts exclude withheld readings; read the comparison summary’s withheld_unlicensed and withheld_indeterminate fields to report those populations beside the published counts. These values are computed over all elements before applying an optional ?verdict= filter, so a filtered response still reports the comparison-wide counts. The response also carries comparable_digest_refold from the associated run summary, or null when the diff has no run, the run is gone, or no re-fold disclosure was recorded; see the re-fold fields documented above. The response also carries value_coverage for the direction identified by this diff_hash, including when shape=scope; see the [Prover comparison guide] (/docs/Genesis-Prover/Overview#2-comparison-the-system-diff) for its counting semantics and the distinction between an unavailable disclosure and values that were all compared. It also carries object_presence and not_measured for that same direction; their field shapes and null semantics are documented in the [review population response] (/docs/Genesis-API/API-Reference#get-api-estate-comparisons-diff-hash-review-population). Only shape=full also returns which_proof_applies. It explains each rewritten view in views[] (source_view, target_view, kind, reason, and behavior_proof_run_id), counts unchanged-text views in same_text_views with a shared same_text_reason, and identifies next_view. Kinds are needs_behavior_proof, behavior_proof_passed, behavior_proof_failed, behavior_proof_did_not_run, behavior_proof_passed_data_not_compared, data_differs, and data_explained_by_rule. This is explanatory evidence from the stored comparison, not a verdict; it is null for a backward comparison. It is computed over the comparison’s elements before an optional verdict filter, and is absent from scope responses. A view whose behavior_proof_run_id is set also carries test_case_coverage: run_id, a one-line sentence, situation_count, covered_count, by_side (original and rewritten, each situations and covered), covered[] and not_covered[] (each side, view, situation, claim_tag, case_ids), not_credited[] (claim, case_ids, why) with not_credited_count, not_matched[] (names, case_ids, why: the run’s test cases with coverage claims that name neither view) with not_matched_count, listed_up_to (the most entries each list holds), and caveat. It says which logic situations of the two view texts that run’s approved test cases claimed, as the agent stated when designing them; running the proof does not check it. A test case belongs to the view its output_relation names, compared on schema and name. If the relation matches no view in the comparison, Prover uses target_node’s dbt model name only when that name matches exactly one view pair. Each list is capped at listed_up_to entries, while the counts cover the full set; at most 25 views are worked out in one read, and any additional view reports that its coverage is not known. See the [Prover comparison guide] (/docs/Genesis-Prover/Overview#rewritten-views-and-behavior-proofs) for how to act on it. Detail responses also carry populations, the comparison’s two differently scoped counts of “differences” and the arithmetic over each — the same block the read_comparison tool publishes, from the same writer, so the tool answer and this one cannot be two readings of one row. populations.elements carries total, match, differing_or_indeterminate, decided, licensed, unlicensed, indeterminate, errored_reads, and basis; elements.total is the whole denominator (match + licensed + unlicensed + indeterminate + errored_reads) while differing_or_indeterminate is the narrower subtotal — adding the count columns yourself produces the second and reads as the first. populations.findings is the separately scoped ledger population and its total is null here because this route makes no findings read, and populations.why_they_differ says why the two must never be added. It is unconditional and costs nothing: every number is read off the row this route already built, and a count this shape did not make is null rather than a derived zero. The same detail response carries writer_attribution counts and the per-relation writer_readings used to derive them for target relations. The counts include the relations denominator plus attributed, unattributable, and unmeasured; the qualifier is null only when every relation was attributed to a re-runnable mechanism. A reading attributed from a Genesis Flow run also includes flow_run with flow_id, flow_name, flow_version, run_id, step_name, step_run_id, step_started_at, and step_completed_at. shape=scope omits writer_attribution and writer_readings because it does not read payload. The detail response also carries the assumption disclosure from the run that minted the comparison; see the Prover comparison guide for field semantics. When an assumption is withdrawn for the comparison’s estate pair, later comparison responses disclose it in withdrawn_assumptions. The withdrawal set is part of the next comparison’s request identity, so a comparison made before the withdrawal is not reused. The request identity and the withdrawal records used for the comparison are taken from one snapshot, so the run’s withdrawal bylines cannot change if the standing changes after the request is keyed. The stored verdict of an earlier comparison is unchanged; a sign-off whose pass relied on the withdrawn assumption is reported as reopened when review state is read. A later sealed specification records the withdrawals in its provenance as assumption_withdrawals, and read_spec exposes those citations under who_decided.

`GET /api/estate/system-diffs/{diff_hash}/assumptions`

The response’s data contains diff_hash, pair_fingerprint, component_pair, and an assumptions list. Each entry has id, statement, withdrawn, and withdrawal; withdrawal is null when the assumption stands, otherwise it includes id, statement, withdrawn_by, withdrawn_by_kind, withdrawn_at, and reason. The list contains the pair’s rule-borne assumptions and the target platform’s identifier-case and engine-collation licenses when this comparison relied on them. It can also include the built-in PostgreSQL type assumptions, the verified unique-index limitation, and the behavior-proven translated-view and source-built-output assumptions. Their ids include identifier_case:<platform>, collation_ordering:<component_pair>, platform_type:<component_pair>:<type-rule>, platform_cannot_enforce_unique:<platform>, translated_view_behavior_proven, and source_built_output. The Prover guide documents the conditions behind the new comparison assumptions.

`POST /api/estate/system-diffs/{diff_hash}/assumptions/{assumption_id}/withdraw`

Send an optional JSON body { "reason": "..." }. The response’s data contains event_id, pair_fingerprint, component_pair, assumption_id, action: "withdraw", the actor fields, reason, reopened, and created_at. reopened records the comparisons whose pass relied on the assumption at withdrawal time; it does not persist a sign-off status, which is recalculated when review state is read.

`POST /api/estate/system-diffs/{diff_hash}/assumptions/{assumption_id}/restore`

Send the same optional reason body. The response has the withdrawal response shape with action: "restore". A restore affects later comparisons; a sign-off reopened by a prior withdrawal stands again when the withdrawal is no longer in force and no other relied-on assumption reopens it. The full payload also includes licensed_breakdown, which gives the licensed element count by comparison and the provenance counts that contributed to it, and object_measurement_keys, the measured row-count/boundary fingerprints used to support unambiguous rename hypotheses. These derived disclosures do not change the diff hash. Case-folded column correspondence is recorded as licensed column_relocated elements. For categorical columns whose value-count key spaces cannot be lined up because float-rendering coverage is split or unknown, the element is indeterminate with cause="categorical_recipe_mismatch"; its relied_on.basis distinguishes recipe_split_unmeasured from recipe_unknown. For a comparison created by a sealed model-aware proof, the detail response also includes target_model_hash and split_key_evidence. Split elements carry provenance: ["model:split"]; model:ghost identifies declared ghost rows excluded from hub key readings, and model:metadata identifies columns derived by the vault load rather than carried from the legacy object. The comparison does not silently compare a legacy object to a satellite or link’s derived rows; those image contents remain unmeasured and the response explains that basis. The detail response also includes model_readings for model-aware comparisons. It maps each legacy object to the comparison kinds this run actually decided and the target objects read for them. An open finding on that object and kind remains not_exercised when the map has no such reading or does not include the finding’s target; absence from the current result is not treated as a re-verification. Use shape=scope when paging the comparison’s findings and the element document is not needed. The scope response identifies the comparison and carries its four stored counts, but omits payload, errored_reads, and clean rather than reporting unmeasured zeros. Every response names its shape in comparison_shape.

Status	Meaning
`404`	Mediated diff not found.

`GET /api/estate/system-diffs/{diff_hash}/families/{family_signature}/members`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Content-addressed mediated-diff id.
`family_signature`	path	string	none	Yes	Systemic-family id from the diff’s family rollup.
`status`	query	string	`open`	No	`open` (unresolved residual) or `all` (include closed members).
`offset`	query	integer	`0`	No	Pagination offset into the member set.
`limit`	query	integer	configured page size	No	Page size for this response. Defaults to and is clamped to `estate_char.findings.family_members_page_size` (schema default `500`). Page through with `offset`/`limit` to reach every member.

Successful responses include data with family_signature, total, offset, limit, and members (each an annotated finding with its evidence).

Status	Meaning
`404`	Mediated diff not found.

`GET /api/estate/fault-drill-coverage`

Field	In	Type	Default	Required	Description
`snapshot_id`	query	string	none	Yes	Characterization snapshot whose sealed contract’s fault-drill coverage to return.

Successful responses include data with available plus, when available is true, headline stats (coverage, obligation_coverage, drills_total, caught_total, survived_total, blind_spot_count, and related fields) and the full report (by_class per-mutation-class coverage, blind_spots, results). When no fault-drill run has produced a report for this snapshot yet, data is {"available": false} — trigger POST /api/estate/estates/{estate_id}/fault-drill on demand (the static meter no longer runs on every scan by default).

`GET /api/estate/behavioral`

Field	In	Type	Default	Required	Description
`component_pair`	query	string	none	Yes	Component pair to return the latest trajectory-campaign result for (for example `postgres->databricks`).

Legacy pair-scoped trajectory-campaign detail. Successful responses include data with available plus, when available is true, component_pair, diff_hash (the comparison the campaign was run against, null when none), reproducible, findings_count, candidate_engine, step_count, and verdicts — per-step outcomes (PASS / FAIL / MISSING with row-count and digest agreement) from feeding identical synthetic streams into both estates. When the pair has no trajectory-campaign run, data is {"available": false}. A component pair names engine types (for example postgres->databricks), which every comparison between two such estates shares, so this route can return a campaign about a different estate’s objects — anything rendered on one comparison must use GET /api/estate/behavioral/steps-for-diff/{diff_hash} (per-step markers) or GET /api/estate/behavioral/chip-for-diff/{diff_hash} (verification chip).

`GET /api/estate/behavioral/steps-for-diff/{diff_hash}`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Content-addressed mediated-diff id for the comparison whose per-step behavioral outcomes to resolve.

Diff-scoped per-step behavioral outcomes: the trajectory campaign run against this comparison (matched on its summary.diff_hash, never on the component pair) and its per-step agree/diverge verdicts, which back the comparison’s behavioral markers. Same data shape as GET /api/estate/behavioral; only the resolution rule differs. When no campaign was run against this comparison, data is {"available": false} and the UI renders no markers. Read-only.

`GET /api/estate/behavioral/chip-for-diff/{diff_hash}`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Content-addressed mediated-diff id for the comparison whose behavioral chip to resolve.

Diff-scoped, verdict-backed behavioral chip for a comparison. Resolves the stimulus run that stimulated this diff (same resolver as GET /api/estate/stimulus/run-for-diff/{diff_hash}) and reflects its authoritative verdict — not any trajectory that merely shares the estate pair. Successful responses include data with available plus, when available is true, verified (true only for a finished verdict with grading mode spec_graded or baseline_subtracted and unlicensed_count == 0; null/ungraded/running never verify), grading_mode, verdict (matched_count, licensed_count, unlicensed_count, indeterminate_count), status, run_id, diff_hash, rounds_succeeded, escalation_tier, and finding_severity. When the comparison was never stimulated, data is {"available": false} and the UI renders no chip. Read-only.

`GET /api/estate/stimulus/preflight`

Field	In	Type	Default	Required	Description
`diff_hash`	query	string or null	`null`	Conditional	Persisted mediated diff to check (its two snapshots define the pair).
`source_snapshot_id`	query	string or null	`null`	Conditional	Source characterization snapshot id.
`target_snapshot_id`	query	string or null	`null`	Conditional	Target characterization snapshot id.
`executor`	query	string or null	`null`	No	Executor name to validate. Omit to use the configured default (`genesis-agent`).

Provide diff_hash, or both source_snapshot_id and target_snapshot_id. Side-effect-free feasibility probe the compare / escalation dialogs call on open. Successful responses include data with possible (false on a hard blocker — feature off, unresolvable comparison, unreachable connection, unreadable registry, no configured executor/agent, no provable ETL for an agent-driven executor, or a pair contract that is stale or displaced), requires_override (true while possible stays true when a side is a live non-clone estate — the GUI requires an explicit in-place-injection confirmation), etl_provable (whether the comparison’s estates have a registered, cloned ETL code asset the stimulus can execute — always true for non-agent executors such as legacy-bench), reasons (named conditions/blockers), pair_contract (the resolution path, contract_hash when one is authoritative, stale, drifted, and any unverified_at_submit identities), and resolved context (diff_hash, component_pair, source_estate, target_estate). pair_contract.resolution is ratified, lineage, legacy_default, or displaced. Each reason carries code and message; per-side connection blockers also include side (source or target); requires_override reasons may include estates (named non-clone estates). Reason codes include feature_disabled, unresolved_comparison, requires_override, executor_unconfigured, etl_not_provable, agent_unconfigured, connection_unreachable, connection_registry_unreadable, pair_contract_missing, pair_contract_stale, and pair_contract_displaced. A missing contract warns when the legacy default can address the pair and hard-blocks when it cannot. When etl_not_provable, the message names the missing code asset and how to register and clone it. Read-only — never allocates a run or commissions an agent. An unresolvable comparison returns possible: false with a reason instead of HTTP 404.

`POST /api/estate/stimulus/run`

Field	In	Type	Default	Required	Description
`diff_hash`	body	string or null	`null`	Conditional	Persisted mediated diff to stimulate (its two snapshots define the pair). Maximum length `255`.
`source_snapshot_id`	body	string or null	`null`	Conditional	Source characterization snapshot id. Maximum length `255`.
`target_snapshot_id`	body	string or null	`null`	Conditional	Target characterization snapshot id. Maximum length `255`.
`executor`	body	string or null	`null`	No	Executor name. Omit to use the configured default (`genesis-agent`). Pass `legacy-bench` explicitly for the programmatic shopbench plumbing check.
`allow_in_place`	body	boolean	`false`	No	When `true`, override the clone-isolation gate and allow injection into a non-clone (production) estate. Default `false` — non-clone comparisons are refused.
`rounds`	body	integer or null	`null`	No	Number of escalating stimulus rounds to run. The server clamps to `[1, 5]`; omit to use the configured default (`estate_char.stimulus.rounds`).
`start_tier`	body	string or null	`null`	No	Tier the escalation ladder starts at for round 1: `nominal`, `boundary`, or `adversarial`. Omit (or `nominal`) to start at nominal; `boundary` / `adversarial` shift the ladder up for a deeper escalation run on the same comparison. Unknown values are rejected with `422`.

Provide diff_hash, or both source_snapshot_id and target_snapshot_id. Submit-and-return: an AI-designed synthetic edge batch is injected identically into the source and target clones, the downstream ETL is re-run on both sides, and the two worlds are handed to the deterministic differential comparison. A ratified or lineage-resolved pair contract supplies each input table’s logical-to-physical relation mapping, per-side column spellings, and island locator; the submission tools validate rows against each declared island before accepting them. Machine-checkable spec loci are resolved through that same contract: the logical locus remains the comparison identity, while each side’s declared physical relation, columns, and key predicate are used for SQL. A contract-less pair uses the legacy default, which binds its registered batch-manifest inputs late, uses the legacy id-column floor (id >= 900000), and discloses that provenance on the run. In contract mode, the ETL reply must preserve statements_run as separate source and target lists; provenance is verified against each side’s declared assets, and the pair is verified only when both sides pass. The response returns immediately with run_id, top-level status: "running", executor, and data. The default executor commissions a minutes-long Genesis agent mission (watchable over /api/ws/estate/live?run_id=); the designed batch, per-step evidence, agent thread id, completion report, and triggered follow-up land on the run row. Poll GET /api/estate/runs/{run_id}. When the run finishes, its summary.outcome includes aggregate prediction_counts, which discloses checked, confirmed, confirmed_source_oracle, confirmed_authored, violated, unreliable, unconfirmed, unpredictable, review_routed, malformed, and integrity_failures. A round can verify only when its sealed predictions are fully accounted for, have no unjudged, review-routed, or malformed entries, and either contain no sealed predictions or include source-oracle confirmation; authored-only matches are disclosed but do not provide confirming authority. Predictions that cannot be mechanically judged remain disclosed as non-confirming outcomes rather than being treated as a pass.

Status	Meaning
`400`	Stimulus is disabled (`estate_char.stimulus.enabled=false`), the executor is unknown, the clone-isolation gate refuses (`allow_in_place=false` on a non-clone estate), or the default `genesis-agent` executor cannot prove the ETL on every side. Under a contract, each side’s declared assets and attestation grade are checked independently; `invocation_attested` remains refused until the server-recorded invocation evidence exists. For content-traceable ETL, register and clone the required SQL/dbt asset, then retry; `legacy-bench` is exempt.
`503`	The `genesis-agent` executor was selected, but the model provider cannot commission it. With no provider configured, `details` is `"llm_provider_not_configured"`; when a configured provider does not answer, `details` is `"llm_provider_unreachable"` with `cause` (`login_expired`, `unreachable`, `rate_limited`, or `provider_error`) and `operator_detail`. No stimulus run is created.
`404`	Comparison or snapshot pair is unknown or not visible to the caller. Both cases answer alike.
`409`	A stimulus run is already in progress for the pair (single-flight); concurrent submissions are admitted by physical pair and the later run yields to the earlier one. Wait for it to finish before starting another. Stale (orphaned) runs are reconciled and do not block a fresh submit.

`GET /api/estate/findings`

Field	In	Type	Default	Required	Description
`component_pair`	query	string	none	No	Filter to one component pair (for example `postgres->databricks`).
`status`	query	string	`open`	No	`open`, `closed`, or `all` (returns both open and closed).
`view`	query	string	`rows`	No	`rows` returns the full finding rows. `rulings` returns only `finding_key`, `disposition`, `object_name`, `column` (with `column_name`, the same value under the ledger row’s own spelling), `updated_at`, `status`, `disposition_note`, `created_at`, and `superseded_by_pair`, without evidence or systemic-family annotation.
`include_consult`	query	boolean	`false`	No	When `true`, add each finding’s `consult_ruling` state block when it carries a Prover Consult ruling. The block includes the state, verdict, apply mode, and `ruling_digest_id` required by a decision; the ruling body is not included. This adds one database query per 500 rows, so it is off by default.
`include_evidence`	query	boolean	`false`	No	`rows` only. When `true`, include each finding’s evidence document (`source_value`, `target_value`, and sampled rows). It is off by default because it is the large column; combining it with `view=rulings` returns `400`.
`limit`	query	integer or null	`150`	No	Page size, clamped to `1`–`900` for slim rows, `1`–`500` with `include_consult=true`, or `1`–`150` with `include_evidence=true`. `null` requests the whole filtered ledger.
`cursor`	query	string or null	`null`	No	Opaque position from the previous page’s `next_cursor`; resumes strictly after that row using the `(created_at, finding_key)` keyset. A malformed, unreadable, timezone-naive, or ledger cursor returns `400`; see the ledger endpoint for cursor compatibility.

The response always includes data, next_cursor, and has_more. next_cursor is null on the final page; otherwise pass it as cursor to continue. Both rows and rulings use the same keyset, so view=rulings is bounded and resumable too. The rulings projection includes created_at as its resume anchor and still omits evidence and systemic-family annotation. The server reads one row beyond the requested page to set has_more; it does not count the full ledger. Each row includes finding_key, component_pair, comparison, object_name, optional column_name, status, disposition fields when set, evidence, and additive systemic-family fields when present: family_signature, family_direction, and family_pattern. family_signature_shape is persisted when those coordinates came from the finding row’s stored family stamp, or computed when they were derived from its evidence document for this response. Both views carry superseded_by_pair, the pair now used by the finding’s identity class when the row’s pair was superseded after a scope change; it is null when the row’s pair is still current or cannot be placed in a class. This read-time label is stamped after visibility filtering, so identity reads are made only for distinct pairs among the rows visible to the caller. For behavioral prediction findings, evidence preserves the measured column separately from the row selector. missing_row and predicted_value evidence includes row_key (the exact selector), key_column, key_value, predicted_value, source_value, and target_value; for missing_row, target_value is null and target_absent_reason is no row produced. When a side’s read matched one row whose cell was SQL NULL, measured_null lists that side (source or target); the receipt renders the cell as NULL, distinguishing a measured NULL from a value that was not read. detail remains a human-readable predicted-versus-actual receipt. Use view=rulings when joining recorded rulings to comparison rows. It applies the same component_pair and status filters while avoiding evidence decoding and systemic-family computation. updated_at is the ruling revision token for correlating this projection with a separate read that contains author or note details; created_at is the page-resume anchor. status is the finding lifecycle, so a request with status=all includes closed findings; disposition_note carries the grounds for the recorded verdict. The comparison listing uses this projection server-side to populate ruling_rollup before returning each row. The list routes do not emit the evidence document unless include_evidence=true is requested on view=rows; the server still reads it internally when computing systemic family annotations. For a complete ledger, follow next_cursor rather than expecting one unbounded response. When include_consult=true, rows with a Prover Consult ruling also include consult_ruling, or null when none exists. Its state is one of recorded, pending_approval, provisional, ratified, or declined; actionable indicates whether approve or decline is currently available. The ruling_digest_id identifies the exact ruling a human read and must be sent to either decision endpoint. Use the detail endpoint below to load the rationale, probes, guard, and constitution before deciding.

`GET /api/estate/findings/{finding_key}/consult-ruling`

Returns the current Prover Consult state and the full ruling body for one finding. The response includes finding_key, finding_id, ruling_digest_id, state, actionable, verdict, apply_mode, finding_sha, ruled_at, any decision metadata, and ruling with the seat’s rationale, probes, guard, and constitution version. It also carries requested_by_kind (agent, service, or null when the ruling was recorded before its origin was), requested_by_bot_id, decides_through_action_review, and action_review — the linked Action Review request (proposal_id, status, url, decided_by_label) or null. This is the read to use before approving or declining. It returns 404 when nobody has consulted about the finding.

`POST /api/estate/findings/{finding_key}/consult-ruling/request-approval`

Asks for Action Review approval of the recorded ruling. A ruling an agent or a service asked for — or one recorded before its origin was — is approved or declined only through this request (prover.approve_consult_ruling.v1); the approve and decline endpoints below answer it 409 with code: consult_requires_action_review. The caller becomes the requester and may decide the request. Idempotent: a request already asking is returned with replayed: true. Requires view_connections and a signed-in person when authentication is enabled; any person may request and decide it, with no special approval permission. A person’s own PAT is accepted and attributed to its owner.

Field	In	Type	Default	Required	Description
`finding_key`	path	string	none	Yes	Finding key from the ledger.
`ruling_digest_id`	body	string	none	Yes	Exact digest the caller read; the request is for that ruling only.

The response carries proposal_id, status, url (where a person decides it) and replayed. 409 with code: consult_approval_declined when a person (or a policy) declined its request, including after that decline is recorded on the finding — the ruling is closed and the next step is a new Consult ruling — code: consult_ruling_decided when the ruling was otherwise already decided, and a plain 409 when the digest is stale. 503 when the Action Review ledger is unavailable.

`POST /api/estate/findings/{finding_key}/consult-ruling/approve`

Approves the recorded ruling. Under human_approval, this seeds and ratifies its direction in one action. Under auto, it ratifies the provisional direction. Any signed-in person may approve or decline the ruling, including the person who requested it, without a special approval permission. The route requires view_connections; the person’s own PAT is attributed to its owner.

Field	In	Type	Default	Required	Description
`finding_key`	path	string	none	Yes	Finding key from the ledger.
`ruling_digest_id`	body	string	none	Yes	Exact digest from the finding’s `consult_ruling` block. A stale digest is rejected rather than applied to a newer ruling.
`note`	body	string or null	`null`	No	Optional decision note. Maximum length `2000`.

The successful data object includes decision: "approved", the resulting board: "ratified", the finding event event_id, and the ruling_id established.

`POST /api/estate/findings/{finding_key}/consult-ruling/decline`

Declines the recorded ruling. Under human_approval, nothing was seeded and the finding remains unlicensed. Under auto, the provisional direction is withdrawn only when it was established by this exact ruling. The request body and person-signing requirements are the same as the approve endpoint; its successful data object uses decision: "declined" and board: "declined".

Status	Meaning
`400`	The ruling is not an accepted ruling that can be decided, or it has no ambiguity slot to apply.
`403`	Caller lacks `view_connections` or does not have a signing identity.
`404`	The finding has no Prover Consult ruling.
`409`	`ruling_digest_id` is stale because the finding now carries a newer ruling; re-read the finding before deciding. With `code: consult_requires_action_review`, an agent or a service asked for the ruling: ask for approval instead.

`GET /api/estate/findings/dispositions`

Field	In	Type	Default	Required	Description
`component_pair`	query	string	none	No	Filter to one component pair.
`status`	query	string	`open`	No	`open`, `closed`, or `all`.
`diff_hash`	query	string	none	No	Filter to findings most recently exhibited by this comparison.
`comparison`	query	string	none	No	Filter by comparison class.
`object_name`	query	string	none	No	Filter by object name.
`disposition`	query	string	none	No	Recorded diagnosis, or `undiagnosed` for findings with no diagnosis.
`offset`	query	integer	`0`	No	Number of matching findings to skip; negative values are treated as `0`.
`limit`	query	integer	none	No	Maximum findings to return. When omitted, all filtered findings are returned.

The response includes findings, total, offset, limit, and by_disposition. Each finding carries its key, comparison and object coordinates — comparison, object_name, column (null at object grain), the spelling a graded drift_finding discrepancy declares, so the two surfaces join on the discrepancy’s own key; column_name carries the same value under the ledger row’s own spelling for one release — status, current disposition, disposition_note, dispositioned_by, disposition_proposed_by when an agent-staged package was used, dispositioned_under_model (the target_model_hash of the comparison reading the ruling judged), prover_defect_report_id, prover_defect_filing, prover_defect_filing_detail, waiver_owner, waiver_expires_at, last_seen_diff, updated_at, and superseded_by_pair. The latter is the pair now used by the finding’s identity class when its recorded pair was superseded after a scope change; otherwise it is null. It is a read-time label and does not move or close the finding. For an older finding whose waiver terms were not recorded, waiver_owner and waiver_expires_at are null; the API does not infer an expiry. For an instrument_defect ruling, prover_defect_filing is delivered, user_action_required, or failed; see False alarm (Prover) for the filing-status meanings. A ruling is honored only when the later comparison uses the same target model, including null for a comparison with no model. by_disposition counts the visible filtered set before paging and uses undiagnosed for findings whose disposition is null. Findings from comparisons the caller cannot see are omitted before paging and counting; a hidden diff_hash is returned as not found. The endpoint does not return evidence or systemic-family annotations. Invalid status or disposition values return 422 rather than an empty successful page.

`GET /api/estate/findings/ranked`

Field	In	Type	Default	Required	Description
`component_pair`	query	string	none	No	Filter to one component pair (for example `postgres->databricks`).
`status`	query	string	`open`	No	`open`, `closed`, or `all` (returns both open and closed).
`include_evidence`	query	boolean	`false`	No	Include each finding’s evidence document. It is omitted by default because it is the large column in the ledger.

Each row includes the flat finding fields plus blast-radius and plane annotations in rank order (highest deviation first). Evidence is included only when include_evidence=true.

`GET /api/estate/findings/ledger`

Field	In	Type	Default	Required	Description
`diff_hash`	query	string[]	none	No	Repeatable comparison diff hash. Naming one or more coordinates scopes the read and its lifecycle fold; a scope with no matching coordinate returns an empty page.
`run_id`	query	string[]	none	No	Repeatable stimulus-run id. Naming one or more coordinates scopes the read and its lifecycle fold. A finding belongs when its materialized pointers, provenance, or retained lifecycle events name either a supplied `diff_hash` or `run_id`.
`include_lineage`	query	boolean	`false`	No	Include each finding’s lifecycle `lineage` array. It is omitted by default because its size grows with the number of recorded transitions; `lineage_truncated` remains available either way.
`limit`	query	integer	`150`	No	Maximum rows to return. Values are clamped to `1`–`250`.
`cursor`	query	string or null	`null`	No	Opaque `next_cursor` from the previous response. Resumes strictly after the prior page using the `(first_minted_at, signature)` keyset, newest minted first. Each ledger cursor also carries the walk watermark. A malformed, timezone-naive, findings-listing, or pre-change ledger cursor returns `400`.

Returns a bounded page with data, next_cursor, and has_more. Follow next_cursor until has_more is false to walk the matching open set. The ledger is ordered by most recently minted finding first using (first_minted_at, signature), while updated_at remains available on each row for surfaces that need activity order. The watermark is the first row’s mint position on page 1; findings minted after the walk starts are excluded from that walk. A finding open for the whole walk is returned exactly once, but this is not an instantaneous snapshot: membership is evaluated when each page reads its mint position. A finding resolved before that page is read is omitted, and one that reopens after the cursor has passed its position waits for the next walk. Visibility is applied before the page limit, so each page is filled with rows the principal may see when enough remain. has_more reports whether more visible rows follow, and the opaque cursor resumes that admitted-row walk. hidden reports withheld findings encountered after this page’s last returned row in the current read window; on the final page it counts through the end of the walk. It is page-local, not a ledger-wide total. Each row is folded from the append-only lifecycle event log (estate_char_finding_events) and carries:

Field	Type	Description
`finding_id`	integer	Durable app-minted `#N` for the finding (reused across reopen).
`signature`	string	Content-addressed finding signature.
`state`	string	Current ledger state: `new`, `still_open`, or `reopened`.
`is_open`	boolean	Always `true` in this endpoint — resolved findings are omitted.
`streak`	integer	Consecutive runs that re-observed this finding while open.
`runs_since_opened`	integer	Runs since the current open occurrence began.
`opened_diff`	string or null	Diff hash where the finding was first opened (or last reopened).
`resolved_diff`	string or null	Diff hash where the finding was last resolved, when applicable.
`reopened_diff`	string or null	Diff hash of the most recent reopen, when applicable.
`recurrence`	integer or null	Recurrence count from the materialized projection when present.
`excepted`	boolean	Whether a human disposition is attached.
`disposition`	string or null	Human diagnosis when set.
`provenance`	object	First-mint provenance: `run_id`, `layer` (`at_rest` or `stimulus`), optional `round`, optional `tier`.
`first_minted_at`	string or null	ISO-8601 timestamp of the finding’s first mint. This immutable value is the ledger page and cursor ordering anchor.
`last_seen_run_id`	string or null	Run that most recently observed the finding.
`rests_on_reopened_seal`	object or null	Reopen notice when `last_seen_run_id` is a verdict over a seal whose clarification was overturned or withdrawn; otherwise `null`. Uses the same notice as the run’s `reopened` field and is derived at read time, not folded into the event history. For an open finding, relay the notice rather than reporting it as a live failure of a standing verdict; the finding remains open and its history is unchanged.
`updated_at`	string or null	ISO-8601 timestamp of the most recent lifecycle transition.
`lineage`	object[] (when requested)	Tamper-evident case history in chronological order. Each entry carries `state`, `run_id`, `diff_hash`, `layer`, `round`, `tier`, `coverage_qualifier`, `created_at`, `licensed_by`, and `disposition_contested`. For a `licensed_by_rule` close, `licensed_by` contains the rule provenance tags and `disposition_contested` is `true` when the standing diagnosis is `target_defect`.
`lineage_truncated`	boolean	Present and `true` only when the row was floored from the materialized projection because its events aged off the read window — lineage may be empty.

Resolved findings (no_longer_observed) are not returned here; load one by durable number with GET /api/estate/findings/{finding_id}/history. This ledger is distinct from GET /api/estate/findings (remediation-loop rows keyed by finding_key) and from GET /api/estate/findings/{finding_key}/episodes (reconciliation-episode sightings). A cursor minted by the findings listing is not valid here because the two endpoints walk the same key in opposite directions. Ledger cursors minted before the mint-position key change must also be discarded; restart the walk without cursor after upgrading.

`GET /api/estate/findings/ledger/summary`

Returns counts for the open ledger without the finding rows. The response has a data object with these keys:

Field	Type	Description
`open_total`	integer	Number of open lifecycle-ledger findings. Rows without a durable `finding_id` are excluded.
`by_state`	object	Counts by the materialized `prior_state` projection.
`by_layer`	object	Counts by provenance layer, such as `at_rest` or `stimulus`.
`by_pair`	object	One `{open, behavioral, at_rest}` count object per concrete `pair_fingerprint`.
`pair_unresolved`	object	`{open, behavioral, at_rest}` counts for rows whose estate pair is missing or carries the `pair_unknown` sentinel.

The summary reads the materialized open-findings projection and does not fold the event log. Its by_state values can therefore lag a lifecycle transition that is still inside the ledger fold window; use the ledger or a finding’s history when you need folded state for an individual finding.

`GET /api/estate/findings/{finding_id}/history`

Field	In	Type	Default	Required	Description
`finding_id`	path	integer	none	Yes	Durable `#N` from the cross-run lifecycle ledger.

Successful responses include data with the same folded lifecycle object shape as one row of GET /api/estate/findings/ledger (including lineage for both open and resolved findings). The history is a pure fold over the append-only event log — opened rX, resolved rY, reopened rZ — so it cannot disagree with the ledger’s current state. The response also derives rests_on_reopened_seal at read time, as described in the ledger response fields. That adds one scalar read for the run that last saw the finding and, when that run names a spec, reads of its seal provenance and reviews.

Status	Meaning
`404`	No finding carries that durable number, or the caller cannot see the comparison that minted it (`success: false`, `message` names the id).
`422`	`finding_id` is not an integer.

`GET /api/estate/comparison-events`

Field	In	Type	Default	Required	Description
`component_pair`	query	string	none	No	Filter to one component pair.
`limit`	query	integer	`25`	No	Maximum comparison events to return, newest first. Values are clamped to `1`–`20,000`; omitting it uses `25`.

Each event is one comparison run (A vs B at time t). Rows include diff_hash, run_id, component_pair, pair_fingerprint, delta_hash, source and target endpoint snapshots, created_at, verdict counts (licensed_count, unlicensed_count, indeterminate_count, matched_count), plus published_unlicensed_count / published_indeterminate_count and withheld_unlicensed / withheld_indeterminate. The published fields exclude readings withheld for an undeclared target shape; the withheld fields are null when nothing was withheld. Rows also include finding_counts (opened / recurred / closed), and the systemic-family rollup in families. Each family includes its signature and counts plus sample_members; each sample member carries finding_key, object_name, column_name, disposition, and an evidence object narrowed to source_value and target_value (or null when evidence is absent). The listing omits member_keys and full evidence documents; fetch one event’s findings for the complete rows. The settled_at_run object contains person_ruled and instrument_void counts from the residue this comparison measured, as they were settled when the run executed; it is null when that historical record is unavailable, not a zero count. A recorded run that only closed findings can legitimately return zero for both counts. Per-finding rows are not inlined; load them for one event via GET /api/estate/comparison-events/{diff_hash}/findings (newest events first). The response also includes truncated, which is true when more events remain beyond the page, and total_row_count, which is the exact event count only when the page is complete; it is null on a truncated page.

`GET /api/estate/comparison-events/{diff_hash}/findings`

The diff_hash path accepts an unambiguous 8-or-more-character prefix as well as the full digest; ambiguity and minimum-length refusals are described in the toolkit short hash contract.

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Content-addressed mediated-diff id for the comparison whose findings to return.
`view`	query	string	`rows`	No	`rows` (the full ledger rows), `index` (the element → finding-key join only), or `keys` (the naming fields needed to identify findings). Any other value is rejected with 422.
`family_signature`	query	string	none	No	Narrow to one systemic family, so opening a cluster costs that cluster rather than every finding the comparison exhibited.
`settlement_basis`	query	string	none	No	Narrow any view before pagination to `person_ruled`, `instrument_void`, `closed_by_diff`, or `unsettled`. Other values are rejected. `settlement_counts` still covers the whole comparison.
`offset`	query	integer	`0`	No	First row of the page. `rows` only.
`limit`	query	integer	configured page size	No	Page size for this response. Defaults to and is clamped to `estate_char.findings.family_members_page_size` (schema default `500`). `rows` only.

Successful responses include data as an object: {diff_hash, view, total, offset, limit, settlement_counts, settled_at_run, settled_at_run_basis, findings[]}. total is the count before slicing, so a caller knows how far it has to page. settlement_counts contains one count for each basis — person_ruled, instrument_void, closed_by_diff, and unsettled — across every finding the comparison exhibited, not only the returned page or a filtered family. settled_at_run repeats the parent comparison event’s historical split; null means that the as-of-run record is unknown, and settled_at_run_basis explains why. With view=rows, each entry of findings carries finding_key, comparison metadata (comparison, object_name, column_name when present), event_role (opened, recurred, or closed), decoded evidence, and systemic-family annotations when present (family_signature, family_direction, family_pattern). It also carries top-level column, detail, source_value, and target_value fields, read directly from the corresponding values in evidence rather than re-derived. Missing evidence values are null; when there is no evidence object, column falls back to column_name. Every row also carries rests_on_reopened_seal: the read-time reopen notice when the run that last saw the finding is a verdict over a seal whose ruling was withdrawn or overturned, otherwise null. The finding remains open; relay the notice rather than presenting it as a live failure of that ruling. Deriving the notice costs one indexed event query and one scalar run read per 500 rows, plus seal-provenance and review reads when any run names a spec. See the ledger response fields for the notice semantics. Every row also carries settlement: {settled, settlement_basis, settled_by, settled_by_basis, settled_at, settled_at_basis}. Read this block to determine whether the difference is accounted for; status, state, and closed_by_diff describe whether it is still observed, so a settled finding can still be open there. settlement_basis is one of person_ruled, instrument_void, closed_by_diff, or unsettled. settled_by identifies the person for the first two bases when the ledger has an identity; otherwise it is null and settled_by_basis explains why. settled_at is the instant the ledger stamped a person_ruled or instrument_void ruling, written in the same transaction as the verdict. It is never updated_at, which records the row’s last write of any kind. A legacy row ruled before disposition timestamps existed returns settled_at: null with a basis explaining that age; closed_by_diff and unsettled also return null with their own basis because neither is a person ruling. With view=index, each entry carries only the join coordinates (finding_key, comparison, object_name, column_name), event_role, the family (family_signature, family_direction), and disposition_at_run. Index entries carry the same settlement block as row entries. disposition_at_run is the finding’s disposition when this comparison ran, not its current ledger disposition. The response also includes dispositions_at_run_available: true only when a lifecycle record exists and covers every non-closed finding measured by the run. A false value means the historical rulings cannot be fully reconstructed; treat each missing disposition_at_run as unknown rather than as an unreviewed finding. Closure rows are excluded from this coverage because they were not part of the run’s residue. evidence is present only on a finding this comparison closed — a closure is absent from the comparison’s own measured elements by construction, so nothing else describes it. The index is never sliced (offset is 0, limit is null): a client joins every measured element against it, and a truncated join does not fail, it silently blanks the affordances that hang off a finding key. With view=rows, the page also carries person_acceptance, the reviewed outcome without its item list, or null when no person’s acceptance stands. It includes the same approver_names map described in the comparison review response. Each row carries person_accepted: true only when the person accepted that finding and the comparison reads Verified; when person_acceptance is null, all rows are false. This is separate from the machine lifecycle: the finding remains observed and can still have state: "still_open". The index and keys views carry neither field. The row view’s acceptance check costs one review-log field-patches query per page. If a verified person’s exception stands, it also folds the review outcome and resolves one population row. When that outcome stands, this includes an uncapped stimulus run-feed scan, a scoped finding-ledger fold, the population’s complete member set, and the comparison’s findings ledger. With view=keys, each entry carries only finding_key, event_role, object_name, column_name, and last_seen_diff. Use it to enumerate findings for disposition without transferring or decoding their evidence and lifecycle trail; page it with offset and limit like view=rows. settlement_basis applies to every view before the page is cut, so a filtered page is a subset of the comparison, not merely a filter over one page; settlement_counts remains the whole-comparison denominator. Returns an empty page (total: 0) when the diff hash was never recorded — a comparison that exhibited nothing and one that was never run are the same absence to a reviewer, so neither is an error.

`GET /api/estate/findings/families`

Field	In	Type	Default	Required	Description
`component_pair`	query	string	none	No	Filter to one component pair.
`status`	query	string	`open`	No	`open`, `closed`, or `all` (returns both open and closed).
`with_deferrals`	query	boolean	`false`	No	When `true`, include `deferred_family_signatures` with the signatures of listed families parked by the current person. The value is opt-in because it performs an additional notes read.

Each row summarizes one systemic family: family_signature, member and object counts, and sample members. signature_shape is persisted only when every member was placed from its stored family coordinates; it is computed when any member had to be derived from its evidence document. Each sample member includes finding_key, object_name, column_name, and disposition, plus an evidence object containing only source_value and target_value; when evidence is absent, evidence is null. The listing omits member_keys and does not inline whole evidence documents. Use the family member or witness drill-down endpoints when you need the full finding evidence. Open families are returned first, largest first. The response also includes deferred_family_signatures: null unless with_deferrals=true, otherwise a list of the listed families the current person has parked with a Leave for now note. A family remains parked when later notes are added; the deferral is not replaced by the newest ordinary note. A deferral note is a family note whose body starts with [deferred:indeterminate]. Pair-scoped notes apply to that pair; an unscoped family note applies to the family across pairs. Only findings on comparisons the caller may see are folded into these rows; hidden findings do not contribute members, counts, or samples, and families with no visible members are omitted. A deferral badge counts only notes the caller may read: pair-scoped deferrals on visible pairs, plus pairless deferrals authored by the caller.

`POST /api/estate/findings/{finding_key}/disposition`

Field	In	Type	Default	Required	Description
`finding_key`	path	string	none	Yes	Finding id from the ledger.
`disposition`	body	string	none	Yes	One of `target_defect`, `source_drift`, `promote_pi`, `promote_delta`, `spec_defect`, `instrument_defect`, or `waived`.
`note`	body	string	none	No	Optional diagnosis note. Maximum length `2000`.

Successful responses include finding_key and disposition. The finding stays open — only re-verification on a later diff run (when the difference is gone) closes it. The adjudicator identity is taken from the authenticated session when auth is enabled, never from the request body; when auth is disabled, writes are attributed to local operator (auth disabled).

Status	Meaning
`400`	Unknown `disposition` value.
`403`	Caller lacks `ratify_source_contract`, or (with auth enabled) the caller is not a genuinely authenticated human.
`404`	Finding not found.

`POST /api/estate/findings/families/{family_signature}/disposition`

Field	In	Type	Default	Required	Description
`family_signature`	path	string	none	Yes	Systemic-family id from `GET /api/estate/findings/families`.
`disposition`	body	string	none	Yes	One of `target_defect`, `source_drift`, `promote_pi`, `promote_delta`, `spec_defect`, `instrument_defect`, or `waived`.
`note`	body	string	none	No	Optional diagnosis note. Maximum length `2000`.

Successful responses include family_signature, disposition, applied_count (number of open member findings updated), and skipped_count (number of open members left alone because they already carried a diagnosis). Members stay open — only re-verification on a later diff run closes each one individually. The adjudicator identity is taken from the authenticated session when auth is enabled, never from the request body; when auth is disabled, writes are attributed to local operator (auth disabled).

Status	Meaning
`400`	Unknown `disposition` value.
`403`	Caller lacks `ratify_source_contract`, or (with auth enabled) the caller is not a genuinely authenticated human.
`404`	Family not found or has no open members.

`POST /api/estate/comparison-events/{diff_hash}/disposition-packages`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Content-addressed comparison whose findings the package diagnoses.
`title`	body	string	none	Yes	Package summary shown in Human Review. Minimum length `1`, maximum `200`.
`justification`	body	string	none	No	The case for approving the package, in plain business English: why the proposer is asking and what the approver is taking on. Shown above the items. Maximum length `4000`.
`proposer_display_name`	body	string	none	No	Self-declared readable label for an agent proposer. Display only and unverified; the proposer identity is derived from the authenticated caller. Maximum length `200`.
`mode`	body	string	`initial`	No	`initial` records first diagnoses on findings with no diagnosis; `corrective` supersedes recorded diagnoses. A package cannot mix the two modes.
`waiver_owner`	body	string or null	`null`	No	Default owner for each `waived` item that does not name its own owner.
`waiver_expires_at`	body	string or null	`null`	No	Default ISO-8601 expiry for each `waived` item that does not name its own expiry. It must be in the future when the package is staged.
`items`	body	object[]	none	Conditional	Explicit proposed diagnoses, one per finding. Each item requires `finding_key` and `disposition`; optional fields are `plain_summary` (maximum `600`), `note` (maximum `2000`), `rule_id` (maximum `64`), `clarification_id` (maximum `64`), `waiver_owner`, and `waiver_expires_at`. Waiver terms apply only to `waived` items; each such item needs an owner and future expiry, resolved from item values before the body defaults. `target_defect` is refused: send-backs are applied directly and are never staged for approval. Use exactly one of `items` or `select`. Minimum `1`, maximum `2000` items.
`select`	body	object or null	`null`	Conditional	Server-side family selector. Requires `family_signature` and one `disposition`; optional `note` (maximum `2000`), `plain_summary` (maximum `600`), and `rule_id` (maximum `64`) are copied to every expanded item. It selects this comparison’s undiagnosed findings in that family, whatever their status, and is valid only for `mode: "initial"`. `target_defect` is refused: send-backs are applied directly and are never staged for approval. For `waived`, the body-level waiver terms apply to every expanded item. Use `items` for a corrective package.

A package containing target_defect is refused before staging, whether the diagnosis appears in items, a family selector, or a corrective package. A send-back keeps its finding open until a fresh comparison verifies the fix; use the direct disposition_system_diff_finding tool instead. Other diagnoses that settle a difference without a fix remain in the human-approval package path. Staging also refuses the whole package before writing when an included lasting-rule promotion fails the approval preflight. The response’s refused_items identifies each affected finding_key, its locus, approval reason, and plain_reason; no person is asked to approve a package containing a promotion that cannot be licensed. The tool reference describes the corrective choices returned to the proposer; see the disposition package tool guidance. The package is validated against the addressed comparison’s current ledger state and accepts only findings most recently exhibited by that comparison. In initial mode, every item must be undiagnosed. In corrective mode, every item must already carry a diagnosis and the proposed diagnosis must differ from the one recorded; use this mode to replace a mistaken verdict. A selector is expanded inside the same transaction that stages the package, so its expansion response block reports the family and selected count. corrective with select is refused because a family selector names undiagnosed findings. Each item’s plain_summary is the one-sentence, business-language explanation shown to the person signing; note remains the technical rationale for the record. The waived disposition is a time-limited exception: its owner and future expiry are staged with the item and included in the approval projection. Terms on another disposition are refused. A retry that changes only waiver terms is a different request, not an idempotent replay. The latest Adjudicator verdict also constrains defect proposals: if it is question or spec_ambiguity, a proposed target_defect or spec_defect is refused with 400 unless that item cites a clarification_id recorded on an estate that scanned either side of this comparison, after the seat asked, and ratified by a signed-in person. An agent-certified clarification or one ratified with authentication disabled does not carry the defect. A promote_delta or waived item may instead cite the owner’s ruling: the clarification must be recorded on an estate that scanned either side of this comparison and must not be overturned; ratification is not required. Its provenance label is retained. Unanswered escalations are refused; the error names the seat’s outcome and provisional_position, explains why a cited clarification did not qualify when applicable, lists up to 20 affected findings, and gives a count for any remaining ones. A citation that fails these checks or appears on another item is refused; nothing is staged. Unknown fields at the request, selector, or item level are refused with 422; the error names the unknown and accepted fields, and nothing is staged. The response includes package_id, diff_hash, mode, item_count, subject_fingerprint, approval_url, approval_generation, action_review, and coverage; selector requests also include expansion, while listed requests return it as null. coverage records the comparison-wide exhibited, dispositioned, and undispositioned counts measured when the package was staged, plus proposed_here; retries return that original measurement. When a staged item proposes a different disposition from a still-open package on the same estate pair, the response also includes open_package_conflicts, with one entry per package (package_id, diff_hash, and item_count for the new package’s disagreeing items). The conflict is disclosed but does not refuse staging; whichever package is signed first sets the record. No finding is changed by this request. See propose_finding_disposition_package and propose_finding_disposition_correction for the agent hand-off guidance. Staging is agent-reachable and requires view_connections. With authentication enabled, the proposer identity is recorded for review; this request does not require a human approver. The approval link opens the package in Human Review. Packages staged through a Genesis agent tool use the acting agent as the proposer of record and retain the authenticated caller as the person the agent worked for; if the agent runtime has no bot id, the proposer is agent (unattributed). A direct HTTP request omits that agent context and remains attributed to its authenticated caller. When that caller is a service identity, staging also asks for Action Review approval immediately. If the request cannot be minted, the package remains staged and its read exposes can_request_approval so approval can be requested from the package later. If a person declines the package’s linked Action Review request, the package is closed as retracted and the comparison is free for the agent to stage a new initial package. Policy denial of a linked direct selective decision also closes that package generation; package reads identify it with retracted_as: "policy_denied_in_action_review".

Status	Meaning
`400`	Unknown mode or disposition, invalid package, duplicate or unknown finding, a mode precondition failure, or a corrective diagnosis equal to the one already recorded.
`422`	Request validation fails, including when an item or family selector proposes `target_defect`; send-backs cannot be staged in a package.
`403`	Caller lacks `view_connections`.
`404`	Comparison not found.
`409`	An open initial package already stands on the comparison; the response identifies the package and whether it can be withdrawn. Finish or withdraw that package before staging another initial package. Staging is also refused when a live bundle Action Review request claims a correspondence rule proposed by this package or promoted under by one of its items (`code: "rule_held_by_bundle"`, with the owning bundle identifiers); decide that request first.
`503`	The Action Review state of a bundle claiming a correspondence rule proposed by this package or promoted under by one of its items could not be read (`code: "rule_hold_unreadable"`). Retry after the request state is available.

`GET /api/estate/comparison-events/{diff_hash}/disposition-packages`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Content-addressed comparison whose staged packages are listed.
`status`	query	string	none	No	Filter to `open`, `closed`, or `retracted`.

Returns data as summary rows, newest proposal first. Each row includes package_id, diff_hash, title, status, mode, proposer attribution, justification, proposed_at, item_count, decided_count, and undecided_count, approval_generation, and the package’s approval_url. decided_count counts all settled items, including legacy send-backs applied without a person’s approval and items returned to their proposer because no one could approve them; it is not necessarily the number of human rulings or signatures. Such items do not appear in the package’s human signature record. Rows also include retracted_at, retracted_by, and retracted_as; these are null while the package stands. For a package closed by an Action Review decline, retracted_as is declined_in_action_review; policy denial of a direct selective decision is policy_denied_in_action_review. Summary rows also include can_request_approval, true for an open agent- or service-staged package with no current Action Review owner when no request has been made or its prior request can be renewed. Use this state to offer the package’s approval-request action. Each row also includes approval_run, the latest approval run for the current package generation, or null when there is none to show. It reports whether an approval is accepted, applying, done, or failed, and its signed-item count. A failed run remains in listing rows for one hour; the package read retains the current generation’s latest run. Evidence-bound Prover packages also expose evidence_error; it is null for legacy packages and valid evidence, and contains the refusal reason when persisted evidence cannot be authenticated. viewer_can_sign is true when the caller has a signing identity and the package is open; it is false with viewer_cannot_sign_reason set to no_signing_identity or not_open otherwise. Any person may sign, including the package proposer, and no special approval permission is required. viewer_can_apply matches viewer_can_sign. These verdicts are never null. Each row also includes viewer_signs_as: the identity this caller’s signature would carry, resolved by the same rule as the approval write, or null when the caller has no signing identity. Listing a package does not include its items or evidence — that would cost a ledger join per row — and each row names where they are instead: items_at is the path of the package read endpoint for that package, composed from the route this API registers for it. GET /api/estate/disposition-packages/mine rows carry the same items_at.

Status	Meaning
`403`	Caller lacks `view_connections`.
`404`	Comparison not found.

`GET /api/estate/disposition-packages/mine`

Returns data as the caller’s most recent standing package sign-offs across comparisons. Each row includes the package summary fields plus my_decided_count, my_approved_count, my_rejected_count, my_decided_keys, and my_last_decided_at; only that caller’s decisions are counted. Decisions later withdrawn are not listed, although they remain in the audit history. The response also includes truncated; when true, older signatures may exist beyond the bounded scan of recent decisions and the client must surface that the worklist is partial. A caller without a signing identity receives an empty data array. With authentication disabled and no X-Genesis-Signed-As claim, the listing treats the system_default_user and local-operator principals as the same signer, so Action Review package approvals recorded for the local operator are included.

Status	Meaning
`403`	Caller lacks `view_connections`.

`GET /api/estate/signoffs/waiting`

Field	In	Type	Default	Required	Description
`diff_hashes`	query	string	none	Yes	Comma-separated comparison hashes. Whitespace around each hash is ignored and duplicate hashes are collapsed. At most `200` distinct comparisons may be requested.

Returns data as a map keyed by each requested stored comparison this caller may see whose snapshots resolve to an estate pair. A comparison outside the caller’s visible scope, not stored, or without a resolvable pair is absent rather than returned with empty lists. Each value has packages, the comparison’s open disposition packages, and rules, its rule-review rows; either list can be empty when no queue items are waiting. Both lists carry the caller’s signability fields. Package rows do not include Action Review links; their action_review is null and can_request_approval is false. Use the comparison’s package listing when Action Review links are needed. The rule rows include bundle-hold and signability details, as in the single-comparison rule-review read. This read is for the Prover landing’s Needs you worklist. It does not run rule consent read-repair. It requires view_connections and is read-only. More than 200 distinct hashes returns 400 rather than silently truncating the worklist. Rule rows are selected per comparison pair: a rule appears when no binding exists for that exact pair and its earliest definition is not retired. A binding to another pair does not clear this pair’s work item, and legacy definition status does not hide an otherwise unbound rule.

Status	Meaning
`400`	More than `200` distinct comparison hashes were requested.
`403`	Caller lacks `view_connections`.

`GET /api/estate/comparison-events/{diff_hash}/disposition-packages/{package_id}`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Comparison containing the package.
`package_id`	path	string	none	Yes	Staged package id returned by the create endpoint.

The response includes data with the package status (open, closed, or retracted) and mode (initial or corrective), the verified proposer identity, any unverified proposer_display_name claim, justification, item_count, decided_count and undecided_count (the same counts the listing row carries), and each item’s proposed disposition, plain_summary, optional rule_id, promotes_rule, decision, reviewer identity and timestamp, stale state, and live subject evidence. Each item also returns its staged waiver_owner and waiver_expires_at when terms were recorded. returned_to_proposer is null unless the item was handed back because no approvable lasting rule remained; then it contains the approval’s reason, its plain_reason, and returned_at. This is settled package state, not a human decision. Subject evidence includes comparison, object name and resolved object_type when known, column name, status, last-seen comparison, current disposition, source and target values, detail, and family coordinates. An item whose defect verdict was carried over the seat’s question, or a promote_delta or waived item with a cited owner’s ruling, also includes clarification with clarification_id, subject, statement, label, reviewed_by, reviewed_at, and answers_outcome. reviewed_by and reviewed_at may be null for a ruling nobody reviewed; answers_outcome is null on a ruling item because it answers no seat question. The field is null when the item cites no clarification. For corrective packages, each item also exposes current_disposition, the diagnosis recorded when the package was staged, so the signing surface shows the verdict being replaced as well as the proposed one. Each item carries adjudicator_verdict, the Adjudicator ruling that backs it: verdict_id, adjudication_id, outcome, confidence, the finding’s durable finding_id (#N, or null), and link — staged when the ruling’s own proceeding staged this package, ledger when it is the newest ruling the verdict log holds on the finding. It is null when no proceeding ruled on the finding. It also carries departs_from — the earlier ruling (verdict_id, outcome) this verdict overturned, or null. Reading it costs one or two verdict-log queries per package read. Each item carries open_package_conflicts: every package that was still open on the same estate pair when this one was staged and whose item on the same finding proposed a different disposition (package_id, diff_hash, proposed_disposition); empty when none. Staging is not refused over it — whichever package is signed first sets the record. A moved item is marked stale; fresh undecided items remain independently reviewable. signature lists every signer separately, the items each signer decided, and their approval/rejection counts; it is null before any decision. A decision records self_approved: true when its signer is also the package proposer. viewer_signs_as identifies the identity that would be recorded if the caller signs, or is null when the caller may read but may not sign. A person’s own PAT is accepted and labelled via personal access token. The response also includes viewer_can_sign and viewer_can_apply, plus viewer_cannot_sign_reason when the caller cannot sign. The reason is no_signing_identity or not_open; it is null when the caller can sign. Any signed-in person, including the proposer, can sign without a special approval permission, so viewer_can_apply matches viewer_can_sign. viewer_withdrawable_keys is a string[] (default []) of item keys whose signatures this caller may withdraw. It is empty unless the caller has a verified principal, the package is not corrective, and the listed rulings were recorded under that principal. A signature whose lasting rule still licenses the pair or a reclaim conflict can still be refused when withdrawal is submitted. Evidence-bound Prover packages additionally return evidence_fingerprint, evidence_summary (the captured comparison, scope, and member count), evidence_scope, evidence_member_count, and remeasurement: "not_enqueued". evidence_error is null when the persisted envelope authenticates and contains the server’s refusal reason when it does not; an evidence error does not change the separate viewer_signs_as eligibility result. The response also includes approval_generation, the package generation an Action Review item must name to own approval, and action_review, the current Action Review item head when one owns this generation. A lapsed or applied item may be returned as action_review_history; it is history, not the current owner. It also includes can_request_approval, true for an open package staged by an agent or service when no Action Review item currently owns approval and the request has not yet been made or can be renewed. A service-staged HTTP package normally attempts to create its request during staging; this field surfaces the retry path when no request was created or its request later lapsed. It also returns retracted_at, retracted_by, and retracted_as, which are null while the package stands; retracted_as: "declined_in_action_review" identifies a package closed by a person’s Action Review decline, and "policy_denied_in_action_review" identifies one closed by policy denial. The response also includes approval_projection_digest, the digest that a native selective decision must send with the package generation. It also includes promotion_previews, the staged promotions’ shared pair_fingerprint, previews, and unavailable entries (including each unavailable item’s plain_reason). The preview contents and refusal fields are the same as the promotion-preview endpoint. Because the approval projection already computes these previews, the package read returns them with the package rather than requiring a second request from the approval page. approval_run reports the current generation’s latest approval: run_id, state (accepted, applying, done, or failed), started_by, timestamps, the optional action_review_proposal_id, total and signed counts, the named items and their signed flags, and signed_by. A failed run includes reason, not_recorded entries with per-item retryability, and the overall retryable flag. The run reflects recorded package decisions, not just the submitted request; done means every named item carries its requested ruling.

Status	Meaning
`403`	Caller lacks `view_connections`.
`404`	Comparison or package not found.

`GET /api/estate/comparison-events/{diff_hash}/disposition-packages/{package_id}/promotion-preview`

Preview the correspondence rules that approving this package’s promotion items would create. The response is a snapshot and writes nothing; the package may change before approval, which remains authoritative. This read costs a package fold, a findings-ledger read, and rule resolution and pair-binding reads for the promotions previewed, so call it once per package rather than once per item.

Query parameter	Type	Default	Description
`finding_key`	string[]	omitted	Repeat to preview specific package items, including items amended to promotions; when omitted, previews the package’s staged promotions. Keys outside the package are returned as unavailable.

data contains diff_hash, package_id, the shared pair_fingerprint, previews, and unavailable. Each preview describes the drafted rule, including its rule_id, component_pair, rule_kind, title, claim, applies_to, and edge_fixtures. reusability_refusal is the agent-facing refusal or null; plain_reusability_refusal explains the same refusal in business English or is null when there is no such refusal. A revoked approval for this estate pair is reported here before the reviewer approves. Each unavailable entry includes finding_key, reason, and plain_reason; the latter explains why the promotion cannot be approved and what the reviewer can do. Items approval would refuse are reported here rather than shown as licences. The preview also applies the approval’s field-survival check using the pair’s configuration. Qualification that requires running against the configured pair remains checked during approval.

Status	Meaning
`403`	Caller lacks `view_connections`.
`404`	Comparison or package not found.

`GET /api/estate/comparison-events/{diff_hash}/disposition-packages/{package_id}/record`

Read the package’s signing record and the Action Review request associated with its current generation, without loading the package’s per-item review data. The approval result line can use this endpoint instead of the full package read.

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Comparison containing the package.
`package_id`	path	string	none	Yes	Staged package id.

The response returns data.package_id, data.diff_hash, data.title, data.signature, data.action_review, and data.action_review_history. signature contains each signer’s identity and the decisions covered by that signature; it is null before any decision. action_review is the request that currently owns the package approval, or null when there is no owner. action_review_history is the request for the current package generation when it no longer owns approval (for example, after applying or lapsing undecided); it is not the current owner. The request objects use the same projection as the full disposition package read. This read does not return package items, evidence, staleness, the viewer’s verdict, or approval projection. Each call performs a view_connections permission check, one comparison-existence read, one read of this package’s review-log events, and one Action Review link read; it does not do the full read’s findings-ledger join, Adjudicator verdict read, or approval projection.

Status	Meaning
`403`	Caller lacks `view_connections`.
`404`	Comparison or package not found.

`POST /api/estate/comparison-events/{diff_hash}/disposition-packages/{package_id}/approve`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Comparison containing the package.
`package_id`	path	string	none	Yes	Staged package id.
`decisions`	body	object[]	none	Yes	Selected rulings. Each item requires `finding_key` and `decision` (`approve` or `reject`); `disposition` optionally amends an approval, `note` optionally replaces the proposal note, and `waiver_owner` / `waiver_expires_at` can specify terms for an approved `waived` disposition. An approval as staged accepts its recorded waiver terms; changing an item to `waived` requires a future expiry and named owner. Minimum `1`, maximum `2000` decisions.
`expected_projection_digest`	body	string	none	Yes	`approval_projection_digest` shown in the package read before the reviewer chose rulings.
`expected_generation`	body	integer	none	Yes	`approval_generation` shown in the package read; minimum `0`.

For packages otherwise eligible for direct selective decisions, this path is available only after their all-staged Action Review request lapses. Agent- or service-staged packages cannot be approved or partially decided here. A person can decline one only by rejecting every open item in a single submission when no live Action Review request covers it. Decide a live request through Action Review. After a request lapses, a whole-package decline needs no renewal; approval still does. Each native selective submission is recorded as Action Review action prover.decide_disposition_package.v1; its response includes the sealed action_review_proposal_id. The digest and generation bind the request to the package projection the reviewer saw and are checked again under the package lock. Only named items are ruled on; omitted items remain undecided. approve writes the proposed diagnosis, or the supplied amended disposition, under the authenticated human’s identity. For each approved item, a disposition other than target_defect can also resolve matching unexpected_change items in the selected Human Review population. Duplicate-coordinate population groups resolve only when the package covers every member; target_defect does not license a population item. reject retires the proposal without writing a disposition. The response includes applied_count, skipped_count, rejected_count, applied_keys, rejected_keys, approved_by, proposed_by, population_resolved_count, the number of Human Review blockers resolved by this approval, ratified_rules (each with finding_key and rule_id), corrections (each with finding_key, prior_disposition, and the new disposition), and refused_items (each with finding_key and the server-stated reason). An eligible promote_pi item qualifies and ratifies its correspondence rule in the same signing action, using the reviewed comparison’s persisted pair configuration. A rule proposed by an agent or service cannot be ratified as part of a person’s package: request its own Action Review approval first, then approve the package. If a promotion cannot be licensed, that item remains undecided and is reported in refused_items; other selected items can still be applied. A package decision is selective, and an item cannot be decided a second time. For a corrective package, approval supersedes the staged prior diagnosis using a compare-and-swap check; the response’s corrections list records each old-to-new transition. If a selected promotion is refused, other selected items can still be applied; refused items remain undecided and the response has complete: false. complete is true only when the submission succeeds without refused items. If every selected approval is refused, no ruling is recorded. When the remaining undecided items also all fail the approval preflight, the response includes returned_keys for the items handed back to the proposer; the package closes instead of asking another person to review rules that cannot be approved. For an initial package, approval writes findings with set-based statements rather than one write per item. Each row carries its own diagnosis, note, waiver terms, and compare-and-swap values, so distinct item values do not require separate writes. Typical packages use three SQL statements; larger batches are split to stay within bound-value limits. The endpoint responds after the Prover decision commits. For an applied decision, family-dossier cache invalidation, sealing the linked Action Review outcome, and any instrument_defect Prover-defect filing finish after the response. Until the outcome is sealed, the linked Action Review request remains claimed. Filing status is recorded on each finding and can be read from the findings dispositions API; see False alarm (Prover) for the filing-status meanings. Any signed-in person can approve this package, including its proposer, without a special approval permission. The response and stored decision identify an approval by the proposer with self_approved: true; a person’s PAT signs as its owner. Approval checks the staged subject state transactionally; a changed finding cannot be approved, although it may still be rejected so a stale package can be retired. For an evidence-bound Prover package whose evidence_error is non-null, approval is refused with the same stale/refusal response; rejection remains available so the unsafe package can be retired. The package does not enqueue a fresh comparison or remeasurement.

Status	Meaning
`400`	Invalid decision, unknown package item, repeated decision, unknown amended disposition, or every selected promotion was refused because its rule could not be licensed.
`403`	Caller lacks `view_connections` or does not have a signing identity.
`404`	Comparison or package not found.
`409`	The package projection or generation changed, another Action Review item owns approval, policy denied the decision, an approved finding moved, or an approval, partial decision, or incomplete decline of an agent- or service-staged package requires Action Review (`code: "action_review_required"`). An executor authorization refusal returns `execution_authorization_denied`. These refusals happen before the decision transaction, so no decision is written. Reload the package or stage a fresh one as appropriate; renew a lapsed request to approve it through the `renew-approval` endpoint.

`POST /api/estate/comparison-events/{diff_hash}/disposition-packages/{package_id}/approval-runs`

Accepts the same selective decision request as /approve, but answers once the approval run is recorded rather than waiting for its decision to finish. The path parameters and body are the same as /approve. The response uses HTTP 202 and includes run plus already_signed_keys. The package read and package-list rows expose the run while it is being recorded. If every named item already carries exactly the requested ruling, run is null, no new run is written, and already_signed_keys names those items. run.state is accepted before recording begins, applying while the decision is being applied, done once all named items carry the requested rulings, or failed if the run stops with items not recorded. The run includes its run_id, signer and timestamps, total and signed counts, per-item signed flags, signed_by, and the linked action_review_proposal_id when known. A failed run also returns a plain reason, not_recorded entries with individual retryable flags, and an overall retryable flag. Use those fields to show progress and determine whether an item can safely be submitted again. If an attempted decision has an uncertain outcome, the failed run’s reason says the server could not confirm whether it was recorded and includes the request ID; the underlying detail is in the server log, not the response. Reload the package before trying again to check where its decisions stand. Any signed-in person can start an approval run, including the package proposer; no special approval permission is required. A self-approval is recorded as self_approved: true. It refuses an approval already in progress for the same package. Other decision checks match /approve, including the package generation and projection guards, Action Review ownership, and waiver expiry validation.

Status	Meaning
`202`	Approval accepted; the run is included in the response.
`400`	Invalid decision, including an expired waiver.
`403`	Caller lacks `view_connections` or does not have a signing identity.
`404`	Comparison or package not found.
`409`	An approval is already in progress (`code: "approval_in_progress"`), the package changed or was withdrawn, Action Review owns the decision, or policy refused it. No run is accepted.

`POST /api/estate/comparison-events/{diff_hash}/disposition-packages/{package_id}/renew-approval`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Comparison containing the package.
`package_id`	path	string	none	Yes	Package whose undecided Action Review request lapsed.
`approval_generation`	body	integer	none	Yes	Generation read from the package before asking again.

Mints a fresh Action Review item for the same open package only when the previous request lapsed without a decision. The response includes proposal_id, its effective status, and renewed; a live item is reused with renewed: false. The generation is a compare-and-swap guard: if the package changed after the page read, the request returns 409 with package_changed instead of asking a person to approve an unread package. A declined request, an applied request, or a package that is no longer open cannot be renewed.

Status	Meaning
`403`	Caller lacks `view_connections` or does not have a signing identity.
`404`	Comparison or package not found.
`409`	The request was declined, the package is no longer open, its approval generation changed (`code: "package_changed"`), the handler refused the package (`code: "package_refused"`, with an audit reference), an approval-bundle request holds the package, or another live request claims one of its correspondence rules (`code: "rule_held_by_bundle"` or `"rule_hold_unreadable"`). A live bundle request returns `code: "package_in_bundle_request"`; a person-declined bundle returns `package_bundle_declined`; a policy veto returns `package_bundle_policy_denied`. Bundle-hold responses identify the request with `bundle_id`, `bundle_request_id`, and `bundle_request_url`, and include `decided_by_label` and `decision_reason` when available. Decide the conflicting request first; after a bundle decline or policy veto, stage a new package to ask for approval again.
`500`	A fault occurred while minting the Action Review request; retrying will not cure it, even if the response names a `proposal_id`.
`503`	The Action Review ledger or policy did not answer, or no renewal mint is bound. A retry may cure the failure. If the response includes `proposal_id`, the request exists but reading or checking it failed; retry to answer that request rather than minting another.

`POST /api/estate/comparison-events/{diff_hash}/disposition-packages/{package_id}/unsign`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Comparison containing the package.
`package_id`	path	string	none	Yes	Staged package whose signature is being retracted.
`finding_keys`	body	string[]	none	Yes	Package items whose signature to retract. Each named item returns to undiagnosed and can be ruled on again. Minimum `1`, maximum `2000` keys.

This is a compensating action, not a delete: the decision remains in the review history as signed and then retracted, while successfully retracted findings are returned to the open undiagnosed set. The caller must be the same person identity whose signature covers at least one named item. With authentication enabled, that can be the person’s sign-in or their own PAT; an agent or machine token cannot withdraw a signature. Items whose ledger row no longer carries that signature are left unchanged and disclosed in skipped; a request naming only another person’s items is rejected. If the signature ratified a correspondence rule that is still licensing the comparison’s estate pair, retraction is refused; revoke that rule first in the Platform rules surface, then retry this endpoint. Successful responses include package_id, retracted_count, retracted_keys, skipped (each with finding_key and the server-stated reason), retracted_by, and population_reopened_count, the number of Human Review items whose package-based resolution was re-opened. A corrective package cannot be unsigned: clearing it would erase the diagnosis it superseded rather than restore the prior verdict and attribution. Submit another corrective package to change that verdict. Retracting an approval re-opens its package-bound population items in the same transaction; items still covered by the package’s remaining approvals, or resolved by another authorization, remain resolved. The signature projection in the package read shrinks to exclude items that were retracted.

Status	Meaning
`400`	Empty item list, unknown package item, an item that has not been decided, or a signature whose still-active correspondence rule must be revoked first.
`403`	Caller lacks `view_connections`, has no signing identity, or is not the signer of any named item.
`404`	Comparison or package not found.

`POST /api/estate/comparison-events/{diff_hash}/disposition-packages/{package_id}/retract`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Comparison containing the package.
`package_id`	path	string	none	Yes	Open package staged by the caller’s identity.
`reason`	body	string or null	`null`	No	Optional explanation recorded in the review log; maximum length `2000`.

Withdraws the caller’s own package before any item has a decision. Any signed-in person may also withdraw an unanswered package staged by an agent or service; this does not permit withdrawing a package staged by another person. The person’s own PAT is accepted as their identity. The operation changes no finding disposition; it records the package as retracted and removes it from the reviewer’s waiting worklist. The response includes package_id, diff_hash, status: "retracted", retracted_by, retracted_as ("proposer" or "operator"), reason, and item_count. A package closed because its linked Action Review request was declined or policy denied is instead represented in package reads with retracted_as: "declined_in_action_review" or "policy_denied_in_action_review"; it releases its open-package claim so a new initial package can be staged. The caller’s identity is resolved server-side; there is no request body identity field. When supplied, reason is trimmed and recorded; blank reasons are stored as absent.

Status	Meaning
`403`	Caller lacks `view_connections`, is not the package proposer, or has no signing identity when clearing an agent- or service-staged package.
`404`	Comparison or package not found.
`409`	The package was already retracted or at least one item already carries a ruling.

`GET /api/estate/comparisons/{diff_hash}/review/bundles`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Comparison whose standing approval bundles are listed.

Returns data with diff_hash and bundles[], oldest first. Each bundle includes bundle_id, the display-only proposed_by, proposer_principal (the proposal principal; with authentication disabled, a local operator’s proposal uses local-operator), proposed_at, rationale, brief when the bundle carries one, run_id, population_hash, carries, approval_route, approval_url, approval_url_basis, and approval_path. approval_route is action_review for an agent-staged bundle carrying correspondence rules and no disposition or evidence-gap packages; it is direct otherwise. approval_path is the same review page relative to the Genesis dashboard and remains present when approval_url is null because the deployment publishes no public base URL. A bundle carrying disposition packages or using the action_review route also includes action_review, with the linked proposal’s proposal_id, status, and url. If that link cannot be read, status is unavailable, reason is ledger_read_failed or adapter_unavailable, and proposal_id and url are null. It also includes viewer_signs_as, the signer label this caller’s approval would record, viewer_can_sign, and viewer_cannot_sign_reason. The latter two reflect whether the approval door would accept this caller on this bundle: viewer_can_sign is false with reason package_requires_action_review for bundles carrying disposition packages or agent_bundle_requires_action_review for rules-only bundles using the action_review route; neither kind can be approved through the bundle endpoint. Otherwise, viewer_can_sign is null when no signer is available, false when approval would be refused, and true when it would be accepted. When the signer is unavailable, viewer_cannot_sign_reason is no_signing_identity; otherwise it is not_open when the bundle is no longer awaiting approval. The proposer may sign their own bundle without a special permission. It is null when the caller may sign. The reason reports the first refusal the approval door would encounter. population_moved is true when a bundle carrying evidence-gap packages was assembled against a different current population hash; current_population_hash is null for a bundle that carries no evidence-gap packages. Bundles whose members were already settled or whose recorded scope changed are not offered as standing work. When evidence gaps are carried, carries.evidence_gap_packages also returns the staged waiver_owner and waiver_expires_at.

Status	Meaning
`404`	Comparison not found.

`POST /api/estate/comparisons/{diff_hash}/review/bundles`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Comparison whose review populations the bundle names.
`rationale`	body	string	none	Yes	One reason for the whole human decision. Maximum length `4000`.
`brief`	body	object or null	`null`	No	Optional short account shown first on the Action Review request. When supplied, it requires `title` (1–120 characters), `proposal` (1–400), `why` (1–400), and `weigh` (1–4 non-empty statements, each 1–200 characters); additional fields, including a recommendation, are refused.
`rule_ids`	body	string[]	`[]`	No	Open correspondence proposal ids to carry. Use this or `all_proposed_rules`, never both. Maximum `200` ids.
`all_proposed_rules`	body	boolean	`false`	No	Carry every open correspondence proposal offered for the comparison. Rules excluded by the defaults eligibility predicate are reported rather than carried.
`package_ids`	body	string[]	`[]`	No	Open disposition package ids to carry as proposed. Maximum `200` ids.
`evidence_gap_package_ids`	body	string[]	`[]`	No	Evidence-gap exception package ids to carry. Use this or `all_open_evidence_gaps`, never both. Maximum `200` ids.
`all_open_evidence_gaps`	body	boolean	`false`	No	Carry every offered evidence-gap package with at least one open member, except partial-seal `open_clause` packages. Name an individual package in `evidence_gap_package_ids` to stage one explicitly.
`evidence_gap_waiver_owner`	body	string or null	`null`	No	Owner for accepted evidence-gap exceptions. When omitted, the approving person is recorded as their owner.
`evidence_gap_waiver_expires_at`	body	string or null	`null`	Conditional	Future ISO-8601 expiry for accepted evidence-gap exceptions. Required when the bundle carries any evidence-gap package; approval refuses if it is missing or has passed, and no bundle member is approved.

Unknown body fields are refused with 422; the error names the unknown and accepted fields, and no bundle is staged. A part that exceeds its brief bound is also refused; the server does not shorten it. The response includes bundle_id, brief when the bundle carries one, approval_route, the comparison’s current run_id and population_hash, the trimmed rationale, approval_url and its basis, approval_path, and carries. For a bundle carrying disposition packages, it also includes action_review with the composite proposal’s proposal_id, status, url, card_sent result, and adopted_package_requests, the array of package-request proposal IDs withdrawn in favor of the composite request. This array is empty for bundles proposed through this human-facing HTTP route. Use action_review.url for that human decision; the separate bundle approval endpoint cannot approve package members. An agent-staged bundle carrying correspondence rules and no package members also uses route action_review and includes that linked request. Proposals staged by a human through this HTTP endpoint use route direct. For direct-route bundles, use approval_url (or approval_path when the URL is null). approval_path is the same review page relative to the Genesis dashboard and remains present when approval_url is null because the deployment publishes no public base URL. The carries object reports each kind’s ids and count: correspondence rules as count of of_proposed, disposition packages with submitted item_count of of_undispositioned_findings, and evidence-gap packages with member counts of of_open_members. It also includes excluded_rules; each excluded rule has its rule_id, title, rule_kind, the eligibility refusal, and the remedy. A human’s all_proposed_rules selection leaves out a rule whose sign_off_route is action_review; its remedy is to request approval for that rule separately. Data-derived and unclassified rules are also left out of bulk selection. A person cannot name one in this route; an agent may name one in a rules-only bundle through propose_approval_bundle, subject to its one-rule limit. Repeating the same membership and recorded scope for the same proposer replays the standing bundle without writing another event. Staging changes no rule, package, finding, or evidence-gap decision. A bundle is bound to the scope read when it is proposed; approval refuses if a package’s undecided items or an evidence-gap package’s members moved after staging. When the bundle creates a composite Action Review request, it can claim each correspondence rule it carries only if no other live request or open agent- or service-staged package owns that rule on the estate pair. A package owns a rule it proposed or that one of its items promotes under; a conflict returns rule_owned_by_package with the owning package identifier. Replacements and retractions clear pending bundle asks from Action Review.

Status	Meaning
`400`	Missing rationale, ambiguous selector, empty bundle, unknown member, closed package, or another invalid request.
`403`	Caller lacks `view_connections`.
`404`	Comparison not found.
`409`	The composite Action Review proposal was refused during derivation (`details: "action_review_request_refused"`). Typed handler refusals include their reason; a correspondence-rule claim conflict uses `rule_held_by_bundle`, `rule_hold_unreadable`, or `rule_owned_by_package`. Decide the existing request or package first. Other derivation causes are replaced with a generic refusal and audit reference.
`413`	Bundle staged, but the Action Review ledger cannot store a request this large (`details: "bundle_too_large"`). Withdraw the bundle and split its members across smaller bundles.
`500`	The composite Action Review request was not made because of a server fault (`details: "action_review_mint_fault"`). The failure detail is in the server log; retrying will not cure it.
`503`	Bundle staged, but Action Review is unavailable: ledger failures return `details: "action_review_ledger_unavailable"` and can be retried; unavailable wiring returns `details: "action_review_wiring_unavailable"` and can be retried after the service is configured. If the composite request was inserted but could not be read back, the response includes `proposal_id`, `bundle_retracted: false`, and `withdrawn_package_requests` when applicable; the request exists with unknown state, so retry the same proposal to read it. Infrastructure and unexpected failure details are logged, not returned in the response.

`POST /api/estate/comparisons/{diff_hash}/review/bundles/{bundle_id}/approve`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Comparison containing the bundle.
`bundle_id`	path	string	none	Yes	Bundle id returned by the bundle-list or bundle-propose route.

The request has no body: approval cannot widen the membership fixed at proposal time. A bundle carrying any disposition package is refused atomically with rule: "package_requires_action_review"; an agent-staged rules-only bundle is refused with rule: "agent_bundle_requires_action_review". Neither refusal approves any member; both bundles settle through their composite Action Review request. For other bundles, one transaction sends correspondence rules through rule ratification and evidence-gap members through the exception-approval path. The response includes bundle_id, the approval event id, approved_by, and per-kind results for rules, packages, and evidence_gaps. Any signed-in person can approve this bundle, including its proposer, without a special approval permission. The response includes self_approved to identify an approval by the bundle’s proposer. Bundles carrying disposition packages are refused through this endpoint as described above. With authentication enabled, a person’s own sign-in or PAT can sign and a typed name is refused; PAT signatures are attributed to their owner. With authentication disabled, the caller is recorded under X-Genesis-Signed-As with (self-reported, auth disabled), or as local operator (auth disabled) when the header is absent.

Status	Meaning
`400`	Invalid or no-longer-bindable member, a bundle carries a disposition package and requires composite Action Review authorization, another live bundle’s Action Review request holds one of its rules, or another approval refusal.
`403`	Caller lacks `view_connections` or the signer rule refuses the caller.
`404`	Comparison or bundle not found.
`409`	The bundle was already approved, withdrawn, or its recorded package membership or evidence-gap population moved.

`GET /api/estate/remediation-requests`

Field	In	Type	Default	Required	Description
`pair_fingerprint`	query	string	none	No	Filter to one estate pair fingerprint.
`family_signature`	query	string	none	No	Filter to one systemic finding family.
`status`	query	string	none	No	Filter by remediation-request lifecycle status.

Returns data as an array of defect remediation requests, newest first. Only requests whose named finding and/or estate pair the caller may see are returned; unattributable or hidden requests are omitted and not counted. Each row includes lifecycle fields such as status, created_by (filer), and dispatched_by (the human who authorised dispatch, set when status is dispatched; null while still open). Filing the same defect twice is idempotent — the server content-addresses the request.

`POST /api/estate/remediation-requests`

Field	In	Type	Default	Required	Description
`family_signature`	body	string	none	No*	Systemic family id. One of `family_signature` or `finding_key` is required. Maximum length `128`.
`finding_key`	body	string	none	No*	Lone finding id. One of `family_signature` or `finding_key` is required. Maximum length `64`.
`pair_fingerprint`	body	string	none	No	Estate pair fingerprint. Maximum length `512`.
`component_pair`	body	string	none	No	Component pair label (for example `postgres->databricks`). Maximum length `128`.
`comparison`	body	string	none	Yes	Comparison class for the defect. Maximum length `64`.
`direction`	body	string	none	No	Direction label when applicable. Maximum length `64`.
`objects`	body	string[]	`[]`	No	Affected object names. Maximum `5000` entries.
`member_count`	body	integer	`0`	No	Family member count when filing against a family. Minimum `0`.
`expected_summary`	body	string	none	Yes	Expected-side summary for the hand-off. Maximum length `4000`.
`actual_summary`	body	string	none	Yes	Actual-side summary for the hand-off. Maximum length `4000`.
`adjudication_state`	body	string	`human_confirmed_for_agent`	No	`human_confirmed_for_agent` (real work for a coding agent) or `needs_human_review`.

Successful responses include created (false when the request already existed) and data with the persisted remediation request. The server generates authoritative fix instructions — they are not trusted from the client. Dispositioning the finding or family as target_defect remains a separate call (POST /api/estate/findings/.../disposition). The filer identity is taken from the authenticated session when auth is enabled, never from the request body; when auth is disabled, writes are attributed to local operator (auth disabled).

Status	Meaning
`400`	Validation failure (for example neither `family_signature` nor `finding_key` provided).
`403`	Caller lacks `ratify_source_contract`, or (with auth enabled) the caller is not a genuinely authenticated human.

`POST /api/estate/remediation-requests/{request_id}/dispatch`

Field	In	Type	Default	Required	Description
`request_id`	path	string	none	Yes	Remediation request id to advance.

Successful responses include request_id and status (dispatched). The dispatch transition is human-gated: the authenticated adjudicator is stamped on the persisted request as dispatched_by (readable via GET /api/estate/remediation-requests) when auth is enabled; when auth is disabled, writes are attributed to local operator (auth disabled). That field is written once at dispatch and is not cleared by later lifecycle transitions.

Status	Meaning
`400`	Dispatch failed (for example request is not in a dispatchable state).
`403`	Caller lacks `ratify_source_contract`, or (with auth enabled) the caller is not a genuinely authenticated human.
`404`	Remediation request not found.

`GET /api/estate/notes`

Field	In	Type	Default	Required	Description
`target_kind`	query	string	none	Yes	Note target kind: `family`, `object`, or `rule`.
`target_ref`	query	string	none	Yes	Target identifier (family signature, object name, or rule id).
`pair_fingerprint`	query	string	none	No	Optional pair scope for the note thread.

Returns data as an array of collaboration notes on one target, oldest first. Notes on an estate pair are returned only when the caller may see a comparison on that pair. Pairless notes are returned only when the caller authored them.

`POST /api/estate/notes`

Field	In	Type	Default	Required	Description
`target_kind`	body	string	none	Yes	One of `family`, `object`, or `rule`.
`target_ref`	body	string	none	Yes	Target identifier. Minimum length `1`, maximum `512`.
`pair_fingerprint`	body	string	none	No	Optional pair scope. Maximum length `512`.
`body`	body	string	none	Yes	Note text. Minimum length `1`, maximum `4000`.

Successful responses include data with the persisted note. Notes are append-only. The author identity is taken from the authenticated session when auth is enabled, never from the request body; when auth is disabled, writes are attributed to local operator (auth disabled).

Status	Meaning
`400`	Unknown `target_kind` or validation failure.
`403`	With auth enabled, the caller is not a genuinely authenticated human.

`GET /api/estate/comparisons/{diff_hash}/history`

List who touched one comparison and the conversation for each act, newest first. The history combines runs that name the comparison, recorded review decisions, rulings, comments and proposals, and the requirements documents those runs were graded against. Each entry has a plain-language action, an actor (person, agent, or unrecorded), and a kind (run, review, or requirements). A person actor can include their directory name; on_behalf_of identifies a person an agent acted for. run_id and finding_id are present when the entry refers to one. conversation.state is openable when the caller may open the recorded conversation, not_shared_with_you when it is recorded but not accessible to the caller, not_linkable when the thread is recorded without its agent, or not_recorded when there is no conversation address. Only an openable conversation includes bot_id and thread_id; the other states do not disclose its address. Returns data with diff_hash, entries[], and truncated. The response keeps at most the newest 200 entries. truncated is true when entries exceed that limit, the run or review-event read reaches its 200-run or 500-event limit, or more than 20 distinct requirements documents are named. The read checks comparison visibility, scans narrow run-table columns, reads at most 500 review events, and reads provenance for up to 20 requirements documents. It also checks access once per distinct conversation in the returned entries and batches display-name lookup for named people. Unknown and caller-invisible comparisons both return 404.

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Comparison whose history is listed.

Each entries[] object has these fields:

Field	Type	Description
`at`	string or null	ISO-8601 timestamp, or `null` when the source record has none; entries without a timestamp sort last.
`kind`	string	`run`, `review`, or `requirements`.
`action`	string	Plain-language description of the recorded act.
`actor`	object	`kind`, `id`, and `name`. The `kind` is `person`, `agent`, or `unrecorded`; `id` is the person’s user id or email, the agent’s bot id, or `null` when unrecorded or an agent has no id. `name` is a person’s directory display name, or `null`.
`on_behalf_of`	object or null	Person `{id, name}` when an agent acted on their behalf; otherwise `null`.
`conversation`	object	`state`, and `bot_id` plus `thread_id` only when `state` is `openable`. Other states are `not_shared_with_you`, `not_linkable`, and `not_recorded`.
`run_id`	string or null	Related run id on run entries and run-decision events.
`finding_id`	string or null	Related finding id for a finding decision or comment.

`GET /api/estate/comparisons/{diff_hash}/latest-conversation`

Find the newest conversation about a comparison that belongs to the caller. The Prover workspace uses this when a person clicks an Ask button, so the question continues in the conversation that contains the comparison’s context. Only the caller’s own conversation is returned; a public or shared conversation, or one the caller can read through an admin permission, is not eligible. The route requires VIEW_CONNECTIONS. If no owned conversation is found, conversation is null and the Ask flow starts a new conversation. The lookup considers conversations recorded by runs about the comparison and by staged decision packages. It checks ownership newest first, up to five candidates. It reads at most ten run rows and ten review-event rows, then checks thread ownership until a match is found. Unknown and caller-invisible comparisons both return 404.

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Comparison whose conversation is requested.

Returns data with diff_hash and conversation:

Field	Type	Description
`diff_hash`	string	Comparison identifier.
`conversation`	object or null	The newest matching conversation, or `null` when none is the caller’s own.
`conversation.bot_id`	string	Agent that owns the conversation.
`conversation.thread_id`	string	Conversation thread to continue.
`conversation.at`	string or null	ISO-8601 timestamp of its newest act, or `null` when not recorded.
`conversation.action`	string	Plain-language description of its newest act.

Status	Meaning
`404`	Comparison not found or not visible to the caller.

`GET /api/estate/comparisons/{diff_hash}/review`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Mediated-diff id from `GET /api/estate/system-diffs`.

Returns data with the folded comparison review state:

Field	Type	Description
`diff_hash`	string	Comparison identifier.
`decision`	string	Run-level verdict: `awaiting_review`, `approved`, or `approved_with_exceptions`. Gated at read time against the selected conformance population — a stored approval is withdrawn in the response when the population is incomplete, still has unresolved blockers, or its `run_id` / `population_hash` no longer match the coordinates recorded on the approval event.
`decided_by`	string or null	Author of the current verdict. `null` when `decision` is `awaiting_review`.
`decided_at`	string or null	Timestamp of the current verdict. `null` when `decision` is `awaiting_review`.
`run_reset`	object or null	`{by, at}` for a person’s explicit reset to `awaiting_review`; otherwise `null`. A reset records that the run was not approved and keeps a comparison off Verified until a verified person records an approval.
`approval_carried_from`	object or null	On a comparison whose approval was carried here by a re-grade, identifies the original comparison (`diff_hash`), original decision run and event (`run_id`, `event_id`), original decider and decision time (`decided_by`, `decided_at`), the recomputed comparison (`recomputed_diff_hash`), the run that carried it (`carried_by_run_id`), and carry time (`carried_at`), with the retired and current engine versions. The decision remains the original person’s decision, not a new approval at re-grade time. `null` when no approval was carried here.
`approval_carried_to`	object or null	On the comparison whose approval was carried elsewhere, describes the carried decision and names its destination comparison (`carried_to_diff_hash`) and run (`carried_to_run_id`). If this comparison’s review log does not record the carry, the read derives it from the run decision on the recomputed comparison of the same snapshot pair, including older carry records that name that comparison as `carried_from.diff_hash`. It is `null` when no carry of the current decision is found.
`authority`	string or null	Optional free text stating who authorised the decision, in the caller’s words. Recorded beside the server-derived reviewer identity, never instead of it. `null` when omitted or when `decision` is `awaiting_review`.
`decision_approval_basis`	object or null	Structured approval record for the standing run-level verdict: `basis`, `person_id`, `person`, and `channel`; agent approvals also include `agent_id`, `agent`, `thread_id`, `goal`, and the server-observed `context`. Agent bases are `agent_person_present` or `agent_delegated`. `null` when no verdict stands or for decisions recorded before this record existed.
`decision_run_id`	string or null	Conformance `run_id` the approval was recorded against. `null` when `decision` is `awaiting_review`.
`decision_population_hash`	string or null	Content hash of the complete review worklist the approval was recorded against. `null` when `decision` is `awaiting_review`.
`stands`	boolean	Whether the recorded verdict currently accounts for the comparison under the checks performed by this read. This is the same revalidated standing exposed by `find_proofs`; `false` identifies a verdict that does not currently stand, including a decision withdrawn after a finding was re-diagnosed.
`review_decision_basis`	string	Measured explanation for `stands`, including the finding and time when a re-diagnosis withdrew a decision. A retracted exception that is later re-approved is evaluated by its final state and does not leave the approval withdrawn.
`person_acceptance`	object or null	The reviewed outcome when verified people’s standing approvals cover every item that kept the comparison off Verified; otherwise `null`. A run-level decision is not required: the verified grants must cover the exact complete, materialized population, with measured, non-withheld members; the outcome is absent while a grade is pending or an open behavioral catch remains. An explicit `run_reset` keeps it off Verified until a verified approval replaces the reset. The object includes `outcome: "accepted_by_person"`, `accepted_count`, `failed_checks_accepted`, `approved_by` (the grant signers), `approver_names` (each original approver principal mapped to that user’s own display name, or `null` when there is no user record or display name), `decision`, `decided_by`, `decided_at`, `run_id`, `population_hash`, and `items`. The run-decision fields are `null` when no run decision stands. Each item identifies `finding_id`, `kind`, `description`, `locus`, `failed_check`, `accepted_as` (`exception`, `ruling`, or `false_alarm`), `by`, `by_name` (that principal’s display name, or `null` when there is no user record or display name), `at`, `reason`, and `disposition`. A failed spec requirement accepted by a person remains counted in `failed_checks_accepted`; this outcome does not change the machine grade.
`source_moved_since_approval`	object	Disclosure about whether the source estate has CHANGED since the reading this approval was recorded against. This is separate from `stands` and never withdraws the decision. The object always includes `count`, `readings_since`, `basis`, `approved_snapshot_id`, `latest_snapshot_id`, `latest_at`, `latest_changed_snapshot_id`, and `latest_changed_at`; `count` and `readings_since` are numeric only for `basis` `measured`, `no_newer_snapshot` or `no_content_change`.
`target_moved_since_approval`	object	The same disclosure for the target estate. The count is of later readings of that estate boundary whose measured content DIFFERS from the bound one — not of later readings, and not only of readings taken after the approval timestamp.
`findings`	object[]	Per-finding review state (see below).
`cluster_rulings`	object[]	Every same-cause group proposed as ONE reusable ruling through `POST .../review/propose-cluster-rule`, recorded in the transaction that wrote its rules. Each is `{members, rule_ids, owner, proposed_at, lifecycle}`: the finding ids, the rule each member got (in member order), the reviewer who proposed it, and `lifecycle` — `proposed` whether its rules await sign-off or are signed (the Π worklist says which), `withdrawn` when one of its rules was taken off this comparison’s worklist, `retired` when one was rejected (the group cannot be proposed again: that request is refused). Rules written by proposing each finding on its own are not a group ruling and appear here as nothing. Costs one read of the rules’ status column when the comparison holds any.

For the movement basis vocabulary and the distinction between a clean zero and an unmeasurable result, see the find_proofs response contract. Each item in findings includes finding_id, diagnosis, disposition, workflow, owner, exception_approved, exception_run_id, exception_population_hash, exception_package_id, updated_by, updated_at, comments (array of {comment_id, text, author, created_at}), and audit (array of {event_id, kind, author, created_at, detail}).

Status	Meaning
`404`	Comparison not found.

`GET /api/estate/comparisons/{diff_hash}/attestation`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Mediated-diff id from `GET /api/estate/system-diffs`.

The response returns data.diff_hash and data.attestation. The attestation is null when no stored attestation binds this comparison; otherwise it is the newest match, selected from attestations on contracts for the comparison’s source snapshot whose transition names this exact diff_hash.

Attestation field	Type	Description
`attestation_id`	string	Stored attestation identifier.
`contract_hash`	string	Contract the attestation was created from.
`signer`	string or null	Recorded signer.
`created_at`	string or null	Attestation creation time.
`signed`	boolean	Whether a signed envelope was stored with the attestation; this read does not verify it.
`lifecycle`	string	`current`, `superseded`, `tainted`, or `revoked`. `tainted` identifies a revoke whose `status_reason` starts with `tainted:`.
`status_reason`	string or null	Reason recorded for the lifecycle status.
`superseded_by`	string or null	Attestation that superseded this one, when applicable.
`attestation_status`	string or null	`clean` or `qualified`, as recorded by the signed transition.
`open_waiver_count`	integer	Number of open waivers carried by the signed statement; it is not recomputed from current review state.

This summary costs two reads. It does not verify the signature or re-derive the attestation bundle; use POST /api/estate/attestations/{attestation_id}/verify for that check.

Status	Meaning
`404`	Comparison not found.

`POST /api/estate/comparisons/{diff_hash}/proof-report`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Mediated-diff id from `GET /api/estate/system-diffs`.
`format`	query	`pdf` or `md`	`pdf`	No	Download as PDF or Markdown.

Returns the report bytes as application/pdf or text/markdown. The response sets Content-Disposition and X-Attestation-Id; fetch GET /api/estate/attestations/{attestation_id} to retrieve the signed envelope to ship beside the report. The first download mints the signed statement; later downloads reuse it while the underlying comparison, grade, specification, approval and signing key are unchanged. The report requires a standing Human Review approval, a verified grade for this comparison against its sealed specification with every check passing, no unexplained or undetermined differences after the specification’s reclassification, no open unexplained behavioural findings, and configured report signing. A stimulus run is not required: when behaviour was not tested, the report discloses that limitation prominently on its first page and in its limits. 409 returns payload.reasons when an eligibility condition is not met, or immediately when another report for the same comparison is being prepared; 404 means the comparison is unknown. PDF rendering can take up to two minutes. Cost: review approval and readiness reads (including an uncapped stimulus-run feed scan), signing-key resolution and, for a new statement, an attestation mint; PDF format also runs one headless Chromium render.

`GET /api/estate/attestation/public-key`

Returns data with the public verification material; the private signing key is never returned. Cost: one config read, one secret lookup and one permission check. Callers with manage_secrets also receive key-source diagnostics, which cost an environment scan, a config read and up to two secret-existence reads; other callers do not receive an admin field.

Field	Type	Description
`configured`	boolean	Whether a signing key can be resolved.
`key_id`	string or null	Configured id or stable id derived from the key.
`algorithm`	string	`Ed25519`.
`public_key`	string or null	Raw 32-byte public key, base64.
`public_key_pem`	string or null	The same public key as PEM SubjectPublicKeyInfo.
`payload_type`	string	Signed envelope payload type.
`signing_domain`	string	Domain prefix covered by the signature.
`reason`	string or null	Why the key is unavailable when `configured` is false.
`can_set_up`	boolean	True when no key or setup blocker exists and this caller has `manage_secrets`.
`admin`	object; present only for callers with `manage_secrets`	Administrator-only details: `source` (`environment_override`, `reference`, `default_secret`, `none`, or `unknown`), a plain-language `source_label`, optional `problem` and `notice` sentences, and `own_key_setting` (`estate_char.attestation.signing_key`). It never contains the key value.

`POST /api/estate/attestation/signing-key/test`

No request body is required. This signs a throwaway statement with the configured key and verifies it with the public half. It writes nothing, creates no attestation, and is safe to repeat. The response’s data.ok reports whether the check passed, data.key_id contains the key id when available, and data.message explains the result and, when relevant, where the key comes from. Missing or invalid key material is returned in a 200 result rather than an HTTP error. Cost: resolving the key, one signature and one verification in memory, plus an environment scan, one config read and one secret-existence read for the key-source diagnostics. Requires manage_secrets.

Status	Meaning
`403`	Caller does not have `manage_secrets`.

`POST /api/estate/attestation/signing-key`

No request body is required. The endpoint generates an Ed25519 key pair on the server, stores the private key in the encrypted shared secret store, and returns only data.key_id, data.public_key (base64 raw bytes), and data.public_key_pem. The key id is derived from the public key unless an operator configured estate_char.attestation.key_id. This operation never replaces or rotates an existing key and refuses when the signing field is configured by an operator or environment override. Cost: key generation, secret-store creation and readback, and config and environment override checks.

Status	Meaning
`403`	Caller does not have `manage_secrets`.
`409`	A key is already configured or stored, an operator override blocks setup, or another concurrent setup stored its key first.
`503`	The secret store could not save or read back the key.

`GET /api/estate/comparisons/{diff_hash}/review/population`

A comparison hidden from the caller returns 404, as an unknown comparison does.

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Mediated-diff id.
`offset`	query	integer	`0`	No	Pagination offset into the selected run’s complete review worklist. Minimum `0`.
`limit`	query	integer	configured page size	No	Page size for this response. Defaults to and is clamped to `estate_char.findings.family_members_page_size` (schema default `500`). Page through with `offset`/`limit` to reach every member.

Successful responses include data with the selected conformance run’s population status and one member page:

Field	Type	Description
`run_id`	string or null	Selected conformance `run_id` for this comparison. `null` when no finished run is available.
`population_hash`	string or null	Content hash of the complete worklist for `run_id`. `null` when the population is incomplete.
`complete`	boolean	`true` only when every blocker in the selected run is materialized server-side and any recorded rulings can be accounted for (a truncated or partially persisted sample returns `false`).
`incomplete_reason`	string or null	Human-readable reason when `complete` is `false` (for example no finished conformance run, grading still running, or persisted sample smaller than the run’s drift count).
`total_count`	integer	Exact number of independently reviewable blockers in the selected population.
`unresolved_count`	integer	Members still requiring review after recorded rulings and approved one-time exceptions are applied. A ruling counts only when its ledger finding accounts for the complete matching population group.
`offset`	integer	Echo of the requested offset.
`limit`	integer	Effective page size after clamping.
`members`	object[]	One page of blocker identities (see below). When grading attributes unpaired scope entries to one missing `schema_map`, the population represents that cause once instead of adding one member per entry.
`resolved_by_ruling_count`	integer	Members accounted for by a person’s recorded ruling; these are decisions, not waivers. Defaults to `0`.
`resolved_as_false_alarm_count`	integer	Members settled as False alarm (Prover), counted separately from rulings that accept or charge a difference. Defaults to `0`.
`resolved_by_exception_count`	integer	Members waived by an approved one-time exception without a ruling. Defaults to `0`.
`row_identity_basis`	object or null	Per object pair, discloses whether identity came from a caller declaration, an engine declaration, or no identity. A failed caller declaration identifies a withheld pair; `null` is returned for comparisons persisted before this disclosure existed.
`row_identity_evidence`	object or null	Live uniqueness evidence for each declared object: row, distinct, and NULL-key counts plus probe time. It belongs to the run that minted the comparison, not the shared diff record; empty means that run declared nothing.
`row_identity_evidence_run_id`	string or null	Run id that owns `row_identity_evidence`; `null` when the comparison names no run.
`undeclared_target_shape`	object or null	The minting run’s guidance when the target is shaped like a Data Vault but the comparison’s spec declared no `target_model`. It identifies the detected shape, the model to declare, and how many readings were withheld. It explains the withholding; it does not decide it. `null` on other comparisons.
`withheld_count`	integer or null	Number of members whose `resolution` is `withheld`, counted from the population marks. Withheld readings remain in `total_count` and are not folded into `unresolved_count`; `null` means the population is incomplete.
`withheld_readings`	object[] or null	When the target-shape guidance applies, the coordinates `{comparison, object_name, column}` of every reading withheld from the comparison, including when the population is incomplete. This is provided for screens that build findings from the diff themselves; `null` on other comparisons.
`object_presence`	object or null	Per-source-object disclosure of whether the target holds the object. `objects` lists every `missing`, `undetermined`, and `absent_as_declared` object before up to `200` `present` objects; `counts` is exact; `surplus` lists up to `200` target objects not in the source and `surplus_count` is exact. `not_built` separately lists declared derived targets that are missing from the build; these are not source objects and are excluded from the source-object counts. `omitted` gives the number not listed and `truncated` indicates either list was cut. `withheld: true` means no one-to-one readings were published, so presence is `undetermined` rather than inferred. `basis` identifies the comparison elements used. `null` means the comparison predates this disclosure, not that all objects are present.
`not_measured`	object or null	Exact disclosure of readings whose verdict was `indeterminate` or `errored`. `readings` lists up to `200` entries with `object`, `column`, `comparison`, `verdict`, and `cause`; `count` and `by_cause` cover the full population; `omitted` and `truncated` describe the bounded list; `rest` identifies the `read_comparison` call that returns the remainder. `withheld: true` says the comparison withheld its one-to-one readings. `null` means the comparison predates this disclosure, not that no readings were unmeasured.
`comparisons_matched`	integer or null	Number of comparisons the engine matched, as recorded in the diff. `null` means no count was recorded. With `nothing_compared: true`, `0` means re-prove with a `schema_map`, except when `nothing_compared_cause` is `declared_mapping_matched_zero`: check that the target snapshot is the build described by the mapping, then re-prove. `null` means re-run the comparison; when no mapping was declared, declare the mapping.
`nothing_compared`	boolean	`false`	`true` when the comparison compared nothing: its stored `matched_count` is `0` (no object on one side was addressed to one on the other, whatever the cause, including an undeclared schema map), no matched count can be read for it, or its readings were withheld because no object paired on either side and no mapping was declared. Such a comparison cannot carry an approval unless the population carries a `spec_grade`; a verified one permits approval once the population is complete and `unresolved_count` is `0`. No `spec_grade` is ever carried when `nothing_compared_cause` is `schema_map_undeclared`: nothing was addressed, so only a re-prove with a `schema_map` lifts the refusal. `false` when something matched, including when unpaired readings are published beside guidance.
`nothing_compared_cause`	string or null	`null`	Remedy for a comparison that compared nothing: `undeclared_target_shape` (declare the mapping as the spec’s `target_model`), `declared_mapping_matched_zero` (check the target snapshot is the build the mapping describes, then re-prove), `no_matched_count` (re-run the comparison so it records a count), `schema_map_undeclared` (the comparison’s own engine says no `schema_map` addressed the source to the target, so nothing was compared: re-prove with one; no `spec_grade` stands in for it), or `matched_zero` (re-prove with a `schema_map`). `null` when `nothing_compared` is false. The cause uses the same priority as the approval refusal’s next call.
`spec_grade`	object or null	`null`	The specified grade that stands for the comparison’s verdict. For a comparison whose tables paired none (`matched_zero` or `declared_mapping_matched_zero`) because its spec derives the target from the source, it carries `run_id`, `verified`, `status`, and `blockers`; the run decision reads it in place of the empty pairing, allowing a verified grade to proceed to the ordinary completeness and blocker rules and refusing an unverified one with `reason: "spec_grade_not_verified"`. For a comparison whose tables paired, it is the review page’s selected specified grade and also carries `tables_paired: true` and `accounting`: `explained`, `unexplained` (null when drift was not measured), `indeterminate`, `errored`, and `outside_scope` (source tables a narrow spec does not claim to cover). A pending grade has `status: "pending"` and `pending: true`; it has no verdict accounting. `null` when no specified grade stands for the comparison.

For a partial seal, spec_grade.open_clauses is the number of clauses left open and spec_grade.spec_seal_state is partial; an unreadable seal kind is unknown. Such a grade has verified: false and cannot stand in for a verified grade on a comparison with no paired tables. Each item in members includes finding_id, kind (unexpected_change, missing_requirement, or evidence_gap), comparison, object_name, column, spec_id, locus, description, detail, source_value, target_value, cause, related_finding_id, rename_hypothesis_basis, samples, and resolution. samples is empty except on a failed spec check (comparison obligation_failed), which has no single source or target value. It lists the keys the check’s detail sentence quotes, each with the same evidence the sentence gives it. Each entry has key, column, source, target, no_row_on and sampled. source and target are the values the check read, where null is SQL NULL and "" is empty text; a key that differed in several columns has one entry per column. no_row_on is source or target when the check placed every failing key on that side, and the entry then carries no values. sampled is false for a quoted key the check sampled no value for and placed on no side. unexpected_change members also include finding_key and witnesses_available. finding_key is the findings-ledger key accepted by the finding-scoped witness endpoint; it is populated only when exactly one non-closed ledger finding was minted at the member’s coordinate. It is null for requirement or evidence gaps, an unminted locus, or an ambiguous coordinate shared by multiple entity-scoped findings. witnesses_available is true when that key can be used to fetch a witness document and otherwise false; a witness document may still disclose that localization was declined. resolution is open, ruling, exception, or withheld: ruling means a person’s recorded ledger ruling accounts for the member, exception means an approved one-time exception accounts for it, withheld means the engine measured a reading from an undeclared Data Vault pairing and nobody needs to disposition it, and open means neither a person nor the engine accounts for it. When both a person decision and withholding could apply, the person decision remains. Withholding applies only to unexpected_change and evidence_gap members at the coordinates in withheld_readings; an unmet missing_requirement remains unresolved. When exactly one object_missing member and one object_surplus member share the same final dotted object-name segment, both are annotated with cause="rename_hypothesis", each member’s related_finding_id points to the other finding, and rename_hypothesis_basis is measured_agreement when their measured row count and boundaries agree or shared_object_name when only the final dotted name segment matched. Measurement agreement is considered before name matching, and ambiguous candidates are not linked. Name matching follows the comparison’s case_insensitive_object_names setting. For a partial seal, each open clause adds an evidence_gap member with cause: "open_clause" and object_name / locus set to clause <clause-id>. Each clause is independently addressable; it remains resolution: "open" until accounted for. Requested-change members also include failed_by, the ids of the spec checks that failed that item. It is empty when no check failed it and on every other member. This field distinguishes an item known to have failed from one no check decided. A failed spec-check member also includes relations_read: the graded-side tables it read, in record order, when no structural item claims the check (object_name is empty). It is empty on other members and when the check has a structural object. Use this list for the objects named by the check instead of parsing its display locus. A new target column nobody accounts for appears as an evidence_gap with cause: "target_column_unaccounted", its object.column in locus, and a description and detail explaining the person decision. It remains open until reviewed; an approved exception package records the columns as expected, while a column judged spurious must be sent back as a defect. See scope verdicts for how the grade identifies these columns. An input scope member also carries scope_target_presence: present or absent according to whether the target holds the object. It is null on every other member; unlike scope_status: "indeterminate", it distinguishes an input that is present from one that is absent. For a failed-check member, detail makes sampled evidence unambiguous: SQL NULL is shown as NULL, empty text as "" (empty text), and text that spells either marker is quoted and marked (text). A quoted key says (no row on the source) or (no row on the target) when its missing side was established; different keys can identify different missing sides. If no value was sampled and no side was established, it says (no value sampled). Numeric-looking text with leading zeroes, such as 0110, keeps its digits rather than being read as a number. resolution may also be false_alarm for a member settled by an instrument_defect ruling; those members are counted in resolved_as_false_alarm_count rather than resolved_by_ruling_count. See False alarm (Prover) for the user-facing meaning. Use this route (not a truncated findings sample) to page the full worklist and to obtain the run_id / population_hash pair callers should send with approval writes.

Status	Meaning
`404`	Comparison not found.

`GET /api/estate/grades/{run_id}/review/population`

Field	In	Type	Default	Required	Description
`run_id`	path	string	none	Yes	Run id of a grade that read no comparison.
`offset`	query	integer	`0`	No	Pagination offset into the grade’s failed-check worklist. Minimum `0`.
`limit`	query	integer	configured page size	No	Page size. Defaults to and is clamped to `estate_char.findings.family_members_page_size` (schema default `500`).

The response has the same member-page fields as the comparison population route, but its members are the grade’s failed checks and its review is addressed by run_id, not a comparison hash. comparison_made is false; proofless_grade identifies the spec and seal that were graded, displays the disclosure that no comparison against a build was made, and includes the next call that can create one. approval_refusal is always present and explains that the review can take rulings but cannot carry an approval. resolved_by_exception_count counts failed checks covered by approved one-time exceptions. The route returns 404 when the run is not a grade that read no comparison or when the caller may not see the run.

`POST /api/estate/grades/{run_id}/review/finding`

Field	In	Type	Default	Required	Description
`run_id`	path	string	none	Yes	Run id of a grade that read no comparison.
`finding_id`	body	string	none	Yes	Failed-check finding id from the proofless review population.
`diagnosis`	body	string or null	omitted	No	Diagnosis slug. Omitted = leave unchanged; an explicitly empty string clears the field.
`disposition`	body	string or null	omitted	No	Next-action slug. Omitted = leave unchanged; an explicitly empty string clears the field.
`workflow`	body	string or null	omitted	No	Workflow-status slug. Omitted = leave unchanged; an explicitly empty string clears the field.
`owner`	body	string or null	omitted	No	Accountable owner. Omitted = leave unchanged; an explicitly empty string clears the field.
`exception_approved`	body	boolean or null	omitted	No	One-time-exception approval flag. Omitted = leave unchanged.
`run_id`	body	string or null	omitted	No	Expected grade run id for optimistic concurrency.
`population_hash`	body	string or null	omitted	No	Expected proofless review population hash; supply it with the body `run_id` when either is set.

At least one review-state field must be present. The route applies the same patch semantics as the comparison finding route and returns the refreshed proofless review page, including approval_refusal. Granting exception_approved: true requires a genuinely authenticated human on an auth-enabled stack. A stale expected grade or population returns 409; a non-proofless or hidden run returns the same 404 as the proofless review-page read.

`GET /api/estate/comparisons/{diff_hash}/review/evidence-gap-packages`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Mediated-diff id.

The response includes data with the currently offered evidence-gap exception packages and their population binding:

Field	Type	Description
`diff_hash`	string	Comparison identifier.
`run_id`	string or null	Finished conformance `run_id` that binds the offered packages. `null` when no finished population can be resolved.
`population_hash`	string or null	Content hash of the complete worklist bound to the packages. `null` when no complete population can be resolved.
`packages`	object[]	One package per `(object_name, cause)` pair. Packages group evidence gaps that share one measured abstention cause; they do not create a disposition or correspondence rule.

Each item in packages includes package_id, object_name, cause, measured_columns, member_finding_ids, members, member_count, open_count, approved_count, package_approved_count, and approved_by. Evidence gaps withheld because the comparison paired a legacy object with an undeclared Data Vault object are not offered as exception packages; read the population response’s undeclared_target_shape and withheld_readings instead. Each item in members includes finding_id, comparison, column, locus, detail, and resolution. measured_columns identifies where the abstaining measurements sit; it is not a claim that those columns caused a sibling’s abstention. approved_count includes members accounted for by any exception on the population, while package_approved_count counts only members signed by this package. approved_by is populated only when this package’s signature covers every member. An evidence-gap package is offered only when the comparison has a finished run and a complete stored population. Members without a recorded machine cause are not packaged and remain available for per-finding review. Package ids are tied to the run, population hash, object, and cause, so a stale id from a superseded population is not reusable.

Status	Meaning
`404`	Comparison not found.

`POST /api/estate/comparisons/{diff_hash}/review/evidence-gap-packages/{package_id}/approve`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Mediated-diff id.
`package_id`	path	string	none	Yes	Evidence-gap package id returned by the package-list route.

The request has no body. The server accepts every open member currently covered by the package, binds each approval to the package’s run_id and population_hash, and records the authenticated human as approved_by. Members already accounted for by any exception on that population are skipped; the package does not create a ruling, disposition, or correspondence rule. The response includes data with package_id, diff_hash, approved_count (members changed by this call), unresolved_count (members still blocking sign-off), and approved_by. Granting the package requires the same genuinely authenticated-human check as a per-finding exception approval. On an auth-enabled stack, system, machine, and delegated identities receive 403; with auth disabled, the approval is permitted and attributed locally.

Status	Meaning
`403`	A non-human identity tried to approve an evidence-gap package on an auth-enabled stack.
`404`	Comparison not found, or the package id is not currently offered.

`POST /api/estate/comparisons/{diff_hash}/review/evidence-gap-packages/{package_id}/withdraw`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Mediated-diff id.
`package_id`	path	string	none	Yes	Evidence-gap package id returned by the package-list route.

The request has no body. The server withdraws only the members approved by this package, reopening them for review. Hand-approved members and members approved by another package remain accounted for. Any permitted reviewer or service identity may withdraw the package; this route does not require the original signer or the genuinely authenticated-human approval gate. The response includes data with package_id, diff_hash, and reopened_count (members reopened by this call). Re-read the review population after withdrawal to refresh the worklist and sign-off counts.

Status	Meaning
`404`	Comparison not found, or the package id is not currently offered.

`GET /api/estate/comparisons/{diff_hash}/witnesses`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Mediated-diff id.
`comparison`	query	string	none	Yes	Review-population member’s comparison coordinate. Minimum length `1`.
`object`	query	string	none	Yes	Review-population member’s `object_name` coordinate. Minimum length `1`.
`column`	query	string or null	`null`	No	Review-population member’s column coordinate. Omit it for an object-level finding. Minimum length `1` when supplied.
`timeout_seconds`	query	integer	`30`	No	Wall-clock budget for live estate queries. Clamped to `5`–`120`.
`refresh`	query	boolean	`false`	No	When `true`, bypass the persisted row-sample cache and re-run the live cross-estate probe against current data.

Use the comparison, object, and column values from one review-population member. The response is the same bounded witness document served by GET /api/estate/findings/{finding_key}/witnesses: per-side column definitions and rows, counts, alignment caveats, and the full plan disclosure. Exact, sampled, and declined localization semantics are preserved. This route is useful when finding_key is unavailable; only findings on comparisons the caller may see are considered, and it refuses to guess when multiple visible entity-scoped findings share the coordinate. A hidden comparison is answered as not found. For a comparison with a verified caller-declared row identity, witness localization pairs rows under that declared key. Otherwise it uses the comparison’s disclosed basis, if any, and preserves the existing declined or sampled behavior when localization cannot be proved.

Status	Meaning
`404`	Comparison was not recorded, or no ledger finding was minted at the supplied coordinate.
`409`	Multiple ledger findings share the supplied coordinate; use one returned `finding_key` with the finding-scoped witness endpoint.

`POST /api/estate/comparisons/{diff_hash}/review/finding`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Mediated-diff id.
`finding_id`	body	string	none	Yes	Finding id. Minimum length `1`, maximum `512`.
`diagnosis`	body	string or null	omitted	No	Diagnosis slug. Maximum length `64`. Omitted = leave unchanged; an explicitly empty string clears the field.
`disposition`	body	string or null	omitted	No	Next-action slug. Maximum length `64`. Omitted = leave unchanged; an explicitly empty string clears the field.
`workflow`	body	string or null	omitted	No	Workflow-status slug. Maximum length `64`. Omitted = leave unchanged; an explicitly empty string clears the field.
`owner`	body	string or null	omitted	No	Accountable owner. Maximum length `255`. Omitted = leave unchanged; an explicitly empty string clears the field.
`exception_approved`	body	boolean or null	omitted	No	One-time-exception approval flag. Omitted = leave unchanged.
`run_id`	body	string or null	omitted	No	Conformance `run_id` of the population the reviewer acted against. Maximum length `255`. Must be supplied together with `population_hash` when either is set.
`population_hash`	body	string or null	omitted	No	Content hash of that population’s complete worklist. Maximum length `64`. Must be supplied together with `run_id` when either is set.

At least one of diagnosis, disposition, workflow, owner, or exception_approved must be present in the request body. Patch semantics: only fields explicitly set in the body are applied, so two reviewers editing different fields of one finding merge instead of clobbering each other. Writes to the same field are last-write-wins; superseded values remain in the finding’s audit trail. Changing diagnosis or disposition retracts exception_approved and resets the run-level decision to awaiting_review. When exception_approved is true and both run_id and population_hash are present, the server records exception_run_id and exception_population_hash on the finding so a later re-grade cannot silently reuse the exception. When a disposition package approval resolves the exception, the response also records the package id in exception_package_id; this field is server-written and is null for a hand-approved exception. Granting a one-time exception (exception_approved: true) additionally requires a genuinely authenticated human: on a stack with auth enabled a system, machine or delegated identity is refused with 403. The annotation fields — and clearing an exception — are not gated that way. With auth disabled the approval is permitted and attributed locally, because every caller on such a stack already reads as the administrator. Successful responses include data with the whole folded comparison review state (not just the edited finding), so a reviewer sees concurrent writes the moment they save. The author is taken from the authenticated request context (email, then display name, then user id), never from the body; when auth is disabled or no identity is available, writes are attributed to local operator (auth disabled).

Status	Meaning
`403`	A non-human identity tried to grant an exception on an auth-enabled stack.
`404`	Comparison not found.
`422`	Validation failure (for example an empty patch with no fields set, or `run_id` without `population_hash`).

`POST /api/estate/comparisons/{diff_hash}/review/findings/bulk`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Mediated-diff id.
`finding_ids`	body	string[]	none	Yes	Review-log subjects to adjudicate. Minimum `1`, maximum `200`; each id must be `1` to `512` characters and may appear only once.
`diagnosis`	body	string or null	omitted	No	Diagnosis slug. Maximum length `64`; only an explicitly set field is applied.
`disposition`	body	string or null	omitted	No	Next-action slug. Maximum length `64`; only an explicitly set field is applied.
`workflow`	body	string or null	omitted	No	Workflow-status slug. Maximum length `64`; only an explicitly set field is applied.
`owner`	body	string or null	omitted	No	Accountable owner. Maximum length `255`; only an explicitly set field is applied.
`exception_approved`	body	boolean or null	omitted	No	One-time-exception approval flag.
`comment`	body	string or null	omitted	No	Shared rationale appended to every named finding. Maximum length `4000`.
`run_id`	body	string or null	omitted	No	Conformance run bound to an exception approval. Maximum length `255`; must be supplied with `population_hash`.
`population_hash`	body	string or null	omitted	No	Complete worklist hash for the exception population. Maximum length `64`; must be supplied with `run_id`.

The request applies one explicitly-set review patch and optional shared comment to every named finding in a single transaction. It is all-or-nothing: blank or duplicate ids, more than 200 ids, ids over the length limit, or a request that sets neither a review field nor a comment is refused before any event is written. Granting an exception carries the SAME human-authority requirement as the single-finding route, so a caller refused there cannot approve by batching. For a group exception (exception_approved: true) without an explicit owner, the authenticated reviewer is recorded as the owner of each named finding that has no owner; existing owners are preserved. The response includes the whole folded comparison review state plus adjudicated_count and event_count (the number of findings changed and review log rows appended). Event ordering is preserved across all named findings.

Status	Meaning
`400`	Invalid or duplicated finding ids, too many findings, or an empty adjudication.
`403`	A non-human identity tried to grant an exception on an auth-enabled stack.
`404`	Comparison not found.
`422`	Validation failure, including an incomplete `run_id` / `population_hash` pair.

`POST /api/estate/comparisons/{diff_hash}/review/comment`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Mediated-diff id.
`finding_id`	body	string	none	Yes	Finding id. Minimum length `1`, maximum `512`.
`text`	body	string	none	Yes	Comment text. Minimum length `1`, maximum `4000`. Whitespace-only text is refused.

Comments are append-only — they are never edited or deleted. Successful responses include data with the whole folded comparison review state. Author attribution follows the same rules as POST .../review/finding.

Status	Meaning
`404`	Comparison not found.
`422`	Validation failure (for example whitespace-only `text`).

`POST /api/estate/comparisons/{diff_hash}/review/decision`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Mediated-diff id.
`decision`	body	string	none	Yes	Run-level review verdict. One of `awaiting_review`, `approved`, or `approved_with_exceptions`.
`authority`	body	string or null	`null`	No	Optional free text stating who authorised this decision, in the caller’s words. Maximum length `4000`. It is recorded beside the server-derived reviewer identity and does not authorize the request. `awaiting_review` cannot carry `authority`; omit it when resetting the verdict.
`run_id`	body	string or null	omitted	No	Conformance `run_id` of the population the reviewer approved. Maximum length `255`. Optional optimistic-concurrency coordinate — when set, must match the server’s selected population or the write is refused.
`population_hash`	body	string or null	omitted	No	Content hash of that population’s complete worklist. Maximum length `64`. Optional optimistic-concurrency coordinate — when set, must match the server’s selected population or the write is refused.

Successful responses include data with the whole folded comparison review state. When decision is awaiting_review, decided_by, decided_at, decision_run_id, and decision_population_hash are cleared. For approved / approved_with_exceptions, the server validates that the selected population is complete, has unresolved_count == 0, and records run_id / population_hash on the approval event. Author attribution follows the same rules as POST .../review/finding. Recording ANY run-level verdict requires a genuinely authenticated human: on a stack with auth enabled a system, machine or delegated identity is refused with 403. That rule covers approved, approved_with_exceptions, and awaiting_review alike: resetting a verdict is a statement about the run just as an approval is, so it is not an authority-free escape from the gate. With auth disabled the verdict is permitted and attributed locally, because every caller on such a stack already reads as the administrator.

Status	Meaning
`403`	A non-human identity tried to record the run verdict on an auth-enabled stack.
`404`	Comparison not found.
`409`	Approval refused — nothing was compared, the population is incomplete, it still has unresolved blockers, or `run_id` / `population_hash` no longer match the selected population. When nothing was compared and blockers also exist, the refusal message names both the unresolved blocker count and the known pairing reason instead of claiming that nothing was compared. When a `spec_grade` stands for the comparison and is not verified, the refusal instead carries `reason: "spec_grade_not_verified"`, the grade, and a `next` naming `read_comparison`; a verified one lifts the nothing-compared refusal. A `schema_map_undeclared` comparison never carries one, so its refusal stands until it is re-proved with a `schema_map`. Otherwise the refusal payload includes `reason: "nothing_compared"` and a `next` call for that case: `author_spec` with a `target_model` for `undeclared_target_shape`; `prove` again when no matched count can be read; `prove` with a `schema_map` for `matched_zero` and `schema_map_undeclared`; or, for `declared_mapping_matched_zero`, check that the target snapshot is the build described by the mapping and then re-prove.
`422`	Validation failure (for example an unknown `decision` value, or `authority`, `run_id`, or `population_hash` supplied with `awaiting_review`).

`POST /api/estate/comparisons/{diff_hash}/review/propose-rule`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Mediated-diff id.
`finding_id`	body	string	none	Yes	Review-log subject (the finding the audit event is recorded against). Minimum length `1`, maximum `512`.
`finding_key`	body	string	none	Yes	Ledger key the server reads first-hand evidence from — evidence is never taken from the client. Minimum length `1`, maximum `512`.

Drafts a reusable Π rule from the finding’s first-hand evidence and records the proposal. The rule enters the Π review worklist at pending_review (still status='proposed' — never auto-ratified), attributed to the caller, and the review-log event is written in the same transaction. Successful responses include data with the whole folded comparison review state plus proposed_rule_id (the new rule id). Author attribution follows the same rules as POST .../review/finding.

Status	Meaning
`404`	Comparison not found or not visible to the caller, or the finding has no first-hand evidence to propose a rule from.
`409`	For a caller with `manage_all_connections`, an endpoint has no estate or scan-run connection binding, so no principal can open the review link. Nothing is staged; the response names the affected snapshot and its recorded connection, when present.

`POST /api/estate/comparisons/{diff_hash}/review/propose-cluster-rule`

Field	In	Type	Default	Required	Description
`diff_hash`	path	string	none	Yes	Mediated-diff id.
`members`	body	object[]	none	Yes	The cluster’s findings, each `{finding_id, finding_key}` as `POST .../review/propose-rule` takes them. Minimum `1`, maximum `200`; each `finding_id` may appear once.

Proposes one reusable ruling for a same-cause cluster. Each member gets its own single-column rule, drafted from its own first-hand evidence (never from the client), so every licence keeps its one-element boundary. Rules that fold the same way share a mechanism signature, so the Π worklist presents the cluster as one question over every member’s site, which one consent signs. In the same transaction, every member with no owner is recorded as owned by the caller. Successful responses include data with the whole folded comparison review state plus proposed_rule_ids, one per member, in member order. The same transaction records the ruling itself, which the state reports in cluster_rulings with the caller as owner; proposing the same members again records nothing new and keeps the first owner. All or nothing:

Status	Meaning
`400`	A member derives no reusable rule from its evidence, or derives a different rule from the rest of the cluster (a different normalizer, type map or type pin), or derives a rule that was rejected (proposing it again cannot revive it; the detail names the rule). The detail names those members. Also a repeated `finding_id`. Nothing is written.
`422`	An empty or blank `finding_id` / `finding_key`, no members, or more than `200` members. Refused by the request schema; nothing is written.
`404`	Comparison not found or not visible to the caller.
`409`	For a caller with `manage_all_connections`, an endpoint has no estate or scan-run connection binding, so no principal can open the review link. Nothing is staged; the response names the affected snapshot and its recorded connection, when present.

`POST /api/estate/verifications`

Run a system_diff Contract against its pre-registered source / target connections server-side, or verify a sealed compiled derivational artifact by compiled_spec_hash, and return the whole verification result. The comparison executes under the authenticated caller’s identity (connection RBAC applies), never a body-supplied bot — matching every other estate engine call. Verification references existing connections and never creates one or reads its credentials. Supply exactly one form:

spec — a single Contract as a JSON object (connections live inside the Contract),
spec_yaml — the same Contract as YAML text, or
compiled_spec_hash — a sealed derivational artifact in the compiled-spec store, verified by ref and expanded into one comparison per obligation.

The compiled_spec_hash form carries no connections (a blind-authored artifact only ever saw a source catalog), so source_connection_id and target_connection_id are required with it — they are injected into every obligation at verify time and must already be registered on the instance. A registered connection may be a legacy database connection or a saved Connections-API database connection; for the latter, use its <type>.<name> identifier. A saved Connections-API connection with a registered query transport, such as palantir_foundry, is also valid. Other non-queryable Connections-API entries are not valid verification bindings. Optional source_db_type / target_db_type override engine selection; when omitted, engines are resolved from the registered connection metadata (defaulting to snowflake when unknown).

Field	In	Type	Default	Required	Description
`spec`	body	object or null	`null`	No*	The Contract as a JSON object.
`spec_yaml`	body	string or null	`null`	No*	The Contract as YAML text (alternative to `spec`). Maximum length `200000`.
`compiled_spec_hash`	body	string or null	`null`	No*	Content hash of a sealed compiled derivational artifact to verify by ref. Maximum length `255`.
`source_connection_id`	body	string or null	`null`	No**	Registered source connection injected into every obligation (required with `compiled_spec_hash`). Maximum length `255`.
`target_connection_id`	body	string or null	`null`	No**	Registered target connection injected into every obligation (required with `compiled_spec_hash`). Maximum length `255`.
`source_db_type`	body	string or null	`null`	No	Optional source engine for the by-ref form; resolved from the registered connection when omitted. Maximum length `255`.
`target_db_type`	body	string or null	`null`	No	Optional target engine for the by-ref form; resolved from the registered connection when omitted. Maximum length `255`.
`invariant_side`	body	string	`source`	No	For the by-ref form, the fallback estate for single-relation `invariant` obligations that declare no `invariant_side` of their own (one that does is graded on the side it declares). `source` grades against `source_connection_id` and `source_catalog`; `target` grades against `target_connection_id` and `target_catalog`. Keyed obligations always compare source vs target.

* Provide exactly one of spec, spec_yaml, or compiled_spec_hash. Supplying none or more than one returns 422. ** Required when compiled_spec_hash is supplied. For a by-ref request, an invariant obligation is graded wholly on one estate rather than compared source-to-target. An obligation that declares its own invariant_side in the compiled spec is graded on the side it declares; this request field is the FALLBACK for every obligation that declares none, and defaults to source. Set it to target when the target estate is the one being built and validated. The selected side’s connection and catalog are used together, so target requires target_connection_id; an unsupported value or a missing target connection returns an ERROR result for the affected invariant instead of falling back to the source estate. This selector does not change keyed obligations, which continue to compare the source and target estates. When both sides use the same registered connection, invariant_side: "target" requires target_catalog when the resolved engine can bind more than one catalog (for example, Databricks or Snowflake). On an engine known to use one database per connection, the connection itself identifies the database, so a target-side invariant may omit target_catalog and is graded against that database. An unstated engine keeps the catalog requirement because the system cannot prove that the connection is single-database. For source_catalog and target_catalog, the same admission rule applies as for the persisting compiled grade: on an engine that cannot bind a session catalog, a named value must match the database recorded by that side’s snapshot or the request returns 400 before any obligation is graded. See the compiled grade catalog contract. Inline Contract responses (spec / spec_yaml) include data with the full single-run engine result:

Field	Type	Description
`run_id`	string	Persisted verification run id.
`verdict`	string	Engine verdict (for example `PASS`, `FAIL`).
`rows_compared`	integer or null	Rows compared when applicable.
`mismatched_key_count`	integer	Count of localized mismatched keys; when `mismatched_key_count_semantics` is `lower_bound`, this is a floor rather than the full count.
`mismatched_keys`	array	Localized key values the chat finished path drops.
`mismatched_keys_overflow`	integer	Additional mismatched keys found past the stored-key cap, when positive.
`mismatched_key_count_semantics`	string	`lower_bound` when localization stopped early, so `mismatched_key_count` must be read as a floor; omitted for a measured count.
`mismatch_directions`	object	Counts localized keys by direction: `only_source`, `only_target`, or `differing`. Hash-based localization records these directions too; `unclassified` means the per-run mismatch-key detail cap left the key without a direction.
`differing_columns`	object	For `differing` keys, counts by column of the keys outside tolerance.
`differing_samples`	array	Bounded samples of differing keys with `key`, `column`, `source`, and `target` values. Values are text and are included when the verifier localized the difference.
`one_sided_samples`	object	Bounded key samples by membership direction: `only_source` and `only_target`, with up to five keys per direction. These identify which keys are present on only one side; `mismatch_directions` gives the counts. Older stored records may omit this field.
`hot_suspended_key_count`	integer	Count of hot-suspended keys.
`hot_suspended_keys`	array	Hot-suspended key values.
`per_column`	object	Per-column comparison detail.
`aggregate_failure_count`	integer	Count of aggregate value-pair failures.
`aggregate_failures`	array	Source vs target aggregate value pairs (count/sum/min/max) the chat finished path drops.
`localization_method`	string or null	How mismatched keys were localized.
`key_duplicates`	object or null	Key-duplicate evidence when present.
`key_nulls`	object or null	Key-null evidence when present.
`key_type_conflicts`	object or null	Key type-conflict evidence when present.
`truncated`	boolean	Whether the run was truncated.
`truncation_reason`	string or null	Why the run was truncated.
`reason`	string or null	Engine explanation for an `INDETERMINATE` result when available, including a checksum that verified key membership but had no value column to measure.
`indeterminate_reason`	string or null	Machine-readable reason for an indeterminate result. `checksum_key_only` means the checksum projection contained only key columns, so content was not verified.
`watermark`	object or null	Watermark metadata when present.
`instrument`	object or null	Instrument metadata when present.

Compiled-spec responses (compiled_spec_hash) include data with a batch result:

Field	Type	Description
`spec_hash`	string	The compiled artifact hash verified.
`seal`	object	Seal metadata from the verified artifact.
`obligations`	array	One summary per obligation (`obligation_id`, `kind`, `title`, `verdict`, localized evidence, `run_id`, and `error` when applicable). Each summary also includes `relation`, the declared locus (`invariant` relation or `null` for comparison obligations), plus `source_catalog_effective` and `target_catalog_effective`, identifying the catalogs actually read; an invariant populates only its graded side, and an `ERROR` leaves both `null`. `source_read` is `null` when no landed-copy substitution was used; for an eligible keyed Foundry-source obligation served from a full landed copy, or a source-side invariant whose relation is served from one, it is an object with `read_from: "landed_copy"`, `copies` (each with `dataset_rid`, three-part Databricks `table`, and warehouse-reported `landed_at`), and a `statement` describing the substitution. Invariant summaries also include `invariant_violation_count`, `rows_compared` (the rows examined by the same scan, or `null` when the invariant errored), and `invariant_relation`. `relations_read` lists the graded-side tables parsed from `target_sql`; when the parser cannot read that SQL in the target engine’s dialect, `target_sql_unreadable` gives its reason and `relations_read` includes only any relation declared directly on the obligation. An errored obligation may include `cause` as `spec_as_written` or `instrument`; it is `null` when the instrument did not declare a cause. Keyed obligations also carry the engine’s `engine_verdict`, plus `key_duplicates`, `key_nulls`, and `key_type_conflicts` when the key probes measured duplicate, NULL-bearing, or differently typed key evidence. They also carry `truncated`, `truncation_reason`, `reason`, and `indeterminate_reason` when an indeterminate read needs its measured refusal recorded. These fields explain an `INDETERMINATE` key refusal rather than a check that never ran; `cause: "instrument"` is used when a side could not type a key or the run stopped before deciding, while a key-only checksum is `cause: "spec_as_written"`. When a keyed obligation localizes mismatches, its evidence also includes `mismatched_key_count_semantics: "lower_bound"` when the count is a floor, `mismatched_keys_overflow` when additional keys were found past the cap, `mismatch_directions`, `differing_columns`, bounded `differing_samples`, and `one_sided_samples` (up to five key values in each of `only_source` and `only_target`); a one-row differing check can therefore show the compared column and its source and target values.
`probe_records`	array	Grain-probe quarantine records from the fan-out pass.
`degeneracy`	object	One probe reading per obligation, keyed by `obligation_id`. Each reading is `measured`, `errored`, or `unmeasured`, with the probe’s `findings` and a `basis`. A reading taken from a landed copy also includes the same `source_read` evidence as its obligation. The probe reads up to 20,000 rows per probeable obligation.
`read_started_at`	string	UTC ISO-8601 timestamp when live obligation reads began.
`read_finished_at`	string	UTC ISO-8601 timestamp when live obligation reads and the degeneracy probe finished.
`summary`	object	Batch counts: `obligation_count`, `verdicts` (map), `probed_count`, `quarantined_count`, `quarantined_obligation_ids`.

An errored compiled-spec obligation may also include errored_sql; see the compiled-grade response for its fields. For a Foundry source with a Databricks target and keyed obligations that read dataset RIDs, verification also searches the Databricks target schemas named by the obligations’ target_sql: one information_schema.tables read per schema and one SHOW TBLPROPERTIES per listed table. A schema with more than 200 tables is skipped. Only one full stamped copy per RID is eligible; a row-limited sample, a table marked as a pipeline rebuild, or an ambiguous copy is not used. If selected, the obligation’s source SQL runs on the target connection and engine. A source-side invariant may also use a landed copy when its relation names a dataset RID and no obligation’s target-side read uses that copy; an invariant graded on the target keeps its target read. The search is best-effort; when it cannot establish an eligible copy, verification uses the usual source-side route. See the Prover guide for the full grade behavior and the Foundry migration tools guide for how copies are stamped and how to adopt a pre-existing table. For a keyed obligation that errors, the verifier checks whether its target_sql reads columns the target relation lacks. When the compiled artifact declares a target_model, only the columns that model declares for the relation are considered; when it declares none, every column the statement reads is. When a first-row read confirms that the target relation exists and lacks one of those columns, and the source population can be counted, the obligation is returned as FAIL over that population rather than ERROR: every source row is charged to the failure because the target statement could not run. No key was localized, so mismatched_key_count is null; the population is unchecked_source_rows. Its summary includes missing_target_columns (relation.column names), and also missing_declared_columns when the columns come from target_model. If the relation cannot be read, returns no row, or the source population cannot be measured, the original ERROR remains. Invariant obligations are graded as source-side column-domain checks rather than keyed source-vs-target comparisons. A valid invariant runs against invariant_relation on the source connection and reports both the population it examined in rows_compared and the violations in invariant_violation_count: a violation count of 0 produces PASS, and a count greater than 0 produces FAIL. Malformed invariants, failed queries, or invariants with no gradable constraint produce ERROR; their violation count and rows_compared are null. Invariant checks support not_null, numeric min / max, non-empty allowed_values, and finite declarations. finite is recorded but emits no predicate in this grade, so it does not by itself produce a violation. Numeric bounds and allowed_values do not count a NULL as a violation under SQL three-valued logic; add not_null when a NULL must fail. An unbindable catalog also produces ERROR; its violation count and effective catalog fields are null. The compiled-spec pass also runs a read-only degeneracy probe against the source for each obligation whose expected side is executable. The probe is capped at 20,000 rows per obligation and never changes the verdict: measured records what it read and which of the three known degeneracies it found, errored records a refused or failed probe, and unmeasured records an obligation the probe did not execute or a source it could not open. Use read_started_at and read_finished_at as the live-read window; obligations run sequentially, so the timestamps are not a claim that every read happened at one instant.

Status	Meaning
`400`	Contract could not be parsed; an endpoint references an unregistered connection; the compiled artifact is unsealed or tampered; or the Contract / obligation is not yet supported by the engine (for example checksum methods on compound or non-integer keys).
`503`	The connection store could not be read while checking the Contract’s registered connections. Genesis reports the store outage instead of treating the registry as empty and returning an unregistered-connection error.
`404`	Unknown `compiled_spec_hash`.
`422`	No spec form supplied, more than one form supplied, or `compiled_spec_hash` without both `source_connection_id` and `target_connection_id`.

`POST /api/estate/episodes/import`

Import one bench loop-gate artifact bundle (report.json plus optional journal.json, loop_result.json, and compiled obligations) as a stored reconciliation episode. report is the only required artifact — a report-only bundle imports as an open episode with zero rounds. journal and loop_result carry reconcile rounds when the loop was driven; obligations upgrades finding identity from the fallback family key to the full semantic anchor. Party identities default to the journal’s; a journal-less bundle must name implementer_id and prover_id explicitly.

Field	In	Type	Default	Required	Description
`spec_family`	body	string	none	Yes	Spec family for scope and finding identity. Minimum length `1`, maximum `255`.
`report`	body	object	none	Yes	The loop-gate `report.json` object.
`journal`	body	object or null	`null`	No	The loop-gate `journal.json` object.
`loop_result`	body	object or null	`null`	No	The loop-gate `loop_result.json` object.
`obligations`	body	object[] or null	`null`	No	Compiled obligation entries for anchor identity.
`estate_id`	body	string or null	`null`	No	Estate scope anchor (wins over `connection_ref` when present). Maximum length `255`.
`connection_ref`	body	string or null	`null`	No	Connection scope anchor when `estate_id` is omitted. Maximum length `255`.
`subject_kind`	body	string	`"bench_task"`	No	Subject kind stamped on the episode. Maximum length `32`.
`implementer_id`	body	string or null	`null`	No	Implementer party identity. Maximum length `255`.
`prover_id`	body	string or null	`null`	No	Prover party identity (the only identity that may license). Maximum length `255`.

Successful responses include data with the stored episode view (episode row, numbered issues, and append-only events journal). Re-importing the same (scope_key, source_run_id) returns the existing episode without mutation.

Status	Meaning
`400`	Bundle refused — normalization failure, a finding without a signature, or licensing-doctrine violation (for example the implementer licensed its own position, or a licensor is not the episode’s prover). Nothing is persisted.

`POST /api/estate/episodes/open`

Open a reconciliation episode from a finished spec_conformance grading run. The server derives scope from the run (estate/connection plus the view’s spec_name), derives implementer-actionable findings from the run view, and allocates issue numbers (summary.numbering: "server"). Party identities fall back to estate_char.episodes.implementer_id (default "implementer-agent") and estate_char.episodes.prover_id (default "prover-agent") when omitted. A clean run opens the same episode shape with no issues, so the successful reconciliation is still recorded and can be closed through the ordinary close route.

Field	In	Type	Default	Required	Description
`run_id`	body	string	none	Yes	Finished `spec_conformance` run to open from. Minimum length `1`, maximum `255`.
`implementer_id`	body	string or null	`null`	No	Implementer party identity. Maximum length `255`.
`prover_id`	body	string or null	`null`	No	Prover party identity (the only identity that may license). Maximum length `255`.

Successful responses include data with the stored episode view (episode row, numbered issues, and append-only events journal). Re-opening from the same opening_run_id returns the existing episode without mutation. Opening a new episode terminally supersedes any prior open episode for the same scope. The episode’s spec_hash is the run provenance’s compiled_spec_hash — the compiled artifact hash used for grading — not the view’s own spec_hash. If the run has no compiled_spec_hash, the episode still opens with spec_hash: null; the episode’s summary_notes records the missing identity, and the episode cannot be resumed against a spec. When the run view carries a diff_hash, the server resolves component_pair from the mediated diff and stores that pair on the episode. Drift findings link honestly to existing diff-ledger rows rather than opening duplicates, and later rounds reuse the episode’s stored pair. If the diff row is gone, linkage degrades observably via episode summary_notes without blocking the open.

Status	Meaning
`400`	Run refused — not a finished `spec_conformance` run, the run has not finished grading, the run view carries no spec name, or a derived finding has no signature. Nothing is persisted.
`404`	Unknown run.

`POST /api/estate/episodes/open-live`

Open a live derivational/bench reconciliation episode before round 1 from graded obligations the orchestrator supplies directly (each verify_against_contract verdict the loop gate collected off the instance), instead of deriving issues from a finished spec_conformance run view. Party identities fall back to estate_char.episodes.implementer_id (default "implementer-agent") and estate_char.episodes.prover_id (default "prover-agent") when omitted. Every opened issue is plain open (never pre-licensed). Eve replies, prover adjudication, and close reuse the existing POST /api/estate/episodes/{episode_id}/issues/{issue_number}/respond, POST .../adjudicate, and POST .../close routes.

Field	In	Type	Default	Required	Description
`opening_run_id`	body	string	none	Yes	Run id that opened the live episode (for example the loop gate’s verification run). Minimum length `1`, maximum `255`.
`spec_family`	body	string	none	Yes	Spec family for scope and finding identity. Minimum length `1`, maximum `255`.
`findings`	body	object[]	none	Yes	Graded derivational obligations to reconcile. Minimum length `1`. See GradeFinding fields.
`estate_id`	body	string or null	`null`	No	Estate scope anchor (wins over `connection_ref` when present). Maximum length `255`.
`connection_ref`	body	string or null	`null`	No	Connection scope anchor when `estate_id` is omitted. Maximum length `255`.
`subject_kind`	body	string	`"bench_task"`	No	Subject kind stamped on the episode. Maximum length `32`.
`implementer_id`	body	string or null	`null`	No	Implementer party identity. Maximum length `255`.
`prover_id`	body	string or null	`null`	No	Prover party identity (the only identity that may license). Maximum length `255`.
`diff_hash`	body	string or null	`null`	No	Optional mediated-diff linkage. Maximum length `255`.
`spec_hash`	body	string or null	`null`	No	Optional sealed-spec linkage. Maximum length `255`.

Successful responses include data with the stored episode view (episode row, numbered issues, and append-only events journal).

Status	Meaning
`400`	Live episode refused — for example no open findings after derivation, a clean grade, or a finding without a signature. Nothing is persisted.
`422`	Schema refusal — for example an empty `findings` array (a live episode needs at least one finding).

GradeFinding fields

Each item in findings for POST /api/estate/episodes/open-live and POST /api/estate/episodes/{episode_id}/rounds/live:

Field	Type	Default	Required	Description
`finding_id`	string	none	Yes	Stable finding signature used to assign the durable ledger number. This is not the numeric durable `#N` returned on episode issues. Minimum length `1`, maximum `255`.
`title`	string	`""`	No	Human-readable title. Maximum length `1000`.
`tier`	string	`"derivational"`	No	Finding tier. Maximum length `32`.
`kind`	string	`""`	No	Finding kind. Maximum length `64`.
`object_name`	string	`""`	No	Qualified object name. Maximum length `512`.
`key_columns`	string[]	`[]`	No	Row-identity key columns.
`compare_columns`	string[]	`[]`	No	Compared value columns.
`category`	string or null	`null`	No	Optional category. Maximum length `64`.
`evidence`	object	`{}`	No	Grade evidence (mismatch counts, sampled keys, aggregate value pairs).

Opened issues are never pre-licensed — state / licensor are deliberately absent from this wire shape.

`POST /api/estate/episodes/{episode_id}/rounds`

Append one full re-grade round to an open episode. The server derives still-failing findings from the grade run’s view under the episode’s scope (so durable finding keys line up round over round) and computes the differential. Drift findings are re-keyed against the episode’s stored component_pair before the differential is computed. For a persisted grade, closure by absence is limited to the categories covered by the run’s tiers_graded field (read from the view or its provenance): the structural tier covers structural and drift, while the derivational tier covers derivational. An open issue in a category that this round did not grade is carried forward instead of being marked resolved. A missing or empty tiers_graded value provides no category coverage, so absent issues are carried.

Field	In	Type	Default	Required	Description
`episode_id`	path	string	none	Yes	Episode id (for example `ecep_…`).
`grade_run_id`	body	string	none	Yes	Finished re-grade run whose view supplies the current failing set. Minimum length `1`, maximum `255`.

Successful responses include data with the updated episode view (episode row, numbered issues, and append-only events journal).

Status	Meaning
`400`	The re-grade run has not finished yet, the re-grade run is a different subject than the episode, or a derived finding has no signature.
`404`	Unknown episode or episode not visible to the caller; unknown grade run or a run whose named comparison, estate, or connection is not visible to the caller.
`409`	Episode is not open.

`POST /api/estate/episodes/{episode_id}/rounds/live`

Append one live re-grade round from the orchestrator’s current still-failing obligations (the round’s grade-vector / findings delta) rather than a finished conformance grade run. The server re-derives issues under the episode’s scope (so durable finding keys line up round over round) and computes the resolved/carried/new differential. The round’s identity is its findings; a Gap-A verification run is persisted and inspectable on its own, so no grade-run reference is folded here.

Field	In	Type	Default	Required	Description
`episode_id`	path	string	none	Yes	Episode id (for example `ecep_…`).
`findings`	body	object[]	`[]`	No	Still-failing obligations for this round. See GradeFinding fields. An empty list resolves every open issue.

Successful responses include data with the updated episode view (episode row, numbered issues, and append-only events journal).

Status	Meaning
`400`	Live round refused — for example findings that cannot be derived under the episode’s scope or a finding without a signature.
`404`	Unknown episode or one not visible to the caller.
`409`	Episode is not open.

`POST /api/estate/episodes/{episode_id}/close`

Record the orchestrator’s terminal decision for one episode. superseded is deliberately absent — only a newer open episode sets that status.

Field	In	Type	Default	Required	Description
`episode_id`	path	string	none	Yes	Episode id (for example `ecep_…`).
`status`	body	string	none	Yes	Terminal status: `resolved`, `disputed`, or `abandoned`.
`reason`	body	string or null	`null`	No	Optional terminal reason. Maximum length `512`.

Successful responses include data with the closed episode view (episode row, numbered issues, and append-only events journal).

Status	Meaning
`404`	Unknown episode or one not visible to the caller.
`409`	Episode is not open, or `status: "resolved"` was requested while one or more episode issues are still open and unaccounted for. An open issue is accounted for when its finding ledger carries a licensing ruling; missing or unknown ledger state remains unaccounted for.

`POST /api/estate/episodes/{episode_id}/issues/{issue_number}/respond`

The implementer’s machine-channel reply for one numbered issue. actor_id is verified at the store seam against the episode’s registered implementer identity — the route performs no identity magic of its own.

Field	In	Type	Default	Required	Description
`episode_id`	path	string	none	Yes	Episode id (for example `ecep_…`).
`issue_number`	path	integer	none	Yes	Issue number within the episode.
`actor_id`	body	string	none	Yes	Implementer party identity. Minimum length `1`, maximum `255`.
`kind`	body	string	none	Yes	Reply kind: `fixed`, `explanation`, or `fixed_note`.
`text`	body	string	`""`	No	Free-text reply body. Maximum length `4000`.
`fix_description`	body	string or null	`null`	No	Description of the fix claimed. Maximum length `4000`.
`residual_note`	body	string or null	`null`	No	Residual concern or ambiguity note. Maximum length `4000`.
`spec_ambiguity`	body	boolean	`false`	No	When `true`, flags spec ambiguity in the journal.

Successful responses include data with the updated episode view (episode row, numbered issues, and append-only events journal).

Status	Meaning
`403`	Identity binding or licensing-doctrine refusal (for example `actor_id` is not the episode’s registered implementer).
`404`	Unknown episode or one not visible to the caller.
`409`	Episode state forbids the reply (for example the issue is already settled).

`POST /api/estate/episodes/{episode_id}/issues/{issue_number}/adjudicate`

The prover’s machine-channel verdict for one numbered issue. Only the episode’s registered prover may adjudicate; on agree the licensor recorded is that prover.

Field	In	Type	Default	Required	Description
`episode_id`	path	string	none	Yes	Episode id (for example `ecep_…`).
`issue_number`	path	integer	none	Yes	Issue number within the episode.
`actor_id`	body	string	none	Yes	Prover party identity. Minimum length `1`, maximum `255`.
`verdict`	body	string	none	Yes	Verdict: `agree`, `withdraw`, or `dispute`.
`rationale`	body	string	`""`	No	Prover rationale. Maximum length `4000`.

Successful responses include data with the updated episode view (episode row, numbered issues, and append-only events journal).

Status	Meaning
`403`	Identity binding or licensing-doctrine refusal (for example the implementer attempting to license, or `actor_id` is not the episode’s registered prover).
`404`	Unknown episode or one not visible to the caller.
`409`	Issue is already settled or episode state forbids adjudication.

`POST /api/estate/findings/{finding_key}/ruling`

The human court’s ruling on a contested finding (ledger disposition). The deciding human is taken from the request context, never the body; auth-off callers are attributed as local operator (auth disabled).

Field	In	Type	Default	Required	Description
`finding_key`	path	string	none	Yes	Durable finding key from the obligation ledger.
`ruling`	body	string	none	Yes	Human ruling: `license`, `uphold`, `withdraw`, or `reconfirm_license`.
`note`	body	string or null	`null`	No	Optional ruling note. Maximum length `2000`.
`expected_evidence_sig`	body	string or null	`null`	No	For `reconfirm_license` only: the evidence signature the caller read. Supplied and stale, the act is refused `409` rather than binding the licence to a sighting that arrived after the reviewer looked. Ignored by the other rulings, which change no evidence binding. Maximum length `64`.

Successful responses include data with the durable ledger row after the ruling. reconfirm_license is the one value that records no disposition. A license granted under evidence-signature version 1 whose preimage counted zero cannot be migrated onto version 2 without binding it to a fact nobody measured, so it stays pinned at version 1 carrying license_evidence_resign_blocked_basis; this act answers that question. It re-signs the license onto the evidence as it now stands under the current version, clears the basis and license_evidence_changed, stamps license_evidence_resigned_at, and records the answering identity in license_evidence_reconfirmed_by. Send expected_evidence_sig to say WHICH evidence the answer is about: a grade landing between the reading and the call otherwise moves what the licence silently covers, and the record would claim a human accepted a reading that arrived after they looked. It leaves the GRANT alone — licensed_by, licensed_at, licensed_episode_id and license_note are unchanged, because re-confirming is not re-licensing and a second license ruling would credit the original decision to whoever answered the migration question.

Status	Meaning
`403`	Identity binding refusal.
`404`	Finding unknown or episode state forbids the ruling.
`409`	A `reconfirm_license` naming a finding that is not a pinned standing license: not licensed, not pinned, or with no episode sighting to bind to — or one whose evidence moved since the `expected_evidence_sig` the caller read. The finding exists, so this is not a `404`.

`GET /api/estate/episodes`

Field	In	Type	Default	Required	Description
`spec_family`	query	string or null	`null`	No	Filter to one spec family.
`estate_id`	query	string or null	`null`	No	Filter to one estate.
`status`	query	string or null	`null`	No	Filter to one episode status (for example `open`, `resolved`, `disputed`, `superseded`, `abandoned`).
`limit`	query	integer	`50`	No	Maximum episodes to return.

Returns data as an array of visible episode rows, newest first. Episodes on a comparison the caller cannot open are omitted. Without a comparison, visibility is checked against the named estate and any known recorded connection, or against the recorded connection alone when no estate is named. A page can therefore contain fewer than limit rows. Listing returns episode metadata only — call GET /api/estate/episodes/{episode_id} for issues and the journal.

`GET /api/estate/episodes/{episode_id}`

Field	In	Type	Default	Required	Description
`episode_id`	path	string	none	Yes	Episode id (for example `ecep_…`).

Successful responses include data with the episode row, numbered issues (each carrying the numeric durable_finding_id when its signature is known, plus prior_ledger_status and prior_resolved snapshots from import). Issues also include disposition, ledger_status, and counts_open: the owning finding ledger’s human disposition, its standing status, and the store’s fail-closed verdict for whether the issue still counts against the episode. counts_open is true only for an issue whose state is open and whose ledger does not carry a licensing ruling or the licensed status. durable_finding_id is the durable finding ledger’s #N, shared by diff-linked and obligation findings; use it with GET /api/estate/findings/{finding_id}/history when you need the finding’s cross-episode lifecycle. The string finding_id inside an issue is the finding signature used for obligation identity, not this numeric ledger number.

Status	Meaning
`404`	Unknown episode or one the caller may not see.

`GET /api/estate/findings/{finding_key}/episodes`

Field	In	Type	Default	Required	Description
`finding_key`	path	string	none	Yes	Durable finding key from the obligation ledger.

Successful responses include data with:

Field	Type	Description
`ledger`	object or null	The durable ledger row (`status`, `reopen_count`, license and resolution timestamps, semantic `anchor`, and related metadata), or `null` when the finding has only episode sightings and no ledger row yet. If any sighting is hidden, `seen_count`, `reopen_count`, `reopened_at`, `first_seen`, `last_seen`, `occurrence_started_at`, `first_episode_id`, `last_episode_id`, `resolved_episode_id`, `licensed_episode_id`, and `license_evidence_changed` are `null` on an obligation-ledger row; its standing status and licensing/resolution state remain.
`sightings`	object[]	Episode issue rows for this finding that the caller may see, joined to their parent episode (`opened_at`, `episode_status`, `source_run_id`), newest episode first.
`license_reconfirmation`	object	The `reconfirm_license` door’s state for this finding: `offered` is `true` only when the finding is a standing, pinned license with a current episode sighting; `refusal` is the door’s exact reason when it is not offered; and `evidence_sig` is the signature to echo as `expected_evidence_sig` when it is offered. If the newest sighting is hidden, an offered reconfirmation is withheld and its evidence signature is `null`.

The history read performs its usual ledger and episode reads, plus one latest-sighting read only when the finding is both a standing license and pinned. An unknown finding that has episode sightings but no obligation-ledger row returns license_reconfirmation.offered: false because there is no license binding to re-confirm. See the ruling endpoint above for the expected_evidence_sig precondition and the effect of reconfirm_license. The caller must be able to see the comparison that minted a comparison-minted finding; otherwise the endpoint returns 404. For other findings, only sightings in episodes the caller may see are included. An obligation-only finding with no visible sightings returns 404. When any sighting is hidden, the endpoint withholds the listed ledger fields folded over the complete sighting history rather than deriving misleading partial totals. A reconfirmation is not offered when its evidence comes from the hidden newest sighting.

Status	Meaning
`404`	Unknown finding, a comparison-minted finding on a hidden comparison, or an obligation-only finding with no visible sightings.

`GET /api/estate/findings/{finding_key}/witnesses`

Field	In	Type	Default	Required	Description
`finding_key`	path	string	none	Yes	Finding id from the ledger.
`timeout_seconds`	query	integer	`30`	No	Wall-clock budget for live estate queries. Clamped to `5`–`120`.
`refresh`	query	boolean	`false`	No	When `true`, bypass the persisted row-sample cache and re-run the live cross-estate probe against current data.

Successful responses include data with a bounded read-only witness document: per-side column definitions and rows (with the problem column highlighted when applicable), counts, alignment caveats, and the full plan disclosure (queries run, limits, skipped or timed-out queries). Each side’s witness metadata also reports declared_key_basis: declared when the caller supplied the key used for localization, or engine_declared when the key came from the engine. The caller must be able to see the comparison that minted the finding; an unknown finding or one on a hidden comparison returns 404. Live queries use each side’s own registered connection when it can be identified, not merely the connection associated with the shared (dialect, database) label. This keeps a SQLite-to-SQLite witness on each side’s own file even though both databases are labeled main. If the label matches multiple connections and the side’s connection cannot be identified, the service does not guess from the label; the stored boundary connection is used and any connection error appears in the query disclosure. When a stored declared key uses an expression this build cannot read, localization declines with decline_reason="unreadable_declared_key" rather than pairing rows under a different key. For a finding whose current occurrence is from the stimulus layer, the response is still successful but data.available is false: no at-rest probe is run because the injected synthetic batch has already been torn down, and the reason discloses that the at-rest result would answer a different question. When a sealed prediction receipt is present, that reason includes the receipt; otherwise it states that no behavioral evidence was recorded. For addressing_incoherence findings whose evidence has no target_object, the witness plan abstains on the target side rather than treating the target as absent. A missing target object in an incompletely enumerated characterization snapshot remains unknown, and a cached witness document that includes a target side is not reused for this abstaining recipe. For row_count, content_digest, column_content_digest, categorical_value_counts, and column_null_count findings, data.localization uses the same staged count and paged key/hash path when the safety checks pass. result_kind: "rows" returns exact source_only_rows, target_only_rows, and changed_rows when there are at most 100 differing keys; each changed row includes the source and target row plus a cells array with the differing column, source_value, and target_value. Column-content localization hashes only the named column, and null-count localization reports only null-state transitions; its finding wording says NULL values, not empty text values. categorical_value_counts instead returns result_kind: "value_count_changes" with empty row arrays and a distinct value_count_changes array. Each entry contains canonical_value, source_count, target_count, and delta (target minus source); more than 100 values on either side or more than 100 changed values declines with value_difference_fence and an empty value array. Exact key localization is available for tables up to 10,000 rows per side when the paged and independent live reads remain consistent. When more than 100 keys differ, the key comparison remains exact but row details are sampled deterministically; the payload reports completeness: "exact_keys_sampled_rows" instead of "exact". Declined results disclose a decline_reason such as table_exceeds_row_fence, budget_exhausted, concurrent_modification, or query_error, rather than returning partial row arrays. The localization fence is 100 rows per key/hash page, 10,000 total rows per side, and 100 pages per side; the connector execution ceiling is 110 rows to allow the row and grouped-value sentinel checks. column_distinct_count includes data.value_differences, which compares the distinct values on each side and reports up to 20 source_only.values and target_only.values. The payload includes compared_as, comparison_note, found, complete, and decline_reason; each direction’s total is available only when the comparison is complete. The status is "listed" when differences are listed, "no_differences" when a complete comparison finds none, and "declined" when the values cannot be listed. Values are listed only when the column resolves on both sides, the engines and column types support a shared comparison, and neither side has more than 40,000 distinct values. When a value list declines, the pane falls back to the most-frequent-value samples, paired by frequency rank. These findings still include an explicit declined data.localization payload. column_min_value and column_max_value retain their evidence panes and pair by statistic_rank; column_type_params also retains its evidence pane. For column_max_length, each side shows its own longest-value rows, paired by length rank rather than row identity; only rendered length is compared. The generated length column name appears in notes (normally witness_rendered_length, with a suffix if that name is already used). Binary row samples show size and hex up to 32 bytes, or size and a SHA-256 fingerprint for larger values; binary values in distinct-value lists use fingerprints. Column names in emitted SQL are resolved independently per estate side against that side’s latest characterization snapshot (measured column names, with declared keys as fallback), so cross-dialect comparisons use each engine’s catalog spelling — for example order_id on postgres and ORDER_ID on snowflake. When a logical column name cannot be matched unambiguously on a side, the planner omits the affected queries and records the reason in alignment_caveat and notes rather than running SQL that would fail. Samples are served from a persisted cache by default; the response may include cached and cached_at when served from cache. Read-only by construction — the planner emits SELECT / information_schema statements with hard row limits. The timeout_seconds budget is shared across all localization stages. A query that outlives the remaining budget is disclosed with timed_out: true (rather than skipped: true); an incomplete localization is therefore declined and is not reused from the response cache. Exact means complete and untruncated for the disclosed independent live reads; the two databases are not observed in one shared transaction.

Status	Meaning
`404`	Finding not found.

`GET /api/estate/findings/families/{family_signature}/witnesses`

Field	In	Type	Default	Required	Description
`family_signature`	path	string	none	Yes	Systemic-family id from `GET /api/estate/findings/families`.
`timeout_seconds`	query	integer	`30`	No	Wall-clock budget for live estate queries. Clamped to `5`–`120`.
`refresh`	query	boolean	`false`	No	When `true`, bypass the persisted cache and re-run the live probe for every sampled member.

Successful responses include data with family_signature, comparison, member_count, sampled_count, and members (witness documents for an open-first sample of at most three member findings). Each member’s samples are served from a persisted cache by default. Only visible family members contribute to member_count or the sample; a family with no visible members is answered as unknown.

Status	Meaning
`404`	Family not found, or no members are on comparisons the caller may see.

`GET /api/estate/dossier`

Field	In	Type	Default	Required	Description
`kind`	query	string	none	Yes	`family` or `behavioral`.
`diff_hash`	query	string	none	Conditional	Required when `kind=family`. Mediated-diff id.
`family_signature`	query	string	none	Conditional	Required when `kind=family`. Systemic-family id.
`status`	query	string	`open`	No	When `kind=family`: `open` (default) or `all` — scopes which ledger members are gathered.
`run_id`	query	string	none	Conditional	Required when `kind=behavioral`. Behavioral-validation run id.
`step`	query	string	none	Conditional	Required when `kind=behavioral`. Diverged validation step id.
`refresh`	query	boolean	`false`	No	When `kind=family` and `true`, bypass the persisted dossier cache and re-assemble from live state (rewrites the cache). Ignored for `kind=behavioral`.

Successful responses include data with kind, title, summary (one-paragraph factual summary reusable by the drawer), markdown (the complete ticket-grade dossier), filename (deterministic download-safe name), cached (true when served from the persisted dossier cache; null for behavioral dossiers, which are not cached), and cached_at (ISO-8601 timestamp of when the cached assembly was first persisted; only set on a cache hit). For kind=family, the dossier carries comparison identity, the fact kind in plain language, the visible member list with per-member was→now evidence, the affected-object rollup, adjudication state + notes, the suspected fault class, and a reproduction recipe. Family dossiers are served cache-first when warm; the cache is invalidated automatically when adjudication state changes (finding or family disposition, or a note on the family). A caller-specific family read is assembled live from ledger rows whose first_seen_diff comparison is visible to that caller, rather than read from the shared cache. For kind=behavioral, the dossier carries the injected synthetic stimulus, each side’s outcome, the diverged object, the arsenal attack class/tier when recorded, a replay pointer, and a reproduction recipe. A run the caller may not see is answered as an unknown run (404). When kind=family identifies a known diff but the selected family has no members under status, the endpoint returns 404 with the message This hand-off packet has no members. and a structured error payload containing code set to "dossier_family_empty" plus identifiers for diff_hash, family_signature, and status. Clients can use this response to show an unavailable hand-off packet without rendering raw dossier internals. Unknown dossier subjects still use the generic 404 response.

Status	Meaning
`400`	Missing or unknown `kind`, or missing required keys for the chosen kind.
`404`	Dossier subject not found.

`GET /api/estate/arsenal/ranking`

Field	In	Type	Default	Required	Description
`component_pair`	query	string	none	Yes	Component pair to rank attacks for (for example `postgres->databricks`).
`migrator_id`	query	string	none	No	Optional migrator scope.
`contract_id`	query	string	none	No	Optional contract scope.
`pair_fingerprint`	query	string	none	No	Optional estate-pair fingerprint scope.
`top_k`	query	integer	none	No	Maximum attack chips to return.

Successful responses include data with the operator_ui-redacted selection: attack chips (class, aim, potency, rationale), coverage summary, and held_out_withheld_count. Veiled recipes are stripped and held-out families are withheld (only their count is disclosed). The full recipe set never crosses this boundary — that is the evidence-ledger view.

`POST /api/estate/contracts/{contract_id}/attestation`

Field	In	Type	Default	Required	Description
`contract_id`	path	string	none	Yes	Source contract id to attest.
`allow_open_residue`	query	boolean	`false`	No	When `true`, mint a `qualified` attestation that embeds every open gate disclosure (structural residue, open behavioral findings, or unverified behavioral coverage) instead of refusing export.

Returns run_id and a data summary. By default, export refuses while the transition has structural residue, unlicensed open behavioral findings, or unverified behavioral coverage. Setting allow_open_residue=true is an explicit human choice to mint a QUALIFIED attestation embedding every disclosure — a clean attestation is never minted over an open gate. The operator identity is taken from the authenticated session, never from the request body.

Status	Meaning
`400`	Attestation export failed (for example open gates without `allow_open_residue`).

`GET /api/estate/contracts/{contract_id}/attestations`

Field	In	Type	Default	Required	Description
`contract_id`	path	string	none	Yes	Source contract id.

Returns data as an array of visible attestation rows for the contract, newest first (lifecycle fields included). Its contract’s snapshot must be visible; if an attestation binds a comparison, the caller must be able to open that comparison as well. A statement binding no comparison is judged by its snapshot alone, and a hidden snapshot returns an empty list.

`GET /api/estate/attestations/{attestation_id}`

Field	In	Type	Default	Required	Description
`attestation_id`	path	string	none	Yes	Stored attestation id.

Returns data with the stored attestation document. The caller must be able to see both the comparison it binds and the snapshot its contract was compiled from; an attestation binding no comparison is judged by its snapshot alone.

Status	Meaning
`404`	Unknown attestation or one the caller may not see.

`GET /api/estate/attestations/{attestation_id}/report`

Field	In	Type	Default	Required	Description
`attestation_id`	path	string	none	Yes	Stored attestation id.

Successful responses include data with the attestation-viewer document: grade × plane coverage matrix, qualification, waivers, and ledger-head linkage.

Status	Meaning
`404`	Attestation not found or one the caller may not see.

`POST /api/estate/attestations/{attestation_id}/verify`

Field	In	Type	Default	Required	Description
`attestation_id`	path	string	none	Yes	Stored attestation id to verify.

Successful responses include data with the signature verdict and bundle re-derivation checks.

Status	Meaning
`400`	Verification failed (invalid signature or bundle mismatch).
`404`	Attestation not found or one the caller may not see; visibility is checked before verification.

`GET /api/estate/correspondence-rules`

Field	In	Type	Default	Required	Description
`component_pair`	query	string	none	No	Filter to one component pair.
`diff_hash`	query	string or null	`null`	No	Scope the list to the concrete estate pair resolved from a stored system diff.
`status`	query	string	none	No	Filter by rule status: `proposed`, `ratified`, or `retired`.

Each row includes rule_id, component_pair, status, provenance, qualification (edge-fixture results when present), and payload. When diff_hash is supplied, the response projects pair-scoped approval state for that comparison; an approval for another estate pair is not treated as active. When a qualification has per-fixture results but lacks either stored failure count, the response derives false_acceptances from licensed rejects and false_rejections from unlicensed accepts. A qualification without results is not assigned these counts. Rows also include proposer_kind (agent, person, service, or null) and proposer_bot_id (the acting bot id when known for an agent proposal; otherwise null), plus proposer_display_name (the proposing agent’s runtime bot-registry name when available; otherwise null). These fields come from trusted caller context, not a request-body value. The first registration records the proposer kind and bot id; later registrations do not replace them. A missing proposer_display_name can be filled by a later registration from the same agent when its runtime name becomes available; a recorded name is never replaced, and the name is not inferred from the bot id. agent identifies a proposal attributed to an agent, person a genuine human HTTP caller, and service a known service identity or a direct tool-endpoint call. null means the caller could not be established or the rule predates these fields. For an unbound proposal held by a live bundle Action Review request, the row also includes owning_bundle_id, owning_bundle_diff_hash, and owning_bundle_request_id; these are null when no bundle holds the rule. If the bundle is known but its request cannot be read, the bundle identifiers are returned and owning_bundle_request_id is null. owning_bundle_request_status is the request’s effective ledger status when readable, and null when no request can be named or read. Proposed rows also include sign_off_route: action_review for any rule an agent or service proposed, including data-derived or unclassified rules; otherwise direct. Ratified and retired rows return null. Use the route-specific sign-off rather than inferring it from proposer_kind. data contains only rules already in the registry. The separate built_in array contains rules the selected pair’s compares bind without proposal or ratification; they are not registry rows and are independent of registry status and comparison-specific rule scoping. When neither a pair nor a comparison is named, built_in spans every pair; otherwise it describes the resolved pair. Use GET .../pack-availability to check shipped-pack counts and POST .../propose to seed an unproposed pack. Use GET .../pack-consent to inspect the shipped pack directly, including each rule’s vendor consent_tier, its effective_consent_tier after the dialect-pair evidence gate, whether this estate pair has adopted it, and whether a one-click toggle is available. The response keeps measurement templates separate from rules; templates are reference forms, are not adoptable, and carry no consent tier.

`GET /api/estate/correspondence-rules/pack-availability`

Field	In	Type	Default	Required	Description
`component_pair`	query	string	none	Yes	Engine pair `'<source>-><target>'` (for example `mssql->databricks`).

Successful responses include component_pair, shipped_count (rules the shipped pack defines — 0 when none ships), proposed_count (pack rules already seeded into the registry), and unproposed_count (shipped but not yet proposed — a nonzero value drives the product propose affordance), plus built_in_count (rules the pair’s compares bind without proposal; these are separate from and never included in shipped_count, so built-in rules can exist even when all three pack counts are 0).

Status	Meaning
`403`	Caller lacks `view_connections`.
`500`	Pack status lookup failed.

Field	In	Type	Default	Required	Description
`component_pair`	query	string or null	`null`	No	Engine pair `'<source>-><target>'` (for example `mssql->databricks`). When omitted, the service resolves the pair from `diff_hash`.
`diff_hash`	query	string or null	`null`	No	Stored system-diff hash whose resolved estate pair supplies adoption state and pair fingerprints.

Returns the shipped pack for component_pair, with one rules entry per shipped rule. Each rule includes its exported ref, content-addressed rule_id, consent_tier, effective_consent_tier, consent_tier_reason, optional degrade_reason, direction, reverse_would_lose, optional adoption_note, fixture_count, configuration_predicates, adopted, and adoptable. The effective_consent_tier can be lower than the shipped tier when the dialect pair does not have the evidence required for zero-click licensing. The response’s templates array contains reference measurement forms with adoptable: false; they do not license or ratify anything.

Status	Meaning
`400`	The pair or comparison context is invalid.
`403`	Caller lacks `view_connections`.
`404`	The requested comparison or resolved estate pair is not found.

`POST /api/estate/correspondence-rules/adopt`

Field	In	Type	Default	Required	Description
`component_pair`	body	string	none	Yes	Engine pair the shipped pack belongs to. Minimum length `1`, maximum `128`.
`diff_hash`	body	string	none	Yes	Stored system-diff hash that identifies the comparison and therefore the concrete estate pair. Exactly `64` characters.
`refs`	body	array of strings	none	Yes	Shipped rule references to adopt, such as `['R1', 'R3']`. Minimum `1`, maximum `64` entries.

Adopts only rules whose effective tier is checkbox. The server re-qualifies each selected rule against the source and target snapshots behind diff_hash, then binds it for that estate pair. Each requested reference gets an independent result, so one failed qualification does not prevent other selected rules from being adopted. Unknown references, auto rules, and ceremony rules are returned as per-rule failures rather than silently skipped. The operation requires ratify_source_contract and a genuinely authenticated human; adopted_by comes from the authenticated user context, not the request body. Successful responses include component_pair, diff_hash, adopted_count, and a rules array. Each outcome includes ref, rule_id and title when known, adopted, and, when applicable, adopted_by or error. A rule held by a live bundle Action Review request is not adopted; its outcome includes code: "rule_held_by_bundle" and owning_bundle_id so the caller can direct the reviewer to that bundle.

Status	Meaning
`400`	The request is invalid, the comparison is unknown, or the pair does not match the comparison.
`403`	Caller lacks `ratify_source_contract` or is not a genuinely authenticated human.
`404`	The requested comparison or resolved estate pair is not found.

`POST /api/estate/correspondence-rules/accept-defaults`

Field	In	Type	Default	Required	Description
`diff_hash`	body	string	none	Yes	Stored system-diff hash that identifies the comparison and therefore the concrete estate pair. Exactly `64` characters.
`rule_ids`	body	array of strings	none	Yes	Registry rule ids to accept, all recorded under the one consent event this call writes. Minimum `1`, maximum `200` entries.

The batch sibling of POST /api/estate/correspondence-rules/{rule_id}/ratify. Any signed-in person can accept the listed defaults with view_connections; no special approval permission is required. Each named rule is re-qualified against the snapshots behind diff_hash before it binds, and each gets an independent verdict — an unknown id, an already-decided rule and a failed re-qualification each refuse that rule by name and leave the others to bind. The signer comes from the authenticated user context, never the request body, and the estate pair from the stored comparison, never the caller. The batch action accepts only rules whose subject is structural. A rule that licenses a statistic derived from the values — such as a minimum, maximum, or distinct count — is refused by name here because wrong data can explain that difference as readily as the two engines do. It still requires individual human review. For an agent- or service-proposed rule, use the one-rule Action Review request below. Its evidence is shown in the Prover review guide; approval re-qualifies it against this comparison before ratifying it. An agent- or service-proposed rule with sign_off_route: "action_review" is also refused in its per-rule outcome with code: "rule_requires_action_review"; ask for that rule’s approval through POST /api/estate/correspondence-rules/{rule_id}/request-approval instead. Every rule that bound is recorded in a SINGLE platform_defaults_accepted event on the comparison’s review log, returned as consent_event_id. One signature may cover several mechanisms: a mechanism is the unit of the question a consent surface asks (one checkbox each), while one press is one act and one act is one event. The event payload carries the mechanism breakdown, so a later reader can still see which distinct behaviours the signature covered. When nothing bound, no event is written and consent_event_id is null: a consent record over an empty decision would be a false record of consent. The bindings and that event are written in ONE transaction, so a binding can never outlive a failed event write and become a licence attributable to no signature. Licensing is decided at diff time, so a newly bound rule changes no number until the comparison runs again. The call therefore enqueues that re-evaluation itself, resubmitting the same comparison through the ordinary system-diff flow and carrying forward everything the stored comparison recorded about how it was mediated: its two snapshots, its delta, its addressing map (ν), its case-folding, and its recorded title with the spec kind that title was given under. The one input it does not carry is the operator’s quiescence attestation, and that is deliberate: an attestation is one person’s first-hand assertion about the one comparison they launched, so it is never replayed onto a run they did not start — accepting platform defaults approves licensing rules, it is not a re-attestation that nothing was writing. An unattested re-run therefore ABSTAINS where the attested original decided, and knows LESS than the comparison it replaces. The recompute object reports enqueued, the run_id to watch, and — when no run was started — the reason. When the comparison being re-run was decided on an attestation, quiescence_attestation_dropped names the attesters (declared_by), their note, and decided_on_attestation — how many elements the original decided on their word, which is the number this re-run cannot decide. decided_on_attestation is null when the stored record carries no readable count: the attestation is still disclosed, its size is simply unknown, which is not the same as zero. quiescence_attestation_dropped itself is null when no attestation is on record for that comparison — usually because none was made, but also when the originating run row is gone or its summary predates the disclosure. Read it as “nothing to disclose”, never as a positive claim that the original was unattested. Any refusal to start (nothing bound, a diff of the same pair already running, a snapshot that has since gone, stored mediation metadata that is not readable) is disclosed here rather than raised, because the signature has already landed and a failed response would report a consent that succeeded as an error. Automatic re-evaluation is best-effort, not a delivery guarantee. The consent commits before the submit is attempted and the two are not joined, so a request cancelled in between — or an enqueue that fails unexpectedly — leaves the rules ratified with no run. That gap is reconciled on the read: GET /api/estate/rule-reviews?diff_hash=… re-enqueues a batch consent that no later comparison of the same pair answers, once, attributed to the original signer. A consent nobody reads back is never reconciled; POST /api/estate/system-diffs remains the explicit re-run for a comparison whose numbers still look stale. Successful responses include diff_hash, component_pair, pair_fingerprint, accepted_by, accepted_count, consent_event_id, a rules array of per-rule outcomes (rule_id, title, accepted, error, and, when held, code and owning_bundle_id), a mechanisms array coalescing the accepted rules into the questions they actually asked (signature, rule_kind, label, rule_ids, sites), and recompute.

Status	Meaning
`400`	The request is invalid, or the consent was refused for the whole batch.
`403`	Caller lacks `view_connections` or does not have a signing identity.
`404`	The named comparison is unknown.

When a live bundle Action Review request holds a requested rule, that rule’s outcome is refused with code: "rule_held_by_bundle" and its owning_bundle_id; other rule outcomes remain independent. If the request state cannot be read, the outcome uses code: "rule_hold_unreadable" and still identifies the bundle.

`POST /api/estate/correspondence-rules/propose`

Field	In	Type	Default	Required	Description
`component_pair`	body	string	none	Yes	Engine pair `'<source>-><target>'` (for example `mssql->databricks`). Minimum length `1`, maximum `128`.
`source_snapshot_id`	body	string or null	`null`	No	SOURCE characterization snapshot id whose fingerprints qualification records. Maximum length `64`.
`target_snapshot_id`	body	string or null	`null`	No	TARGET characterization snapshot id (same role as source). Maximum length `64`.

Propose-class (view_connections), not ratification: seeds the pair’s shipped Π pack, edge-qualifies each rule, and places them on the review worklist. Rules are eligible and license nothing until a named human ratifies each one on POST /api/estate/correspondence-rules/{rule_id}/ratify. Pass both snapshot ids when available so qualification can record the configured pair’s environment fingerprints and rules can reach configuration_qualified (the tier ratification requires). Delegates to the same seam as the propose_correspondence_rules agent tool. The proposer identity is taken from the authenticated session (email, display name, or user id — audit only), never from the request body. Successful responses include component_pair and rules — an array of proposed rules, each with rule_id, title, qualified, provenance, and configuration_recorded when present.

Status	Meaning
`400`	Proposal failed — for example the pair ships no default proposal pack.
`403`	Caller lacks `view_connections`.
`409`	A live bundle Action Review request conflicts with this operation; the error includes the stable refusal `code` and owning bundle identifiers.

`POST /api/estate/correspondence-rules/{rule_id}/withdraw`

Field	In	Type	Default	Required	Description
`rule_id`	path	string	none	Yes	Proposed correspondence rule id from the registry.
`diff_hash`	body	string	none	Yes	Stored system-diff hash identifying the comparison whose worklist loses the proposal. Exactly `64` characters.
`reason`	body	string	none	Yes	Why the proposal does not belong on this comparison’s worklist. The server trims it before journaling; `1`–`2000` characters and not blank after trimming.

Withdraws the proposal from this comparison only. It does not reject or revoke the correspondence-rule definition, remove the proposal from another comparison, or license anything. The server checks the ground rather than trusting a caller-supplied classification: foreign_origin when the recorded origin estate pair differs, outside_boundary when a legacy proposal has no recorded origin and its named object is absent from the comparison’s measured inventory, or own_proposal when the authenticated caller created the proposal. Every successful withdrawal is written to the comparison review journal and is idempotent while the withdrawal remains in force. A later proposal derived by the same comparison cancels that comparison’s withdrawal and makes the row visible again. Successful responses include rule_id, diff_hash, withdrawn_by, reason, grounds, and event_id. withdrawn_by is derived from the caller context; the request body cannot choose it.

Status	Meaning
`400`	The request is invalid, including an empty withdrawal reason.
`403`	The rule is not an unbound proposal, or the server cannot establish `foreign_origin`, `outside_boundary`, or `own_proposal`.
`404`	The comparison or correspondence rule is not found.

`POST /api/estate/correspondence-rules/{rule_id}/qualify`

Field	In	Type	Default	Required	Description
`rule_id`	path	string	none	Yes	Correspondence rule id from the registry.
`diff_hash`	body	string or null	`null`	No	Comparison whose pair fingerprints the qualification records against. Maximum length `64`. When omitted, the pair’s most recent forward diff is used.

The step between propose and ratify: evaluates the rule’s edge fixtures and records the configured-pair field-survival evidence a passing evaluation earns. Fingerprints come from the two characterization snapshots behind diff_hash when the ratifier is in a comparison context, otherwise from the rule’s pair’s most recent forward diff. With fingerprints recorded the rule reaches configuration_qualified (the tier ratification requires); without them only synthetic_observed, and ratification stays refused. Successful responses include rule_id, qualified (whether the rule’s edge fixtures passed), provenance (provenance tier the qualification earned, when present), and configuration_recorded (whether the configured pair’s fingerprints were recorded). The ratifier identity is taken from the authenticated session, never from the request body.

Status	Meaning
`400`	Qualification failed — for example the proposal has no passing edge-fixture qualification (its observed difference is not a known rendering), or the rule is not in `proposed` status.
`403`	Caller lacks `view_connections`.
`404`	Rule not found.
`409`	A live bundle Action Review request holds the rule; the error includes the stable refusal `code` and owning bundle identifiers.

`POST /api/estate/correspondence-rules/{rule_id}/ratify`

Field	In	Type	Default	Required	Description
`rule_id`	path	string	none	Yes	Correspondence rule id from the registry.
`diff_hash`	body	string	none	Yes	Stored system diff whose server-resolved estate pair this approval targets. Exactly 64 characters.

Successful responses include rule_id, pair_fingerprint (the concrete estate pair approved), and ratified_by (the resolved signer label). Ratification applies only to that estate pair; approving the same rule for a different pair requires a separate action. With authentication disabled, send the caller’s name in X-Genesis-Signed-As; it is recorded with (self-reported, auth disabled), or as local operator (auth disabled) when the header is absent. With authentication enabled, any signed-in person signs and a typed name is refused; the rule’s proposer may sign their own proposal. A person’s own PAT is accepted and attributed to its owner. Ratification refuses rules that lack a passing edge-fixture qualification. Rules whose sign_off_route is action_review cannot be ratified through this direct endpoint; request and decide their approval through Action Review instead.

Status	Meaning
`400`	Rule is not qualified for ratification.
`403`	Caller lacks `view_connections` or the signer rule refuses the caller.
`404`	Rule not found.
`409`	The rule requires Action Review (`code: "rule_requires_action_review"`, `sign_off_route: "action_review"`), a live bundle Action Review request holds it (`code: "rule_held_by_bundle"`, owning bundle identifiers, and request details), or it was withdrawn from this comparison (`code: "rule_withdrawn_here"`, with `withdrawn_by`, `reason`, and `grounds`). A withdrawn rule must be proposed again before it can be ratified here.
`503`	The request state of a bundle holding this rule could not be read; the response uses `code: "rule_hold_unreadable"`. Retry shortly.

`POST /api/estate/correspondence-rules/{rule_id}/request-approval`

Field	In	Type	Default	Required	Description
`rule_id`	path	string	none	Yes	Correspondence rule id from the registry.
`diff_hash`	body	string	none	Yes	Stored system diff whose server-resolved estate pair scopes the approval. Exactly 64 characters.

Ask for Action Review approval of one agent- or service-proposed correspondence rule. The rule’s original proposer remains the proposer of record; the authenticated caller requests its approval. This stages a one-rule approval bundle and a linked Action Review item. For a data-derived or unclassified rule, the request carries the evidence shown in the Prover review guide and approval re-qualifies the rule against the comparison before ratifying it. If a live bundle request already holds the rule, the endpoint returns that request with replayed: true rather than staging another. An open agent- or service-staged disposition package owns a rule it proposed or that one of its items promotes under, and is approved through that package. A rule pinned or derived by a person’s open package can use its own request; approve the package after the rule. The response includes bundle_id, diff_hash, proposal_id, the request status and url, card_sent, and replayed. Approve the linked request in Action Review; this endpoint does not ratify the rule itself.

Status	Meaning
`403`	Caller lacks `view_connections` or does not have a signing identity.
`404`	Comparison or correspondence rule not found.
`409`	Rule signs off directly (`code: "rule_signs_off_directly"`), is owned by an open agent- or service-staged disposition package (`code: "rule_owned_by_package"`, with `owning_package_id`), is claimed by another live bundle request (`code: "rule_held_by_bundle"`), its claim state cannot be read (`code: "rule_hold_unreadable"`), or was withdrawn from this comparison (`code: "rule_withdrawn_here"`, with `withdrawn_by`, `reason`, and `grounds`). A withdrawn rule must be proposed again before it can be requested or approved here. Only one live Action Review request can claim a correspondence rule on an estate pair; decide the current request or package before requesting another.
`503`	The state of a bundle request holding the rule could not be read. Retry shortly.

`POST /api/estate/correspondence-rules/{rule_id}/reject`

Field	In	Type	Default	Required	Description
`rule_id`	path	string	none	Yes	Correspondence rule id from the registry.
`diff_hash`	body	string or null	`null`	No	Stored comparison whose worklist offered the rule. Its estate pair must match the rule’s scope. Exactly 64 characters when supplied. Omit it, or the body, for clients that do not send a comparison: rejection uses a comparison of the rule’s pair the caller can see, and returns `404` if none is visible.

Successful responses include rule_id, review_status (revoked), and reviewed_by (the resolved signer label). Rejection retires the proposal so it stops licensing anything and leaves the pending-review worklist. The comparison is checked with the same visibility rule as its read; a hidden comparison returns 404. The rule must also be scoped to that comparison’s estate pair or it is answered as an unknown rule. When diff_hash is omitted, Genesis selects a visible comparison of the rule’s pair; if the caller can see none, the rule is answered as unknown (404). The rejecter identity is taken from the authenticated session, never from the request body. A ratified rule is revoked (POST /api/estate/correspondence-rules/{rule_id}/revoke), never rejected — the store refuses rejection of a ratified rule (400).

Status	Meaning
`400`	Rejection failed — for example the rule is already ratified or not in `proposed` status.
`403`	Caller lacks `view_connections` or the signer rule refuses the caller.
`404`	Comparison hidden or unknown, or rule unknown or not scoped to its estate pair.
`409`	A live bundle Action Review request holds the rule; the response includes `code: "rule_held_by_bundle"`, `owning_bundle_id`, `owning_bundle_diff_hash`, and the `action_review` request details.
`503`	The request state of a bundle holding this rule could not be read; the response uses `code: "rule_hold_unreadable"`. Retry shortly.

`POST /api/estate/correspondence-rules/{rule_id}/revoke`

Field	In	Type	Default	Required	Description
`rule_id`	path	string	none	Yes	Correspondence rule id from the registry.
`diff_hash`	body	string	none	Yes	Stored system diff whose server-resolved estate pair approval is being revoked. Exactly 64 characters.
`reason`	body	string	none	Yes	Why the rule is being retired (for example absorbed by a broader rule). Minimum length `1`, maximum `2000`.
`superseded_by`	body	string or null	`null`	No	`rule_id` of the rule that absorbs this one, when superseding. Maximum length `64`.

Successful responses include rule_id, pair_fingerprint, status (retired), revoked_by (the resolved signer label), and superseded_by when set. Revocation retires the approval only for that estate pair; other pair approvals and matching code-reviewed corridor defaults remain independent. Diffs already registered that cite the rule keep their frozen verdicts. The revoker identity is the resolved signer label; with authentication enabled it comes from the authenticated principal, and with authentication disabled it follows X-Genesis-Signed-As or the local-operator fallback. This is the registry-level revoke (with required reason and optional superseded_by). For the ratification-review worklist revoke without a reason field, use POST /api/estate/rule-reviews/{rule_id}/revoke instead.

Status	Meaning
`400`	Revoke failed (for example blank `reason` or rule is not ratified).
`403`	Caller lacks `ratify_source_contract`, the signer rule refuses the caller, or the caller is not permitted to revoke.
`404`	Rule not found.

`GET /api/estate/rule-reviews`

Field	In	Type	Default	Required	Description
`component_pair`	query	string	none	No	Filter to one component pair (for example `postgres->databricks`).
`diff_hash`	query	string or null	`null`	No	Scope the worklist to the concrete estate pair resolved from a stored system diff.
`source`	query	string	none	No	Filter to one source dialect.
`review_status`	query	enum (`pending_review` \| `confirmed` \| `revoked`)	none	No	Filter by derived review state. Unknown values are rejected with `422`.

Returns data as an array of Π correspondence rules for the operator ratification-review worklist. Each row includes the rule fields from the registry plus an effective review_status, viewer_signs_as, and viewer_can_sign. viewer_signs_as is the identity this caller’s review write would record when the caller has a signing identity, or null otherwise; any signed-in person can sign without a special permission, including the rule’s proposer. viewer_can_sign is whether the caller may sign that row, or null beside a null signer. A caller may read the worklist without being eligible to sign when they have no signing identity. With authentication disabled, viewer_signs_as uses the X-Genesis-Signed-As name and its (self-reported, auth disabled) disclosure, or local operator (auth disabled) when the header is absent. Rows also include server-derived mechanism_signature, mechanism_label, mechanism_provenance, scope, and mechanism_relation. The signature groups rules that ask the same consent question; the label states that question in reader-facing words; and mechanism_provenance distinguishes Platform default from a ruling (including its signer when recorded). scope identifies whether the rule applies to a pair or a single site. mechanism_relation is null when no relationship is present, or states that the rule extends the platform default when the other rules in this response establish a strict widening. usage is null on this route — merge counts from GET /api/estate/rule-usage client-side so the worklist renders immediately. With diff_hash, rows and review status are limited to approvals for that comparison’s estate pair. Unbound proposals are additionally scoped to the comparison: a recorded foreign origin or an object outside the comparison’s measured boundary is omitted, while a proposal that belongs to the comparison remains visible with outside_boundary: false and, when approval would refuse it, a non-null blocked_reason. Pair-generic rules and rules already bound to the comparison are not removed by this proposal filter. Each row also includes default_refusal, which is null when the rule may be offered in the pre-ticked platform-default set and otherwise contains the reason it must be handled through the single-rule ceremony instead. This is separate from blocked_reason: a rule can be approvable on its own while still being ineligible for batch consent. An unbound proposal held by a live bundle Action Review request also includes owning_bundle_id, owning_bundle_diff_hash, and owning_bundle_request_id; these are null when no bundle holds it. If its request cannot be read, the bundle identifiers remain available and the request id is null.

Status	Meaning
`422`	Request validation failed, including an unknown `review_status` value.

With diff_hash, this read also reconciles. A batch consent (platform_defaults_accepted) on that comparison which no later comparison of the same pair answers is re-enqueued once, attributed to the original signer — the repair for a consent whose automatic re-evaluation was lost between the approval transaction and the submit. It is best-effort and cannot fail the read: an unreadable reconciliation is logged and the worklist is returned regardless. Callers that poll this endpoint should expect it to start at most one background system_diff run per consent event, never one per request.

`GET /api/estate/rule-reviews/by-comparison`

Field	In	Type	Default	Required	Description
`diff_hashes`	query	string	none	Yes	Comma-separated stored comparison hashes. Whitespace around each hash is ignored; duplicate values are collapsed.

Returns data as a map keyed by each requested diff_hash that names a stored comparison whose source and target snapshots resolve to an estate pair the caller may see. Each value is an array of rule-review rows scoped to that comparison’s pair. Unlike the focused GET /api/estate/rule-reviews?diff_hash=…, this batched route does not include the bundle-hold fields. A requested hash that is unknown, cannot resolve its pair, or is not visible to the caller is absent from data; an existing comparison with no rules is represented by an empty array. This endpoint is intended for a review landing page that needs pending-platform- default cues for several comparison cards. Unlike the single-comparison diff_hash read, it does not run consent read-repair or enqueue background system_diff work. It requires view_connections and is read-only.

`GET /api/estate/rule-usage`

Field	In	Type	Default	Required	Description
`diff_hash`	query	string or null	`null`	No	Limit counts to the stored comparison identified by this hash.

Successful responses include data as a map keyed by full rule_id:

Field	Type	Description
`licensed_count`	integer	Differences this rule licensed across mediated diffs.
`comparison_count`	integer	Distinct comparisons in which the rule licensed at least one difference.

Unscoped counts are memoized per comparison: a new comparison folds only its own payload, while repeated reads reuse already folded comparisons. Supplying diff_hash returns counts for that comparison only. Without diff_hash, counts include only comparisons the caller may see; an unknown or unreadable diff_hash returns 404 rather than disclosing the comparison.

`GET /api/estate/rule-reviews/{rule_id}`

Field	In	Type	Default	Required	Description
`rule_id`	path	string	none	Yes	Correspondence rule id from the registry or worklist.
`diff_hash`	query	string or null	`null`	No	Scope the dossier and its usage counts to the concrete estate pair resolved from a stored system diff.

Successful responses include data with the rule’s full review dossier: payload (what the rule matches/licenses), edge fixtures (accept and reject), provenance tier, qualification, field_events, effective review_status, viewer_signs_as (the identity this caller’s review write would record, or null when they may read but not sign), viewer_can_sign, and populated usage (licensed_count, comparison_count). When diff_hash is supplied, the response also includes the normalized full diff_hash that identified the exact comparison scope. sign_off_route is action_review or direct while the rule is proposed, and null once it is ratified or retired. Under a comparison, the dossier also includes owning_bundle_id, owning_bundle_diff_hash, owning_bundle_request_id, and owning_bundle_request_status for a bundle holding the rule; they are null when no bundle holds it. If the bundle is known but its request cannot be read, the bundle identifiers remain available while the request id and status are null. For a still-proposed rule withdrawn from the comparison identified by diff_hash, withdrawn_here contains withdrawn_by, reason, grounds, and withdrawn_at (ISO 8601 when available); otherwise it is null. The withdrawal keeps the rule off that comparison’s worklist until it is proposed again. On an authentication-disabled stack, viewer_signs_as is the self-reported signer label from X-Genesis-Signed-As, or local operator (auth disabled) when the header is absent.

Status	Meaning
`404`	Rule not found.

`POST /api/estate/rule-reviews/{rule_id}/confirm`

Field	In	Type	Default	Required	Description
`rule_id`	path	string	none	Yes	Ratified correspondence rule to confirm after review.
`diff_hash`	body	string	none	Yes	Stored system diff whose server-resolved estate pair approval is being confirmed. Exactly 64 characters.

Successful responses include rule_id, pair_fingerprint, review_status (confirmed), and reviewed_by (the resolved signer label). Confirmation is additive for that estate pair — the approval stays ratified and keeps licensing future diffs for that pair. The reviewer identity is the resolved signer label: the authenticated principal when auth is enabled, or the disclosed self-reported/local label when auth is disabled.

Status	Meaning
`400`	Confirm failed (for example rule is not ratified or already reviewed).
`403`	Caller lacks `view_connections` or the signer rule refuses the caller.
`404`	Rule not found.

`POST /api/estate/rule-reviews/{rule_id}/revoke`

Field	In	Type	Default	Required	Description
`rule_id`	path	string	none	Yes	Ratified correspondence rule to revoke after review.
`diff_hash`	body	string	none	Yes	Stored system diff whose server-resolved estate pair approval is being revoked. Exactly 64 characters.

Successful responses include rule_id, pair_fingerprint, review_status (revoked), and reviewed_by (the resolved signer label). Revocation retires the human approval only for that estate pair; matching code-reviewed corridor defaults retain independent authority. Existing diff records remain immutable evidence. The reviewer identity is the resolved signer label: the authenticated principal when auth is enabled, or the disclosed self-reported/local label when auth is disabled.

Status	Meaning
`400`	Revoke failed (for example rule is not ratified).
`403`	Caller lacks `view_connections` or the signer rule refuses the caller.
`404`	Rule not found.

`GET /api/estate/waivers`

Field	In	Type	Default	Required	Description
`expiring_within_days`	query	integer	`14`	No	Include waivers expiring within this many days in the expiring-soon alert set.

Returns data with classified waivers (owner, expiry, scope) and summary counts across deltas the caller may see. The ledger also includes waivers granted in comparison review: one-time exceptions and waived finding dispositions, with any recorded owner, approver, expiry, and comparison/finding scope. Older waivers without recorded terms remain as recorded; no expiry is inferred. A waiver whose recorded expiry has passed no longer licenses the exception.

`POST /api/estate/deltas/preview`

Field	In	Type	Default	Required	Description
`contract_id`	body	string	none	Yes	Stored source contract to compile against. Minimum length `1`.
`delta`	body	object	none	Yes	Draft delta document (`schema_version`, `boundary_hash`, `operations`).

Dry-compiles the draft Δ against the contract. Successful responses include data with footprint vector, validation issues, touched obligations, coverage impact, and consumer impact. Nothing is persisted.

Status	Meaning
`400`	Delta preview failed (validation or compile error).
`404`	Contract not found.

`POST /api/estate/deltas`

Field	In	Type	Default	Required	Description
`delta`	body	object	none	Yes	Delta document to register as proposed.

Successful responses include delta_hash (content-addressed id) and data with the proposal summary (status, operation_count, already_existed). The operator identity is taken from the authenticated session, never from the request body. Ratification remains a separate human-gated route.

Status	Meaning
`400`	Invalid delta document.

`POST /api/estate/deltas/{delta_hash}/ratify`

Field	In	Type	Default	Required	Description
`delta_hash`	path	string	none	Yes	Content-addressed Δ id.

Successful responses include delta_hash and ratified_by (authenticated human). The ratifier identity is taken from the authenticated session, never from the request body. The empty delta is explicitly ratifiable.

Status	Meaning
`403`	Caller lacks `ratify_source_contract`, auth is disabled, or the caller is not a genuinely authenticated human.
`404`	Delta not found.

`GET /api/estate/knowledge`

Field	In	Type	Default	Required	Description
`component_pair`	query	string	none	No	Filter to one component pair.
`migrator_id`	query	string	none	No	Filter to one migrator scope.
`source_platform`	query	string	none	No	Filter to one source platform.
`target_platform`	query	string	none	No	Filter to one target platform.
`phenomenon_kind`	query	string	none	No	Filter to one phenomenon kind.
`provenance`	query	string	none	No	Filter to one provenance tier.
`disclosure`	query	string	none	No	Filter to one disclosure class.
`signal`	query	string	none	No	Filter to one signal label.
`include_superseded`	query	boolean	`false`	No	Include superseded atoms.
`limit`	query	integer	none	No	Maximum atoms to return. Omitted by default → every matching atom is returned; pass `limit` to page down.

Filters are ANDed exact matches (unset = wildcard). Successful responses include data with the operator_ui redaction: atoms (each with atom_id, scope, phenomenon class labels, provenance, disclosure, and yield_stats — never evidence refs), returned_count, held_out_withheld_count, and disclosure_note. Held-out atoms never appear in atoms; only their withheld count is disclosed.

`GET /api/estate/knowledge/coverage`

This endpoint does not document any request body or query fields. Successful responses include data with the corpus-wide inventory: persisted (the live corpus), harvestable (what a sweep would mint from current store state), gap (harvestable but not yet persisted), source_counts per collector, and fully_swept. Each tally is bucketed by phenomenon kind, provenance tier, disclosure, component pair, and source instrument.

`GET /api/estate/knowledge/comparison`

Field	In	Type	Default	Required	Description
`component_pair`	query	string	none	Yes	Component pair for the per-comparison knowledge view.
`migrator_id`	query	string	none	No	Optional migrator scope.

Successful responses include data with contributed (redacted atoms this pair’s own artifacts minted) and informing (all scope-matched atoms shaping this pair’s instruments — the jitter prior and arsenal ranking), plus counts for each bucket. Both views are operator_ui-redacted; held-out atoms surface only as a withheld count.

`POST /api/estate/knowledge/collect`

This endpoint does not document any request body or query fields. Runs one idempotent knowledge sweep — a deterministic re-derivation of the corpus’s abstracted knowledge. Re-running on unchanged store state inserts nothing. Successful responses include data with atom_count, per-source counts, and inserted / skipped / superseded totals. The operator identity is taken from the authenticated session, never from the request body.

Status	Meaning
`400`	Knowledge collection failed.

Dataset inventory endpoint

Method	Path	Description	Auth behavior
`GET`	`/api/datasets`	List dataset metadata visible to the caller. This inventory call is read-only.	When auth is enabled, returns only datasets the caller can `read`. App tokens only include datasets granted dataset `read` access.

`GET /api/datasets`

This endpoint does not document any request body or query fields. It returns success plus a datasets array of DatasetInfo objects. This endpoint does not refresh datasets or trigger retention cleanup; cleanup runs separately through the configured background cleanup job.

Status	Meaning
`200`	Returns `DatasetListResponse` with the datasets visible to the caller.
`404`	The datasets backend is disabled.

Dataset detail endpoint

Method	Path	Description	Auth behavior
`GET`	`/api/datasets/{dataset_id}`	Return one dataset plus top-level freshness metadata that apps can consume without inspecting snapshot internals.	Requires dataset `read` access. App tokens must grant dataset `read`.

`GET /api/datasets/{dataset_id}`

Field	In	Type	Default	Required	Description
`dataset_id`	path	string	none	Yes	Dataset identifier.

In addition to success and dataset, the response can include these top-level fields:

Field	Type	Description
`dataset_id`	string or null	Echo of the requested dataset identifier.
`active_snapshot_id`	string or null	Snapshot identifier for the active materialized snapshot when present.
`last_refresh_at`	string or null	Timestamp of the most recent refresh attempt.
`snapshot_built_at`	string or null	Timestamp when the active snapshot was built.
`row_counts`	object	Per-source row counts from snapshot metadata. Keys are source/table names and values are integers.
`table_name_mapping`	object	Mapping from logical dataset source names to materialized SQLite table names.

Status	Meaning
`200`	Returns `DatasetGetResponse` with the dataset plus freshness metadata.
`403`	Caller lacks dataset `read` access, or an app token does not grant dataset `read`.
`404`	Dataset was not found, or the datasets backend is disabled.

Built-in `genesis_cost_usage_cube_v1`

The protected Cost & Usage cube (genesis_cost_usage_cube_v1) materializes three system-metrics sources: cost_usage_cube → cost_usage_cube_v1, users_dim → users_dim_v1, and scan_usage → scan_usage_v1. The scan_usage_v1 table holds Twin scan LLM spend at hourly grain with token counts and USD cost columns (cost_input_usd, cost_output_usd, cost_cache_read_usd, cost_cache_write_usd, cost_total_usd). Cost columns are NULL when a row cannot be priced (for example an empty model). Scan-cost views on the preset:

View ID	Purpose
`scan_cost_by_source_v1`	Cost, tokens, and requests grouped by `source_id`.
`scan_cost_by_operation_v1`	Cost, tokens, and requests grouped by `operation`.
`scan_cost_by_model_v1`	Cost, tokens, and requests grouped by `model` and `provider`.
`scan_cost_over_time_v1`	Daily cost, tokens, and requests (`date_utc`).
`scan_unpriced_v1`	Unpriced token totals where `cost_total_usd` is NULL.
`top_threads_by_cost_v1`	Known LLM and metered-service spend, pricing counts, tokens, and chat turns grouped by `instance` and `thread_id`.

top_threads_by_cost_v1 sums cost_usd for llm_call and metered_service_request rows; the total remains NULL when no call has a known price. Its unpriced_call_count and unknown_price_call_count describe those same rows and are complete only when pricing_counts_complete is 1. The view counts tokens from those call rows and chat turns from chat_turn_activity. Twin scan facts are written to SCAN_USAGE_FACTS by the twin_scan_cost_sync background job before dataset refresh materializes scan_usage_v1. The genesis_cost_usage_dashboard app exposes a Scan Cost tab over these views.

Internal cost accounting endpoints

These read-only endpoints back the serving instance’s internal Costs screen. They never accept an instance identifier. Summary, activity, execution, facts, and calls reads are scoped to the serving instance. The gap ledger has no instance column, so its rows are not scoped to the serving instance and may include other instances’ facts on a shared store. All routes except the gap ledger require ACCESS_PULSE_PANEL; the gap ledger requires ACCESS_CONFIG_PANEL. They are available on every install. These internal routes are excluded from the published OpenAPI schema.

Method	Path	Description
`GET`	`/api/costs/summary`	Return spend totals and their quality, freshness, legacy, gap, and post-disable qualifiers for a window; optionally include spend breakdowns.
`GET`	`/api/costs/activities`	Return one cursor page of activities ranked by known priced spend, with execution counts and activity dimensions.
`GET`	`/api/costs/activities/{producer}/{activity_type}/{activity_id}/facts`	Return one producer-qualified activity’s rollup buckets and retained raw-fact page.
`GET`	`/api/costs/activities/{activity_type}/{activity_id}/facts`	Resolve an unambiguous activity and return its rollup buckets and retained raw-fact page.
`GET`	`/api/costs/activities/{producer}/{activity_type}/{activity_id}/executions`	Return one cursor page of executions for exactly one producer and activity.
`GET`	`/api/costs/activities/{activity_type}/{activity_id}/executions`	Return one cursor page of executions when the activity resolves to one producer.
`GET`	`/api/costs/executions/{execution_key}/calls`	Return retained raw calls for one execution, or an expired-evidence response when those calls are no longer retained.
`GET`	`/api/costs/gap-ledger/{reason}`	Return one cursor page of deduplicated gap identities and recorded measures for a reason.
`GET`	`/api/costs/control-state`	Return the serving instance’s per-agent budgets and Context Graph cap state.
`GET`	`/api/costs/context-graph-sources/{source_id:path}/sweep-status`	Return one Context Graph source’s effective sweep budget and latest compact outcome.

The producer path value is chat or context_graph. Unattributed spend can exist under both producers, so producer-qualified paths keep those activities and their drilldowns separate. The older producer-less facts and executions paths resolve only when the activity belongs to one producer; otherwise they return 409 with code: ambiguous_activity_producer. The gap-ledger route accepts only administrators with ACCESS_CONFIG_PANEL. Its reason is one of post_disable, late_after_seal, revised_after_seal, expired_summarized, or legacy_unproven_residual. The windowed summary’s gap_ledger.legacy_unproven_residual discloses what pre-068 legacy rows of released open days counted beyond the raw facts that still prove them; this residual is never included in any total. Its fact_count counts residual rows (one per legacy row key, or one per day when the shortfall names no key), and row_count counts unproven facts. Fact rows for this reason use producer ~unknown, because those legacy rows named no producer. Because the ledger has no instance column, treat its results as shared-store evidence, not as facts for the serving instance alone. Each gap-ledger response contains the echoed reason, a facts page, and the standard page cursors. A fact identifies the producer, fact_id, identity, reason, and UTC event day. measures contains row_count, request_count, prompt_tokens, completion_tokens, cache_read_tokens, cache_write_tokens, and known_priced_total_usd when the ledger recorded them; otherwise it is null. epoch_start_utc is null when the fact has no disable epoch. The page is deduplicated to the latest version of each fact identity. The limit and cursor fields described below page through these records. The source sweep endpoint takes source_id as a path parameter (1–2048 characters) and has no query parameters. It reads Twin on demand for the selected source; it does not retrieve scan history or queued object names. The response contains source_id, available, effective_budget, last_outcome, and budget_has_room_now. effective_budget has nullable max_active_seconds, max_objects, max_queries, and max_containers limits; null limits are unbounded. last_outcome is null when no cycle outcome has been recorded, or contains status (in_progress, complete, incomplete, or halted), stop_reason (drained, time_slice, token_cap, budget_exhausted, superseded, throttled, or cancelled), recorded_at_utc, and budget_exhausted_units, and usage. usage is null when Twin recorded no usage or the recorded usage cannot be read; otherwise it contains the sweep’s total active_seconds, objects, queries, and containers across its cycles as of that recorded outcome. These are counts and seconds, not cost amounts. budget_has_room_now is null when that check does not apply. When Twin cannot provide a valid response, including for an unregistered source, available is false and the budget and outcome fields are null. The windowed endpoints accept these shared query fields:

Field	In	Type	Default	Required	Description
`preset`	query	`24h` \| `7d` \| `30d` \| `6mo` \| `custom`	`30d`	No	Window preset. Use `custom` with both `from_utc` and `to_utc`.
`from_utc`	query	ISO 8601 datetime	none	Conditional	Custom window start in UTC.
`to_utc`	query	ISO 8601 datetime	none	Conditional	Custom window end in UTC, exclusive.

Custom windows must include both endpoints and fit within the supported 400-day range. A window that is incomplete, too wide, outside the supported range, or ends in the future returns 422 rather than being silently truncated. The response reports the requested window and the effective_window actually summed after snapping to the rollup grain. Windowed responses also include instance_id, instance_name_generated, unsupported_substrate, evidence_level, and producer freshness. instance_name_generated is a boolean that is true when instance_id is a generated fallback for an install with no configured name; it defaults to false. Every cost response envelope also includes rollups_ready. It is false before the rollup job’s first run has created its read models, or on an unsupported storage substrate; in either case, the response contains no figures, returns empty lists where applicable, and does not treat the result as zero spend or an error. Each producer freshness entry includes advisory as a string or null (default null). dimension_rekey_incomplete means some older days’ breakdowns could not be rebuilt; last_error names those days. This advisory does not change the producer state, and totals are unaffected. over_cap_day_lagging accompanies a stale state whose cursor is current when a day over the complete-day cap has been written since its rebuild began and the rebuild has stayed open for more than two job intervals; that day’s spend then trails its writes, and last_error names the day. A quiet backlog does not set this advisory, nor does it appear while another day holds the source. Every cost response envelope also includes recording_since, the store’s recording cutover timestamp, or null before the store exists or on an unsupported storage substrate. Windows starting before this timestamp are clamped to it. The summary’s excluded_legacy reports spend recorded since the cutover with no known instance beside the total, never in the total; it is null when there are no figures. Producer freshness state can be healthy, stale, error, disabled, unknown, unsupported, or preparing. When totals is present, known_priced_total_usd includes only catalog-priced facts. estimated_price is separate and contains usd, row_count, and request_count for facts priced at an estimated rate (including a default rate or a price whose source was not recorded); those dollars are not included in the known-priced total. unpriced separately counts facts with no price. The summary response’s series is null when rollups are not ready or the substrate is unsupported. Otherwise it contains grain (hour or day), a bucket_count, and dense buckets covering the effective window. Each bucket has from_utc and to_utc bounds clipped to that window, complete, known_priced_total_usd, estimated_usd, total_tokens, reserved_tokens, unpriced counts (row_count, request_count, and total_tokens), and fact_count. A bucket is complete only when both sources have daily rows and every such row is sealed for that bucket’s UTC day; otherwise its figures are the amounts rolled up so far. known_priced_total_usd is catalog-priced spend; estimated_usd is estimated-price spend reported apart from that total. Reserved tokens are never priced, and unpriced usage is excluded from known-priced spend. On a stable snapshot, bucket sums match totals. rollup_write_position_utc reports the older rollup write position, or null when either position is unknown; it indicates progress, not event-time completeness. Trace endpoints (activities, activity facts, activity executions, and execution calls) also accept these scope and dimension query fields:

Field	In	Type	Default	Description
`scope`	query	`instance`	`instance`	Read this instance’s facts, the only scope. Any other value returns `422`.
`tier`	query	`hourly` \| `daily` \| null	selected for the window	Choose the rollup grain. Hourly data is unavailable beyond its 90-day retention window and returns `422`.
`producer`	query filter	`chat` \| `context_graph`	none	Limit trace rows to one source producer.
`operation`, `source`, `model`, `bot_id`, `provider`	query filters	non-empty string, up to 255 characters	none	Match the corresponding trace dimension.
`origin`	query filter	`user` \| `background` \| `unspecified` \| `not_recorded`	none	Match the runtime origin.
`call_type`	query filter	`completion` \| `embedding` \| `metered_service` \| `unspecified` \| `not_recorded`	none	Match the kind of call.
`source_group`	query filter	`conversations` \| `scheduled_jobs` \| `system_operations` \| `unattributed`	none	Match the activity source group.
`pricing_quality`	query filter	`catalog` \| `estimated` \| `unpriced`	none	Match the pricing classification.
`attribution_quality`	query filter	`full` \| `partial` \| `legacy` \| `unattributed`	none	Match the attribution classification.
`other_scope`	query	string token, up to 8192 characters	none	Select the complement represented by an `Other` breakdown entry. It cannot be combined with explicit dimension filters; refresh the breakdown if the token is stale.

An other_scope token is tied to its instance, window, and tier. A stale token returns 409 with code: stale_other_scope. Trace filters are non-empty and limited to 255 characters; enum filters accept only the values listed above. The summary endpoint accepts include_breakdowns (boolean, default false) and breakdowns_only (boolean, default false). When include_breakdowns is true, the response includes breakdowns; otherwise it is null. The object has operation, origin, call_type, and source dimensions. Each dimension contains entries, entry_count, and truncated; each entry reports its key and key_state (value, group, not_recorded, or other), known_priced_total_usd, estimated_usd, total_tokens, prompt_tokens, completion_tokens, cache_read_tokens, cache_write_tokens, reserved_tokens, request_count, fact_count, and unpriced (row_count, request_count, total_tokens). An other entry can carry an other_scope token for filtering its complement. Each dimension is capped at 50 entries, with excess values folded into its final other entry; rekey_complete reports whether older dimension keys were rebuilt. When breakdowns_only is true, it implies include_breakdowns and returns the breakdowns without reading totals, excluded_legacy, unsummarized_post_disable, gap_ledger, or series; those fields are null and the response echoes breakdowns_only: true. This is not a summary with no recorded spend. This mode uses three SELECTs; requesting include_breakdowns on the regular summary adds one full-key rollup-tier read. Activity, facts, executions, calls, and gap-ledger endpoints add cursor pagination:

Field	In	Type	Default	Description
`limit`	query	integer, `1`–`200`	`50`	Rows per page.
`cursor`	query	string up to 8192 characters or null	`null`	The previous response’s opaque, unpadded URL-safe `page.next_cursor`; use it only with the same list and filters.
`include_breakdown`	query	boolean	`false`	Include per-model breakdowns for activities or per-dimension breakdowns for executions.

Each paginated response includes page.limit, page.next_cursor, page.truncated_for_size, and page.cursor_unavailable. Response bodies are limited to 250,000 bytes; when that budget ends a page before its requested limit, truncated_for_size is true and next_cursor continues after the last returned row. If the last returned row’s key cannot be encoded within the cursor limit, cursor_unavailable is true and the list ends without a usable cursor. A malformed cursor or one issued for a different list returns 422. An individual row that exceeds the 20,000-byte row ceiling is shortened to fit; its truncated_fields names any shortened fields. The activity row’s producer is part of its identity. Use the producer-qualified facts and executions paths when a producer-less activity path is ambiguous. Those facts routes accept view (compact or full, default compact) and unexecuted (boolean, default false; when true, restricts buckets and raw facts to facts not marked as execution-bearing), in addition to the window, pagination, scope, tier, and trace-filter fields. They return rollup buckets, retention/completeness counts, and one bounded page of retained raw facts. Executions routes also accept include_reconciliation (boolean, default false). When requested, the response includes reconciliation totals; when omitted, those lines are null. This option adds one pass over the activity’s rollup-tier window. A producer-less execution request that matches multiple producers returns 409 with code: ambiguous_activity_producer. Activity rows include recurring (boolean or null). It is true for a cron or interval scheduler job, false for a one-shot (date) job and every non-job activity, and null when the job’s trigger snapshot is missing or unknown. The calls endpoint uses the opaque execution_key returned by the execution list and accepts limit and cursor plus:

Field	In	Type	Default	Description
`view`	query	`compact` \| `full`	`compact`	`compact` returns the fields shown by the Costs screen; `full` returns every canonical call field.

It also accepts an optional window (preset, from_utc, and to_utc) and the trace scope, tier, and dimension filters above. Unlike the other windowed routes, calls omit the window by default; a filtered calls request needs its parent window when it uses dimension filters, other_scope, or an explicit tier. Pass the execution key unchanged: older keys may use the colon-delimited form, while producer-qualified keys use the v2: form. A producer-less key that matches more than one producer returns 409 with code: ambiguous_execution_key. Compact call rows include cache_read_tokens and cache_write_tokens alongside the prompt and completion token counts. Context Graph bucket rows also include reserved_tokens, the embedding tokens reserved against the cap and never priced. Cache and reserved token counts can be null when they were not recorded; the Costs screen displays those values as a dash rather than zero. An unknown execution or activity returns 404. A malformed execution key or an otherwise unsupported report request returns 422. Calls report calls_completeness as complete, partial, or expired; an expired execution returns 200 with no raw calls and marks the evidence as expired. The control-state response carries evidence_level: null; its Context Graph cap includes can_edit, can_edit_reason, and the path to the existing Digital Twin cap editor, and this API provides no write route. can_edit_reason is null when editable; otherwise it is context_graph_unavailable when Twin did not respond, or requires_permission:access_config_panel when the caller lacks that permission. A dataset refresh keeps the instance column as it has always been, the agent id, so saved views, filters and joins on it are unchanged. The install a fact was recorded on is the install_instance column: the fact’s own instance, or legacy-unknown for a row written before the contract. A source’s instance parameter still selects an agent; its install_instance parameter selects an install. Canonical cost-fact rows retain the following activity, lineage, and rollup fields for consumers of the materialized dataset: The cube includes provider usage from auxiliary and background LLM calls, successful non-token metered-service requests, and ordinary chat, tool, and thread activity. Use usage_kind to tell metered-service requests from LLM calls. Non-token requests are materialized as llm_call rows, counted as calls and chat turns as they always were; the usage_kind column is metered_service_request on them (llm_call on an LLM call). Their cost_total_usd remains NULL because Genesis does not estimate the provider’s charge. When a producer supplies a synthetic thread label, Genesis keeps that label in thread_id for traceability but does not treat it as a conversation thread in canonical rollups. For activity caused by a scheduled prompt, Genesis carries a snapshot of the scheduler job and run into the cost fact. The snapshot is accepted only from trusted internal-service WebSocket callers, not from browser-supplied message metadata. A snapshot without scheduler_job_id is discarded; a snapshot with a job id but no run id is retained and represents job-level cost without a specific execution. These fields appear in the materialized dataset after a dataset refresh.

Field	Type	Description
`instance`	string	The agent (`bot_id`), as it has always been, for every row type. Saved views and filters on it are unchanged.
`install_instance`	string	The install the fact was recorded on: the fact’s own instance, or `legacy-unknown` for a row written before the contract.
`usage_kind`	string	On an `llm_call` row: `llm_call` for an LLM call, `metered_service_request` for a request to a per-request paid service. Empty on other row types.
`bot_id`	string	Agent associated with the fact and the agent filter used by the cost read plan.
`thread_id`	string	Thread associated with the activity or summary row, when available.
`parent_thread_id`	string	Parent thread identifier for lineage, when available.
`usage_category`	string	Not populated in this dataset: always empty. Use `usage_kind` to tell metered-service requests from LLM calls.
`usage_subcategory`	string	Not populated in this dataset: always empty.
`invocation_origin`	string	Not populated in this dataset: always empty.
`scheduler_job_id`	string	Scheduler job identifier for cost caused by a scheduled prompt, when available.
`scheduler_run_id`	string	Scheduler run identifier for cost caused by a scheduled prompt, when available.
`scheduler_job_name`	string	Job name snapshot captured when the scheduled run started, when available.
`scheduler_cadence`	string	Human-readable cadence snapshot, such as `cron 0 6 * * *`, `interval 15m`, or `once 2026-10-01T06:00Z`, when available.
`scheduler_trigger_json`	string	Serialized trigger snapshot captured when the scheduled run started, when available. It can also contain recovery metadata when an identifier was compacted.
`scheduler_owner_id`	string	Scheduler owner identifier captured when the scheduled run started, when available.
`data_rollup_source`	string	Source used to produce the row, such as `chat_turn_facts`, `tool_usage_facts`, `app_usage_facts`, `thread_summary` (a persisted thread summary) or `chat_turn_facts_synth_thread_summary` (a thread with no persisted summary).
`cost_usd`	float or null	The row’s cost in USD: a call’s stored amount, labelled or not. `null` for a call with no stored amount or one labelled `unpriced`, and for a synthesized thread summary none of whose calls has a cost. A persisted thread summary carries its stored cost.
`pricing_counts_complete`	integer	`1` on chat call rows and synthesized thread summaries, whose gap counts below are complete; otherwise `0`.
`unpriced_call_count`	integer	Calls represented by the row that are labelled unpriced; their cost is not in `cost_usd`.
`unknown_price_call_count`	integer	Calls represented by the row with no recognised pricing label, or no stored amount. An unlabelled call’s stored amount is still in `cost_usd`.
`child_thread_count`	integer	Direct child threads, from a persisted thread summary; `0` on other rows.
`child_thread_cost_usd`	float	Cost of the direct child threads, from a persisted thread summary; `0` on other rows.
`child_thread_unpriced_call_count`	integer	Always `0` in this dataset.
`child_thread_unknown_price_call_count`	integer	Always `0` in this dataset.
`cost_total_with_children_usd`	float	The thread’s cost with its direct children, from a persisted thread summary; `0` on other rows.

A thread with a persisted summary reports that summary’s values. A thread without one gets a summary synthesized from the window’s chat facts, with no child rollup. With an install_instance filter, persisted summaries are not read, because they record no install: every summary is synthesized from that install’s facts.

Dataset refresh endpoint

This route is mounted under /api/datasets/....

Method	Path	Description	Auth behavior
`POST`	`/api/datasets/{dataset_id}/refresh`	Refresh one dataset snapshot, optionally limited to selected sources.	Requires dataset `manage` access. App tokens receive `403 Forbidden`.

`POST /api/datasets/{dataset_id}/refresh`

Field	In	Type	Default	Required	Description
`dataset_id`	path	string	none	Yes	Dataset identifier to refresh.
`only_source_ids`	body	string[] or null	`null`	No	Optional subset of source IDs to refresh. Omit or pass `null` to refresh all sources.

Status	Meaning
`200`	Returns `DatasetRefreshResponse` with updated snapshot metadata.
`400`	For query-result datasets, the stored SQL is missing, malformed, or is not replayable. Genesis first parses the SQL in the target connection’s dialect, so valid single statements using dialect-specific identifier quoting are accepted. Stored writes are not replayed during refresh because doing so could apply the write again; re-run the query to create a fresh query result. It also rejects clearly corrupted SQL, including pagination text concatenated with another `SELECT` statement or multiple SQL statements submitted as a single query.
`403`	Caller lacks dataset `manage` access, or the request used an app token.
`404`	Dataset was not found, or the datasets backend is disabled.
`413`	With durable storage enabled, the new snapshot exceeds `sqlite_durability.user_db_max_bytes`; the refresh fails and the previous snapshot remains active.

When only_source_ids contains a source that is not present in the dataset definition, the 400 detail payload includes these fields:

Field	Type	Description
`message`	string	Human-readable validation failure.
`unknown_source_ids`	string[]	Requested source IDs that do not exist in the dataset definition.
`available_source_ids`	string[]	Valid source IDs currently defined on the dataset.

Dataset delete endpoint

Method	Path	Description	Auth behavior
`DELETE`	`/api/datasets/{dataset_id}`	Delete one dataset. Built-in protected datasets cannot be deleted, and datasets still bound to apps require explicit confirmation.	Requires dataset `manage` access. App tokens receive `403 Forbidden`.

`DELETE /api/datasets/{dataset_id}`

Field	In	Type	Default	Required	Description
`dataset_id`	path	string	none	Yes	Dataset identifier to delete.
`confirm`	query	boolean	`false`	No	Re-call with `true` after Genesis reports `requires_confirmation: true` for a dataset still bound to one or more apps.

On success, this endpoint returns success: true and the deleted dataset_id. When deletion is blocked or requires confirmation, the error detail payload can include these fields:

Field	Type	Description
`success`	boolean	`false` for blocked or confirmation-required delete attempts.
`requires_confirmation`	boolean	`true` when Genesis found one or more bound apps and requires `confirm=true` before deleting.
`delete_blocked`	boolean	`true` when Genesis blocks the delete outright, such as for protected system datasets or unreadable binding metadata.
`dataset_id`	string	Dataset identifier Genesis evaluated.
`bound_app_count`	integer	Number of apps currently bound to the dataset. Present on confirmation-required responses.
`bound_apps`	object[]	Bound app summaries. Each item can include `app_id`, `display_name`, and `status`. Present on confirmation-required responses.
`message`	string	Human-readable explanation of why Genesis blocked the delete or requested confirmation.

Status	Meaning
`200`	Dataset deleted successfully and returns `success: true` plus `dataset_id`.
`403`	Caller lacks dataset `manage` access, the request used an app token, or the dataset is a protected built-in system dataset.
`404`	Dataset was not found, or the datasets backend is disabled.
`409`	Genesis could not safely inspect dataset bindings, or the dataset is still bound to one or more apps and requires explicit confirmation.
`503`	Durable snapshot removal failed, or a refresh held the dataset lock for more than 30 seconds; the dataset remains available and the delete can be retried.

Dataset datasource endpoint

Use this AG Grid server-side row model (SSRM) route when the client needs server-side grouping, sorting, pivoting, or tree expansion against a dataset table or view.

Method	Path	Description	Auth behavior
`POST`	`/api/datasets/{dataset_id}/datasource`	Run SSRM operations against a dataset table or view.	Requires dataset `read` access. App tokens must grant dataset `read`.

`POST /api/datasets/{dataset_id}/datasource`

Field	In	Type	Default	Required	Description
`dataset_id`	path	string	none	Yes	Dataset identifier.
`table`	query or body	string or null	`null`	No	Dataset table to query. Provide only one of `table` or `view`. When both are omitted, Genesis uses the dataset default target.
`view`	query or body	string or null	`null`	No	Dataset view to query. Provide only one of `table` or `view`. When both are omitted, Genesis uses the dataset default target.
`startRow`	body	integer	`0`	No	SSRM start row. Minimum `0`.
`endRow`	body	integer	`100`	No	SSRM end row. Minimum `1`.
`rowGroupCols`	body	object[]	`[]`	No	SSRM row grouping descriptors.
`valueCols`	body	object[]	`[]`	No	SSRM value column descriptors.
`pivotCols`	body	object[]	`[]`	No	SSRM pivot column descriptors.
`pivotMode`	body	boolean	`false`	No	Whether SSRM pivot mode is enabled.
`groupKeys`	body	string[] or integer[]	`[]`	No	SSRM group key path for the current expansion level.
`filterModel`	body	object	`{}`	No	SSRM filter model.
`sortModel`	body	object[]	`[]`	No	SSRM sort model.

The response returns QueryResultSSRMResponse fields such as rows, lastRow, optional pivotResultFields, optional secondaryColumns, and, when available, the executed sql plus original base_sql.

Status	Meaning
`200`	Returns `QueryResultSSRMResponse` with SSRM row data and optional SQL metadata.
`400`	The request specified both `table` and `view`, or the SSRM payload was otherwise invalid for the selected dataset target.
`403`	Caller lacks dataset `read` access, or an app token does not grant dataset `read`.
`404`	Dataset was not found, or the requested dataset table/view does not exist.
`410`	The active snapshot is unavailable locally and has no durable copy to restore. Refresh the dataset to build a new snapshot.

POST /api/datasets/{dataset_id}/query is intentionally unsupported. Genesis returns 400 Bad Request with details.unsupported_endpoint, suggested_endpoint, suggested_method, suggested_body, and alternatives[] that point callers to /tables/{table_name}/rows, /views/{view_id}/rows, or /datasource.

Dataset row endpoints

These routes return one page of materialized dataset rows for a table or saved view. columns is returned only on the first page (page = 0) to avoid repeating schema metadata on later pages.

Method	Path	Description	Auth behavior
`POST`	`/api/datasets/{dataset_id}/tables/{table_name}/rows`	Return one page of rows for a dataset table.	Requires dataset `read` access. App tokens must grant dataset `read`.
`POST`	`/api/datasets/{dataset_id}/views/{view_id}/rows`	Return one page of rows for a dataset view.	Requires dataset `read` access. App tokens must grant dataset `read`.

Shared dataset row request fields

Field	In	Type	Default	Required	Description
`dataset_id`	path	string	none	Yes	Dataset identifier.
`table_name`	path	string	none	Conditional	Table name used by `POST /api/datasets/{dataset_id}/tables/{table_name}/rows`.
`view_id`	path	string	none	Conditional	View identifier used by `POST /api/datasets/{dataset_id}/views/{view_id}/rows`.
`page`	body	integer	`0`	No	Zero-based page number. Minimum `0`.
`page_size`	body	integer	`50`	No	Number of rows per page. Allowed range: `1` to `10000`.
`limit`	body	integer or null	`null`	No	Alias for `page_size`. Allowed range: `1` to `10000`.
`offset`	body	integer or null	`null`	No	Optional 0-based row offset alternative to `page`. Provide only one of `page` or `offset`. Genesis converts `offset` to `page` using floor division by the effective page size.
`filters`	body	object or object[]	`{}`	No	Equality filters. Accepts either an object map such as `{"AGENT_NAME":"Alice"}` or a legacy list of clauses such as `[{"column":"AGENT_NAME","op":"eq","value":"Alice"}]`. Legacy clauses accept `column`, `column_id`, or `field`; accept `op` or `operator`; and support `eq`, `==`, and `in`.
`sort`	body	object[]	`[]`	No	Sort specification array. Each item uses `column_id` plus `direction` (`asc` or `desc`, default `asc`).
`include_total`	body	boolean	`false`	No	When `true`, also compute and return `total_rows`.

Camel-case request aliases pageSize and includeTotal are also accepted on these row endpoints.

Dataset row response fields

Field	Type	Description
`rows`	object[]	Returned page of dataset rows.
`total_rows`	integer or null	Total matching row count when `include_total=true`; otherwise `null`.
`columns`	string[] or null	Column names for the dataset object. Returned on page `0`; omitted on later pages.
`has_more`	boolean	True when more rows are available beyond the returned page.
`truncated`	boolean	Compatibility alias for `has_more`.

Status	Meaning
`200`	Returns `DatasetRowsResponse` with row data and pagination metadata.
`403`	Caller lacks dataset `read` access, or an app token does not grant dataset `read`.
`404`	Dataset was not found. The table-rows route also returns `404` when `table_name` is not present in the dataset.
`410`	The active snapshot is unavailable locally and has no durable copy to restore. Refresh the dataset to build a new snapshot.

Genesis App registry writes

POST /api/apps, POST /api/apps/{app_id}/rename, PATCH /api/apps/{app_id}/metadata, and DELETE /api/apps/{app_id} apply registry changes only after the registry is saved. If the save is unavailable, these endpoints return HTTP 503 and do not apply the requested registry change; retry after a short wait. A create using an ID whose previous app is still being removed returns HTTP 409; retry after cleanup finishes. POST /api/apps accepts an omitted request body; Genesis uses the create request-field defaults documented in Genesis Apps. POST /api/apps/{app_id}/rename accepts display_name. Unknown request fields return HTTP 422 without changing the name; for example, title is not a rename field. Use PATCH /api/apps/{app_id}/metadata to set the metadata title (or its display_name alias). DELETE /api/apps/{app_id} preserves the workspace by default. Add the delete_workspace=true query parameter to also remove it and purge the app’s saved versions, Production assignment and promotion history, and file-level change history before removing the registry entry. If durable storage is unavailable or the apps repository is still being restored, the delete returns HTTP 503 and the app remains registered; retry after the store is available. Databricks Apps also rebuild missing saved-version files from durable Git when an operation needs them; see Genesis on Databricks. See Databricks durable-store behavior.

Genesis App Git history and revert

Method	Path	Description
`GET`	`/api/apps/{app_id}/history`	Return Git commit history for an app.
`POST`	`/api/apps/{app_id}/revert`	Restore app files to their state at the `target_commit` in the request body.

On macOS without an installed Git executable, the app history route uses snapshots instead of attempting to run the /usr/bin/git developer-tools stub. In a Databricks App, agent Git refuses operations on repositories with unsupported local or worktree configuration, submodules, or an incomplete safety check. The revert route returns HTTP 409 with the refusal detail. See the Git policy.

Genesis App status health fields

The versioned-app responses from GET /api/apps and GET /api/apps/{app_id}/status include data-layer health fields. This keeps a running app whose own Genesis API credential was recently refused from appearing healthy merely because its process still answers requests.

Field	Type	Description
`health`	string	`"degraded"` while a recent refused Genesis API call is recorded; otherwise `"ok"`.
`last_api_error`	object or null	Diagnostic details for the latest refused Genesis API call, including its method, path, status code, reason, timestamps, and refusal count. The evidence can remain after `health` returns to `"ok"`.

For the refusal symptoms, log correlation, and recovery steps, see Diagnosing a data-layer auth failure.

Genesis App list stop reason

Each GET /api/apps list record includes the app’s last stop reason:

Field	Type	Description
`stop_reason`	string or null	Why the app last stopped (for example, `dataset_preflight_failed`, `server_restart`, or `autostart_failed`); `null` when no stop reason is recorded. `autostart_failed` means Genesis did not start the app again after a restart.

Genesis App proxy behavior

When a browser request is proxied through /api/apps/{app_id}/proxy/... or /api/apps/{app_id}/remote/proxy/... and the target app has dataset bindings, Genesis can mint a short-lived viewer-scoped app token and forward it upstream to the app as X-Genesis-App-Token. Browsers do not need to set this header themselves. When auth.enabled is true and auth.provider is hosted, the proxy removes the inbound session credential headers (Authorization, Cookie, X-CSRF-Token, and X-XSRF-Token) and hosted identity headers before forwarding the request to the app. Hosted identity headers include names beginning with Sf-Context-Current-User, X-Auth-Request-, X-Forwarded-, or X-Genesis-Hosted-. Genesis then sets X-Forwarded-Host, X-Forwarded-Proto, and X-Forwarded-Prefix from the proxied request, so a consumed hosted assertion or caller-supplied forwarding identity is not exposed to the app. When auth.enabled is true and auth.provider is proxy, the proxy also removes the inbound session credential and hosted identity headers. It removes the configured proxy-auth user, email, groups, display-name, and access-token headers, including names without a recognized prefix. X-Forwarded-Access-Token is never forwarded to app code. Genesis sets X-Forwarded-Host, X-Forwarded-Proto, and X-Forwarded-Prefix itself rather than passing through caller-supplied values. If the proxy cannot resolve GenesisApp authorization configuration because the configuration has not been initialized yet, the proxied request returns 503 with the detail GenesisApp authorization configuration is temporarily unavailable. Retry the request after authorization configuration initialization completes. Successful app-proxy responses identified as PDFs are returned as downloads: Genesis sets Content-Type: application/pdf, adds X-Content-Type-Options: nosniff, and uses an attachment Content-Disposition with a sanitized filename. A response is treated as a PDF when its media type is application/pdf, or when the requested path ends in .pdf and the response has no media type or uses application/octet-stream. Other responses and non-2xx responses retain their upstream headers.

When app code is handling one of these proxied requests and uses Python requests or stdlib urllib.request to call GENESIS_API_BASE_URL or GENESIS_API_BASE, Genesis also auto-forwards the current app token by adding X-Genesis-App-Token to outgoing /api/... requests to that same Genesis API origin. Existing outgoing headers are preserved; the runtime patch overrides any stale token the app attached.Long-lived microapp processes (Dash, Flask, and similar) that keep running after start get this forwarding automatically at interpreter startup via sitecustomize.py in the microapp runtime-support shim. Versioned apps get the same shim for every declared runtime type, so their process token is proactively renewed while the app remains running. On proxied requests it injects the inbound viewer-scoped X-Genesis-App-Token header Genesis minted for the current browser session. On background-thread calls with no Flask request context it uses the rotating process token, or falls back to the startup GENESIS_APP_TOKEN env var. Token precedence is: inbound viewer token → rotating process token → GENESIS_APP_TOKEN.Locally hosted apps load the shim from the Genesis server workspace overlay. Remote deployments use the same shim in the genesis-app-runner container image (container/Dockerfile.app-runner adds runtime_support/ to PYTHONPATH).Genesis mints the process token with a default 6-hour TTL (21600 seconds). When GENESIS_APP_ID and GENESIS_APP_TOKEN are set, the runtime proactively rotates the process token via POST /api/apps/{app_id}/app-token/rotate about 10 minutes before expiry so dataset and /api/query calls do not start returning 401 after the original TTL.Runtime environment flags (string; default true unless noted):

Variable	Default	Effect
`GENESIS_RUNTIME_REQUEST_TOKEN_FORWARDING_ENABLED`	`true`	Set to `false` to disable the entire runtime token-forwarding patch (`requests` and `urllib.request`).
`GENESIS_RUNTIME_APP_TOKEN_AUTO_ROTATE_ENABLED`	`true`	Set to `false` to disable proactive rotation only. Forwarding still injects the startup `GENESIS_APP_TOKEN` on background-thread calls.

For both flags, Genesis treats 1, true, yes, on, and enabled as true and 0, false, no, off, and disabled as false.Custom app code that manages its own token lifecycle can call POST /api/apps/{app_id}/app-token/rotate directly (see below). Otherwise rely on the runtime patch or send GENESIS_APP_TOKEN explicitly on each call.The same runtime patch records outbound Genesis API calls in the app’s captured stdout/stderr with the [GENESIS_APP_API] prefix. HTTP failures are logged at WARNING without the query string, so an operator can correlate a refused token call with the app’s STATUS health signal without exposing proxied viewer tokens.

The local proxy can auto-start a stopped local runtime on HTML navigation. It also recovers stale running records after a Genesis server restart: status checks for running require the recorded internal port on 127.0.0.1 to be reachable (0.25 s timeout) in addition to PID liveness; starting checks PID only. When a proxied request finds the local port dead, Genesis invalidates the short-lived proxy status cache, reconciles status, and — for HTML GET requests — returns the same activation page used for stopped apps so the runtime restarts without a manual start call. Non-HTML proxy requests in that case return 503 with detail GenesisApp runtime is restarting after a server restart. Reload the app to continue. When the upstream accepts the connection but exceeds the proxy timeout, Genesis returns 504 with detail GenesisApp timed out while responding. Please retry. and does not reconcile the runtime to crashed. The remote proxy only forwards to an existing remote deployment and keeps the Genesis proxy path stable even when the backend also publishes a direct URL. For a top-level browser GET to a production proxy URL without a valid user credential, deployments using the interactive auth0 or oidc provider redirect the browser to /apps/ with the app ID and original proxy path. The Apps page resolves a fresh _auth token after sign-in and returns the browser to that same-origin app proxy path. This redirect is limited to page navigations (Sec-Fetch-Dest: document, or Accept: text/html when fetch metadata is absent); it does not apply to iframe, fetch, or non-GET requests. The proxy accepts the returned _auth token into an app-scoped, HTTP-only cookie and redirects again without the token in the URL. The cookie lasts one hour. A proxy request that already carries _auth is not redirected to sign-in again if that token is refused. This sign-in flow does not grant app access: normal app view checks still apply, and other auth providers do not use this redirect. If an HTML navigation reaches a shared app link without view access, Genesis returns a friendly access-denied page with the same 401 or 403 status. Non-HTML requests still receive the standard HTTP error response. App view access can come from ownership, explicit app grants, or shared-role visibility when the caller and app owner both hold a role that includes view_shared_role_resources. That widening applies only to App view; refresh, edit, and manage still require the normal owner or explicit policy path.

Genesis App server token capability manifest

A GenesisApp’s server authenticates to the Genesis REST API with X-Genesis-App-Token. That token is deliberately not a general Genesis API credential — it reaches a fixed set of platform endpoints. Fetch this manifest at authoring or start-up time instead of guessing routes; anything absent from the returned capabilities list is refused when called with an app token, no matter how the request is written. For the wider API, call it from the app’s front-end with the signed-in user’s session (fetch with credentials: 'include'), which is also what keeps a human in the loop on irreversible actions. The contract is identical for every app. The path parameter app_id is accepted for URL symmetry but is not resolved — that keeps this endpoint from doubling as a way to test whether an app exists. When a valid app token is presented on a path outside this contract (and no user credential is also present), Genesis returns 403 with a message that points callers to this manifest instead of falling through to a generic 401.

Method	Path	Description	Required access
`GET`	`/api/apps/{app_id}/capabilities`	Return the platform API routes this app’s server token may call.	Any authenticated caller, or valid `X-Genesis-App-Token`

`GET /api/apps/{app_id}/capabilities`

Field	In	Type	Default	Required	Description
`app_id`	path	string	none	Yes	Genesis App identifier. Accepted for URL symmetry; the response does not depend on whether this app exists.

Field	Type	Description
`version`	string	Contract version; changes when entries are added or removed. Current value: `"1"`.
`capabilities`	object[]	Allowlisted routes the app server token may call.
`capabilities[].route`	string	OpenAPI-style route template (for example `/api/datasets/{dataset_id}`).
`capabilities[].methods`	string[]	HTTP methods the endpoint is used with. Advisory only — authorization is path-level, so this is not an additional restriction.
`capabilities[].description`	string	What the capability is for.
`uncovered_route_guidance`	string	What to do for Genesis APIs that are not in `capabilities`.

Current capabilities entries (as of version "1"):

Route	Methods	Description
`/api/datasets`	`GET`, `POST`	List datasets the app’s delegated user can see.
`/api/datasets/{dataset_id}`	`GET`, `POST`	Read a dataset and its rows, tables, views, datasource and sharing metadata. Covers every path under `/api/datasets/`, including `/api/datasets/{dataset_id}/tables/{table_name}/rows` and `/api/datasets/{dataset_id}/views/{view_id}/rows`.
`/api/query`	`POST`	Run a query through the platform query service.
`/api/query-results`	`GET`, `POST`	Fetch results for a previously submitted query.
`/api/query-results/{query_id}`	`GET`	Fetch results for a specific query id.
`/api/tts/{operation}`	`GET`, `POST`	Text-to-speech synthesis and voice listing.
`/api/apps/{app_id}/llm/call`	`POST`	Chat-style LLM call scoped to this app.
`/api/apps/{app_id}/llm/direct`	`POST`	Base-completion LLM call scoped to this app.
`/api/apps/{app_id}/workspace`	`GET`	Read this app’s workspace metadata.
`/api/apps/{app_id}/files/write`	`POST`	Write a file into this app’s workspace.
`/api/apps/{app_id}/capabilities`	`GET`	This contract. Fetch it at runtime to discover which platform routes this app’s server token may call.

Status	Meaning
`200`	Returns the capability manifest.
`401`	Authentication required and no valid credential was presented.

Genesis App token rotation endpoint

Long-lived app workers call this route to mint a fresh GENESIS_APP_TOKEN without restarting the process. The microapp runtime also calls it automatically shortly before the current process token expires (see Genesis App proxy behavior).

Method	Path	Description	Required access
`POST`	`/api/apps/{app_id}/app-token/rotate`	Mint a new app token using the current (or recently expired) app token.	Valid `X-Genesis-App-Token` for `{app_id}`

`POST /api/apps/{app_id}/app-token/rotate`

Send the current app token in the X-Genesis-App-Token header. Genesis accepts tokens that expired within the last 48 hours (172800 seconds) so workers can recover after a brief outage without a full app restart.

Field	In	Type	Default	Required	Description
`app_id`	path	string	none	Yes	Genesis App identifier. Must match the `app_id` claim in the presented token.
`ttl_seconds`	query	integer	`21600`	No	Lifetime of the new token in seconds. Clamped to `300`–`86400`.

Request body is optional empty JSON ({}).

Field	Type	Description
`success`	boolean	Whether rotation succeeded.
`token`	string	New `GENESIS_APP_TOKEN` value. Send as `X-Genesis-App-Token` on subsequent API calls.
`ttl_seconds`	integer	Effective TTL applied to the new token.

Status	Meaning
`200`	Returns a new token with the same dataset, action, connection, and delegated-user claims as the presented token.
`401`	`X-Genesis-App-Token` header missing, invalid, or outside the rotation grace window.
`403`	Token `app_id` does not match the path `app_id`.
`404`	Genesis App was not found.

Genesis App LLM endpoints

Method	Path	Description	Required access
`POST`	`/api/apps/{app_id}/llm/call`	Execute one app-scoped chat turn through a Genesis agent. Omit `thread_id` to create a new chat thread.	App `view` + agent access to `bot_id`
`POST`	`/api/apps/{app_id}/llm/direct`	Execute a direct one-shot model completion without agent orchestration.	App `view`

App code should send X-Genesis-App-Token on both routes. Like other app routes, the token’s app_id must match the path app_id.

`POST /api/apps/{app_id}/llm/call`

Field	In	Type	Default	Required	Description
`app_id`	path	string	none	Yes	Genesis App identifier.
`bot_id`	body	string	none	Yes	Agent that should handle the chat turn.
`prompt`	body	string	none	Yes	Prompt text to send to the agent. Maximum `50000` characters.
`thread_id`	body	string or `null`	`null`	No	Optional existing thread id. Omit to create a new thread.
`model_tier`	body	`"frontier" \| "main" \| "fast" \| null`	`null`	No	Optional per-call model tier override.
`provider`	body	string or `null`	`null`	No	Optional provider override.
`execution_lane`	body	string or null	`null`	No	Deprecated compatibility field. Prompt dispatch uses the async dispatcher; the `express` lane is no longer selectable.
`timeout_seconds`	body	number	`120.0`	No	Maximum wait time for a completed response. Allowed range: `5.0` to `600.0`.

If thread_id is omitted, Genesis creates a new thread. New threads seed their initial model_tier and provider from the app authoring thread when available, otherwise they fall back to main and no stored provider override. Existing threads keep their current model settings unless model_tier or provider is supplied in the request. It returns these top-level fields:

Field	Type	Description
`success`	boolean	Whether the chat turn completed successfully.
`app_id`	string	Genesis App identifier.
`bot_id`	string	Agent that handled the request.
`thread_id`	string	Thread used for the turn.
`message_id`	string	Message id for the submitted chat turn.
`response`	string	Final response text returned for the turn.
`status`	string	Message-processing status, typically `finished` on success.
`model`	string or `null`	Resolved model name when Genesis can surface it.
`model_tier`	string	Effective thread model tier after any applied overrides.
`provider`	string or `null`	Resolved provider currently in effect for the thread when Genesis can surface it.
`execution_lane`	string	Effective prompt dispatch lane, normally `async`; `legacy` indicates the synchronous fallback path.
`created_thread`	boolean	Whether Genesis created a new thread for this call.

Status	Meaning
`200`	Chat turn completed and returned a response payload.
`400`	Invalid thread model settings or other bad request data.
`403`	Caller lacks App `view` access or agent access to `bot_id`.
`404`	App was not found.
`422`	Request body validation failed.
`500`	Genesis failed to execute the app-scoped chat turn.
`504`	The wait timeout elapsed before Genesis persisted a non-empty response.

`POST /api/apps/{app_id}/llm/direct`

Field	In	Type	Default	Required	Description
`app_id`	path	string	none	Yes	Genesis App identifier.
`prompt`	body	string	none	Yes	Prompt text for the direct completion. Maximum `50000` characters.
`model_tier`	body	`"frontier" \| "main" \| "fast" \| null`	`null`	No	Optional direct-call tier override.
`provider`	body	string or `null`	`null`	No	Optional provider override.
`timeout_seconds`	body	number	`120.0`	No	Maximum wait time for a completed response. Allowed range: `5.0` to `600.0`.

When model_tier and provider are omitted, Genesis inherits the app authoring thread defaults when available; otherwise it falls back to main plus the deployment’s configured main provider. It returns these top-level fields:

Field	Type	Description
`success`	boolean	Whether the direct completion succeeded.
`app_id`	string	Genesis App identifier.
`response`	string	Model response text.
`status`	string	Completion status, typically `finished` on success.
`provider`	string	Resolved provider used for the completion.
`model_tier`	string	Effective model tier used for the completion.
`configured_model`	string	Configured model selected before the provider call.
`model`	string	Model identifier reported by the provider response when available, otherwise the configured model.

Status	Meaning
`200`	Direct completion succeeded and returned a response payload.
`400`	Direct LLM configuration or request parameters were invalid.
`403`	Caller lacks App `view` access.
`404`	App was not found.
`422`	Request body validation failed. Common causes: missing or empty `prompt`, `model_tier` not exactly `frontier`, `main`, or `fast`, or `timeout_seconds` outside `5.0`–`600.0`. This route has no `response_format` field — put JSON instructions in `prompt` and parse the `response` string.
`500`	Genesis failed to execute the direct completion.

Genesis App validation endpoint

Method	Path	Description	Required access
`POST`	`/api/apps/{app_id}/validate`	Validate the current Genesis App workspace. For `presentation_deck` apps, the response includes slide-level `errors`, `warnings`, and `hints`.	App `view`

POST /api/microapps/{app_id}/validate is a legacy alias for the same behavior.

`POST /api/apps/{app_id}/validate`

Field	In	Type	Default	Required	Description
`app_id`	path	string	none	Yes	Genesis App identifier.
`check_images`	body	boolean	`true`	No	Whether to run image validation checks.
`check_audio`	body	boolean	`true`	No	Whether to run audio validation checks.
`target_slide`	body	integer or null	`null`	No	Optional 1-based slide number to validate. Allowed range: `1` to `500`.
`target_stage`	body	integer or null	`null`	No	Optional 1-based stage number to validate for staged slides. Allowed range: `1` to `100`.
`slide_range`	body	string or null	`null`	No	Optional 1-based inclusive slide range to validate, formatted as `low-high` such as `1-6`. `low` and `high` must stay within the deck’s slide count and `low <= high`.
`stage_sweep`	body	boolean or null	`null`	No	When `true`, validate that the targeted slide(s) expose staged content for a stage-sweep capture. Requires `slide_range` or `target_slide`.

Response fields include success, app_id, optional runtime_type, checks, errors[], warnings[], hints[], and error. POST /api/apps/{app_id}/start and POST /api/apps/{app_id}/restart also accept validate_slide_range (string or null, default null) and validate_stage_sweep (boolean or null, default null) when validate_before_restart=true, forwarding the same targeted deck checks through the automatic pre-start validation pass. On successful START and RESTART responses, hints contains outcome guidance for a person operating the app. caller_hints is separate API-caller guidance about the validate_before_restart and auto_capture_after_restart request parameters and the capture result; either field is null when it has no entries.

For presentation_deck apps, validation warnings can include slide.tts_alias_without_canonical_n when a slide uses narration, speaker_notes, notes, voiceover, or script without canonical n. That warning does not block validation by itself, but TTS generation skips that slide until narration is moved into n. When narration intent is explicit (for example the deck declares audio.format or metadata audio_required=true), missing fallback narration audio is promoted from a warning to a blocking validation error.

For presentation_deck apps, string-valued slide.t entries still warn when they contain HTML or entity-like markup, because plain title strings render as escaped text. To opt into safe title markup, use an object with exactly one key: {"html":"<span>Styled</span>"} for markup or {"text":"Plain title"} for escaped text. Invalid title objects surface slide.title_object_invalid. Python slides and stages must set py or python to a workspace file under presentation_slides/*.py that defines callable render(ctx). Missing files, path escapes, or renderer validation failures surface as slide.python_source_missing, slide.python_import_failed, stage.python_source_missing, or stage.python_import_failed. Outside a Databricks App, validation imports the renderer and checks its callable signature. In a Databricks App, Genesis parses and compiles the source without executing it; the renderer must be an undecorated top-level function accepting a context argument, and import errors appear only when the slide renders. These renderer files load as standalone workspace scripts, so use absolute imports such as from presentation_slides.utils import helper instead of relative imports.presentation_deck workspaces also ship scaffolded presentation.js and presentation_styles.css runtime assets referenced by app.py. Genesis copies them into the live workspace on start when missing, and treats edits to those files as restart-relevant alongside app.py and requirements.txt.

Genesis App screenshot capture

Method	Path	Description	Required access
`POST`	`/api/apps/{app_id}/capture`	Capture a screenshot of a running Genesis App. `/api/microapps/{app_id}/capture` is a legacy alias.	App `view`, or the internal service token; authentication-disabled deployments allow the request.

`POST /api/apps/{app_id}/capture`

Field	In	Type	Default	Required	Description
`app_id`	path	string	none	Yes	Genesis App identifier.
`thread_id`	body	string or null	`null`	No	Conversation to associate with this capture. On a Databricks App with durable chat uploads, the conversation must exist and be accessible to the caller, or be a known conversation on an internal-token request, for the screenshot to be kept across restarts.
`acting_user_id`	body	string or null	`null`	No	User the agent is acting for (maximum 256 characters). Honored only when the request carries the internal service token; otherwise ignored.
`timeout_seconds`	body	integer	`30`	No	Capture wait timeout; range `3`–`120`.

The response’s durability_warning string is present when a screenshot selected for durable recording could not be stored or attached; a capture not eligible for recording has no warning. The request also accepts capture options including bot_id, include_visual_description, runtime_snapshot_mode, slide, stage, slide_range, stage_sweep, and render-wait selectors/signals. The response includes screenshot paths and render diagnostics when available. Captures that time out before finishing or are replaced by a retry are not kept. See Durable chat uploads on Databricks.

Genesis App dev-session remediation responses

POST /api/apps/{app_id}/dev-session uses the same structured remediation payload described in Blueprint repository sync and dev-session remediation when workspace setup is blocked by an actionable saved-connection problem. OAUTH_RENEWAL_REQUIRED responses use HTTP 409 and return the remediation fields under the FastAPI error detail body.

Genesis App remote deployment endpoints

Method	Path	Description	Required access
`POST`	`/api/apps/{app_id}/deploy`	Deploy an app to `railway`, `eks`, or `docker`. For versioned apps, the body can target either Production or one saved version.	App `manage`
`GET`	`/api/apps/{app_id}/remote/status`	Return persisted `remote_deployment` metadata plus live backend status and health.	App `view`
`POST`	`/api/apps/{app_id}/remote/restart`	Re-deploy the existing remote target and mint a fresh delegated app token.	App `manage`
`POST`	`/api/apps/{app_id}/undeploy`	Tear down the remote deployment and clear persisted remote metadata.	App `manage`
`GET/POST/PUT/PATCH/DELETE/OPTIONS/HEAD`	`/api/apps/{app_id}/remote/proxy/`	Forward requests through Genesis to the deployed remote target root.	App `view`
`GET/POST/PUT/PATCH/DELETE/OPTIONS/HEAD`	`/api/apps/{app_id}/remote/proxy/{path:path}`	Forward requests through Genesis to the deployed remote target.	App `view`

`POST /api/apps/{app_id}/deploy`

Field	In	Type	Default	Required	Description
`app_id`	path	string	none	Yes	Genesis App identifier.
`backend`	body	string	none	Yes	Remote backend: `railway`, `eks`, or `docker`.
`backend_options`	body	object	`{}`	No	Backend-specific options. Common keys include `target_env`, `security_profile`, `credential_name`, `cluster` / `cluster_name`, `namespace`, `region`, `service_type`, `host_port`, `project_id`, and `environment_id`.
`spcs_mode`	body	boolean or null	`null`	No	Optional Snowflake Native App override for remote deploy flows launched from SPCS.
`target_kind`	body	string	`production`	No	Remote target selector. Allowed values: `production` or `version`.
`version_id`	body	string or null	`null`	Conditional	Required when `target_kind` is `version`. Deploys that saved version instead of Production.
`token_ttl_seconds`	body	integer	`86400`	No	Lifetime of the delegated `GENESIS_APP_TOKEN`. Allowed range: `60` to `604800`.
`acknowledge_identity_delegation`	body	boolean	`false`	No	Must be `true` or Genesis rejects the request. Confirms that the remote container will run with the caller’s delegated Genesis identity and data permissions for the requested token TTL.

POST /api/apps/{app_id}/remote/restart accepts the same spcs_mode, token_ttl_seconds, and acknowledge_identity_delegation fields. It reuses the app’s persisted remote backend and target. Genesis App list, detail, and status payloads can now include remote_deployment plus a targets object with local and remote summaries. Each target summary can include proxy_url, target_kind, target_identifier, target_label, backend and URL metadata, and version details when available. When clients need to bypass the caller-scoped apps list cache after an app was created or updated through chat, MCP, or another out-of-band flow, call GET /api/apps?refresh=1. Truthy refresh values such as 1, true, yes, or on invalidate the cached list before Genesis rebuilds the response. On registry load, Genesis renormalizes persisted microapp keys to the canonical app_id form (lowercase letters, numbers, and hyphens; 1–64 characters; must start and end with a letter or digit). Workspace directories discovered on disk are registered under the same canonical id. Duplicate registry rows that collapse to one canonical id after renormalization are skipped so a single bad key cannot hide other apps from GET /api/apps or apps_action(LIST). On Databricks Apps with durable storage enabled, the GenesisApp registry is uploaded to Lakebase before each save and restored before the server serves requests, so the app list survives host replacement. See Durable SQLite stores on Databricks. In SQLAlchemy metadata mode, App and legacy dashboard categories are stored in the metadata database and share database-assigned category IDs. Those IDs remain stable across server restarts while the metadata database is retained.

Context Graph endpoints

These routes are mounted under /api/context-graph/... and back Digital Twin scan administration in the web client. Unless noted otherwise, they require access_config_panel. Lineage-backed Context Graph operations can return HTTP 503 Service Unavailable; see Digital Twin and Context Graph for the disabled-server condition and recovery steps.

Twin log endpoints

GET /api/context-graph/logs/twin reads the tail of twin.log from the Genesis host. The file lives on durable storage alongside the context graph ({STORAGE_PATH}/twin/twin.log), so it survives pod restarts; the TWIN_LOG_FILE environment variable overrides the location. Thread-export support bundles and the Digital Twin log viewer use the same resolver, so the path cannot drift between writer and readers. File rotation is bounded via TWIN_LOG_MAX_BYTES (default 52428800, 50 MiB per file) and TWIN_LOG_BACKUP_COUNT (default 10). Genesis keeps the active file plus up to TWIN_LOG_BACKUP_COUNT rolled backups, capping total disk at approximately (TWIN_LOG_BACKUP_COUNT + 1) × TWIN_LOG_MAX_BYTES (~550 MiB with defaults) while retaining well over a week of sustained high-rate scanning. GET /api/context-graph/logs/twin/download returns the full file as a text/plain attachment named twin.log.

`GET /api/context-graph/logs/twin`

Field	In	Type	Default	Required	Description
`tail`	query	integer	`500`	No	Number of lines from the end of the file. Minimum `1`, maximum `5000`.
`search`	query	string or null	`null`	No	Case-insensitive filter string. When set, Genesis filters lines before taking the tail.

Response fields:

Field	Type	Description
`success`	boolean	Whether the request completed successfully.
`lines`	string[]	Log lines returned after filtering and tailing.
`total_lines`	integer	Total line count in the file before tailing (not affected by `search`).
`returned_lines`	integer	Number of lines in `lines`.
`file_size_bytes`	integer	On-disk size of `twin.log` in bytes.

Returns 404 when twin.log does not exist.

`GET /api/context-graph/logs/twin/download`

This route does not accept query parameters. Returns 200 with Content-Disposition: attachment; filename="twin.log" on success. Returns 404 when twin.log does not exist.

Scan permission check endpoint

POST /api/context-graph/check-permissions resolves a saved connection on the Genesis side and asks Twin to audit whether the credentials can perform a lineage scan. Genesis passes the resolved locator to Twin so the check does not require Twin to call back into Genesis.

`POST /api/context-graph/check-permissions`

Field	In	Type	Default	Required	Description
`connection_type`	body	string	none	Yes	Connection type as shown in the UI (for example `snowflake`, `gitlab`, `github`).
`connection_name`	body	string	none	Yes	Connection name as shown in the UI. Genesis resolves `{connection_type}.{connection_name}`.

Response fields:

Field	Type	Description
`success`	boolean	Whether the overall check succeeded. `false` when connection resolution fails or Twin reports an error.
`checks`	object[]	Individual permission checks. Each item includes `check` (string), `status` (`pass`, `fail`, or `warn`), and `detail` (string).
`summary`	string	Human-readable rollup of the audit result.

When connection resolution fails, Genesis returns success: false with a single checks entry named Resolve connection and status: fail.

Internal Digital Twin integration endpoints

These internal routes are mounted under /api/internal/... and are intended for the Digital Twin MCP subprocess rather than interactive client use.

All internal Digital Twin integration requests require an Authorization header with the internal bearer token: Bearer <internal-token>.

Method	Path	Description
`POST`	`/api/internal/resolve-llm-credentials`	Resolve fresh LLM credentials for a provider. Used by Twin to refresh credentials before each scan cycle. Forces a credential cache miss so the response reflects current database state.

`POST /api/internal/resolve-llm-credentials`

Field	In	Type	Default	Required	Description
`provider`	body	string	`""`	No	LLM provider to resolve. When omitted, empty, or whitespace-only, Genesis resolves the currently active provider from LLM state so Twin always gets the right config even if the `RELOAD_LLM_CONFIG` notification was lost.

It returns these top-level fields:

Field	Type	Description
`success`	boolean	Whether Genesis resolved credentials successfully. When `provider` is `litellm_proxy` and the Twin runtime resolver cannot produce usable proxy auth (for example missing `proxy_api_base`, incomplete OAuth/static-header configuration, or a non-interactive OAuth policy without a service account), Genesis returns `success: false` with `error` set to the resolver reason. Other providers keep the prior shape: an unusable runtime can still return `success: true` with a blank `engine`.
`engine`	string or null	Resolved LLM engine identifier for Twin runtime configuration.
`provider`	string or null	Resolved provider name. When the request omitted `provider`, this is the active provider Genesis selected.
`model`	string or null	Resolved model identifier for the provider.
`api_base`	string or null	Resolved API base URL when applicable.
`api_key`	string or null	Resolved API key or token when applicable.
`extra`	object or null	Additional provider-specific runtime fields. `env_vars` are stripped from this object and returned in the top-level `env_vars` field instead. For AWS Bedrock custom endpoints with a non-bearer `custom_auth_header` (for example `x-api-key`), `extra` may include `litellm_kwargs` — ready-to-spread LiteLLM call kwargs with `aws_bedrock_runtime_endpoint`, `extra_headers`, and placeholder SigV4 credentials so Twin subprocesses match main-process custom-header auth. Bearer, default-endpoint, and IAM Bedrock configs omit `litellm_kwargs`. For `litellm_proxy`, `extra` includes `auth_mechanism` (`api_key`, `oauth`, `static_headers`, or `none`) from the Twin runtime resolver. When `auth_mechanism` is `api_key`, `oauth`, or `static_headers`, `extra` may also include `litellm_kwargs` with `api_key`, `api_base`, and/or `extra_headers` resolved from the active LiteLLM Proxy auth configuration so Twin subprocesses forward the same upstream credentials and headers as the main Genesis process. When `auth_mechanism` is `none`, `litellm_kwargs` is omitted and Twin uses network-identity auth against `api_base`.
`env_vars`	object or null	Provider environment variables to apply in the Twin subprocess. Values can be `null` to clear stale keys when switching providers.
`error`	string or null	Present when `success` is `false`. Returns `No active LLM provider configured` when `provider` was empty and Genesis has no active provider. For `litellm_proxy`, returns the Twin runtime resolver reason when proxy auth cannot be resolved (for example `LiteLLM proxy base_url/api_key is not configured (DB/UI or env).`, OAuth renewal or service-account errors, or `LiteLLM proxy runtime not usable` when no reason is available).

Internal Digital Twin integration example request

curl -X POST "http://<genesis-host>/api/internal/resolve-llm-credentials" \
  -H "Authorization: Bearer <internal-token>" \
  -H "Content-Type: application/json" \
  -d '{"provider":""}'

Internal upgrade-check endpoints

These routes are for the Control Plane’s post-upgrade checks, not interactive client use. Genesis mounts them only when GENESIS_UPGRADE_CHECK_TOKEN is set to a non-empty value when the app starts; otherwise the routes do not exist. Every request requires Authorization: Bearer <GENESIS_UPGRADE_CHECK_TOKEN>. Hosted mode does not expose /api/internal/, so these routes are unreachable there.

Method	Path	Description
`GET`	`/api/internal/upgrade-check/counts`	Read agent, connection, knowledge-graph, and LLM readiness counts. Returns `503` until app startup completes.
`POST`	`/api/internal/upgrade-check/eve-probe`	Start or retrieve the Eve LLM probe. Returns immediately.
`GET`	`/api/internal/upgrade-check/eve-probe/{probe_id}`	Read an Eve probe’s current result.
`POST`	`/api/internal/upgrade-check/blueprint-probe`	Start or retrieve the `upgrade_check` blueprint probe. Waits for the Mission start to settle.
`GET`	`/api/internal/upgrade-check/blueprint-probe/{probe_id}`	Read a blueprint probe’s current result.
`DELETE`	`/api/internal/upgrade-check/blueprint-probe/{probe_id}`	Stop a running blueprint probe and confirm Mission/thread cleanup.

Both POST routes accept exactly this JSON body; extra fields are rejected:

Field	Type	Required	Description
`probe_id`	string	Yes	Agent-generated identifier matching `^[a-z0-9-]{8,64}$`.

Repeated starts with the same probe ID return the existing record. Probe records are held in separate in-memory stores of up to 32 Eve and 32 blueprint probes; finished records are retained for 30 minutes. Reads and cleanup return 404 when the probe is missing or its record has expired. A full store of records it must retain returns 503. The counts response contains:

Field	Type	Description
`agents`	integer	All agents, including built-in and disabled agents.
`connections`	integer	Connection total; a floor if the legacy connection store cannot be read.
`connections_complete`	boolean	`false` when the legacy connection store could not be read.
`knowledge_graph_nodes`	integer or null	Node count, or `null` until the graph is available.
`knowledge_graph_ready`	boolean	Whether the graph node count is available.
`llm_usable`	boolean	Whether an LLM provider is configured and validated.

This request reads the bot cache, reads the two connection stores, makes one Twin stats call bounded at five seconds, and probes LLM readiness; it does not make an LLM completion call. Probe responses contain:

Field	Type	Description
`probe_id`	string	The ID supplied when the probe was started.
`mission_id`	string or null	Blueprint probes only; `null` if no Mission started.
`state`	string	Eve: `running`, `ok`, `llm_unreachable`, or `failed`. Blueprint: `running`, `completed`, `llm_unreachable`, or `failed`.
`detail`	string	Probe result detail.
`started_at`	string	Server-generated ISO-8601 UTC timestamp at whole-second precision.
`finished_at`	string or null	Same timestamp format; `null` while running.

The Eve probe sends one fixed prompt to Eve and is bounded at 90 seconds. The blueprint probe starts the hidden built-in blueprint and is bounded at 300 seconds. Both run under the internal system identity and delete their temporary thread when finished; the blueprint probe also deletes its Mission. The delete route confirms cleanup if artifacts remain and keeps the probe record.

Internal sandbox LLM proxy endpoints

These routes are mounted under /api/internal/sandbox-llm/... and are intended for sandbox Claude Code thread-runner containers, not interactive client use. A per-thread sandbox container calls them with ANTHROPIC_BASE_URL pointed at http://<genesis-host>/api/internal/sandbox-llm (the Anthropic SDK appends /v1/messages or /v1/messages/count_tokens). Genesis validates a thread-scoped session token on each call, injects the real org LLM credentials server-side, and forwards the upstream response — the container never holds the org Anthropic key or other provider credentials.

These routes sit under the /api/internal/ prefix, which is public to AuthRequiredMiddleware (not an Auth0-protected path). Authentication is in-band: the sandbox presents its thread-scoped token as the x-api-key header value. This is not the internal bearer token used by Twin or genesis-scanner routes.

Method	Path	Description
`GET`, `HEAD`	`/api/internal/sandbox-llm/api/hello`	Return `200` for the sandbox client’s connectivity probe. This endpoint does not require the thread-scoped `x-api-key`.
`POST`	`/api/internal/sandbox-llm/v1/messages`	Proxy an Anthropic Messages API call from a sandbox session.
`POST`	`/api/internal/sandbox-llm/v1/messages/count_tokens`	Proxy an Anthropic token-count call from a sandbox session.

Authentication: Except for the connectivity probe, x-api-key must be a live thread-scoped sandbox session token (minted by Genesis when the container starts). Token records are stored in Genesis metadata, so a backend restart does not invalidate an otherwise-live token; the stored expiry still applies. An invalid token returns 401 with an Anthropic-shaped authentication_error body and the message invalid sandbox session token. A token whose stored expiry has passed returns the same status and error type with the message sandbox session token expired. If the token store is unavailable, the proxy returns 503 with an error response; the proxy service uses an Anthropic-shaped api_error body. The GET or HEAD connectivity probe returns a bare 200 without a token and does not proxy an LLM request. Request body: JSON in Anthropic Messages API shape. When sandbox_runner.llm_model is set (Advanced Settings, genesis-config.yaml, or GENESIS_SANDBOX_RUNNER_LLM_MODEL after the startup config→env bridge), Genesis routes through litellm and overrides the request’s model with the configured litellm model (and, when applicable, the thread’s GUI-selected model tier). The proxy honors the request’s stream flag — Claude Code streams by default; when the flag is omitted, the proxy returns the non-stream plain JSON response specified by the Anthropic API default. Mid-conversation role: "system" entries inside messages are hoisted into the top-level system parameter so Bedrock and other litellm providers accept the request. litellm mode: When sandbox_runner.llm_model is set (for example bedrock/us.anthropic.claude-sonnet-4-6), Genesis serves calls via litellm.anthropic_messages and litellm.token_counter. Streaming responses are SSE already in Anthropic wire format and are forwarded unchanged. Databricks models are also supported: when the configured provider has no Anthropic Messages configuration, Genesis bridges the request to chat completions and re-emits the result in Anthropic format, including tool_use blocks. For Databricks models, Genesis translates stop_sequences to Databricks’ stop parameter before forwarding the request. Token usage is metered per call against (bot_id, thread_id) with usage_category: sandbox_runner. The recorded prompt total includes fresh input plus cache-read and cache-write tokens, while those cache counts remain separate for pricing so cached tokens are not counted twice. A turn served entirely from the cache is still recorded when it has prompt usage. For Databricks models, Genesis restores the first text fragment when a streamed reply starts a new text block after a tool call, so that fragment is not lost from the Claude Code response. If the upstream model rejects extended thinking either in the request parameters or replayed message history, Genesis retries the turn once without the thinking parameter and thinking content blocks. Other provider failures preserve a recognized provider status and the corresponding Anthropic error type, allowing Claude Code to distinguish rate limits and request or credential problems. Failures without a recognized status or rate-limit marker remain 502 with api_error. Direct Anthropic fallback: When sandbox_runner.llm_model is unset, Genesis forwards to https://api.anthropic.com/v1/... using the org Anthropic key resolved from AppConfig (litellm_anthropic provider). Returns 502 when neither litellm mode nor a configured Anthropic key is available. Live GUI streaming: During litellm streaming, Genesis tees the forwarded model SSE into the GUI while the container receives the upstream bytes unchanged. Each visible proxy request (one agent step) uses two identifiers; auxiliary requests that do not advertise tools, such as thread-titling calls, are not painted into the chat reply:

message_id — per-step bubble id of the form sbx_{thread_id}_{12-hex}. This identifies the proxy request’s live streaming events.
assistant_message_id — turn-level id from the thread’s active completion (when registered). The streamed text deltas, tool boxes, and persisted message rows all carry this id so the chat UI groups them into one assistant reply and reconciles the live copies with the end-of-turn refetch. Omitted when no active completion is registered (best-effort).
Assistant text: Genesis emits message_response_delta WebSocket events (made_by: sandbox_runner) with the per-step message_id and, when available, assistant_message_id. full_text contains the complete assistant text accumulated across the turn so far, rather than only the current step; clients should use it as the displayed value for the turn. Each delta also checkpoints this growing full_text on the thread’s active completion so a GUI stop mid-turn preserves the partial reply that was already shown.
Tool boxes: When the model SSE includes a completed tool_use block, Genesis emits thread_tool_start with the masked Genesis-native tool name and arguments. When the tool result arrives on a later proxy request, Genesis emits thread_tool_stop once for that tool within the turn, even when earlier results are replayed in subsequent requests. Both events set assistant_message_id to the turn-level id (falling back to the per-step message_id when no completion is registered) so the chat UI renders running/done tool cards live against the same assistant reply (same contract as in-process threads — see Supported progress event types).

Stop during streaming: The GUI stop button bumps the thread’s cancel epoch. While litellm streaming is in progress, the proxy watches that epoch and aborts the upstream generator when it changes — killing the container process does not stop generation because the in-container HTTP call to this proxy stays open. On abort, Genesis opens a brief (10 s) stop window for the thread: any reconnecting sandbox CLI request during that window receives a synthetic empty Anthropic turn SSE instead of regenerating the cut-off step.

Status	Meaning
`200`	Success — streamed `text/event-stream` when `stream` is true, otherwise JSON.
`400`	Request body is not valid JSON.
`401`	Invalid or expired sandbox session token.
`400`	Provider rejected the request (`invalid_request_error`).
`401`	Provider authentication failed (`authentication_error`).
`503`	Sandbox token storage is unavailable (`api_error`).
`403`	Provider denied the request (`permission_error`).
`404`	Provider resource or model was not found (`not_found_error`).
`413`	Provider rejected an oversized request (`request_too_large`).
`429`	Provider rate limit (`rate_limit_error`).
`529`	Provider is overloaded (`overloaded_error`).
`502`	Unclassified LLM routing or provider failure (`api_error`).

Internal Genesis scanner endpoints

These internal routes are mounted under /api/internal/genesis-scanner/... and are intended for Twin migration and scanner automation workflows rather than interactive client use.

All internal Genesis scanner requests require an Authorization header with the internal bearer token: Bearer <internal-token>.

Method	Path	Description
`GET`	`/api/internal/genesis-scanner/inventory`	Return the current Genesis artifact inventory, including normalized SQLite connection path metadata for scanner workflows.
`POST`	`/api/internal/genesis-scanner/scan-sqlite`	Resolve and inspect a SQLite database referenced by dashboard, dataset, or SQLite connection.
`GET`	`/api/internal/genesis-scanner/harvest-export`	Export paginated `harvest_results` rows plus `harvest_control` rows and current Chroma embedding metadata for Twin migration.
`GET`	`/api/internal/genesis-scanner/harvest-embeddings`	Export paginated ChromaDB harvester embeddings together with their source documents and metadata.

`GET /api/internal/genesis-scanner/inventory`

This route does not accept query parameters. It returns these top-level fields:

Field	Type	Description
`dashboards`	object[]	Dashboard inventory.
`datasets`	object[]	Dataset inventory.
`apps`	object[]	Genesis App inventory.
`agents`	object[]	Agent inventory.
`connections`	object[]	Saved connection inventory with locator secrets removed.
`sqlite_connections`	object[]	SQLite subset of `connections`. Each item reports `connection_id`, `path`, `file_exists`, and `is_default`.
`schedules`	object[]	Scheduler job inventory.
`flows`	object[]	Flow inventory.
`local_repos`	object[]	Local repo inventory. Currently returned as an empty array.
`errors`	object	Per-section collection errors keyed by inventory section name.

Each item in datasets, apps, and schedules includes:

Field	Type	Description
`is_builtin`	boolean	`true` when the dataset, Genesis App, or scheduler job is a Genesis-provided built-in; `false` for customer-created items.

For scheduler jobs, this includes system dataset-refresh jobs and the Genesis daily scan job (twin_daily_scan).

During early startup, schedules can be empty and errors.schedules can be present if the scheduler is still starting. Genesis retries the scheduler lookup before returning that partial inventory response.

Each item in sqlite_connections includes:

Field	Type	Description
`connection_id`	string	Saved SQLite connection name.
`path`	string	Resolved SQLite file path when Genesis can validate the saved locator value. Bare managed names such as `my_database` resolve to `{storage_path}/sqlite/my_database.db`, and relative custom file paths are resolved before the response is returned. If validation fails, Genesis echoes the raw saved locator value instead of bypassing validation.
`file_exists`	boolean	`true` only when the validated resolved path exists on disk.
`is_default`	boolean	Whether the saved connection is marked as the default SQLite connection.

`POST /api/internal/genesis-scanner/scan-sqlite`

Field	In	Type	Default	Required	Description
`ref`	body	string	none	Yes	SQLite reference in one of three formats: `dashboard:<id>`, `dataset:<id>`, or a SQLite `connection_id`. When `ref` is a connection ID, Genesis extracts the saved locator path and validates it with the same normalization used at connection-creation time. Bare managed names resolve under `{storage_path}/sqlite/`, and relative custom file paths are resolved before scanning.

It returns these top-level fields:

Field	Type	Description
`ref`	string	Echo of the request reference.
`resolved_path`	string	Validated absolute SQLite file path that Genesis scanned, or attempted to scan when the scan failed after resolution.
`file_size_bytes`	integer	SQLite file size in bytes. Returned as `0` when the scan fails before file size is collected.
`tables`	object[]	Table and view metadata from `sqlite_master`, excluding internal `sqlite_%` objects.
`error`	string or null	Present when Genesis resolves the file but scanning fails.

scan-sqlite returns HTTP 400 when ref cannot be resolved to a SQLite file, and HTTP 403 when the resolved file is one of Genesis’s blocked internal databases: genesis.db, rbac.db, datasets.db, genesis_cache.db, scheduler_jobs.db, lineage.db, flows.db, blueprint_runs.db, or debriefs.db.

`GET /api/internal/genesis-scanner/harvest-export`

Field	In	Type	Default	Required	Description
`offset`	query	integer	`0`	No	Number of `harvest_results` rows to skip.
`limit`	query	integer	`5000`	No	Maximum number of `harvest_results` rows to return.

This endpoint returns these top-level fields:

Field	Type	Description
`harvest_results`	object[]	Serialized page of `harvest_results` rows. Each row omits `embedding`, `embedding_native`, `llama_index`, and `memory_uuid`.
`harvest_control`	object[]	Serialized `harvest_control` rows. Returns an empty array when Genesis cannot read that backend.
`chroma_embedding_info`	object	Embedding metadata from the current harvester collection. When available, it includes `provider`, `model`, `dimensions`, and `doc_count`.
`total_count`	integer	Total number of `harvest_results` rows before pagination.
`offset`	integer	Echo of the requested offset.
`limit`	integer	Echo of the requested limit.

`GET /api/internal/genesis-scanner/harvest-embeddings`

Field	In	Type	Default	Required	Description
`offset`	query	integer	`0`	No	Number of embedding records to skip.
`limit`	query	integer	`100`	No	Maximum number of embedding records to return.

This endpoint returns these top-level fields:

Field	Type	Description
`embeddings`	object[]	Paginated Chroma embedding entries.
`offset`	integer	Echo of the requested offset.
`limit`	integer	Echo of the requested limit.
`total`	integer	Returned as `0` when no current harvester collection is available or the collection read fails.
`error`	string	Present when Genesis cannot read the current harvester collection.

Each entry in embeddings includes:

Field	Type	Description
`id`	string	Chroma document identifier.
`document`	string	Stored document text for the embedding entry.
`metadata`	object	Stored Chroma metadata for the entry.
`embedding`	number[] or null	Embedding vector as a JSON array, or `null` when no embedding payload is available.

SQLite scanner checks reserved database filenames and durable-store paths. The durable metrics.db is blocked by its resolved path rather than by filename; an unrelated user database named metrics.db is not blocked by name alone.

Internal Genesis scanner example requests

curl -X GET "http://<genesis-host>/api/internal/genesis-scanner/inventory" \
  -H "Authorization: Bearer <internal-token>"

curl -X POST "http://<genesis-host>/api/internal/genesis-scanner/scan-sqlite" \
  -H "Authorization: Bearer <internal-token>" \
  -H "Content-Type: application/json" \
  -d '{"ref":"workspace_sqlite"}'

curl -X GET "http://<genesis-host>/api/internal/genesis-scanner/harvest-export?offset=0&limit=5000" \
  -H "Authorization: Bearer <internal-token>"

curl -X GET "http://<genesis-host>/api/internal/genesis-scanner/harvest-embeddings?offset=0&limit=100" \
  -H "Authorization: Bearer <internal-token>"

Bot settings endpoints

These routes manage per-agent settings and require manage_agents. The settings write route applies the same context soft-limit safety cover used by the Agent Center LLM tab. Settings writes and clears for a version-owned agent return HTTP 409 with error_type protected_core_agent; the version_owned field in the bot list and details responses identifies these agents.

Method	Path	Description
`GET`	`/api/bots/settings/definitions`	List supported bot-setting keys, types, allowed values, defaults, and required permissions.
`GET`	`/api/bots/{bot_id}/settings`	Return effective settings, raw overrides, and the current bot soft-limit status.
`PUT`	`/api/bots/{bot_id}/settings`	Set one or more bot-setting overrides.
`DELETE`	`/api/bots/{bot_id}/settings/{key}`	Clear one bot-setting override so the bot inherits again.

The bot-level context soft-limit keys are:

Key	Type	Description
`llm.default_soft_limit_tokens`	number	Default context soft-limit override for the bot, in tokens. When it exceeds the hard limit of the bot’s default-tier model, Genesis clamps the applied value unless the same write acknowledges the override.
`llm.default_soft_limit_acknowledge_exceeds_hard`	boolean	Safety cover for the bot default soft limit. When `true`, Genesis honors an above-hard-limit value, capped at `2,000,000` tokens. The acknowledgement is cleared when the soft limit is set without it, and when the bot’s default provider or tier changes.

When a PUT includes llm.default_soft_limit_tokens, its response data adds requested_soft_limit_tokens, applied_soft_limit_tokens, clamped, clamp_reason, acknowledged_exceeds_hard_limit, hard_limit_resolved, hard_limit_tokens, hard_limit_source, and hard_limit_model_name. An unacknowledged value above the resolved hard limit is persisted as requested but reported as clamped, with the applied value set to that hard limit. Resend the value with llm.default_soft_limit_acknowledge_exceeds_hard: true to override that comparison. If the hard limit cannot be resolved, Genesis does not clamp; hard_limit_resolved is false so clients can distinguish an unchecked value from one that passed comparison. GET /api/bots/{bot_id}/settings exposes the same status under data.soft_limit_status, allowing clients to keep showing a clamp or acknowledged override after a reload. The status is null when the bot has no soft-limit override.

Status	Meaning
`200`	Settings were read, written, listed, or cleared successfully.
`400`	The bot-setting request failed validation or another settings operation failed.
`403`	The caller lacks `manage_agents` or another permission required by the setting.
`409`	`error_type` `protected_core_agent` when the target agent’s definition is version-owned.

Chat thread list endpoint

Thread metadata is scoped to agents registered in the database. Cross-agent thread scans (search, retention archival, ownership resolution) enumerate active bots from BOT_SERVICING rather than inferring agents from storage directories on disk. At server startup, Genesis preloads a thread-metadata cache for each registered bot so first requests do not pay a cold-load penalty. Orphan storage directories without a matching bot row are not indexed. This route is mounted under /api/bots/{bot_id}/threads.

Method	Path	Description	Auth behavior
`GET`	`/api/bots/{bot_id}/threads`	List threads for one agent, with optional hidden-thread, handoff-thread, search, owner, and pagination filters.	Requires agent access. In auth-enabled deployments, visibility, ownership, and sharing filters still apply before results are returned.
`POST`	`/api/bots/{bot_id}/threads`	Create a new thread for the agent.	Requires agent access. The authenticated user becomes the thread owner when auth is enabled.

`POST /api/bots/{bot_id}/threads`

Field	In	Type	Default	Required	Description
`bot_id`	path	string	none	Yes	Agent identifier.
`thread_id`	body	string or null	`null`	No	Optional caller-provided thread id. When omitted, Genesis generates one. Hosted MCP v2 commonly uses ids with the `mcp_` prefix. Leading and trailing whitespace is stripped; an empty string is treated as omitted.
`working_context`	body	object or null	`null`	No	Optional repository, folder, and connection selections to validate and save on the new thread. See Working context endpoints.
`title`	body	string or null	`null`	No	Optional caller-provided thread title, up to 200 characters. Leading and trailing whitespace is stripped; an empty string is treated as omitted. When provided, the thread is created without the runtime `!thread_info` turn, so the request returns after the owner, context, and title are saved. Callers that do not yet have a title can send `New Chat`; the auto-titler replaces it after the first exchange. A titled thread cannot be combined with `blueprint_name`.

The response includes thread_id and an initial title. Without title, thread creation opens through the runtime !thread_info turn and clients that open the thread immediately may also receive an assistant welcome message derived from the bot’s bot_intro. With title, no agent turn or LLM call is made during creation; the runtime loads the stored thread when its first agent turn runs.

`GET /api/bots/{bot_id}/threads`

Field	In	Type	Default	Required	Description
`bot_id`	path	string	none	Yes	Agent identifier for the thread-list route.
`thread_title`	query	string or null	`null`	No	Filter threads by title using a partial, case-insensitive match.
`include_hidden`	query	boolean	`true`	No	Whether to include hidden/system threads.
`include_handoff_threads`	query	boolean	`true`	No	Whether to include threads that Genesis would normally omit from the default sidebar list. Set `false` to suppress internal worker threads, legacy handoff/delegation threads, and other threads whose resolved `show_in_thread_list` is `false`.
`search`	query	string or null	`null`	No	Search term to match thread content.
`my_threads_only`	query	boolean	`false`	No	When `true`, only return threads owned by the current user.
`filter_owner_ids`	query	`string[]` or null	`null`	No	Optional admin filter that keeps only threads owned by the listed user IDs after visibility checks.
`mcp_origin_only`	query	boolean	`false`	No	When `true`, keep only threads opened by the MCP connector: metadata with `mcp_origin` set to a truthy value, `source` equal to `mcp_v2`, or an `mcp_interactive_thread_state` object. The filter is applied before pagination.
`offset`	query	integer	`0`	No	Number of threads to skip before returning results. Minimum `0`.
`limit`	query	integer or null	`null`	No	Maximum number of threads to return. Allowed range: `1` to `500`.

When auth.enabled is true, the send path also repairs legacy threads whose stored owner_id is system_default_user: the first authenticated non-system caller who resumes the thread becomes the stored owner. After that repair, my_threads_only, GET /api/bots/{bot_id}/threads/{thread_id}/share-info, and owner-scoped thread mutations reflect the repaired owner. When auth.enabled is false, Genesis continues to use system_default_user as the canonical owner.

First-party thread sidebars typically call this route with include_hidden=false. To mirror Genesis’s default sidebar behavior, they can also pass include_handoff_threads=false, which excludes threads whose resolved show_in_thread_list value is false.

When mcp_origin_only=true, Genesis sorts the matching threads by the same stored display timestamp used for each returned row before applying offset and limit. Threads without a stored display timestamp are listed last. This lets the hosted MCP connector page through MCP-opened threads consistently across agents. Returned data[] items include show_in_thread_list (boolean), which tells clients whether Genesis intends that thread to appear in the default sidebar list. Legacy handoff/delegation threads without an explicit stored flag resolve to false for backward compatibility. MCP ask_agent chat items also include mcp_work_thread_id (string or null). For an MCP chat, this is the caller’s work-thread ID, which clients can use to group the chat under its originating work thread in a sidebar. It is unset for other threads and is not parent_thread_id; it does not change the runtime’s parent-thread behavior. Each data[] item’s timestamp field drives sidebar sorting and the “last active” label in first-party clients. Genesis resolves it using this priority chain:

imported_display_timestamp from thread metadata — archived imports (for example, conversations uploaded by the chats-sync daemon) pin the conversation’s true historical date here; it wins over newer last_activity values stamped during import.
last_activity from thread metadata.
timestamp from thread metadata.
Timestamp embedded in thread_id (for example, chat_1234567890_...).
Persisted thread-service props (last_activity, timestamp, or created_at).
Plist file modification time.
Current server time as last resort.

Returned values are ISO-8601 strings with millisecond precision and a Z suffix. Thread search results expose the same resolved value in last_activity. thread_new WebSocket events use the same first three metadata keys (imported_display_timestamp, last_activity, timestamp) so a client that inserts a new sidebar row from the socket shows the same date the thread list would return without a reload.

Chat thread import endpoints

These routes are mounted under /api/bots/{bot_id}/threads/... and restore a thread from an exported package. Prefer import-zip for full ZIP exports that include thread.json, message_log.csv, and file attachments; use import only for legacy JSON-only payloads.

Method	Path	Description	Auth behavior
`POST`	`/api/bots/{bot_id}/threads/import-zip`	Import a complete thread ZIP export with smart file reuse or cross-server file import.	Requires agent access. When auth is enabled, Genesis assigns thread ownership to the verified authenticated caller — not to any identity asserted inside the uploaded bundle.
`POST`	`/api/bots/{bot_id}/threads/import`	Import thread data from exported JSON (backwards compatibility).	Same ownership rules as `import-zip`. Does not restore file attachments; use `import-zip` for ZIP exports.

Genesis derives import identity from the cryptographically verified Bearer token on the request (PAT, primary Auth0/OIDC token, or a JWT from an entry in auth.additional_issuers). Values inside the uploaded export — including per-message primary_user in message_log.csv — are never trusted for ownership or access control.A token from an identity_source: email issuer (the OAuth-proxy identity broker) resolves only to an existing user of the deployment’s configured login provider (auth.provider), matched by the token’s verified email — never to users minted by other channels such as Slack. If no such user exists, the request is refused with 403 rather than creating an account: log into the deployment’s web UI once, then retry.During message_log.csv import, Genesis writes each row’s primary_user in MESSAGE_LOG as the verified importer’s identity ({"user_id": "<importer>"}, or null when the request has no authenticated user) and preserves the source CSV value only as display-only provenance in message_metadata.imported_thread_author. That field records who the exported thread said wrote the message; it is not a Genesis user identity and must not be used for authorization.Any sender_provenance value supplied inside an imported thread is removed; imports cannot claim that a message was sent by a verified customer. Imported rows therefore report unrecorded; messages subsequently sent through a server send path receive a new stamp based on that send path.

When the imported thread.json (inside a ZIP or passed as thread_data) includes metadata.source_timestamp, Genesis treats it as the conversation’s true historical date. During materialization Genesis persists it as imported_display_timestamp, which takes priority over last_activity when resolving the sidebar timestamp on GET /api/bots/{bot_id}/threads. Automatic archive importers such as the chats-sync daemon set metadata.source_timestamp so imported threads appear at their original date instead of import time. Manual imports that omit metadata.source_timestamp use the import-time clock and sort to the top of the sidebar like a newly created thread.

`POST /api/bots/{bot_id}/threads/import-zip`

Send the raw ZIP bytes as the request body with Content-Type: application/zip (or application/octet-stream).

Field	In	Type	Default	Required	Description
`bot_id`	path	string	none	Yes	Agent identifier.
`handle_conflict`	query	string	`rename`	No	Conflict policy when the imported `thread_id` already exists. Allowed values: `error`, `rename`, `replace`, `update`.
`new_thread_id`	query	string or null	`null`	No	Custom thread id to use when `handle_conflict=rename`.

When the ZIP contains query_results/results.json, Genesis restores each bundled query result under its original query_id so query-result:// embeds in the imported thread still resolve. Rows whose query_id already exists on the target server are skipped, so re-import stays idempotent. Invalid or oversized payloads are skipped with warnings rather than aborting the whole import.

`POST /api/bots/{bot_id}/threads/import`

Field	In	Type	Default	Required	Description
`bot_id`	path	string	none	Yes	Agent identifier.
`thread_data`	body	object	none	Yes	Exported thread JSON (same shape as `thread.json` in a ZIP export).
`options.handle_conflict`	body	string	`error`	No	Conflict policy when the imported `thread_id` already exists. Allowed values: `error`, `rename`, `replace`, `update`.
`options.new_thread_id`	body	string or null	`null`	No	Custom thread id to use when `handle_conflict=rename`.
`options.preserve_ownership`	body	boolean	`false`	No	Reserved for future use; Genesis currently always assigns ownership to the authenticated importer.

handle_conflict=update continues an existing exported thread in place by appending only messages that are not already stored. Genesis deduplicates using stable message ids: message_id on each thread.json message (also mirrored as metadata.input_uuid) and input_uuid or message_id inside each message_log.csv row’s message_metadata JSON.input_uuid is also how a streamed reply joins its stored rows. Every chat turn has one: the sender’s id when it supplied one, otherwise an id of the form msg_<32 hex> minted when the turn starts. It is the message_id of every message_response_delta WebSocket frame streamed for the turn, the message_id of the turn’s User Prompt row in the thread messages API, and metadata.input_uuid on the turn’s assistant rows. The integer MESSAGE_LOG.message_id column is a storage key only and never appears in a streamed frame.Update mode requires thread ownership (same as replace). Genesis returns 400 when:

The remote thread has diverged — it contains messages absent from the import (likely continued inside Genesis). Use replace to overwrite or rename to import as a new thread.
The existing thread has messages but none expose stable ids (incremental update is not possible). Use replace or rename.

When every message in the import is already present, the request still succeeds with messages_imported: 0 (a valid no-op). Warnings may note how many new messages were appended.Messages appended by an update import are available in the prompt for the next chat turn on that thread.Every import path sets the thread title from user_title, falling back to ai_title and then Imported Thread when those fields are empty. This also updates the title when handle_conflict=update continues an existing thread. If the title update fails after the messages are stored, the import still succeeds and reports the failure in warnings.

Both import routes return ThreadImportResponse with success, thread_id, original_thread_id, renamed, messages_imported, title, and warnings.

Status	Meaning
`200`	Import completed successfully.
`400`	Validation failed or import could not complete (response `detail` carries the error).
`403`	Caller lacks agent access.
`401`	Auth is enabled and the Bearer token was missing, invalid, or from an untrusted issuer.

Chat thread access endpoints

These routes are mounted under /api/bots/{bot_id}/threads/{thread_id}/....

All routes below require access to the target agent. When auth.enabled is true, export, fork, and GET /api/bots/{bot_id}/threads/{thread_id}/access follow the standard thread-access check rather than an owner-only check, so public threads, invited threads, callers with view_all_threads, callers who share a role with the owner where that shared role includes view_shared_role_resources, and legacy/system threads whose owner_id is null or system_default_user remain readable. Shared-role visibility widens only this standard access path; routes below that require ownership or manage_all_threads keep those stricter checks. In the auth behavior notes below, references to the thread owner, ownership, or a caller who owns the thread also include this legacy/system-thread fallback for backward compatibility on most thread mutations, including hide, unhide, delete, and access-list updates.

The same thread-access check also applies to thread-scoped message routes under this path prefix: GET /messages, POST /messages, POST /messages/sync, POST /messages/websocket, GET /messages/{message_id}/response, GET /messages/{message_id}/response/delta, and GET /messages/{message_id}/provider-request-export. In auth-enabled deployments, callers must be allowed to access the target thread before sending or polling messages. The same access check also applies to POST /api/bots/{bot_id}/threads/{thread_id}/profile-pre-llm, which profiles live prompt assembly without sending a model request.

In demo mode, when aggregate spend has reached demo.token_budget_usd, POST /messages, POST /messages/sync, and POST /messages/websocket return HTTP 402 Payment Required with error_type = "payment_required" before accepting the turn. The response includes a details object with spent_usd, cap_usd, and cta_url (from demo.sales_url). Outside demo mode, when the cap is unset (null), or when demo.allow_unlimited_budget is true, these routes do not apply this preflight.

For the default GET /api/bots/{bot_id}/threads/{thread_id}/messages path (source=message_cache, which is also used when source is omitted), Genesis can coalesce concurrent reads that use the same bot_id, thread_id, limit, before_timestamp, and include_tool_calls values. This applies to active threads as well, so identical concurrent polls can share one in-flight read instead of triggering duplicate backend work. Genesis also refreshes volatile thread metadata on the returned payload before sending it back, so fields such as title, checklist, assistant_mode, model_tier, model_provider, execution_lane, and is_active stay current even when the underlying message list came from a cached snapshot. Metadata-only updates do not invalidate that cached message list; Genesis rebuilds it only when message content changes or history compression rewrites the thread. Each message also includes the sender_provenance field described below.

On the default source=message_cache path, Genesis strips internal auth/session metadata keys such as _sf_caller_token, _user_context, and _sf_user_info before returning messages[*].metadata. For messages imported from a thread export, metadata.imported_thread_author may be present as display-only provenance copied from the source export’s primary_user column; it is not a Genesis identity and is not used for access control.

For a User Prompt message, sender_provenance identifies which credential sent the message. It is one of customer, agent, delegated, unverified, or unrecorded; customer is the only value that means a verified human customer. agent identifies a server-internal agent channel, delegated identifies a credential acting on a person’s behalf (such as a PAT, app token, sandbox token, machine token, or prompt sent for another user), unverified means no verified person was established, and unrecorded means the server has no recognized stamp (for example, a legacy row). For assistant and other non-user message types, the field is null.REST message sends never classify as customer: even a verified person’s token used through the programmatic REST door is recorded as unverified. WebSocket sends are classified from the authenticated context, or from a server-internal sender classification. Clients cannot set this field through message_metadata. When a stamped prompt waits for an agent slot, Genesis preserves its sender stamp when resubmitting it instead of classifying the resubmission as a new send. If no stamp was supplied, the send path classifies it afresh.

For newly created client-side thread IDs that are still materializing on the backend, GET /api/bots/{bot_id}/threads/{thread_id}/messages can return model_tier: "" instead of defaulting that field to main. Treat the empty string as “no explicit thread tier has been persisted yet.” Once Genesis finishes creating the backend thread record, the response resolves the effective tier normally.

When thread or message payloads include file or artifact links, Genesis returns root-relative URLs on the current Genesis origin. Standalone and local deployments normally prefix these links with /api, while SPCS omits that prefix. Use returned paths as-is. Git-backed attachments resolve through /api/git/... or /git/..., file-manager attachments through /api/files/... or /files/..., and artifact downloads through /api/artifacts/... or /artifacts/.... Git-backed url and download_url fields may also include an optional v={mtime_ns}-{size} query parameter so clients fetch the current file bytes after a same-path overwrite; combine it with download=true when both are present.

Method	Path	Description	Auth behavior
`POST`	`/api/bots/{bot_id}/threads/{thread_id}/export`	Export a thread as Markdown, PDF, or ZIP.	Requires agent access. When auth is enabled, the caller must also have access to the source thread.
`GET`	`/api/bots/{bot_id}/threads/{thread_id}/title`	Return the current thread title.	Requires agent access. In auth-enabled deployments, direct title lookup only unhides the thread when the caller owns it.
`GET`	`/api/bots/{bot_id}/threads/{thread_id}/share-info`	Return the thread owner, visibility, and share URL metadata.	Requires agent access plus access to the thread. Callers who can already view a private thread can read this metadata without owning the thread.
`POST`	`/api/bots/{bot_id}/threads/{thread_id}/fork`	Create a forked copy of a thread.	Requires agent access. When auth is enabled, the caller must also have access to the source thread.
`GET`	`/api/bots/{bot_id}/threads/{thread_id}/fork-info`	Return fork lineage metadata for a thread created via fork.	Requires agent access plus access to the thread. Returns `data: null` when the thread was not forked or the source thread is not visible.
`PUT`	`/api/bots/{bot_id}/threads/{thread_id}/hide`	Hide a thread without deleting it. The thread remains accessible by direct link.	Requires agent access. When auth is enabled, the thread owner or a caller with `manage_all_threads` can hide the thread.
`PUT`	`/api/bots/{bot_id}/threads/{thread_id}/unhide`	Clear the hidden flag for a thread.	Requires agent access. When auth is enabled, the thread owner or a caller with `manage_all_threads` can unhide the thread.
`DELETE`	`/api/bots/{bot_id}/threads/{thread_id}`	Delete a thread from thread storage and metadata.	Requires agent access. When auth is enabled, the thread owner or a caller with `manage_all_threads` can delete the thread.
`POST`	`/api/bots/{bot_id}/threads/{thread_id}/force-reset`	Clear stuck in-memory thread state, cancel queued async work, and stop shared streams without deleting the thread or its messages.	Requires agent access. When auth is enabled, the caller must also own the thread, including the legacy/system-thread fallback described above.
`POST`	`/api/bots/{bot_id}/threads/{thread_id}/profile-pre-llm`	Profile pre-LLM prompt preparation on a loaded live thread without calling the LLM.	Requires agent access plus access to the thread. The target bot session must also be loaded in memory.
`GET`	`/api/bots/{bot_id}/threads/{thread_id}/messages/{message_id}/provider-request-export`	Generate a sanitized provider request export for one chat turn.	Requires agent access plus access to the thread.
`GET`	`/api/bots/{bot_id}/threads/{thread_id}/activity`	Return the thread’s live activity state, including active completion or tool-call details.	Requires agent access. In auth-enabled deployments, activity details follow normal thread-visibility filtering.
`POST`	`/api/bots/{bot_id}/threads/{thread_id}/background-work/dismiss`	Hide selected or all listed background work from the thread card without stopping it.	Requires agent access. In auth-enabled deployments, only callers who can see the thread can change the list.
`GET`	`/api/bots/{bot_id}/threads/{thread_id}/model-tier`	Return the thread’s current model tier, resolved provider, execution lane, soft-limit metadata, and the model that served its last assistant reply.	Requires agent access.
`PUT`	`/api/bots/{bot_id}/threads/{thread_id}/model-tier`	Update the thread’s model tier and optional provider, execution lane, or soft-limit overrides.	Requires agent access. Update attempts also validate access to the target thread.
`GET`	`/api/bots/{bot_id}/threads/{thread_id}/access`	Return the owner, invited users, and invited roles for a thread.	Requires agent access plus access to the thread.
`PUT`	`/api/bots/{bot_id}/threads/{thread_id}/access`	Replace the full thread access list.	Requires agent access. When auth is enabled, ownership or `manage_all_threads` is required.
`POST`	`/api/bots/{bot_id}/threads/{thread_id}/access/invite`	Add users and roles to a thread’s access list.	Requires agent access. When auth is enabled, ownership or `manage_all_threads` is required.
`POST`	`/api/bots/{bot_id}/threads/{thread_id}/access/remove`	Remove users and roles from a thread’s access list.	Requires agent access. When auth is enabled, ownership or `manage_all_threads` is required.
`GET`	`/api/bots/{bot_id}/working-context-options`	Return the caller’s usable, role-scoped connection choices and default working context for the agent.	Requires agent access. The response contains identifiers and role hints, never credential values.
`GET`	`/api/bots/{bot_id}/threads/{thread_id}/working-context`	Return the saved working context for a thread.	Requires agent access and ownership of the target thread, including the existing system-thread fallback.
`PUT`	`/api/bots/{bot_id}/threads/{thread_id}/working-context`	Validate and replace the saved working context for a thread.	Requires agent access and ownership of the target thread, including the existing system-thread fallback.

Working context endpoints

Working context contains explicit, non-secret selections for a thread’s working location and connections. It grants no additional access; every update is validated against the caller’s current connection grants and repository access.

`GET /api/bots/{bot_id}/working-context-options`

The response is a WorkingContextOptions object:

Field	Type	Description
`connections`	object[]	Usable connection choices. Each item has `id` (string, the canonical `type.name` identifier) and `from_role` (boolean, whether a role grant supplies the choice).
`default_context`	object	Initial selection. It contains `repo_id` (string or null), `folder` (string), and `connections` (string array). Connections supplied by role grants are selected by default.

The connection catalog is scoped to the authenticated caller and agent. The catalog query is cached by the web client for 60 seconds while it is current.

`GET /api/bots/{bot_id}/threads/{thread_id}/working-context`

Returns the saved working-context object or null when the thread has no saved selection. The object has these fields:

Field	Type	Default	Description
`repo_id`	string or null	`null`	Repository identifier.
`folder`	string	`""`	Folder path within `repo_id`; a non-empty folder requires a repository.
`connections`	string[]	`[]`	Canonical connection identifiers to use for the thread. Duplicate identifiers are removed during validation.

`PUT /api/bots/{bot_id}/threads/{thread_id}/working-context`

Send the complete working-context object. The server validates that selected connections are still available, that the caller can view the repository, and that the folder exists inside that repository. Repository and folder values cannot target Git internals or traverse outside the repository. A successful response returns the validated and persisted object.

Field	In	Type	Default	Required	Description
`repo_id`	body	string or null	`null`	No	Repository identifier. Reserved values such as `default` and `uploads` are rejected.
`folder`	body	string	`""`	No	Existing folder path within `repo_id`.
`connections`	body	string[]	`[]`	No	Available canonical connection identifiers, such as `snowflake.analytics`.

Status	Meaning
`200`	Options were returned, or the thread working context was read or saved successfully.
`400`	The working context is malformed, uses an invalid folder or connection identifier, or names a folder that does not exist.
`403`	The caller lacks agent/thread access, repository access, or access to one of the selected connections.
`404`	The target thread does not exist for the given bot.

Shared thread path parameters

Field	In	Type	Default	Required	Description
`bot_id`	path	string	none	Yes	Agent identifier for the thread route.
`thread_id`	path	string	none	Yes	Thread identifier to export, inspect, mutate, or manage access for.

`POST /api/bots/{bot_id}/threads/{thread_id}/export`

Field	In	Type	Default	Required	Description
`format`	query	string	`zip`	No	Export format. Allowed values: `md`, `pdf`, `zip`.
`include_files`	query	boolean	`true`	No	Include file attachments and artifacts in the export.
`include_tool_calls`	query	boolean	`false`	No	Include `tool_calls` arrays and tool messages in the export.
`include_pdf`	query	boolean	`true`	No	Include a PDF version in ZIP exports.
`include_query_results`	query	boolean or null	`null`	No	Bundle cached query results into ZIP exports as `query_results/results.json` so `query-result://` embeds still resolve after cross-server import. When omitted (`null`), Genesis follows the `threads.export_include_query_results` config value (default: `true`). Pass `false` to omit query results. Always omitted when the export is scrubbed for support bundles.
`bug_report`	body	string or null	`null`	No	Optional Markdown bug report to bundle into ZIP exports. Send it as the top-level `bug_report` field in the JSON body.

Header	Type	When present	Description
`Content-Disposition`	`string`	`200`	Attachment disposition with ASCII `filename="..."` and UTF-8 `filename*=UTF-8''...` parameters. See Export download responses.

Status	Meaning
`200`	Binary file download with `text/markdown`, `application/pdf`, or `application/zip`.
`403`	Caller does not have access to the target thread.
`404`	Thread was not found.
`501`	PDF export is unavailable in this deployment because it does not include a browser.
`500`	Export failed on the server.

`PUT /api/bots/{bot_id}/threads/{thread_id}/title`

Field	In	Type	Default	Required	Description
`title`	body	string	none	Yes	New thread title. The request schema accepts 1-500 characters.

It returns these top-level fields:

Field	Type	Description
`success`	boolean	Whether the rename request completed successfully.
`title`	string	Persisted thread title after the rename succeeds.

Status	Meaning
`200`	Returns `RenameThreadResponse` with `success=true` and the updated `title`.
`400`	Title validation failed.
`403`	Caller does not have access to the target agent or auth-enabled thread ownership checks rejected the rename.
`404`	Thread not found for the given bot.
`503`	Another thread-scoped write or compression pass is still holding the title-update path; retry the same request shortly.
`500`	Unexpected server error while renaming the thread.

`POST /api/bots/{bot_id}/threads/{thread_id}/fork`

Field	In	Type	Default	Required	Description
`title`	body	string or null	`null`	No	Optional title override for the forked thread.
`end_index`	body	integer or null	`null`	No	Copy only messages up to and including this 0-based index. Minimum `0`. Ignored when `end_node_id` is provided.
`end_message_id`	body	string or null	`null`	No	Optional message identifier that marks the last message to copy. Overrides `end_index` when both are provided. Ignored when `end_node_id` is provided.
`end_node_id`	body	string or null	`null`	No	Stable plist node id of the last message to copy (inclusive). Preferred over `end_index` and `end_message_id` because node ids are immune to compression-induced index drift. Overrides both when provided.

It returns these top-level fields:

Field	Type	Description
`success`	boolean	Whether the fork completed successfully.
`thread_id`	string	New forked thread identifier.
`title`	string	Forked thread title.
`estimated_context_tokens`	integer or null	Approximate LLM-visible tokens carried into the fork.
`source_context_tokens`	integer or null	Approximate LLM-visible tokens of the full source thread.

Status	Meaning
`200`	Fork completed and returns the new thread id and title.
`400`	Validation failed — for example `end_index` is negative, or `end_node_id` no longer exists in the source thread (refresh the thread and retry).
`403`	Caller does not have access to the target agent or source thread.
`404`	Source thread not found.
`500`	Unexpected server error while forking.

`GET /api/bots/{bot_id}/threads/{thread_id}/fork-info`

Returns fork lineage breadcrumbs when the thread was created via POST .../fork. Otherwise returns success: true with data: null.

Field	In	Type	Default	Required	Description
`bot_id`	path	string	none	Yes	Agent identifier.
`thread_id`	path	string	none	Yes	Forked thread identifier.

data object fields when present:

Field	Type	Description
`forked_from_thread_id`	string	Source thread the fork was copied from.
`forked_from_thread_title`	string or null	Display title of the source thread when visible.
`forked_from_node_id`	string or null	Plist node id of the branch-point message when the fork used `end_node_id`.
`forked_at`	string or null	ISO timestamp when the fork was created.
`fork_point_preview`	string or null	Short preview of the branch-point user or assistant text.

Status	Meaning
`200`	Returns fork lineage or `data: null` for non-forked threads.
`403`	Caller does not have access to the target agent or thread.
`500`	Unexpected server error while loading fork metadata.

`DELETE /api/bots/{bot_id}/threads/{thread_id}`

Field	In	Type	Default	Required	Description
`purge_message_log`	query	boolean	`false`	No	When `true`, hard-delete `MESSAGE_LOG` rows. When `false`, redact `MESSAGE_LOG` payloads while retaining audit records.

This endpoint also supports SQLAlchemy-backed metadata storage, including the Databricks App deployment.

`POST /api/bots/{bot_id}/threads/{thread_id}/force-reset`

This endpoint does not document any request body fields. Besides clearing in-memory thread markers, Genesis also attempts to cancel queued async prompt work and stop any shared streams for the thread. When state is cleared, Genesis also emits the standard terminal realtime events for the thread so subscribers can recover from a stuck loading or streaming state. It returns these top-level fields:

Field	Type	Description
`success`	boolean	Whether the reset request completed successfully.
`thread_id`	string	Thread identifier that was checked.
`cleared_flags`	string[]	Names of the thread-state markers that Genesis cleared, such as `async_pending`, `shared_streams`, `active_completion`, `active_tool`, `is_active`, `handoff_in_progress`, `processing_message_id`, or `interrupt_event`. When Genesis successfully emits the terminal realtime signals after a reset, this array also includes `terminal_notification`.
`message`	string	Human-readable result summary. Returns `Thread state has been force-reset` when state was cleared, or `Thread was not stuck` when no active state remained.

Status	Meaning
`200`	Reset request completed and returns the cleared-state summary.
`403`	Caller does not have access to the target agent, or auth-enabled ownership checks rejected the reset.
`404`	Thread not found for the given bot.
`500`	Unexpected server error while clearing thread state.

`POST /api/bots/{bot_id}/threads/{thread_id}/profile-pre-llm`

Profile live pre-LLM prompt preparation on the loaded thread without calling the model. Genesis clones the thread state, optionally runs one warm-up pass, then measures only prompt-build stages.

Field	In	Type	Default	Required	Description
`repeats`	body	integer	`3`	No	Number of measured trials. Minimum `1`, maximum `10`.
`execution_lane`	body	string	`async`	No	Simulated prompt dispatch lane during prompt preparation. The `express` lane is no longer available.
`append_input_message`	body	boolean	`false`	No	When `true`, Genesis includes `message_text` as a synthetic next user turn before profiling.
`message_text`	body	string	`profile-pre-llm`	No	Probe text used when `append_input_message=true`. Blank or whitespace-only values normalize back to the default.
`warm_caches`	body	boolean	`true`	No	When `true`, Genesis performs one unreported warm-up pass before the measured trials.

It returns these top-level fields:

Field	Type	Description
`ok`	boolean	Whether the profiling request completed successfully.
`bot_id`	string	Agent identifier used for the profile run.
`thread_id`	string	Thread identifier that was profiled.
`execution_lane`	string	Lane simulated during prompt preparation.
`append_input_message`	boolean	Whether Genesis included a synthetic next user turn while profiling.
`message_text`	string	Echoed probe text when `append_input_message=true`; otherwise an empty string.
`warm_caches`	boolean	Whether Genesis performed the unreported warm-up pass before measuring.
`trial_count`	integer	Number of measured trials returned in `trials`. The optional warm-up pass is not counted here.
`trials`	`object[]`	Per-trial timing and size details.
`summary`	object	Aggregate summary stats for `update_llm_messages_ms`, `append_system_context_ms`, `build_runtime_request_snapshot_ms`, and `total_prep_ms`.

`trial` item fields

Field	Type	Description
`trial_index`	integer	One-based trial number.
`timings_ms`	object	Millisecond timings for the measured pre-LLM stages.
`llm_messages_count`	integer	Count of LLM messages produced before the model call.
`payload_bytes`	integer	UTF-8 byte size of the prepared LLM messages payload.
`system_chars`	integer	Total characters contributed by `system` messages.
`runtime_context_chars`	integer	Characters in the runtime-injected context block.
`request_estimated_tokens`	integer	Estimated request token count from the built runtime snapshot.
`cache_flags`	object	Cache-hit flags captured during prompt preparation.

`timings_ms` and per-metric `summary` fields

summary repeats the same shape for update_llm_messages_ms, append_system_context_ms, build_runtime_request_snapshot_ms, and total_prep_ms.

Field	Type	Description
`count`	integer	Number of measured values included for the metric.
`min`	float or `null`	Minimum measured value in milliseconds.
`p50`	float or `null`	Median measured value in milliseconds.
`avg`	float or `null`	Arithmetic mean in milliseconds.
`max`	float or `null`	Maximum measured value in milliseconds.

`cache_flags` fields

Field	Type	Description
`system_context_cache_hit`	boolean or `null`	Whether the system-context cache was hit for the trial.
`request_component_cache_hit`	boolean or `null`	Whether request-component caching was used for the trial.
`llm_turn_cache_hit`	boolean or `null`	Whether turn-level LLM message caching was used for the trial.
`llm_messages_rebuild_skipped`	boolean or `null`	Whether Genesis skipped rebuilding `llm_messages` for the trial.

Status	Meaning
`200`	Returns the profiling payload with `ok=true`, `trials`, and `summary`.
`403`	Caller does not have access to the target agent or thread.
`404`	The thread or live bot session is not available for profiling.
`422`	Request body validation failed.
`500`	Unexpected server error while building the profile.

`GET /api/bots/{bot_id}/threads/{thread_id}/messages/{message_id}/provider-request-export`

Generate a sanitized provider request export for the selected turn. Genesis reconstructs the payload from stored thread history instead of replaying a captured upstream HTTP request, so data.simulated is always true.

Field	In	Type	Default	Required	Description
`message_id`	path	string	none	Yes	Message identifier for the turn to export. Genesis slices the exported conversation through this turn. If the identifier no longer matches a stored message, Genesis falls back to the latest user turn in the thread.

Genesis resolves the provider, model, and endpoint from stored message metadata, thread properties, current model assignments, and provider defaults. Returned endpoint_url values are sanitized and never include embedded credentials. When Genesis cannot infer a concrete chat-completions endpoint, the generated curl falls back to https://<AI_PROVIDER_BASE_URL>/chat/completions. When Anthropic-style prompt caching applies, Genesis preserves cache_control markers on the exported messages[*].content[] blocks so replaying the JSON keeps the same cache intent. In checkpoint mode with the default rolling anchor, the deep breakpoint sits on stable history behind the volatile newest user turn (which carries per-turn date/time context). It returns these top-level fields:

Field	Type	Description
`success`	boolean	Whether the provider request export was generated successfully.
`data.bot_id`	string	Agent identifier used to build the export.
`data.thread_id`	string	Thread identifier used to build the export.
`data.message_id`	string	Message identifier requested for the export.
`data.provider`	string	Resolved provider name, or `thread_provider` if Genesis could not infer one.
`data.model`	string	Resolved model name, or a placeholder such as `<THREAD_PROVIDER_MODEL>` when Genesis cannot infer one.
`data.endpoint_url`	string or `null`	Sanitized provider endpoint used in the export when Genesis can infer one.
`data.request_json`	object	Sanitized request body ready to inspect, copy, or replay.
`data.curl`	string	Copyable `curl` command built from `data.endpoint_url` and `data.request_json`.
`data.generated_at`	float or `null`	Unix timestamp when Genesis generated the export.
`data.simulated`	boolean	Always `true`; Genesis generated the export from thread history rather than a captured wire request.

Status	Meaning
`200`	Returns `ProviderRequestExportResponse` with `success=true` and the generated export in `data`.
`403`	Caller does not have access to the target agent or thread.
`404`	The thread was not found or no thread messages are available to build the export.
`500`	Unexpected server error while generating the export.

`GET /api/bots/{bot_id}/threads/{thread_id}/activity`

This endpoint does not document any query parameters beyond the shared bot_id and thread_id path fields. It returns these top-level fields:

Field	Type	Description
`success`	boolean	Whether the activity lookup completed successfully.
`data.thread_id`	string	Thread identifier whose activity was inspected.
`data.state`	string	Current activity state: `idle`, `completion`, `compression`, or `tool_call`.
`data.state_duration_seconds`	float	Seconds spent in the current state.
`data.active_run_user_relation`	string	Whether the active run was started by the current request user: `self`, `other`, or `unknown`. Present on non-idle responses and defaults to `unknown` when idle or when Genesis cannot resolve the active completion owner (for example, auth-disabled `system_default_user` runs).
`data.active_completion`	object or null	Present when `data.state = "completion"`.
`data.active_tool_call`	object or null	Present when `data.state = "tool_call"`.
`data.active_tool_calls`	object[]	Present when `data.state = "tool_call"` and Genesis is tracking one or more in-flight tool calls.
`data.active_compression`	object or null	Present when `data.state = "compression"`.
`data.background_work`	object[]	Background work the idle thread is waiting on; empty while the thread is still working or the caller cannot see the thread.

`background_work` items

Each item describes one run the agent started and will be notified about when it finishes. Dismissing an item only removes it from the list; it does not stop the work or withdraw the agent’s completion notification.

Field	Type	Description
`run_id`	string	Run, job, or handle identifier.
`kind`	string	Description of the work, in the agent’s words.
`started_at`	float	Unix timestamp when the wake was armed.
`elapsed_seconds`	float	Seconds since the work started.
`finished`	boolean	Whether the work finished and its wake is on the way to the agent.

`active_completion` fields

Field	Type	Description
`message_id`	string	Message identifier Genesis is currently generating.
`status`	string	Completion status: `streaming`, `reconnecting` after a connection failure while an LLM call waits to be retried, or `rate_limit_wait` while provider capacity recovers.
`retry_at`	float or null	Unix timestamp of the next rate-limit retry.
`retry_attempt`	integer or null	One-based rate-limit retry attempt being awaited.
`started_at`	float	Unix timestamp when the completion state began.
`elapsed_seconds`	float	Seconds since the completion state began.
`llm_call_started_at`	float or null	Unix timestamp when the current in-flight LLM call started.
`llm_call_elapsed_seconds`	float	Seconds since the current in-flight LLM call started.
`model`	string or null	LLM model name in use when Genesis can resolve it.
`provider`	string or null	LLM provider name when Genesis can resolve it.
`model_tier`	string or null	Effective model tier such as `frontier`, `main`, or `fast`.
`last_activity_at`	float or null	Unix timestamp of the most recent completion chunk or activity update.

`active_tool_call` fields

Field	Type	Description
`tool_name`	string	Raw tool/function name currently executing.
`tool_call_id`	string or null	Canonical tool-call identifier when available.
`started_at`	float	Unix timestamp when the tool call started.
`elapsed_seconds`	float	Seconds since the tool call started.
`display_label`	string or null	Human-readable label for the running activity.
`activity_kind`	string or null	Normalized activity kind such as `query`, `file`, `agent`, or `tool`.
`data_source_name`	string or null	Underlying datasource or connector name when known.
`query_title`	string or null	Best-effort query title or preview for query-backed tool calls.

`active_compression` fields

Field	Type	Description
`status`	string	Compression status. Current runtime values use `running` while the pass is active.
`started_at`	float	Unix timestamp when compression started.
`elapsed_seconds`	float	Seconds since compression started.
`usage_before_pct`	float or null	Context usage percentage before compression began.
`strategy`	string or null	Compression strategy identifier when available.
`reduction_scope`	string or null	Compression scope identifier when available.
`reason`	string or null	Backend reason that triggered compression.
`phase`	string or null	Completion-loop phase when compression started.
`progress_message`	string or null	Human-readable progress detail for long-running compression.
`progress_pct`	float or null	Estimated compression progress percentage, normalized to `0-100` and rounded to one decimal place.
`progress_phase`	string or null	Machine-readable compression progress phase.
`work_done`	integer or null	Completed compression work units.
`work_total`	integer or null	Total estimated compression work units.
`summary_done`	integer or null	Completed LLM summary chunks.
`summary_total`	integer or null	Total LLM summary chunks.
`parallelism`	integer or null	Configured LLM summary concurrency for this compression.

Status	Meaning
`200`	Returns `ThreadActivityStatusResponse` with activity details and `data.background_work` as applicable.
`403`	Caller does not have access to the target agent.
`500`	Unexpected server error while resolving live thread activity.

`GET /api/bots/{bot_id}/threads/{thread_id}/goal`

Returns the goal attached to the thread, including its current status and verdict. The response is a top-level ThreadGoalResponse with success and goal fields; this endpoint has no additional query parameters.

Field	Type	Description
`verdict`	string or null	`pursuing`, `met`, `failed`, or `blocked`. A `blocked` goal can be revived by a person’s next turn or by the agent’s next declaration that marks no items blocked; `met` and `failed` are final.
`revival`	object or null	The blocked ending this goal was revived from. Null when there is no prior blocked ending.

When present, revival contains:

Field	Type	Description
`revived_by`	string	`person` when a person took a turn on the thread, or `agent` when the agent declared without marking an item blocked.
`revived_at_epoch`	number or null	Epoch second when the block was lifted.
`blocked_on`	string	Action required to lift the original blocked ending.
`blocked_reason`	string	Reason recorded with that ending.
`retracted_items`	string[]	Finish-line item IDs whose `blocked` status was reset to `unmet` during revival.

`POST /api/bots/{bot_id}/threads/{thread_id}/background-work/dismiss`

Hide background work from the thread’s waiting card for everyone who views the thread. The work continues running, and the agent is still notified when it finishes. The caller must have access to the agent and be able to see the thread; a caller who cannot see it receives an empty background_work list and does not change the list.

Field	In	Type	Default	Required	Description
`run_ids`	body	string[]	`[]`	No	Run IDs to hide. An empty or omitted list hides every currently listed run. Maximum 64 IDs.

The response returns success and data, containing thread_id and the remaining background_work items in the same shape as the activity endpoint.

Status	Meaning
`200`	Returns `DismissBackgroundWorkResponse` with the remaining visible work.
`403`	Caller does not have access to the target agent.
`422`	Request validation failed, including more than 64 run IDs.

`GET /api/bots/{bot_id}/threads/{thread_id}/model-tier`

This endpoint does not document any query parameters beyond the shared bot_id and thread_id path fields. It returns these top-level fields:

Field	Type	Description
`success`	boolean	Whether the lookup completed successfully.
`model_tier`	string	Effective thread model tier: `frontier`, `main`, or `fast`.
`provider`	string or `null`	Resolved provider currently in effect for the thread. When no explicit provider override is stored, Genesis can still return the provider from the most recent assistant-used model for that thread.
`execution_lane`	string	Current prompt dispatch lane, normally `async`; `legacy` indicates the synchronous fallback path.
`hard_limit_tokens`	integer or `null`	Hard context limit for the resolved model.
`soft_limit_ceiling_tokens`	integer or `null`	Runtime ceiling after environment and legacy soft-limit caps are applied.
`effective_soft_limit_tokens`	integer or `null`	Effective soft limit after thread, bot, and runtime clamping are resolved.
`soft_limit_override_tokens`	integer or `null`	Explicit thread soft-limit override when one is stored.
`acknowledged_exceeds_hard_limit`	boolean	Whether the thread has an acknowledged soft-limit override above the resolved hard limit.
`served_model_name`	string or `null`	Model that produced the thread’s last assistant reply; `null` before any reply.
`served_model_tier`	string or `null`	Tier the last assistant reply was served at (`frontier`, `main`, or `fast`); `null` before any reply.
`served_model_provider`	string or `null`	Provider that served the last assistant reply; `null` before any reply.
`error`	string or `null`	Error text when `success` is `false`.

Status	Meaning
`200`	Returns `ThreadModelTierResponse`.
`403`	Caller does not have access to the target agent.
`404`	Thread not found for the given bot.
`500`	Unexpected server error while resolving thread model-tier state.

`PUT /api/bots/{bot_id}/threads/{thread_id}/model-tier`

Field	In	Type	Default	Required	Description
`model_tier`	body	string	none	Yes	New thread tier. Allowed values: `frontier`, `main`, `fast`.
`provider`	body	string or `null`	`null`	No	Optional provider override. Include `null` to clear the stored override when you send this field.
`execution_lane`	body	string or `null`	`null`	No	Deprecated compatibility field. The `express` lane is no longer selectable; include `null` to clear the stored value when you send this field.
`soft_limit_tokens`	body	integer or `null`	`null`	No	Optional thread soft-limit override in tokens. Include `null` to clear the stored override when you send this field. Values above the resolved hard limit are clamped unless acknowledged.
`acknowledge_exceeds_hard_limit`	body	boolean	`false`	No	Safety cover for a `soft_limit_tokens` value above the resolved hard limit. When `true`, Genesis honors the override up to the acknowledged-override sanity cap; when `false`, Genesis clamps it and reports the clamp.

When a thread sets provider to openai while Azure OpenAI is the process-wide default, Genesis routes that turn through the public OpenAI API using saved OpenAI credentials instead of the Azure endpoint. The response reuses the same fields as GET /api/bots/{bot_id}/threads/{thread_id}/model-tier, and adds requested_soft_limit_tokens, applied_soft_limit_tokens, clamped, clamp_reason, and acknowledged_exceeds_hard_limit. These let clients distinguish a requested value from the value persisted after safety clamping and tell the operator why a clamp occurred. A successful acknowledged override is reported explicitly rather than closing silently in the UI. When model_tier changes, Genesis also advances the thread’s context-state cache epoch so the next turn rebuilds cached context metadata under the new tier without requiring a thread reset.

Status	Meaning
`200`	Returns `ThreadModelTierResponse`. Validation failures also return `200` with `success=false` and an `error` string.
`401`	Request was unauthenticated in an auth-enabled deployment.
`403`	Caller does not have access to the target agent or thread.
`404`	Thread not found for the given bot.
`500`	Unexpected server error while updating thread model-tier state.

This endpoint does not document any query parameters beyond the shared bot_id and thread_id path fields. It returns these top-level fields:

Field	Type	Description
`success`	boolean	Whether the lookup completed successfully.
`data.thread_id`	string	Thread identifier whose sharing metadata was inspected.
`data.visibility`	string	Current visibility value: `private` or `public`. When persisted metadata stores `visibility` as `null`, Genesis reports `private`.
`data.share_url`	string or `null`	Share URL when the thread is public. `null` for private threads.
`data.owner_id`	string	Thread owner identifier. When persisted metadata stores `owner_id` as `null`, Genesis reports `system_default_user` (the same default used for legacy/system threads).

Status	Meaning
`200`	Returns `ThreadShareInfoResponse`. Private-thread viewers who already have access to the thread can also read this metadata.
`403`	Caller does not have access to the target thread.
`404`	Thread not found for the given bot.
`500`	Unexpected server error while resolving thread share metadata.

Shared access-list body fields

Field	Used by	Type	Default	Description
`invited_users`	`PUT /api/bots/{bot_id}/threads/{thread_id}/access`	`string[]`	`[]`	Full replacement list of user IDs allowed to access the thread.
`invited_roles`	`PUT /api/bots/{bot_id}/threads/{thread_id}/access`	`string[]`	`[]`	Full replacement list of role names allowed to access the thread.
`users`	`POST /api/bots/{bot_id}/threads/{thread_id}/access/invite`, `POST /api/bots/{bot_id}/threads/{thread_id}/access/remove`	`string[]`	`[]`	User IDs to add to or remove from the thread access list.
`roles`	`POST /api/bots/{bot_id}/threads/{thread_id}/access/invite`, `POST /api/bots/{bot_id}/threads/{thread_id}/access/remove`	`string[]`	`[]`	Role names to add to or remove from the thread access list.

Debrief endpoints

These routes store and retrieve saved debriefs for chat threads, missions, and Blueprint Journey aggregates. Each debrief record tracks the latest version in current, while earlier versions remain available by version number.

Debrief routes require an authenticated caller. Thread debrief access follows the same thread-visibility rules as chat. Mission debrief access follows the linked mission thread when one exists; if a mission has no bot/thread anchor, Genesis falls back to owner-only access. Journey debriefs are owner-scoped (the chain was filtered for the generating user’s visibility), require agent access when bot_id is set, and also verify thread ownership on source_thread_id when present.

Method	Path	Description	Auth behavior
`POST`	`/api/debriefs`	Generate a thread, mission, or journey debrief, or regenerate the current one.	Requires an authenticated caller plus access to the source thread, mission, or journey root project.
`GET`	`/api/debriefs/{debrief_id}`	Return the current debrief record, including `current` version detail when present.	Requires access to the underlying thread, mission, or journey.
`GET`	`/api/debriefs/{debrief_id}/versions`	List saved versions for a debrief.	Requires access to the underlying thread, mission, or journey.
`GET`	`/api/debriefs/{debrief_id}/versions/{version_number}`	Return one saved debrief version by numeric version.	Requires access to the underlying thread, mission, or journey.
`DELETE`	`/api/debriefs/{debrief_id}`	Soft-delete a debrief record.	Requires access to the underlying thread, mission, or journey.
`GET`	`/api/threads/{thread_id}/debriefs`	List debrief records for one source thread.	Requires access to the target thread. `bot_id` query param is required.
`GET`	`/api/missions/{mission_id}/debriefs`	List debrief records for one source mission.	Requires access to the target mission. Returns mission-scoped debriefs (`source_kind="mission"`).

Shared debrief record fields

Field	Type	Description
`debrief_id`	string	Stable debrief identifier.
`title`	string	Current title shown for the debrief.
`source_kind`	string	`thread`, `mission`, or `journey`.
`source_thread_id`	string or null	Source thread when the debrief is tied to a thread, a mission thread, or a journey root thread.
`source_mission_id`	string or null	Source mission for mission debriefs, or the root project id for journey debriefs.
`bot_id`	string or null	Agent associated with the source thread when available.
`owner_id`	string or null	Owning user identifier when Genesis persists one.
`visibility`	string	Current visibility value. Current debriefs default to `private`.
`current_version`	integer	Latest saved version number.
`created_at`	string	ISO timestamp when the debrief was created.
`updated_at`	string	ISO timestamp when Genesis saved the latest version.
`deleted_at`	string or null	Soft-delete timestamp when the debrief has been deleted.
`current`	object or null	Expanded current version detail when Genesis includes it.

Shared current-version fields

current and GET /api/debriefs/{debrief_id}/versions/{version_number} return the same version-detail shape.

Field	Type	Description
`version_id`	string	Stable version identifier.
`debrief_id`	string	Parent debrief identifier.
`version_number`	integer	Numeric version in ascending save order.
`generation_method`	string	Generation mode such as `auto_summarize`, `agent_published`, `mission_baked`, `journey_baked`, or `journey_synthesized`.
`generated_by_kind`	string	`user`, `agent`, or `system`.
`generated_by_id`	string or null	Actor identifier when Genesis has one.
`model`	string or null	Model name recorded for LLM-generated debriefs.
`prompt_tokens`	integer or null	Prompt-token count when recorded.
`completion_tokens`	integer or null	Completion-token count when recorded.
`cost_usd`	float or null	Best-effort generation cost when recorded.
`source_up_to_msg_id`	string or null	Source progression marker Genesis used for the saved version. For journey debriefs this carries the evidence fingerprint plus synthesis contract version.
`created_at`	string	ISO timestamp when that version was created.
`payload`	object	Normalized thread, mission, or journey payload. See Debrief payload kinds.
`evidence`	object	Optional evidence mapping captured alongside the debrief.

`POST /api/debriefs`

Field	In	Type	Default	Required	Description
`source.kind`	body	string	none	Yes	Source discriminator. Allowed values: `thread`, `mission`, `journey`.
`source.thread_id`	body	string	none	Conditional	Required when `source.kind="thread"`. Source thread to summarize.
`source.bot_id`	body	string	none	Conditional	Required when `source.kind="thread"`. Agent that owns `source.thread_id`.
`source.mission_id`	body	string	none	Conditional	Required when `source.kind="mission"`. Source mission to summarize.
`source.project_id`	body	string	none	Conditional	Required when `source.kind="journey"`. Root mission project id for the Blueprint chain aggregate.
`regenerate`	body	boolean	`false`	No	When `true`, force Genesis to generate a fresh debrief version instead of reusing the current one.

POST /api/debriefs returns a DebriefRecord. Thread sources produce the original thread-style payload shape. Mission sources produce the mission-shaped payload described below. Journey sources produce a JourneyDebriefPayload aggregate and may auto-generate missing child mission debriefs for recorded stages before harvesting evidence. With regenerate=true, Genesis regenerates the recorded child mission debriefs from each mission’s current state before assembling the Journey snapshot; unavailable mission data or a child debrief causes the regeneration request to fail. When regenerate is false, Genesis returns the existing current version when the evidence fingerprint is unchanged and synthesis already succeeded (or the journey is still in progress). Equivalent overlapping Journey-generation requests share one in-flight result when their normalized root project, owner, and regenerate value match. Genesis allows up to 8 active generations per root project across distinct keys; a request above that limit returns 429 with Too many Journey generations are already active for this project.

Debrief route parameters

Field	Used by	In	Type	Default	Description
`debrief_id`	`GET /api/debriefs/{debrief_id}`, `DELETE /api/debriefs/{debrief_id}`, and both version routes	path	string	none	Target debrief identifier.
`version_number`	`GET /api/debriefs/{debrief_id}/versions/{version_number}`	path	integer	none	Requested numeric version.
`limit`	`GET /api/debriefs/{debrief_id}/versions`	query	integer	`50`	Maximum versions to return. Genesis clamps this to `1-100`.
`offset`	`GET /api/debriefs/{debrief_id}/versions`	query	integer	`0`	Number of version rows to skip.
`thread_id`	`GET /api/threads/{thread_id}/debriefs`	path	string	none	Source thread identifier to list debriefs for.
`bot_id`	`GET /api/threads/{thread_id}/debriefs`	query	string	none	Agent identifier for the source thread. Required.
`mission_id`	`GET /api/missions/{mission_id}/debriefs`	path	string	none	Source mission identifier to list debriefs for.

GET /api/threads/{thread_id}/debriefs and GET /api/missions/{mission_id}/debriefs both return debriefs: DebriefRecord[]. GET /api/debriefs/{debrief_id}/versions returns versions, current_version, and total_versions.

Debrief payload kinds

Field	Type	Description
`payload.kind`	string	`thread`, `mission`, or `journey`. Legacy thread payloads that were saved before the discriminator existed normalize to `thread` on read.
`payload.title`	string	Human-readable title inside the payload.
`payload.status`	string	Thread payloads use `resolved`, `in_progress`, `blocked`, or `informational`. Mission payloads use `completed`, `in_progress`, `blocked`, or `cancelled`. Journey payloads use `needs_attention`, `awaiting_input`, `in_progress`, `paused`, `completed`, `not_started`, `cancelled`, `mixed`, or `unavailable`.
`payload.metrics`	object	Optional elapsed/tool-call/cost summary.

Mission payload sections

Mission debrief payloads are top-to-bottom narrative summaries. These top-level fields can appear on payload when payload.kind="mission".

Field	Type	Description
`section_order`	`string[]`	Server-chosen render order for the mission debrief sections.
`hero`	object or null	Overview hero with headline, optional subhead, and metric tiles.
`ask`	object or null	Original prompt, persona, and summary that started the mission.
`phase_timeline`	`object[]`	Phase-by-phase walkthrough with timings, primary artifacts, inline markdown, and related commits.
`lineage`	object or null	Lineage graph data, namespace labels, and optional Mermaid content.
`conversion_diff`	object or null	Before/after conversion diff for migrated SQL or code artifacts.
`migration_code`	`object[]`	Highlighted repository files, snippets, and line counts for the migration.
`run_summary`	object or null	Structured execution summary with log URLs and per-step outcomes.
`verdict`	object or null	Reconciliation verdict plus row-count and view checks.
`decisions`	`object[]`	Open decisions captured from the mission.
`downstream`	`object[]`	Downstream consumers and cutover actions.
`lessons`	`object[]`	Lessons captured to the Context Graph wiki.
`audit_trail`	`object[]`	Git commits included in the mission trail.
`repo_layout`	`object[]`	Notable repository files and URLs.
`next_steps`	`string[]`	Recommended follow-up actions.

Journey payload sections

Journey debrief payloads are evidence-first aggregates of a Blueprint chain. These top-level fields appear on payload when payload.kind="journey".

Field	Type	Description
`root_project_id`	string	Root mission project id for the chain.
`root_thread_id`	string or null	Root thread id when available.
`bot_id`	string or null	Project manager agent for the root mission.
`journey_id`	string or null	Journey recipe `definition_id` when present on the root thread.
`journey_variant`	string or null	Journey variant (for example `snowflake` or `databricks`).
`journey_label`	string or null	Human-readable journey title from the recipe.
`journey_variant_label`	string or null	Display label for the selected variant.
`journey_description`	string or null	Journey summary from the recipe.
`outcome`	object	Journey status, headline, narrative, deterministic fallback copy, and evidence id references.
`metrics`	object	Aggregate elapsed time, tool calls, and cost when recorded.
`stages`	`object[]`	Per-stage outcomes with `stage_id`, `label`, `planned_status` (`expected`, `spawned`, or `skipped`), stage `status`, optional `child_debrief` reference, validation summary, and nested `phases` with checklist and activity rollups. For an in-progress stage, the live `blueprint_phase` is matched by `phase_number` or `phase_id`, uses `phase_name`, and is reported as `in_progress` even when it is not yet in the recorded phase timeline.
`database_activity`	`object[]`	Query activity rows harvested from recorded stages.
`decisions_attention`	`object[]`	Open decisions that need attention across the Journey.
`next_steps`	`object[]`	Recommended follow-up actions with optional stage linkage.
`connection_context`	`object[]`	Source, target, and supporting connections with `role` (`source`, `target`, or `other`).
`evidence_references`	`object[]`	Stable evidence ids referenced by outcome, stage, and phase fields.
`synthesis`	object	LLM synthesis metadata: `status` (`not_attempted`, `generated`, or `fallback`), `displayed_source` (`deterministic` or `generated`), optional `reason` (`journey_not_completed` or `synthesis_failed`), and fallback stage/field hints.

File manager upload endpoint

The file upload route is mounted at /api/files in standalone and local deployments and at /files in SPCS. A normal upload may use the existing thread, bot, or chat form fields. Launchpad pre-start uploads additionally use the blueprint_start_session_id field, which requires an authenticated user, stores the file in a server-owned temporary session directory, and preserves the exact uploaded bytes for checksum verification at Mission start. On a Databricks App with durable uploads, the upload is copied to the bound Unity Catalog volume before it is recorded; uploads larger than files.max_upload_bytes (default 104857600 bytes / 100 MiB) return 413, and a volume write failure returns 503. The size cap does not apply to other deployments. See Durable chat uploads on Databricks for setup and restore behavior.

Method	Path	Description
`POST`	`/api/files` (or `/files` in SPCS)	Upload one multipart file. Include `blueprint_start_session_id` for a `client_file_onboarding` local-files start. The response returns the server-issued `file_id` used in `local_file_uploads.file_ids`.

File upload form fields

Field	In	Type	Default	Required	Description
`file`	form	file	none	Yes	File content to upload.
`blueprint_start_session_id`	form	string or null	`null`	No	Opaque Launchpad session id for pre-start Mission files. When supplied, Genesis derives the caller-owned temporary storage location and ignores caller-supplied upload ownership fields.

File manager file access endpoints

These routes are mounted at /api/files/... in standalone and local deployments and at /files/... in SPCS.

Method	Path	Description
`GET`	`/api/files/{file_id:path}`	Return metadata for the file identified by `file_id` as a `FileInfoResponse`.
`GET`	`/api/files/{file_id:path}/download`	Download the file identified by `file_id` as an attachment, using its MIME type or `application/octet-stream` when no MIME type is available.

On a Databricks App with durable uploads, the download route restores a missing upload from the bound Unity Catalog volume after checking access. The first download after a restart waits for that copy; it returns 404 if the content is no longer available and 503 if the volume cannot be read. See Durable chat uploads on Databricks.

File manager deletion endpoints

These routes are mounted at /api/files/... in standalone and local deployments and at /files/... in SPCS.

Method	Path	Description
`DELETE`	`/api/files/{file_id}`	Delete the file identified by `file_id`.
`DELETE`	`/api/files/delete-by-path`	Delete the file at the required `path` query value (for SimpleFileStorage mode).

File deletion query parameters

Parameter	In	Type	Default	Required	Description
`path`	query	string	none	Yes, for `/api/files/delete-by-path` (or `/files/delete-by-path` in SPCS)	File path to delete.
`confirm`	query	boolean	`false`	No	In SimpleFileStorage mode, set to `true` to delete an upload that a sent message references.

Both delete routes return 409 when SimpleFileStorage protects an upload referenced by a sent message and confirm is not true. They return 404 if the file is not found and 500 for an internal error.

File manager markdown conversion endpoints

These routes convert Markdown to downloadable documents. They are mounted at /api/files/... in standalone and local deployments and at /files/... in SPCS. The chat UI’s per-message Save as menu posts completed assistant replies to the PDF, DOCX, and HTML routes; Markdown downloads are built client-side without calling these endpoints. All three routes accept multipart/form-data bodies.

Method	Path	Description
`POST`	`/api/files/markdown-to-pdf`	Convert Markdown to PDF and return the file as a download.
`POST`	`/api/files/markdown-to-docx`	Convert Markdown to Word (DOCX) and return the file as a download.
`POST`	`/api/files/markdown-to-html`	Convert Markdown to a self-contained HTML document and return it as a download. Diagrams render live in a browser because Mermaid and Plotly JavaScript are inlined from local assets.

Shared markdown conversion form fields

Field	In	Type	Default	Required	Used by	Description
`filename`	form	string	`document.pdf`, `document.docx`, or `document.html` per route	No	all three	Output filename. Genesis appends the correct extension when the value omits it.
`markdown_content`	form	string or null	`null`	Conditional	all three	Markdown body to convert. Required on the HTML route. On PDF and DOCX routes, omit only when supplying `repo_id` and `file_path` instead.
`repo_id`	form	string or null	`null`	No	PDF, DOCX	Repository ID to read Markdown from instead of posting `markdown_content`.
`file_path`	form	string or null	`null`	No	PDF, DOCX	Path within `repo_id` to read. Must stay inside the repository; symlinks are rejected.
`include_mermaid`	form	boolean	`true`	No	PDF, HTML	Whether to render Mermaid diagrams. Form values such as `true`, `1`, `yes`, or `on` are treated as enabled.
`include_plotly`	form	boolean	`true`	No	PDF, HTML	Whether to render Plotly charts. Form values such as `true`, `1`, `yes`, or `on` are treated as enabled.

When PDF or DOCX conversion reads a repository file, the caller also needs view access to the exact repository named by repo_id; see Git permissions.

Status	Meaning
`200`	Binary download. Media types: `application/pdf`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, or `text/html`. Includes a `Content-Disposition` attachment header with a sanitized filename.
`400`	Missing `markdown_content`, invalid `repo_id`, or invalid repository path on PDF/DOCX git-fetch mode.
`403`	Caller lacks `view` access to the repository in PDF/DOCX git-fetch mode.
`404`	Git-fetch mode could not find the exact named repository or `file_path` inside it.
`501`	PDF conversion is unavailable in this deployment because it does not include a browser.
`500`	Conversion failed or required conversion dependencies are unavailable on the server.

Sandbox file endpoints

These routes serve files generated in sandbox sessions or stored under the configured downloaded_files root and bot_git/repos. In container-based deployments, Genesis prepares the mounted bot_git workspace on startup and ensures repos/, worktrees/, and .genesis_runtime/ exist before files are served.

Method	Path	Description
`GET`	`/api/sandbox/{file_path:path}`	Serve a sandbox file inline for browser viewing.
`GET`	`/api/sandbox/{file_path:path}/download`	Download a sandbox file as an attachment.

Shared sandbox path parameter

Field	In	Type	Default	Required	Description
`file_path`	path	string	none	Yes	URL-encoded path to a file under the `downloaded_files` root or `bot_git/repos`. The resolved path must stay inside those roots and point to an existing file; traversal-style paths return `404 File not found`.

Sandbox backend restrictions

The sandbox manager is mounted under /api/sandbox-manager. In Databricks Apps, GET /api/sandbox-manager/backends omits the local backend, and an explicit local start through POST /api/sandbox-manager/sessions/start is refused with HTTP 400. The profile validation route POST /api/sandbox-manager/profiles/validate-start reports the same backend restriction in its validation errors. Use a remote sandbox backend instead.

CLI terminal admin endpoints

These endpoints support the Pulse → CLI Workspaces admin view for Kubernetes-managed direct CLI terminal workspaces. Listing requires VIEW_SANDBOXES; restarting or canceling a workspace requires MANAGE_SANDBOXES. The endpoints return an empty successful listing when the CLI terminal feature is disabled or when the configured runtime does not expose Kubernetes workspace pods.

Method	Path	Description
`GET`	`/api/cli-terminal/workspaces`	List running CLI terminal workspaces with owner, status, age, and resource information.
`POST`	`/api/cli-terminal/workspaces/{pod_id}/restart`	Delete and recreate the workspace pod identified by `pod_id`.
`DELETE`	`/api/cli-terminal/workspaces/{pod_id}`	Delete (cancel) the workspace pod identified by `pod_id`.

CLI workspace listing response

The GET response includes live_count, the configured max_workspaces ceiling, whether live metrics were available for the request, and a workspaces array. Each workspace item contains:

Field	Type	Description
`id`	string	Workspace pod identifier used by the restart and cancel routes.
`owner_user_id`	string or null	User identifier recorded on the workspace pod.
`owner_email`	string or null	Resolved owner email when available.
`status`	string	Workspace status.
`phase`	string	Kubernetes pod phase.
`ready`	boolean	Whether the workspace is ready.
`age_seconds`	integer	Workspace age in seconds.
`cpu_used_m` / `cpu_limit_m` / `cpu_request_m`	integer or null	CPU usage, limit, and request in millicores.
`memory_used_mib` / `memory_limit_mib` / `memory_request_mib`	integer or null	Memory usage, limit, and request in MiB.
`usage_available`	boolean	Whether live CPU and memory usage was available.

Unified realtime WebSocket

Genesis exposes its multiplexed realtime socket at /api/ws/unified_v2. This endpoint carries chat operations plus server-pushed entity events. To receive thread-scoped server events such as thread_new, thread_artifaqt_delta, or agent_action_request, clients send a subscribe control frame on the unified socket. While Genesis is starting, the handshake is refused with HTTP 503 and Retry-After: 5; clients should retry after the indicated delay. If the ASGI server does not support denial responses, Genesis closes the socket with code 1013 instead, which can appear to clients as HTTP 403 because the socket was not accepted. When auth.enabled is true and auth.provider is auth0 or oidc, the client must send a bearer token in the Authorization header or, when auth.allow_query_token is true, in the token query parameter. Connections missing a required token are rejected before the socket is accepted with close code 1008. Genesis verifies the token before using its claims for session ownership: the signature is checked against the issuer’s JWKS, and the expiry, audience, and issuer are validated. Forged or expired tokens therefore fail the ownership check; a verified caller with MANAGE_SANDBOXES can still bypass the session-owner comparison.

For direct chat responses produced after Genesis routes a message to a bot handler, the response data echoes correlation metadata. bot_id echoes the request’s bot target, thread_id echoes the request’s thread target when present, and request_id is echoed exactly as sent when it is a non-empty string. If the client omits request_id or sends "", Genesis generates a request ID and returns it in the response so multiplexed clients can correlate replies.Genesis also copies the original non-empty client request_id onto the terminal message_processing_complete progress event for that turn. If the client omits request_id or sends "", Genesis omits request_id from that server-pushed completion event instead of inventing a new one there.Some message types that answer an earlier server prompt still require a non-empty client-supplied request_id; those message-specific requirements are called out below.Other server-pushed event frames keep their existing payloads, and malformed messages rejected before routing still use the generic error envelope.

Idempotent `send_message` retries

WebSocket clients may include client_message_id in the data for a send_message frame. Use the same non-empty ID (up to 128 characters) when retrying that message. Genesis scopes IDs to the bot and thread. If the first copy fails while being accepted, a repeat can proceed. When that copy is still pending, Genesis waits up to 10 seconds for its outcome; if it remains pending or was accepted, Genesis suppresses the repeat and sends a message_send_duplicate frame with thread_id and client_message_id in data. Accepted IDs are kept in a per-process, bounded in-memory cache for up to one hour, so this is retry protection rather than durable exactly-once delivery.

Field	In	Type	Default	Required	Description
`client_message_id`	`send_message` data	string	none	No	Client-generated identifier for deduplicating retries of the same send. Reuse the identifier on each retry; a new message needs a new identifier.

Unified WebSocket authentication parameters

Field	In	Type	Default	Required	Description
`Authorization`	header	string	none	Conditional	`Bearer <token>` header required when auth is enabled with Auth0 or OIDC, unless the query-token fallback below is allowed and used.
`token`	query	string	none	Conditional	Alternative token parameter accepted only when `auth.allow_query_token` is `true`.

Unified WebSocket connection parameters

Field	In	Type	Default	Required	Description
`v`	query	string	none	No	Client version. Checked only when `http.enable_request_guards` is `true`; outdated clients are rejected before the socket is accepted (close code `1000`).
`purpose`	query	string	none	No	Optional client hint for server-side lifecycle logging. Recognized values: `chat_pool` (dashboard chat transport) and `unified_manager` (shared entity-update manager). Unknown values are logged as `unknown` and do not affect routing.
`prev_close_code`	query	string	none	No	Optional four-digit WebSocket close code from the client’s preceding socket on reconnect. Genesis accepts values in the range `1000`–`4999`, logs the bounded value for diagnostics, and does not change connection behavior.

Send a client message with type: "subscribe" and these data fields:

Field	In	Type	Default	Required	Description
`subscriptions`	message data	string[]	`[]`	No	Entity streams to subscribe to, such as `threads`.
`entity_ids`	message data	`object<string, string[]>`	`{}`	No	Optional per-entity filters. For `threads`, Genesis uses the agent or bot ID as the entity ID.

Example subscription for thread events from one bot stream:

{
  "type": "subscribe",
  "data": {
    "subscriptions": ["threads"],
    "entity_ids": {
      "threads": ["<bot_id>"]
    }
  }
}

`subscribe_messages` control frame

Send a client message with type: "subscribe_messages" and these data fields:

Field	In	Type	Default	Required	Description
`thread_id`	message data	string	none	Yes	Thread to attach to for live message delivery. Genesis also uses this thread-level stream to deliver thread progress events such as `thread_stream_start`, `thread_tool_start`, `thread_tool_stop`, `thread_stream_stop`, and `message_processing_complete`.

After Genesis accepts a send_message request for a thread, it also attaches that WebSocket connection to the thread’s live message stream. Clients do not need to wait for a separate subscribe_messages round-trip before the server can deliver the accepted reply and its related progress events.

For client-generated chat IDs such as chat_* and litellm_thread_*, Genesis treats an early subscribe_messages request as part of thread materialization rather than an immediate missing-thread error. This lets clients attach the live stream and backfill history while the backend thread record is still being created.

During that same thread-materialization window, the initial message payload delivered on the unified socket can also report model_tier: "" rather than defaulting to main. Treat the empty string as an unset thread override until Genesis has persisted the backend thread metadata.

Repeated subscribe_messages requests for the same bot_id / thread_id pair on one WebSocket connection are idempotent. Genesis returns the existing subscription_id instead of creating a second live subscription, and when the server can reuse the original formatted payload it also reuses data.initial_data.Duplicate subscription_started replies still echo the subscribed thread_id at data.thread_id, so clients should treat that top-level field as canonical for the acknowledgement and use data.initial_data.thread_id only when the nested field is present.

Onboarding approval metadata for `send_message`

The chat onboarding plan card sends its approval through data.message_metadata.onboarding_start on the unified WebSocket send_message frame. This is conditional metadata for the plan card’s Approve and start action, not a general typed confirmation:

Field	Type	Required	Description
`schema_version`	integer	Yes	Must be `1`.
`source_connection_id`	string	Yes	Visible source database connection id, such as `databricks.lakehouse`.
`source_tables`	string[]	Yes	One or more raw table names in `catalog.schema.table` form.
`target_connection_id`	string	Yes	Target connection id; must match `source_connection_id`.
`target_table`	string	Yes	Existing target table in `catalog.schema.table` form.
`documents_folder`	string	Yes	Folder containing the mapping guide and data dictionary.
`source_name`	string	Yes	Source label used by the onboarding blueprint.
`load`	boolean	Yes	Whether the approved kickoff includes permission to load the target.

Genesis retains this metadata only when the message is the kickoff generated from these picks and the picks pass onboarding validation. Malformed metadata or a kickoff that does not match it is dropped; the message still proceeds as ordinary text. The plan card is the supported way to produce the matching metadata and kickoff. For the user flow and chat tools, see Onboard raw tables and Onboarding intake tools.

`ask_user_for_secret` event

When a thread-scoped tool call such as get_web_content(action="ask_user_for_secret") needs a stored credential, Genesis emits an event frame where:

data.entity_type = "threads"
data.entity_id = "<bot_id>"
data.event_type = "ask_user_for_secret"

The nested event payload (data.data) uses these fields:

Field	In	Type	Default	Required	Description
`request_id`	event data	string	none	Yes	Correlation ID for the credential request. Send this value back on `secret_input_response`.
`thread_id`	event data	string	none	Yes	Thread that owns the request.
`bot_id`	event data	string	none	Yes	Agent or bot that owns the thread stream.
`secret_hint`	event data	string	none	Yes	Display hint shown to the user. Genesis derives this from the supplied `secret_hint`.
`suggested_name`	event data	string	none	Yes	Suggested vault secret name, usually starting with `secret_`.
`is_update`	event data	boolean	`false`	Yes	`true` when Genesis is asking the user to replace an existing stored secret after an earlier credential attempt failed.
`anchor_message_id`	event data	string or null	`null`	Yes	Assistant message ID that first-party clients use to anchor the inline credential card to the originating assistant reply.

`secret_input_response` client message

Send a client message with type: "secret_input_response" and these data fields:

Field	In	Type	Default	Required	Description
`request_id`	message data	string	none	Yes	Correlation ID copied from the original `ask_user_for_secret` event.
`secret_name`	message data	string	none	Conditionally	Stored secret name selected or created by the client. Required unless `cancelled = true`.
`cancelled`	message data	boolean	`false`	No	Set `true` when the user dismisses the request instead of submitting a secret name.

When Genesis accepts the message, it replies with type: "secret_input_response" and returns the correlated data.request_id, a boolean data.resolved flag, and the standard direct-response correlation fields described above. A resolved: true response means the server found a matching pending request and accepted the reply. Genesis does not auto-generate a replacement request_id for this message type. Blank or omitted values are rejected because the response must match an outstanding ask_user_for_secret request.

`secret_input_timeout` event

If an ask_user_for_secret request remains unanswered for 600 seconds, Genesis emits data.event_type = "secret_input_timeout" on the same thread stream. The nested event payload (data.data) uses these fields:

Field	In	Type	Default	Required	Description
`request_id`	event data	string	none	Yes	Timed-out credential request ID.
`thread_id`	event data	string	none	Yes	Thread that owned the request.
`bot_id`	event data	string	none	Yes	Agent or bot that owns the thread stream.

Demo budget exhaustion on the unified socket

When demo mode is enabled, demo.allow_unlimited_budget is false, and aggregate spend has reached demo.token_budget_usd, Genesis rejects send_message, replace_last_user_message, and edit_message_and_resume on the unified WebSocket before routing the turn. The check runs only after the agent-access guard succeeds so unauthorized callers do not see aggregate spent_usd / cap_usd figures. Genesis replies with type: "subscription_error", error_code: "demo_budget_exceeded", and message text Demo budget exceeded. Please contact sales to discuss a full deployment. The nested details object includes:

Field	Type	Description
`thread_id`	string or null	Thread from the client request when present.
`spent_usd`	number	Aggregate spend in USD (four decimal places).
`cap_usd`	number	Configured cap in USD (four decimal places).
`cta_url`	string	Sales or booking URL from `demo.sales_url`.

For replace_last_user_message, the budget gate runs before any rewind so a blocked replacement does not remove the persisted last user turn. For edit_message_and_resume, the budget gate also runs before any rewind so a blocked edit does not archive thread history.

`edit_message_and_resume` client message

Send a client message with type: "edit_message_and_resume" to edit any prior user message and re-run the conversation from that point. Unlike replace_last_user_message (in-flight last turn only), this archives every turn from the target node onward — messages are marked discarded, not physically removed — then resends the edited text through the normal pipeline.

Field	In	Type	Default	Required	Description
`bot_id`	message data	string	none	Yes	Agent that owns the thread.
`thread_id`	message data	string	none	Yes	Thread to edit.
`target_node_id`	message data	string	none	Yes	Stable plist `node_id` of the user message to replace.
`new_message`	message data	string	none	Yes	Replacement user prompt text.
`files`	message data	string[]	`[]`	No	File-manager ids to attach to the resent turn.
`execution_lane`	message data	string	none	No	Deprecated compatibility field. The `express` lane is no longer selectable; prompt dispatch uses the async dispatcher.
`message_metadata`	message data	object	none	No	Optional resend metadata echoed on the subsequent turn. To preserve the subject of a Prover chat, include a valid `prover_context` object; the WebSocket also accepts the camelCase alias `proverContext`.
`timeout_seconds`	message data	number	`6.0`	No	Stop-and-confirm timeout when an in-flight stream must be interrupted before the rewind.

message_metadata.prover_context is a versioned, immutable subject for a Prover chat. It must contain version: 1, a comparison with diff_hash, source_snapshot_id, target_snapshot_id, delta_hash, and component_pair, and, when the subject is used to stage a package, run_id and pair_fingerprint so the captured evidence can be authenticated. It has a scope with kind (comparison, issue_group, or finding), key, and label, plus a members array. Each member requires review_id, comparison_kind, and a relationship of new, remaining, changed, regressed, or resolved; package staging additionally requires each captured member’s finding_key, positive ledger_id, object_name, and relationship to match the authoritative ledger and review population. Optional column and requirement details may also be included. The array accepts at most 512 members and the complete sanitized object is limited to 256 KiB. Genesis keeps the sanitized Prover subject from the thread’s first user message when later turns provide different metadata, so follow-up requests continue to refer to the original finding group. The subject is supplied to the model as untrusted UI metadata: its fields are identifiers and observations, not instructions. If Genesis cannot sanitize a supplied prover_context, it rejects that value rather than using it to identify a comparison. Resend valid Prover context to preserve the intended subject; the chat does not substitute a comparison based on rejected metadata. When auth is enabled, the caller must own the thread (same bar as forking). Genesis refuses the edit while a tool is still executing (error_code = "tool_calls_active"). On success Genesis replies with type: "message_edited_and_resumed" and a data object that includes:

Field	Type	Description
`bot_id`	string	Agent identifier.
`thread_id`	string	Thread that was edited.
`target_node_id`	string	Node id that was rewound to.
`edit_id`	string or null	Server-side edit correlation id when present.
`estimated_context_tokens`	integer or null	Approximate LLM-visible tokens after the rewind.
`rewind_stats`	object	Counts such as `discarded_total`, `discarded_user`, `restored_count`, and `dropped_summary_count`.

Failures use type: "edit_message_error" with error_code values such as edit_target_not_found, edit_target_not_user_message, tool_calls_active, edit_rewind_failed, or thread_access_denied. On the first blocked message per thread, Genesis also emits an inline agent_action_request with action_type = "demo_interest" and action_data.trigger = "budget_exhausted" so the thread surfaces the Schedule a Demo card (one-shot per thread, shared dedup with the in-flight budget guard). Notifier failures after the budget error is sent do not change the handled block response.

`agent_action_request` event

When a thread-scoped workflow needs client-side input such as OAuth authorization, a personal-credential binding, or a Try Me demo-interest CTA, Genesis emits an event frame where:

data.entity_type = "threads"
data.entity_id = "<bot_id>"
data.event_type = "agent_action_request"

The nested event payload (data.data) uses these fields:

Field	In	Type	Default	Required	Description
`request_id`	event data	string	none	Yes	Correlation ID for the action request. Send this value back on `agent_action_response`.
`action_type`	event data	string	none	Yes	Requested action card key, such as `oauth_connect`, `credential_prompt`, or `demo_interest`.
`action_data`	event data	object	`{}`	Yes	Action-specific payload rendered by the client.
`thread_id`	event data	string	none	Yes	Thread that owns the request. First-party clients trim surrounding whitespace from `thread_id` and ignore `agent_action_request` events whose `thread_id` is blank or not a string.
`bot_id`	event data	string	none	Yes	Agent or bot that owns the thread stream.
`user_id`	event data	string or null	`null`	Yes	User identity associated with the request when Genesis has one.
`anchor_message_id`	event data	string or null	`null`	Yes	Assistant message ID that first-party clients use to anchor the inline action card to the originating assistant reply.

demo_interest action requests currently use these action_data fields:

Field	Type	When present	Description
`trigger`	string	Always	Trigger that emitted the card. Values include `nudge`, `message_limit`, and `budget_exhausted`.
`message_count`	integer	When present	Thread user-turn count captured when Genesis emitted the CTA (for example on `message_limit`).
`user_email`	string	When Genesis can safely resolve a real signup or corporate email	Synthetic demo auth emails are stripped from the broadcast payload instead of being sent to other thread subscribers.

credential_prompt action requests use these action_data fields:

Field	Type	When present	Description
`connection_type`	string	Always	Saved connection type whose shared connection requires the user’s personal credential.
`connection_name`	string	Always	Saved connection name to use when binding the user’s personal credential.

Genesis sends agent_action_request to connected clients on the thread subscriber stream rather than a separately user-targeted stream. This keeps demo and no-auth browser sessions receiving the request even when user-targeted delivery would not match.

`agent_action_response` client message

Send a client message with type: "agent_action_response" and these data fields:

Field	In	Type	Default	Required	Description
`request_id`	message data	string	none	Yes	Correlation ID copied from the original `agent_action_request`.
`status`	message data	string	none	Yes	Resolution state. Supported values are `resolved`, `cancelled`, and `failed`.
`action_type`	message data	string	none	Yes	Action type being answered, such as `oauth_connect`, `credential_prompt`, or `demo_interest`.
`result_data`	message data	object or null	`null`	No	Optional action-specific result payload, typically included on `resolved` responses.

When action_type = "demo_interest", resolved responses may include these result_data fields:

Field	Type	When present	Description
`action`	string	When the user completes the card	Action name reported by the client. The current first-party value is `schedule_demo`.
`booking_confirmed`	boolean	When the embedded scheduler reports a booking	`true` when the Chili Piper flow confirmed a booking. First-party clients can set this from either the normal `onSuccess` callback or a `CHILI_SCHEDULING_EVENT` message whose `action` is `booked`.
`message_count`	integer	When the original request included a message count	Message count echoed from the original CTA so Genesis can store lead context.

When action_type = "demo_interest" and status = "resolved", Genesis uses result_data to update Try Me lead-capture metadata server-side. For action_type = "oauth_connect", clients should still send agent_action_response when they can so the thread UI can acknowledge the result promptly. Genesis also applies a callback-side safety net: once the OAuth callback persists the grant for the same user and saved connection, the server resolves any matching pending OAuth wait even if the popup cannot send the response back to its opener. For action_type = "credential_prompt", the client submits the principal through PUT /api/connections/{connection_type}/{name}/credentials/me rather than sending secret values in the action response. After that bind succeeds, Genesis resolves the matching pending credential wait for the user and connection. Clients can still send agent_action_response to report the card’s resolved, cancelled, or failed state to the thread.

`agent_action_response_ack` response

When Genesis accepts an agent_action_response, it returns type: "agent_action_response_ack" with these data fields:

Field	Type	Description
`request_id`	string	Correlated action-request identifier.
`status`	string	Echo of the submitted response status.

Successful acknowledgements also include the standard direct-response correlation fields described above. When action_type = "demo_interest", this acknowledgement reflects transport-level acceptance of the client response frame. Try Me lead-capture follow-up runs separately and does not suppress the ack if later server-side processing fails. If request_id is missing or blank, Genesis returns type: "agent_action_response_error" with success = false, error = "request_id is required", and data.error_code = "missing_request_id".

`thread_new` event

When Genesis creates a thread and notifies subscribers on the threads entity stream, it emits an event frame where:

data.entity_type = "threads"
data.entity_id = "<bot_id>"
data.event_type = "thread_new"

The nested event payload (data.data) uses these fields:

Field	In	Type	Default	Required	Description
`thread_id`	event data	string	none	Yes	Newly created thread identifier.
`timestamp`	event data	string	none	Yes	ISO-8601 thread date for sidebar sorting and “last active” labels. Genesis resolves it from thread metadata in this order: `imported_display_timestamp`, then `last_activity`, then `timestamp` — the same metadata keys used first by `GET /api/bots/{bot_id}/threads` list items (see the thread-list `timestamp` priority chain above). Live chats typically receive the current time; imported conversations receive their historical date. Falls back to the current server time only when metadata cannot be read or no value is set.
`thread_title`	event data	string	none	Yes	Title to show for the new thread.
`is_streaming`	event data	boolean	`false`	Yes	Whether the thread is already streaming a reply when announced. Genesis currently emits `false` on creation.
`bot_id`	event data	string	none	Yes	Agent or bot that owns the thread stream.
`owner_user_id`	event data	string or null	`null`	No	Owner user ID when Genesis can resolve it.
`show_in_thread_list`	event data	boolean or null	`null`	No	Whether the thread should appear in the default sidebar list. Genesis omits this field when no explicit list-visibility value is available for the emitted thread.
`has_coding_agent_sessions`	event data	boolean or null	`null`	No	Whether the new thread already has persisted coding-agent session history.

`thread_artifaqt_delta` event

When the most recent completed tool call changes thread artifacts, or when Genesis needs clients to refresh phase-scoped thread state after that tool completes, it emits an event frame where:

data.entity_type = "threads"
data.entity_id = "<bot_id>"
data.event_type = "thread_artifaqt_delta"

The nested event payload (data.data) uses these fields:

Field	In	Type	Default	Required	Description
`thread_id`	event data	string	none	Yes	Thread whose artifacts changed.
`timestamp`	event data	string	none	Yes	Server-rendered timestamp for the notification.
`bot_id`	event data	string	none	Yes	Agent or bot that owns the thread stream.
`artifaqts_delta`	event data	object	`{}`	Yes	Artifact delta for the most recent completed tool call. This object may be empty when Genesis needs clients to refresh thread state without a new artifact delta payload.

artifaqts_delta is phase-scoped. Each entry in artifaqts_delta.phases uses phase_id (string) plus inputs and outputs arrays. For Blueprint and Document Flow threads, Genesis attributes non-blueprint tool outputs to the currently active blueprint phase so clients can group updates by the active phase instead of relying on the fallback "0" phase bucket. For Document Flow replay, the same nested payload can include an optional document_flow_snapshot object. It contains the current artifaqts, optional phase_number and blueprint_name, and messages, a compact list of the Blueprint and coding-agent tool calls and results needed to rebuild coding-agent delegation nodes and their statuses. The snapshot is also emitted when a coding-agent tool starts or stops, allowing a client to show a running delegation before the final artifact update arrives.

Additional thread progress events

Genesis can also emit thread progress event frames for clients that are subscribed to the threads entity stream or already attached to a thread’s live message stream. Thread-scoped delivery keeps Slack-linked and other mirrored thread views receiving progress events even when the broader unified entity subscription is filtered separately. These events use the same outer envelope shape as thread_artifaqt_delta:

type = "event"
success = true
data.entity_type = "threads"
data.entity_id = "<bot_id>"

Their nested payload (data.data) always includes these fields:

Field	In	Type	Default	Required	Description
`thread_id`	event data	string	none	Yes	Thread whose state changed.
`timestamp`	event data	string	none	Yes	Server-rendered timestamp for the notification.
`bot_id`	event data	string	none	Yes	Agent or bot that owns the thread stream.

Supported progress event types

`event_type`	When emitted	Additional payload fields
`thread_stream_start`	The agent starts streaming a reply for the thread.	`latest_sender_user_id`, `source_thread_id`
`thread_stream_stop`	The agent finishes streaming its reply.	`owner_user_id`, `latest_sender_user_id`, `source_thread_id`
`thread_tool_start`	A tool call begins.	`tool_name`, `assistant_message_id`, `turn_id`, `tool_call_id`, `tool_id`, `tool_display_name`, `announcement_text`, `func_args`, `arguments`
`thread_tool_stop`	A tool call finishes.	`tool_name`, `assistant_message_id`, `turn_id`, `tool_call_id`, `tool_id`, `query_result`
`context_budget_refresh`	Thread context-budget or compression state changed; clients should refetch related REST state rather than treating the event as a full snapshot.	`trigger`, `compression`
`message_processing_complete`	All reply streaming and tool activity for the current message is complete.	`latest_sender_user_id`, `source_thread_id`, `message_id`, `request_id`

Top-level `message_complete` frame

Streaming clients should also handle a top-level message_complete frame as the terminal signal for a sandbox turn. Unlike the progress events above, this frame is not wrapped in {"type":"event"}. Its data.content is the definitive assistant text for the turn, including when the live text stream produced no proxy frame before the turn ended.

{
  "type": "message_complete",
  "data": {
    "thread_id": "<thread_id>",
    "bot_id": "<bot_id>",
    "content": "Final assistant response",
    "status": "completed",
    "timestamp": 1710000000.123,
    "message_id": "<message_id>",
    "model": "<model>"
  }
}

The message_id and model fields are included only when available. Clients should use content as the final displayed response and stop waiting for the turn when type is message_complete.

A successful POST /api/bots/{bot_id}/threads/{thread_id}/force-reset request that actually clears stuck state also emits both thread_stream_stop and message_processing_complete on the same thread stream. Realtime clients can use those events to unwind stuck loading or streaming indicators without reopening the thread.

Optional progress-event payload fields

Field	Type	Used by	Description
`latest_sender_user_id`	string	`thread_stream_start`, `thread_stream_stop`, `message_processing_complete`	Most recent end-user sender for the thread when Genesis can resolve it.
`source_thread_id`	string	`thread_stream_start`, `thread_stream_stop`, `message_processing_complete`	Source thread Genesis wants clients to reconcile when the active work is being mirrored back to another thread context.
`owner_user_id`	string	`thread_stream_stop`	Thread owner when Genesis includes it for owner-aware UI behavior.
`message_id`	string	`message_processing_complete`	Message identifier for the completed turn when available.
`request_id`	string	`message_processing_complete`	Correlation ID copied from the original `send_message` request when the client supplied a non-empty `request_id`.
`tool_name`	string	`thread_tool_start`, `thread_tool_stop`	Tool name associated with the event.
`assistant_message_id`	string	`thread_tool_start`, `thread_tool_stop`	Assistant message row the tool activity belongs to, when available.
`turn_id`	string	`thread_tool_start`, `thread_tool_stop`	Server-stamped LLM-iteration identifier that groups all tool calls from one model step. Genesis resolves it from the active completion when the emitter does not supply one. Realtime clients should treat `turn_id` as the authoritative grouping key for inline tool-call cards when present.
`tool_call_id`	string	`thread_tool_start`, `thread_tool_stop`	Canonical tool-call identifier.
`tool_id`	string	`thread_tool_start`, `thread_tool_stop`	Compatibility alias for `tool_call_id`.
`tool_display_name`	string	`thread_tool_start`	Formatted display name for the tool call.
`announcement_text`	string	`thread_tool_start`	Human-readable announcement text such as `Using tool: ...`.
`func_args`	string or JSON value	`thread_tool_start`	Best-effort normalized tool arguments.
`arguments`	string or JSON value	`thread_tool_start`	Compatibility copy of `func_args`.
`query_result`	object	`thread_tool_stop`	Present for query-producing tools when Genesis can return a compact query-result summary.
`trigger`	string	`context_budget_refresh`	Refresh reason such as `tool_stop`, `stream_stop`, `message_processing_complete`, `compression_start`, `compression_complete`, or `compression_failed`.
`compression`	object	`context_budget_refresh`	Optional lightweight compression summary. `compression.status` is `running`, `completed`, or `failed`.

When query_result is present, it can include:

Field	Type	Description
`query_id`	string	Query-result identifier.
`query_title`	string	Display title for the query result. Defaults to `Query Result` when the tool did not supply a title.

When event_type = "context_budget_refresh", the nested compression object can additionally include fields such as usage_before_pct, usage_after_pct, reduction_pct, strategy, reduction_scope, reason, phase, progress_message, progress_pct, progress_phase, work_done, work_total, summary_done, summary_total, and parallelism. Treat that payload as a refresh hint and refetch GET /api/bots/{bot_id}/threads/{thread_id}/activity or the relevant context-budget endpoints (/budget for the panel card, /budget-history when a modal is open) for authoritative state.

Log REST endpoints

Genesis exposes operator-focused log routes under /api/logs/.... These endpoints require the access_config_panel permission. GET /api/logs reads from the in-memory Pulse log buffer and returns a formatted historical snapshot. GET /api/logs/download instead streams the configured log file from disk, so it can include log content older than the buffer-backed REST and WebSocket history views.

Method	Path	Description
`GET`	`/api/logs`	Return a filtered historical snapshot from the in-memory log buffer.
`GET`	`/api/logs/levels`	Return the available log levels.
`GET`	`/api/logs/stats`	Return aggregate log statistics.
`GET`	`/api/logs/download`	Stream the configured log file as a plain-text attachment.
`GET`	`/api/logs/errors/download`	Download the dedicated error log file, or all daily-rotated error log files as a ZIP archive.

`GET /api/logs/download`

Genesis streams the current log file directly from disk. When include_rotated=true, it also appends rotated backups in chronological order, oldest first, separated by file-boundary markers in the response body. Because full log files can be multi-MB, Genesis allows only one active /api/logs/download stream at a time. Concurrent download requests wait for the current stream to finish instead of running in parallel.

Field	In	Type	Default	Required	Description
`include_rotated`	query	boolean	`false`	No	When `true`, include sequential rotated backups such as `app.log.1` and `app.log.2` before the current file. The response filename uses the configured log file stem plus `_all.log`.

Status	Meaning
`200`	Plain-text attachment streamed from disk. Without `include_rotated`, the download filename matches the current log filename. With `include_rotated=true`, the filename uses the configured log file stem plus `_all.log`.
`404`	The log file path is not configured or the resolved log file does not exist.

`GET /api/logs/errors/download`

Genesis streams the dedicated error log from disk. This file captures ERROR/CRITICAL records and any log line that carried an exception traceback. Genesis rotates the file daily at midnight; rotated backups use the suffix .<YYYY-MM-DD> (for example errors.log.2026-06-11). When zip=false (default), Genesis streams only the current error log file as plain text. When zip=true, Genesis packs the current file plus all retained daily-rotated backups (oldest first) into a ZIP archive named error_logs.zip. Error-log downloads share the same single-stream concurrency limit as /api/logs/download.

Field	In	Type	Default	Required	Description
`zip`	query	boolean	`false`	No	When `true`, return `error_logs.zip` containing the current error log and all daily-rotated backups. When `false`, stream only the current error log file.

Status	Meaning
`200`	Plain-text attachment when `zip=false` (filename matches the configured error log, typically `errors.log`). ZIP attachment (`error_logs.zip`, `application/zip`) when `zip=true`.
`404`	Error logging is disabled (`GENESIS_ERROR_LOG_FILE` is empty), the current error log file does not exist (`zip=false`), or no error log files were found (`zip=true`).

Estate live-progress WebSocket

Genesis exposes the Prover theater live-progress channel at /api/ws/estate/live. The socket streams fine-grained, forward-only progress events for estatechar runs (scan, contract compile, system diff, behavioral validation, fold) so clients can follow a run live instead of polling a coarse run summary. Every event is also persisted on the run row, so GET /api/estate/runs/{run_id} and GET /api/estate/active-runs remain a complete fallback when the channel is disabled or the socket drops. The channel is gated by estate_char.live.enabled (default true). When disabled, the server refuses the connection before accept with close code 1013 and clients should fall back to polling. When auth.enabled is true and auth.provider is auth0 or oidc, the client must send a bearer token in the Authorization header or, when auth.allow_query_token is true, in the token query parameter. Connections missing a required token are rejected before the socket is accepted with close code 1008.

Estate live WebSocket connection parameters

At least one of run_id or pair is required. Connecting with neither, or when the caller’s identity cannot be resolved, is rejected with close code 1008.

Field	In	Type	Default	Required	Description
`run_id`	query	string	none	Conditional	Follow one visible run. On connect the server sends a `snapshot` catch-up event, then streams forward-only deltas until `done`; an unknown or hidden run receives `snapshot` with `found: false` and is not followed.
`pair`	query	string	none	Conditional	Follow visible runs whose `pair_fingerprint` matches (a migration source→target pair). On connect the server sends a `snapshot` per matching active run.
`v`	query	string	none	No	Client version. Checked only when `http.enable_request_guards` is `true`; outdated clients are rejected with close code `4403`.
`Authorization`	header	string	none	Conditional	`Bearer <token>` header required when auth is enabled with Auth0 or OIDC, unless the query-token fallback below is allowed and used.
`token`	query	string	none	Conditional	Alternative token parameter accepted only when `auth.allow_query_token` is `true`.

Estate live WebSocket close codes (before accept)

Code	Reason
`1013`	Live channel disabled (`estate_char.live.enabled=false`) or server still starting up.
`4403`	Client version outdated (`http.enable_request_guards` on).
`1008`	Missing auth token, caller identity cannot be resolved, or neither `run_id` nor `pair` supplied.

Estate live WebSocket server event types

Every server → client message is a flat JSON object with type, run_id (absent only on ping), ts (ISO-8601 UTC), and payload fields merged flat onto the envelope (not nested under data).

Type	Purpose
`snapshot`	Late-joiner catch-up sent once per subscribed run on connect; reconstructs current phase and counts from the persisted run summary. Includes `connection_ref` and `role` (`"source"` or `"target"`) so a client joining mid-run can route a characterize scan to the correct Venn cell; source scans may omit `role` (clients default to `"source"`). Includes `found: false` when the `run_id` is unknown.
`phase`	A phase begins (`scan`, `contract`, `diff`, `behavioral`, or `fold`). On a windowed as-of scan, includes `windowed: true` and `window_rule_count` (number of as-of window rules in the boundary).
`scan_progress`	Coarse scan counter (`objects_done`, `objects_total`).
`object_revealed`	One object characterized during the scan (`object_name`, `qualified_name`, running counts).
`scan_truncated`	One object left unread after the Foundry measurement budget expires (`objects_seen`, its enumeration position, and `objects_total`).
`family_found`	One unlicensed deviation class discovered during system diff (`comparison`, `count`, `object_count`, `sample_objects`).
`element_verdict`	One element’s trichotomy verdict during system diff (`comparison`, `object_name`, `column`, `verdict`, `detail`).
`behavioral_case`	One behavioral batch driven during migration validation (`stage`, `engine`, `groups_done`, `groups_total`, `group_label`, `mode`, `injected_rows`).
`summary`	Terminal counts sent just before `done` (shape depends on `run_type`). On a characterize run measured over a locked as-of window, may include `windowed: true` and `window_rule_count`. If a Foundry characterization budget expires with unread objects, includes `objects_budget_truncated` and `measurement_budget_exhausted: {reason, unread_count}`; `objects_done` counts measured objects only.
`done`	Stream end for a run (`status`: `finished` or `error`; `error` when `status="error"`).
`ping`	Heartbeat when idle (no `run_id`). Sent every `estate_char.live.heartbeat_seconds` (default `20`). The server closes the socket after `estate_char.live.idle_timeout_seconds` (default `3600`) of total idleness.

Events for a single run_id are delivered in emission order. Under backpressure the server drops the oldest queued events (bounded by estate_char.live.buffer_size, default 256); on a detected gap, re-fetch the run via GET /api/estate/runs/{run_id} to resync.

Store-first liveness (headless and API runs)

A run launched outside the backend process (agent, script, or API path — launch_mode: "headless-script" on the run row) publishes its emit() events into its own process’s in-memory hub, which the GUI-serving backend never sees. The WebSocket consumer needs no protocol change: the server reconstructs the same forward-only event stream from the persisted run store so the socket looks identical to an in-backend run.

Store-tailing pump — for each followed run_id or pair match, when estate_char.live.store_tail_enabled is true (default), the server polls store.get_run every estate_char.live.store_tail_poll_seconds (default 5) — not the socket keep-alive heartbeat_seconds (default 20) — and synthesizes phase, scan_progress, object_revealed, summary, and done by diffing consecutive summaries. Object names come from the bounded recent_objects buffer in the summary (estate_char.live.recent_objects_buffer, default 25); the exact running count always rides scan_progress. A headless run is tailed from the store immediately. A backend-launched run keeps the pump dormant while in-process hub events are flowing and hands over only after estate_char.live.store_tail_grace_seconds (default 8) of hub silence, so live hub events are never double-delivered. Budget truncation is carried in the summary fields above; the store-tail pump does not synthesize per-object scan_truncated events.
Mid-diff verdicts — when estate_char.live.outbox_enabled is true (default), a headless system_diff run buffers family_found and element_verdict events into the estate_char_run_events outbox; one shared backend tail task per followed run (not per connection) polls by watermark every estate_char.live.outbox_tail_poll_seconds (default 2) and republishes new rows into the live hub. Delivery is at-least-once — keep reducers forward-only and idempotent. Backend-launched diffs do not use the outbox (their emit() already reaches the hub in-process).
Stale-run protection — the shared estate_char.reconcile.stale_after_seconds window defaults to 2400 seconds. A heartbeat keeps a running row alive, but a heartbeat or completion that arrives after reconciliation has closed the row cannot reopen it; inspect the run summary for any recorded late completion.

Connecting with both ?run_id= and ?pair= for the same run follows it once (one snapshot and one pump).

Field	Type	Default	Description
`estate_char.live.store_tail_enabled`	boolean	`true`	Master switch for the store-tailing pump. When `false`, headless runs get only the connect-time `snapshot` plus polling fallback.
`estate_char.live.store_tail_poll_seconds`	integer	`5`	Poll interval for the store-tailing pump — what paces headless/API-run animation on the socket. Deliberately faster than `heartbeat_seconds` so progress advances in step with the frontend’s live cadence.
`estate_char.live.store_tail_grace_seconds`	integer	`8`	Hub-silence window before the pump takes over for a backend-launched run.
`estate_char.live.recent_objects_buffer`	integer	`25`	How many recent object names a running scan carries in its summary for pump-driven `object_revealed` synthesis.
`estate_char.live.outbox_enabled`	boolean	`true`	Master switch for headless system-diff mid-verdict streaming via the run-event outbox.
`estate_char.live.outbox_tail_poll_seconds`	integer	`2`	Poll interval for the shared per-run outbox tail that republishes into the hub.

Estate live WebSocket client messages

The client may grow its subscription on the same socket (for example when a new run starts while the theater is already open):

{ "action": "subscribe", "run_id": "ecrun_..." }

{ "action": "subscribe_pair", "pair": "<pair_fingerprint>" }

No acknowledgement is sent and a snapshot is not re-sent for these subscriptions; future deltas for the added run or pair simply start flowing. Any other inbound message is ignored. Typical integration: call POST /api/estate/characterize (optionally after GET /api/estate/discover-schemas to populate the schema picker), open /api/ws/estate/live?run_id=<run_id> with the returned run_id, and drive the theater from object_revealed and phase events. To run a mediated diff, call POST /api/estate/system-diffs and follow the returned run_id or pair_fingerprint on the same socket. To follow a migration pair across characterize → diff → validate runs, connect with ?pair=<pair_fingerprint> and/or send subscribe / subscribe_pair as each new run id appears in the runs feed.

Log streaming WebSocket

Genesis exposes real-time log monitoring at /api/ws/logs. When auth.enabled is true and auth.provider is auth0 or oidc, the client must send a bearer token in the Authorization header or, when auth.allow_query_token is true, in the token query parameter. Connections missing a required token are rejected before the socket is accepted with close code 1008.

Log WebSocket authentication parameters

Field	In	Type	Default	Required	Description
`Authorization`	header	string	none	Conditional	`Bearer <token>` header required when auth is enabled with Auth0 or OIDC, unless the query-token fallback below is allowed and used.
`token`	query	string	none	Conditional	Alternative token parameter accepted only when `auth.allow_query_token` is `true`.

HTTP request tracing header

Genesis includes an X-Request-Id header on HTTP responses. When the same request produces log entries, that value can also appear as request_id in the live-log context payload, making it easier to trace a failing API call back to the matching Pulse log lines.

Pulse clients typically send subscribe_logs and then get_historical on the same socket. Genesis queues matching live entries that arrive during that bootstrap window and emits each entry once after the historical batch returns, skipping duplicates that were already included in the snapshot.

Log WebSocket message types

Type	Direction	Purpose
`subscribe_logs`	client -> server	Start live delivery using the provided `filters` object.
`get_historical`	client -> server	Return a historical snapshot that matches the provided `filters`.
`subscription_confirmed`	server -> client	Confirms a live subscription and echoes the accepted filters.
`historical_logs`	server -> client	Returns `data` as an array of formatted log entries.
`log_entry`	server -> client	Returns one formatted live log entry in `data`.

Genesis also continues to support get_logs, unsubscribe_logs, get_log_levels, and get_log_statistics on the same socket.

Log filter fields

Genesis accepts both timeRange and time_range in log-socket filter payloads. Context filters are exact-match. module_path is prefix-match. For historical snapshots, get_historical accepts an optional top-level limit field. When omitted it defaults to 2000, and Genesis caps it at 2000. The legacy get_logs message continues to accept filters.limit with the same cap.

Field	Type	Used by	Description
`level`	string	`subscribe_logs`, `get_historical`, `get_logs`	Minimum level filter. Supported values include `ALL`, `ERROR`, `CRITICAL`, `WARNING`, `INFO`, `DEBUG`, and `TELEMETRY`. Omit the field or use `ALL` to disable level filtering.
`timeRange` / `time_range`	string	`subscribe_logs`, `get_historical`, `get_logs`	Time window filter. Supported values: `ALL`, `LAST_HOUR`, `LAST_DAY`, `LAST_WEEK`. Omit the field or use `ALL` to disable time filtering.
`search`	string	`subscribe_logs`, `get_historical`, `get_logs`	Case-insensitive search across message text plus contextual fields and `module_path`. Omit the field or send an empty string to disable search.
`bot_id`	string	`subscribe_logs`, `get_historical`, `get_logs`	Exact-match bot filter.
`thread_id`	string	`subscribe_logs`, `get_historical`, `get_logs`	Exact-match thread filter.
`tool_name`	string	`subscribe_logs`, `get_historical`, `get_logs`	Exact-match tool filter.
`origin`	string	`subscribe_logs`, `get_historical`, `get_logs`	Exact-match origin filter.
`phase`	string	`subscribe_logs`, `get_historical`, `get_logs`	Exact-match phase filter.
`module_path`	string	`subscribe_logs`, `get_historical`, `get_logs`	Prefix filter for the dotted module path in formatted entries.
`request_id`	string	`subscribe_logs`, `get_historical`, `get_logs`	Exact-match request filter. Useful with `X-Request-Id`.
`user_id`	string	`subscribe_logs`, `get_historical`, `get_logs`	Exact-match user filter.
`job_name`	string	`subscribe_logs`, `get_historical`, `get_logs`	Exact-match job filter for scheduled or background work when present.

Formatted log entry fields

Field	Type	Description
`timestamp`	string	Log timestamp string returned by Genesis.
`level`	string	Log level such as `ERROR`, `CRITICAL`, `WARNING`, `INFO`, `DEBUG`, or `TELEMETRY`.
`raw_message`	string	Unmodified log message text.
`module_path`	string	Dotted module path derived from the log source.
`file`	string	Source filename or file path when available.
`line`	integer	Source line number when available.
`function`	string	Source function or method name when available.
`context`	object<string, string>	Structured contextual attribution for the log entry.

Known live-log context keys

These keys are present in context only when Genesis can resolve them for the current unit of work.

Field	Type	Description
`origin`	string	High-level source such as HTTP, WebSocket, startup, or background work.
`phase`	string	Optional execution phase identifier.
`request_id`	string	Request correlation identifier that can match `X-Request-Id`.
`bot_id`	string	Bot or agent identifier.
`thread_id`	string	Thread identifier.
`user_id`	string	Authenticated user identifier when available.
`tool_name`	string	Tool name for tool-execution logs.
`tool_call_id`	string	Canonical tool-call identifier when available.
`job_name`	string	Background or scheduler job name when available.
`parent_bot_id`	string	Parent bot identifier for bot-to-bot dispatch.
`parent_thread_id`	string	Parent thread identifier for bot-to-bot dispatch.
`http_method`	string	HTTP method for request-originated logs.
`http_path`	string	HTTP path for request-originated logs.

Sandbox terminal WebSocket

Genesis exposes interactive sandbox terminal access at /api/ws/sandbox-terminal/{session_id}. When auth.enabled is true and auth.provider is auth0 or oidc, the client must send a bearer token in the Authorization header or, when auth.allow_query_token is true, in the token query parameter. Connections missing a required token are rejected before the socket is accepted with close code 1008. On Windows servers, the local Docker terminal and Railway terminal are unavailable because they require a POSIX pseudo-terminal; Kubernetes-backed terminal sessions are not affected. For azure_aci sessions, each WebSocket connection opens a new Azure exec session. Genesis uses the dimensions in the panel’s opening resize frame; if no resize frame arrives within two seconds, it opens at 24 rows by 120 columns. Azure Container Instances fixes the terminal size for that exec session, so later resize frames do not change it. When available, persisted terminal history, including commands previously run by the agent, is sent as binary frames before the JSON session_ready frame with the container_id. New shell output follows as binary frames. If opening a terminal fails because the host does not support pseudo-terminals, Genesis sends a JSON session_error frame with reason: "pty_unsupported", final: true, and relaunch: false before closing the socket. Its message starts with Interactive terminals are not available here: and includes the host error. If attaching to the container fails with an OSError (for example, Docker exec cannot start on the host or the container is unreachable), the frame has reason: "container_unreachable", final: true, and relaunch: true, with the message This sandbox's container is not reachable from here. A final error stops the chat terminal panel from automatically reconnecting to that target.

Sandbox terminal connection parameters

Field	In	Type	Default	Required	Description
`session_id`	path	string	none	Yes	Sandbox terminal session identifier.
`container_id`	query	string	`""`	No	Optional container identifier. If omitted, Genesis tries to resolve the active runtime container for the session.
`shell`	query	string	`"/bin/sh"`	No	Shell to start for new PTY or backend exec sessions.
`Authorization`	header	string	none	Conditional	`Bearer <token>` header required when auth is enabled with Auth0 or OIDC, unless the query-token fallback below is allowed and used.
`token`	query	string	none	Conditional	Alternative token parameter accepted only when `auth.allow_query_token` is `true`.

Direct CLI terminal WebSocket

Genesis exposes a direct terminal for the caller’s own Claude Code workspace at /api/ws/cli-terminal. The connection is accepted only when cli_terminal.enabled is true. With authentication enabled, the caller must also resolve to a user with the use_cli_terminal permission; the bearer token is read from Authorization, or from the token query parameter when auth.allow_query_token is true. The token may be either a JWT or a Genesis Personal Access Token (PAT) beginning with gp_. JWTs are verified against the issuer’s JWKS and checked for expiry, audience, and issuer. PATs are validated against the credential store and resolved to their owner’s user_id. Both token types go through the same use_cli_terminal permission check. Invalid, forged, expired, revoked, unknown, or owner-unverifiable credentials are rejected before the socket is accepted with close code 1008. With authentication disabled, the feature toggle is the only gate, as the deployment has no caller identity to check. Inside a Databricks App, the configured workspace runtime must be kubernetes; the unset runtime defaults to docker, which the App cannot run. If a client reaches the socket with Docker selected, Genesis accepts the socket, sends an error JSON frame explaining that cli_terminal.runtime=kubernetes is needed, then closes it with code 1008.

CLI terminal connection parameters

Field	In	Type	Default	Required	Description
`session`	query	string	`default`	No	Name of the terminal session in the user’s workspace. Reusing a name reattaches to the existing PTY and tmux session.
`term`	query	string	`""`	No	Client terminal type, passed to the workspace so the TUI can use the local emulator’s capabilities.
`cols`	query	integer	none	No	Initial terminal width. Values from `1` through `10000` are accepted.
`rows`	query	integer	none	No	Initial terminal height. Values from `1` through `10000` are accepted.
`caps`	query	string	none	No	Comma-separated client control-frame capabilities. Include `status` to receive workspace-start progress frames; clients that omit it remain compatible with servers that do not send status JSON.
`Authorization`	header	string	none	Conditional	`Bearer <JWT or gp_...>` required when authentication is enabled.
`token`	query	string	none	Conditional	Alternative token parameter accepted only when `auth.allow_query_token` is `true`.

After the socket is accepted, text or binary frames are sent to the PTY as terminal input and terminal output is returned as raw bytes. A text frame containing {"type":"resize","cols":N,"rows":N} changes the PTY size. A resize control frame with invalid values is dropped rather than sent to the PTY; all other text frames are treated as terminal input. The workspace uses named tmux sessions, so the Claude Code process can continue when the client disconnects and be reached again by reconnecting with the same session name. Clients that connect with caps=status receive JSON status control frames while the workspace is attaching. The first frame is {"type":"status","message":"Starting your workspace…","capabilities":["status","redraw"]}; while a cold workspace pod is still starting, Genesis sends a liveness frame every 3 seconds with a message such as Waiting for the workspace pod to be ready… (Ns). These frames are sent before the PTY byte stream begins, and older clients that omit caps=status receive none, so they do not print protocol JSON into the terminal. After the client has received the advertised capabilities, it can request an input-free tmux repaint by sending the control frame {"type":"redraw"}. This refreshes the attached pane without sending a keystroke to the running process. The server also accepts this control frame from clients that already know the protocol. A recognized control frame that cannot be acted on is dropped rather than written to the PTY; text that is not recognized as a control frame is treated as terminal input.

Terminal session ended control frame

When the terminal reader stops, Genesis sends each attached client an error control frame and then closes the WebSocket with close code 1011 and reason terminal session ended. The frame has the following shape:

{"type":"error","message":"<reason>"}

The message explains whether the terminal was closed on the server, the terminal reader stopped, or the workspace running the terminal was restarted or removed. Clients should display the message and let the user reconnect to start a new session. A client that does not handle the control frame still receives the WebSocket close.

Git repository and file endpoints

These endpoints power the Git Browser and Git-backed file delivery APIs. Structured repository operations are mounted under /api/bot-git/v1/.... File and archive delivery routes are mounted under /api/git/... and are also available at /git/... for compatibility links generated elsewhere in Genesis.

Export-related download_url fields, plus chat and thread attachment url/download_url fields for Git-backed files, target these same Git file-serving routes and are returned as root-relative paths on the current origin. In standalone and local deployments they resolve under /api/git/...; in SPCS they resolve under /git/.... Mutable repository files may also carry an optional v query parameter derived from the file’s modification time and size so refreshed payloads bypass stale browser caches after same-path overwrites.

The compatibility /git/... routes are also used by the React Git Browser in SPCS. The same router is mounted at /git/... and /api/git/...; only unprefixed /git/... paths participate in SPA routing. For top-level browser navigations to /git/{repo_id} and non-download /git/{repo_id}/{file_path:path} URLs, Genesis serves the Git Browser SPA shell (index.html) instead of raw file bytes or JSON — including when the path happens to match a repository file. The SPA fetches file content through /api/git/... after it renders, so deep links such as “Open in Git” load the Git Browser instead of a raw 404 or an inline file response.When authentication is enabled, an anonymous browser opening one of these URLs with GET and no Authorization header also receives the SPA shell. The shell contains no repository content; subsequent repository requests still use the normal authentication and Git permission checks. Requests with a rejected Authorization credential are not treated as anonymous page opens.Genesis detects these navigations with the Sec-Fetch-Dest: document header when present. Subresource requests (for example img, iframe, or fetch) that send broad Accept headers are not routed to the SPA shell. Clients that omit Fetch Metadata fall back to the Accept: text/html check.API callers always receive file or JSON responses from /api/git/..., even when they send Accept: text/html. Download requests (?download=true or the /download route) also skip SPA routing on either mount prefix.

When authentication is disabled, Git RBAC checks do not block requests on these routes.

All routes in these Git groups now enforce a system-level Git permission and return 403 Permission denied when the caller lacks that permission. With Git RBAC enabled, direct repository routes also enforce access on the exact repository they serve: read routes require repository view, and write routes require edit or manage where applicable. repo_id must match an existing repository directory exactly; a symlink alias or different casing does not select the repository it points to, and an unknown ID is not treated as a repository.

Git permissions

Permission	Allows
`view_git`	Read-only Git API access: browse directory trees, fetch repository metadata, read file contents for editors, search files, create repository or folder archives, serve files inline, and download files.
`manage_git`	Mutating Git API access: create repositories, manage repository access policies, write files, create folders, move or copy paths, upload or unzip content, and delete repository content.

Shared Git parameters

Field	In	Type	Default	Used by	Description
`path`	path	string	`""`	`GET /api/bot-git/v1/{path:path}`	Relative path under the Git Browser root. An empty path returns the root listing.
`include_metadata`	query	boolean	`false`	`GET /api/bot-git/v1/{path:path}`	Include per-repository metadata when listing the `repos` directory.
`repo_ids`	body	string[]	none	`POST /api/bot-git/v1/repo-metadata-batch`	Repository IDs to fetch in one request. Maximum 50 entries.
`since`	query	string or null	`null`	`GET /api/bot-git/v1/repos/{repo_id}/bundle`	Commit SHA for an incremental Git bundle. Omit for a full-history bundle. If it matches `HEAD`, Genesis returns `304 Not Modified`.
`max_bytes`	query	integer or null	`256000`	`GET /api/bot-git/v1/repos/{repo_id}/file/{file_path:path}`	Maximum bytes returned by the editor read endpoint. Allowed range: `1` to `2000000`.
`max_lines`	query	integer or null	`5000`	`GET /api/bot-git/v1/repos/{repo_id}/file/{file_path:path}`	Maximum lines returned by the editor read endpoint. Allowed range: `1` to `200000`.
`download`	query	boolean	`false`	`GET /api/git/{repo_id}/{file_path:path}`	Force download instead of inline display.
`v`	query	string or null	`null`	`GET /api/git/{repo_id}/{file_path:path}` and `/download`	Optional cache-busting token appended to Genesis-generated links for mutable repository files. Format: `{mtime_ns}-{size}`. The route ignores `v` for authorization and file selection; browsers treat a changed value as a new URL.
`source`	query	string or null	`null`	Git browse, editor-read, archive, and file-serving routes	Optional repo view source selector.
`branch_name`	query	string or null	`null`	Git browse, editor-read, archive, and file-serving routes	Optional branch to open for the resolved repo view.

Read-only Git endpoints

Method	Path	Description	Required permission
`GET`	`/api/bot-git/v1/repos/{repo_id}/metadata`	Return repository metadata for one repository.	`view_git`
`POST`	`/api/bot-git/v1/repo-metadata-batch`	Return metadata for multiple repositories in one request.	`view_git`
`GET`	`/api/bot-git/v1/repos/{repo_id}/bundle`	Stream a Git `.bundle` file for the repository; supports incremental bundles with `since`.	`view_git`
`GET`	`/api/bot-git/v1/repos/{repo_id}/file/{file_path:path}`	Read file content for the editor API.	`view_git`
`POST`	`/api/bot-git/v1/search`	Search file paths and contents across accessible repositories.	`view_git`
`GET`	`/api/bot-git/v1/{path:path}`	Return a directory listing or stream file content from the Git Browser tree. Use `/api/bot-git/v1/repos` to list repositories.	`view_git`
`GET`	`/api/git/{repo_id}/archive`	Download a ZIP archive of a repository.	`view_git`
`GET`	`/api/git/{repo_id}/{folder_path:path}/archive`	Download a ZIP archive of a folder inside a repository.	`view_git`
`GET`	`/api/git/{repo_id}/{file_path:path}`	Serve a repository file inline or as an attachment.	`view_git`
`GET`	`/api/git/{repo_id}/{file_path:path}/download`	Force download of a repository file.	`view_git`

GET /api/git/{repo_id}/archive and GET /api/git/{repo_id}/{folder_path:path}/archive exclude housekeeping paths by default: .archives/, Python caches (__pycache__, *.pyc, *.pyo, *.pyd), OS artifacts (.DS_Store, Thumbs.db), node_modules/, virtual environments (.venv/, venv/), .env and .env.*, .git/, and microapp runtime scratch directories (.microapp_home/, .microapp_state/, .microapp_venv/).

`GET /api/git/{repo_id}/{file_path:path}`

Serves one repository file inline or as an attachment. The convenience /download route is equivalent to ?download=true.

Header	Type	When present	Description
`Cache-Control`	`string`	`200`	`no-store` — prevents intermediaries and browsers from serving stale cached copies of mutable repository files.
`Content-Disposition`	`string`	`200`	`inline; filename="..."` for viewable text, image, and PDF content; otherwise `attachment; filename="..."`. When `download=true`, Genesis always uses `attachment` and serves `application/octet-stream`.

Status	Meaning
`200`	File bytes streamed with the resolved MIME type.
`400`	Resolved path escapes the repository root.
`403`	Caller lacks `view_git` or repository access.
`404`	Repository or file not found.

`GET /api/bot-git/v1/repos/{repo_id}/bundle`

Returns a Git bundle as application/octet-stream. Omit since to create a full-history bundle, or pass since=<commit-sha> to stream only commits after that SHA. If the requested since SHA already matches the repository HEAD, Genesis returns 304 Not Modified with no response body. Both 200 and 304 responses include X-Bundle-Head so clients can track the current repository head commit across incremental syncs. Genesis rejects shallow repositories before building a bundle because partial history cannot produce a complete cloneable bundle. Re-clone the repository without --depth, or run git fetch --unshallow on the existing clone, before retrying the request.

Header	Type	When present	Description
`X-Bundle-Head`	`string`	`200` and `304`	`HEAD` commit SHA at the time Genesis evaluated the request.
`Content-Disposition`	`string`	`200`	Attachment filename such as `customer-onboarding.bundle`.
`Content-Length`	`string`	`200`	Bundle size in bytes.

Status	Meaning
`200`	Binary Git bundle download.
`304`	No changes since the supplied `since` commit.
`409`	Repository is a shallow clone and cannot produce a complete bundle.
`400`	Repository is not git-initialized, `HEAD` could not be resolved, or the supplied `since` commit does not exist in the repository.
`404`	Repository not found.
`500`	Git bundle creation failed.

`GET /api/bot-git/v1/{path:path}`

When the resolved path is a directory, this route returns a JSON directory listing. When the resolved path is a file, it streams the file content instead.

Field	Type	When present	Description
`directories`	`string[]`	Directory responses	Directory names at the requested path.
`files`	`string[]`	Directory responses	File names at the requested path.
`path`	`string`	Directory responses	Resolved path beginning with `/`.
`directory_metadata`	`object` or `null`	Directory responses	Per-repository metadata keyed by directory name. This is populated when listing `/repos` with `include_metadata=true`; each repository’s metadata includes `clone_state` (`"cloning"`, `"incomplete"`, or `null`). `cloning` means a clone into the repository is running; `incomplete` means it has a remote but no checked-out commit, such as after an interrupted clone or for an empty remote. This state is checked on each listing, independently of the repository metadata cache.
`entry_metadata`	`object` or `null`	Directory responses	Best-effort per-entry metadata keyed by entry name. Each entry may include `created_at` (`string` or `null`), `updated_at` (`string` or `null`), and `size_bytes` (`integer` or `null`). `size_bytes` is `null` for directories.

Directory listings include dot-prefixed files and folders (for example .env, .gitignore, and .cursor). Genesis omits Git metadata from listings. Direct requests into .git paths through this Git Browser route return 403 with Access denied: .git directory is off-limits. Git-backed file-serving routes do not serve Git metadata, and mutating repository routes reject paths into it, including paths reached through symlinks. ZIP archive downloads always exclude Git metadata (see the archive endpoints note above).

Mutating Git endpoints

Method	Path	Description	Required permission
`POST`	`/api/bot-git/v1/repos`	Create a repository.	`manage_git`
`GET`	`/api/bot-git/v1/repos/{repo_id}/access`	Return the repository access policy.	`manage_git`
`POST`	`/api/bot-git/v1/repos/{repo_id}/access`	Update the repository access policy.	`manage_git`
`PUT`	`/api/bot-git/v1/repos/{repo_id}/file/{file_path:path}`	Write file content.	`manage_git`
`POST`	`/api/bot-git/v1/repos/{repo_id}/folder`	Create a folder.	`manage_git`
`POST`	`/api/bot-git/v1/repos/{repo_id}/move`	Move a file or folder.	`manage_git`
`POST`	`/api/bot-git/v1/repos/{repo_id}/copy`	Copy a file or folder within one repository.	`manage_git`
`POST`	`/api/bot-git/v1/cross-repo-copy`	Copy a file or folder across repositories.	`manage_git`
`DELETE`	`/api/bot-git/v1/repos/{repo_id}`	Delete a repository.	`manage_git`
`DELETE`	`/api/bot-git/v1/repos/{repo_id}/path`	Delete a file or folder.	`manage_git`
`POST`	`/api/bot-git/v1/repos/{repo_id}/upload`	Upload a file and optionally extract ZIP content.	`manage_git`
`POST`	`/api/bot-git/v1/repos/{repo_id}/upload-batch`	Upload multiple files, preserving supplied relative directories and collision choices.	`manage_git`
`POST`	`/api/bot-git/v1/repos/{repo_id}/unzip`	Extract a ZIP file already stored in the repository.	`manage_git`

`POST /api/bot-git/v1/repos`

Creates a repository under the Git Browser root. The request body accepts these fields:

Field	Type	Default	Description
`repo_id`	string	none	Repository ID. Required.
`repo_type`	string	`storage`	`storage` creates a storage-only repository; `git` initializes Git metadata and creates a Git-backed repository.
`scope`	string	`shared`	Repository access scope.
`owner_user_id`	string or null	`null`	Optional owning user ID.
`owner_bot_id`	string or null	`null`	Optional owning bot ID.
`undeletable`	boolean	`false`	Whether the repository cannot be deleted.

The response includes the effective repo_type read from the repository after creation. A 400 response is returned when repo_type is not storage or git, or when a git repository is requested for a repository ID reserved as storage-only. Existing repository IDs return 409.

`POST /api/bot-git/v1/repos/{repo_id}/upload-batch`

Uploads multiple files as a multipart form. The endpoint requires manage_git and repository edit access. Managed repositories accept writes only when the resolved view is the caller’s WIP view; use source=wip or the corresponding managed-view parameters when selecting that view.

Field	In	Type	Default	Description
`files`	multipart body	file[]	none	Uploaded file bytes. The order must match `manifest`.
`manifest`	multipart form	JSON array	none	One object per file. Each object accepts `name` (string or null), `directory` (string, default `""`), and `collision` (`error`, `replace`, `keep_both`, or `skip`; default `error`).
`target_dir`	multipart form	string	`""`	Repository-relative directory receiving the files.
`upload_id`	multipart form	string or null	`null`	Optional client upload identifier, up to 128 characters, included in the Git tree notification.
`source`	query	string or null	`null`	Optional repository view source selector.
`branch_name`	query	string or null	`null`	Optional branch to open for the resolved repository view.

The response contains results, in file order. Each result includes the requested path, a status of uploaded, conflict, skipped, or failed, and optional saved_path and error fields. When successful files are uploaded to a managed WIP view, commit_hash contains the single local commit created for the batch; commit_error is populated when the files were saved but that commit failed. If any file has a collision with the default error choice, the batch returns conflict results without publishing the batch; retry with an explicit collision choice for each conflict.

Git example requests

curl -X GET "http://<genesis-host>/api/bot-git/v1/repos?include_metadata=true"

curl -X POST http://<genesis-host>/api/bot-git/v1/repo-metadata-batch \
  -H "Content-Type: application/json" \
  -d '{
    "repo_ids": ["customer-onboarding", "shared-prompts"]
  }'

curl -L -X GET "http://<genesis-host>/api/bot-git/v1/repos/customer-onboarding/bundle?since=<commit-sha>" \
  -o customer-onboarding.bundle

curl -X GET "http://<genesis-host>/api/git/customer-onboarding/README.md?download=true"

Bot management endpoints

These routes are mounted under /api/bots/....

Method	Path	Description	Required access
`GET`	`/api/bots`	List agents. By default Genesis returns only active agents the caller can access; optional query flags can include all agents or include disabled agents.	Authenticated caller. `include_all=true` requires `manage_users`; `include_disabled=true` requires `manage_agents`.
`GET`	`/api/bots/deactivated-retention`	Return admin-facing thread-retention summaries for deactivated agents.	`manage_agents`
`GET`	`/api/bots/instruction-blocks/manifest`	Return the toggleable instruction-block manifest used by the agent edit UI.	`manage_agents`
`GET`	`/api/bots/{bot_id}`	Return detailed agent metadata, including the user-facing `bot_intro`, editability, status, instruction render mode, and optional disabled instruction blocks.	Agent access to `bot_id`
`GET`	`/api/bots/{bot_id}/clone-starter`	Return the instruction text that the Copy Agent flow uses to pre-fill `bot_instructions`.	Management rights on `bot_id`
`GET`	`/api/bots/{bot_id}/summary`	Return the aggregated Agent Center overview summary, including status, footprint, reach, recent work, and attention items.	Agent access to `bot_id`
`GET`	`/api/bots/{bot_id}/_debug/rendered-instructions`	Return the fully rendered instruction payload for a bot in debug-enabled environments.	`manage_agents`
`POST`	`/api/bots`	Create a new agent. The creator receives management rights on the new agent.	`manage_agents` or `create_agents`
`PUT`	`/api/bots/{bot_id}`	Update an agent. Built-in or system agents can update instructions, tools, and status, but cannot be renamed. Version-owned agents reject definition changes.	Management rights on `bot_id`
`DELETE`	`/api/bots/{bot_id}`	Soft-delete an agent. Genesis deactivates the agent and either keeps its threads with the deactivated record or moves them to another active agent.	Management rights on `bot_id`
`POST`	`/api/bots/{bot_id}/reset-instructions`	Reset a built-in agent’s instructions to the code default; version-owned definitions cannot be reset by clients.	Management rights on `bot_id`

Genesis refuses agent lifecycle changes that would leave no active agent holding manage_agents. Affected routes return HTTP 409 with error_type last_agents_manager and an error message naming the surviving manager(s) and advising you to grant manage_agents to another active agent first. Attempting to delete built-in Adam or Eve returns HTTP 409 with error_type protected_core_agent instead of soft-deleting them.

Requests that change a version-owned agent definition, including instruction reset, return HTTP 409 with error_type protected_core_agent.

`GET /api/bots`

By default, Genesis returns only active agents the caller can access. When include_disabled=false (the default), Genesis filters out DISABLED agents before applying per-agent access checks.

Field	In	Type	Default	Required	Description
`include_all`	query	boolean	`false`	No	Include all bots. Requires `manage_users`. When `false`, Genesis applies the caller’s agent-access filter.
`include_disabled`	query	boolean	`false`	No	Include disabled bots. Requires `manage_agents`.

The response returns success plus a data array. Fields relevant to list and deactivation-aware UIs include:

Field	Type	Description
`success`	boolean	Whether the list request completed successfully.
`partial`	boolean	`false` when the capability summary is available. `true` when the thread service cannot be reached; the agent list is still returned without the capability-summary values (`default_tool_groups`, `tool_access_mode`, `tool_access_list`, and `resolved_tool_groups`). Defaults to `false`.
`data`	array	Agent list rows.
`data[].bot_id`	`string \| null`	Agent identifier.
`data[].bot_name`	`string \| null`	Agent display name.
`data[].bot_intro`	`string \| null`	Short user-facing description shown in the agents list and the overview hero.
`data[].is_editable`	boolean	Whether the agent can be edited or deleted.
`data[].can_manage`	boolean	Whether the requesting user may edit or delete this agent through global `manage_agents` or a grant on this agent.
`data[].version_owned`	boolean	Whether Genesis owns the agent definition and restores it from the shipped version on upgrade.
`data[].status`	`"ACTIVE" \| "DISABLED"`	Current agent status.

Status	Meaning
`200`	Agent list returned successfully.
`401`	The request did not resolve a caller context.
`403`	The caller requested `include_all=true` without `manage_users`, or `include_disabled=true` without `manage_agents`.
`500`	Agent listing failed on the server.

`GET /api/bots/instruction-blocks/manifest`

Returns success plus a grouped manifest of toggleable instruction blocks that the agent edit UI can render without hardcoding block names.

Field	Type	Description
`success`	boolean	Whether the manifest request completed successfully.
`data.shared`	array	Blocks shown on every agent edit page.
`data.eve_specific`	array	Blocks shown only on Eve’s edit page in structured render mode.
`data.adam_specific`	array	Blocks shown only on Adam’s edit page in structured render mode.

Each block entry contains:

Field	Type	Description
`name`	string	Stable identifier used in `bot_instruction_blocks_disabled`.
`tier`	string	Block tier. Manifest entries are currently optional blocks.
`display_label`	string	Human-readable label shown in the edit UI.
`body`	string	Canonical block text for inline preview.

`GET /api/bots/deactivated-retention`

This admin-only endpoint returns one retention summary per deactivated source agent, ordered newest first by updated_at.

Field	Type	Description
`success`	boolean	Whether the retention-summary request completed successfully.
`data`	array	Deactivated-agent retention summaries.
`data[].bot_id`	string	Deactivated source agent identifier.
`data[].target_bot_id`	`string \| null`	Active destination agent when Genesis moved threads; `null` when threads stayed with the deactivated agent.
`data[].retention_policy`	`"keep_with_agent" \| "move_to_agent"`	Retention policy Genesis applied during the soft-delete.
`data[].moved_thread_count`	integer	Number of threads moved to `target_bot_id`.
`data[].retained_thread_count`	integer	Number of threads kept with the deactivated agent.
`data[].removed_from_index_count`	integer	Number of source-agent threads Genesis removed from the thread-search index during deactivation.
`data[].moved_thread_ids`	`string[]`	Thread identifiers Genesis moved to the destination agent.
`data[].retained_thread_ids`	`string[]`	Thread identifiers Genesis retained on the deactivated agent.
`data[].updated_at`	`string \| null`	When Genesis last updated the retention record.

Status	Meaning
`200`	Retention summaries returned successfully.
`403`	Caller lacks `manage_agents`.
`500`	Retention-summary lookup failed on the server.

Shared bot path parameter

Field	In	Type	Default	Required	Description
`bot_id`	path	string	none	Yes	Agent identifier for the route. Use the exact, case-sensitive value returned by `GET /api/bots` (`Eve` and `eve` are different agents). Agent-keyed RBAC admin routes use the same exact-id rules documented under Agent identifier validation.

`GET /api/bots/{bot_id}`

Returns success plus a data object. Fields relevant to description and instruction editing include: If a bot record has no stored instruction_render_mode, Genesis normalizes the response to structured.

Field	Type	Description
`success`	boolean	Whether the details request completed successfully.
`data.created_at`	`string \| null`	Stored creation timestamp for the bot row. `null` when the backing store has no creation timestamp.
`data.updated_at`	`string \| null`	Stored last-modified timestamp for the bot row. `null` when the backing store has no update timestamp; Genesis never fabricates this value when the details are read.
`data.bot_intro`	`string \| null`	Short user-facing description shown in agent lists and the overview hero.
`data.can_manage`	boolean	Whether the requesting user may edit or delete this agent through global `manage_agents` or a grant on this agent.
`data.version_owned`	boolean	Whether Genesis owns the agent definition and restores it from the shipped version on upgrade.
`data.bot_instructions`	`string \| null`	Stored instructions. For Eve and Adam in structured mode this is the editable persona text, not the fully rendered prompt.
`data.bot_instruction_blocks_disabled`	`string[] \| null`	Optional list of disabled instruction block `name` values that still apply to the bot after Genesis filters out unsupported or non-optional names.
`data.instruction_render_mode`	`"structured" \| "legacy"`	Resolved instruction render mode. Genesis returns `structured` when the stored value is blank or missing; otherwise it reports whether Genesis composes the prompt from structured blocks or treats `bot_instructions` as a legacy full prompt blob.
`data.supports_instruction_reset`	boolean	Whether the bot exposes the reset-to-code-default instruction action.
`data.instructions_are_default`	boolean	Whether the stored instructions currently match the built-in default for that bot.

`GET /api/bots/{bot_id}/clone-starter`

This endpoint does not document any request body or query parameters beyond the shared bot_id path field. It returns success plus a data object with:

Field	Type	Description
`success`	boolean	Whether the clone-starter request completed successfully.
`data.clone_starter_instructions`	string	Instruction text that Genesis uses to pre-fill `bot_instructions` in the Copy Agent flow.

For Eve and Adam, data.clone_starter_instructions is the built-in default persona plus the built-in dynamic instruction block bodies, joined with blank lines in their normal order. For other bots, Genesis returns the stored bot_instructions value after removing any internal [CUSTOM] storage marker.

Status	Meaning
`200`	Clone starter returned successfully.
`403`	Caller lacks management rights on the target bot or agent access to it.
`404`	Agent was not found.
`500`	Clone-starter resolution failed on the server.

`GET /api/bots/{bot_id}/summary`

This endpoint does not document any request body or query fields. It returns success plus a data object with these top-level fields:

Field	Type	Description
`success`	boolean	Whether the summary request completed successfully.
`data.hero`	object	Role statement (derived from a shortened `bot_intro` when set), last meaningful activity, assigned-role count, and allowed Slack-user count.
`data.status`	object	High-level operating state, label, detail, last-activity timestamp, and scope information.
`data.mission`	object	Mission counts, blocked/completed totals, and todo totals.
`data.conversation`	object	Thread counts, unique-user counts, coding-thread counts, observed channels, and conversation scope.
`data.usage`	object	Tool, function, skill, tool-group, data-source, and runtime-usage metrics.
`data.flows`	object	Flow inventory plus recent run counts and latest flow activity.
`data.apps`	object	App totals, deployment/publish counts, and recent app references.
`data.sandboxes`	object	Sandbox availability, session counts, and latest sandbox activity.
`data.reach`	object	Audience metrics such as unique users, public or collaborative threads, observed channels, and scope.
`data.budget`	object	Budget availability, configured budget values, spend totals, and warning or over-budget flags.
`data.recent_work`	array	Ordered recent-work narrative items with `key`, `title`, `detail`, and optional `timestamp_utc`.
`data.attention`	array	Ordered alert items with `severity`, `title`, and optional `detail`.

data.hero.role_statement is populated from bot_intro only. When no description is stored, the field can be null.

Status	Meaning
`200`	Agent summary returned successfully.
`403`	Caller does not have access to the target agent.
`404`	Agent was not found.
`500`	Summary generation failed on the server.

`POST /api/bots`

The caller needs manage_agents or create_agents. A caller with only create_agents receives management rights on the agent created by this request, but cannot edit unrelated agents unless separately granted access. Description- and instruction-related request fields include:

Field	In	Type	Default	Required	Description
`bot_name`	body	string	none	Yes	Bot display name.
`bot_intro`	body	`string \| null`	`null`	No	Short user-facing description shown in agent lists and the overview hero. Maximum length `500`.
`bot_instructions`	body	`string \| null`	`null`	No	Bot instructions (may contain template patterns). Maximum length `250,000` characters.
`bot_instruction_blocks_disabled`	body	`string[] \| null`	`null`	No	Instruction block names disabled for this bot. Genesis persists only optional manifest names that apply to the created bot and ignores unsupported names.
`instruction_render_mode`	body	`"structured" \| "legacy" \| null`	`"structured"`	No	Instruction render mode for structured or legacy prompt composition.

On success Genesis returns success, message, and the created bot_id.

`PUT /api/bots/{bot_id}`

Field	In	Type	Default	Required	Description
`bot_name`	body	string or null	`null`	No	Updated display name. Built-in or system agents keep their existing name even when other fields are updated.
`bot_intro`	body	`string \| null`	`null`	No	Updated short user-facing description shown in agent lists and the overview hero. Maximum length `500`.
`bot_instructions`	body	string or null	`null`	No	Updated agent instructions. Maximum length `250,000` characters.
`bot_instruction_blocks_disabled`	body	`string[] \| null`	`null`	No	Instruction block names disabled for this bot. Genesis persists only optional manifest names that apply to the target bot and ignores unsupported names.
`instruction_render_mode`	body	`"structured" \| "legacy" \| null`	`null`	No	Instruction render mode for structured or legacy prompt composition.
`status`	body	string or null	`null`	No	Agent status. Allowed values: `ACTIVE`, `DISABLED`.

When status changes, Genesis applies a lifecycle transition rather than updating only the database row:

DISABLED — Genesis persists the disabled status, evicts the agent’s live runtime sessions, and rejects new work routed to that agent.
ACTIVE — Genesis persists the active status, rebuilds a usable runtime session before returning success, and returns the agent to normal routing. If runtime startup fails (for example missing LLM configuration), Genesis rolls the status back to DISABLED and returns an error; the agent remains deactivated until reactivation succeeds.

Work already admitted before a deactivation may finish; Genesis does not forcibly cancel an in-progress LLM or tool call. On create and update, bot_instruction_blocks_disabled entries must match the manifest name values returned by GET /api/bots/instruction-blocks/manifest. Genesis only keeps optional block names that apply to the target bot: shared optional blocks for custom agents, plus the matching Eve- or Adam-specific optional blocks for those built-in agents.

Status	Meaning
`200`	Agent updated successfully and returns a human-readable `message`.
`403`	Caller lacks management rights on the target agent.
`404`	Agent was not found.
`409`	`error_type` `last_agents_manager` when setting `status` to `DISABLED` would leave no other active agent holding `manage_agents`; `error_type` `protected_core_agent` when the target is version-owned.
`422`	Request body validation failed.
`500`	Update failed on the server.

`DELETE /api/bots/{bot_id}`

This endpoint uses the shared bot_id path field plus these body fields:

Field	In	Type	Default	Required	Description
`thread_policy`	body	`"keep_with_agent" \| "move_to_agent"`	`"keep_with_agent"`	No	Whether threads remain with the deactivated agent or move to another active agent.
`target_bot_id`	body	`string \| null`	`null`	No	Destination active bot ID when `thread_policy` is `move_to_agent`. Required when moving threads.

This is a soft-delete. Genesis sets the agent status to DISABLED and then applies the requested thread-retention behavior.

With thread_policy="keep_with_agent", Genesis leaves thread files and metadata on the deactivated agent, removes those threads from the thread-search index, and records a deactivated-retention summary.
With thread_policy="move_to_agent", Genesis requires an active destination agent other than the source bot_id, moves thread files and metadata to that agent, reindexes them there, and records the resulting retention summary.

On success, this endpoint returns success and message.

Status	Meaning
`200`	Agent deactivated successfully and returns a human-readable `message`.
`403`	Caller lacks management rights on the target agent.
`404`	Source agent or requested `target_bot_id` was not found.
`409`	`error_type` `last_agents_manager` when this deactivation would leave no other active agent holding `manage_agents`; `error_type` `protected_core_agent` when deleting built-in `Adam` or `Eve`, another non-editable system agent, or a version-owned agent.
`422`	Request body validation failed, such as `thread_policy="move_to_agent"` without `target_bot_id`.
`500`	Deactivation or thread-retention processing failed on the server.

`POST /api/bots/{bot_id}/reset-instructions`

This endpoint does not accept a request body. On success Genesis returns success and message. For Eve and Adam specifically:

In structured mode, reset restores the default persona text and keeps the current bot_instruction_blocks_disabled selections.
On the legacy editing path, reset restores the default persona text, switches instruction_render_mode back to structured, and clears the disabled-block list.

`GET /api/bots/{bot_id}/_debug/rendered-instructions`

This diagnostic route requires manage_agents and returns 403 unless ENABLE_BOT_INSTRUCTIONS_DEBUG=true is set before startup.

Field	Type	Description
`bot_id`	string	Bot identifier.
`rendered`	string	Fully rendered instruction payload after structured or legacy composition.
`render_mode`	string	Resolved instruction render mode used for this bot.
`is_persona_carve_out_bot`	boolean	Whether the bot uses persona-only structured instructions (`Eve` or `Adam`).
`decided_path`	string	Render path name. Current values are `structured-shared`, `structured-eve-adam`, or `legacy-blob`.
`disabled_blocks`	string[]	Resolved disabled block names after parsing stored config.
`block_breakdown`	array	Per-block diagnostic rows.
`stored_bot_instructions_length`	integer	Length of the stored `bot_instructions` value.
`stored_bot_instructions_hash`	string	SHA-256 hash of the stored `bot_instructions` value, prefixed with `sha256:`.
`addendum_legacy_match_check`	object	Stored-instructions markers such as `stored_has_custom_prefix`.

Each block_breakdown row contains:

Field	Type	Description
`name`	string	Block name.
`tier`	string	Block tier.
`gate_passed`	boolean	Whether runtime gating allowed the block to participate in rendering.
`disabled_via_toggle`	boolean	Whether the block was disabled by `bot_instruction_blocks_disabled`.
`present_in_output`	boolean	Whether the block text appears in the rendered prompt.
`length`	integer	Rendered block length in characters.
`byte_offset`	integer	Byte offset where the block begins in `rendered`.

Context Control endpoints

These routes are mounted under /api/context-control/.... They back Agent Center capability controls and the Thread Details model/context drawer, and they require agent access to the target bot_id.

Method	Path	Description	Required access
`GET`	`/api/context-control/threads/{bot_id}/{thread_id}/active`	Return the thread’s effective active tool groups, skills, and merged policy state.	Agent access to `bot_id`
`POST`	`/api/context-control/threads/{bot_id}/{thread_id}/preview`	Preview a context-change patch without persisting it.	Agent access to `bot_id`
`POST`	`/api/context-control/threads/{bot_id}/{thread_id}/apply`	Apply a context-change patch to the thread.	Agent access to `bot_id`
`DELETE`	`/api/context-control/threads/{bot_id}/{thread_id}/active`	Clear the thread’s saved active tool groups, skills, and other thread-scoped context overrides so the thread falls back to the bot’s defaults.	Agent access to `bot_id`
`GET`	`/api/context-control/bots/{bot_id}/defaults`	Return the bot’s saved thread-start defaults.	Agent access to `bot_id`
`PUT`	`/api/context-control/bots/{bot_id}/defaults`	Replace the bot’s saved thread-start defaults.	Manage rights on `bot_id` (`manage_agents`, or a `manage` grant on the agent)
`GET`	`/api/context-control/capabilities/{bot_id}/catalog`	Return the bot’s full capability catalog for tools, skills, and blueprints.	Agent access to `bot_id`
`GET`	`/api/context-control/capabilities/{bot_id}/defaults`	Return the bot’s resolved default capability policy.	Agent access to `bot_id`
`GET`	`/api/context-control/capabilities/{bot_id}/search`	Search the capability catalog for tools, skills, or blueprints.	Agent access to `bot_id`
`GET`	`/api/context-control/threads/{bot_id}/{thread_id}/budget`	Return the thread context-budget card used by the Thread Details panel (usage buckets, compression summary, thread cost totals). Heavy modal-only arrays are omitted.	Agent access to `bot_id`
`GET`	`/api/context-control/threads/{bot_id}/{thread_id}/budget-details`	Return per-request breakdown buckets (system prompt, tool specs, tool I/O, and related entry counts) for the request-details modal.	Agent access to `bot_id`
`GET`	`/api/context-control/threads/{bot_id}/{thread_id}/budget-history`	Return modal-only compression events and per-model pricing rows. Fetched lazily when a client opens pricing or compression-history modals.	Agent access to `bot_id`

GET /api/context-control/capabilities/{bot_id}/catalog reflects AgentSkills imports and deletions immediately after a successful POST /api/agent-skills/import or DELETE /api/agent-skills/{skill_name} call. Clients do not need to wait for the capability-registry reconcile interval before refreshing the catalog.

DELETE /api/context-control/threads/{bot_id}/{thread_id}/active does not accept a request body. On success Genesis returns success: true plus data.cleared to indicate whether any thread-scoped context state was removed.

Shared context patch body fields

These fields are accepted by the preview/apply/defaults patch routes:

Field	In	Type	Default	Required	Description
`model_tier`	body	`"frontier" \| "main" \| "fast" \| null`	`null`	No	Optional thread or bot-default model tier override.
`active_tool_groups`	body	`string[] \| null`	`null`	No	Tool groups to activate for the thread or auto-load as bot defaults.
`active_skills`	body	`string[] \| null`	`null`	No	Skills to activate for the thread or auto-load as bot defaults.
`tool_access_mode`	body	`"all" \| "allowlist" \| "denylist" \| null`	`null`	No	Tool-policy mode applied with the patch.
`tool_access_list`	body	`string[] \| null`	`null`	No	Tool groups referenced by `tool_access_mode`.
`skill_access_mode`	body	`"all" \| "allowlist" \| "denylist" \| null`	`null`	No	Skill-policy mode applied with the patch.
`skill_access_list`	body	`string[] \| null`	`null`	No	Skills referenced by `skill_access_mode`.
`tool_profile_overrides`	body	`object \| null`	`null`	No	Optional map of tool name to profile label.
`context_budget_policy`	body	`object \| null`	`null`	No	Optional context-budget hints applied with the patch.
`never_compress_skills`	body	`string[] \| null`	`null`	No	Bot-defaults route only. Default skills whose injected text thread compression keeps in full; each must be one of the bot’s default skills, and adding beyond `context_management_improvements.max_never_compress_skills_per_agent` (default 3) is refused with `400`.

Policy-disallowed tool groups or skills now return 400 with structured details instead of being silently stripped from the patch. Bot-default updates also return 400 when active_tool_groups would auto-load more than 12 tool groups by default. Operators can raise or lower that auto-load cap with CONTEXT_DEFAULTS_MAX_TOOL_GROUPS. There is no default cap on the total number of tool functions those groups contain — the provider function cap is the only ceiling, and it is enforced at thread preflight (409).

Thread preview/apply requests that name a policy-authorized channel-bound tool group whose runtime adapter cannot dispatch also return 400. Their structured details include unavailable_tool_groups, mapping the group name to the runtime reason; this is distinct from policy_rejected_tool_groups. For the corresponding persistent bot-default behavior, see Data Agent Creation Tools.

Tool-group policy checks (including tool_access_mode="all") validate against the loadable universe: the capability catalog union the live runtime tool-group registry. MCP-backed groups that register after the startup catalog reconcile (for example lineage_tools) remain activatable and assignable to defaults without spurious not_in_policy rejections while the catalog snapshot is still catching up. After validation, tool_access_list and active_tool_groups are persisted exactly — including explicit empty allowlists or denylists — even when the searchable capability index is temporarily empty or stale. Partial bot-default patches that omit policy fields leave existing tool_access_mode, tool_access_list, and active_tool_groups unchanged.

Agents calling the set_bot_context_defaults or set_bot_capability_policy tools in Data Agent Creation Tools receive the same structured rejection payload in the tool response details field (for example rejected_skills and access-mode context), not only the collapsed error string returned by the HTTP middleware for dashboard clients.

Status	Meaning
`200`	Context-control request completed successfully.
`400`	Patch was invalid, requested groups or skills outside the allowed policy, or exceeded the bot-default auto-load cap.
`403`	Caller does not have access to the target agent.
`409`	Thread preflight failed, such as exceeding the provider function cap for the selected active set.
`422`	Request body validation failed.

When a thread preflight exceeds the provider function cap, the 409 response’s details includes provider_limit, active_function_count, over_by, and a remediation object. remediation.message gives the recovery guidance; suggested_groups_to_disable lists optional groups with tool_group, function_count, and just_requested; required_by_active_skills lists groups required by active skills with tool_group, function_count, skills, and just_requested_skills. When previous state is available, just_requested marks a newly active group and just_requested_skills names newly active skills that require the group. Required groups are not offered for removal. If the always-on and skill-required functions alone exceed the limit, the suggestions are empty and the message explains why removing optional groups cannot help.

Context budget read endpoints

These routes do not accept request bodies. On success each returns success: true plus a data object. /budget and /budget-details resolve data.context_limit_tokens through the same pipeline so both endpoints always report the same limit for a thread. Genesis resolves the limit in order: the live trimmer when the thread is in-process (its soft limit already folds in per-request, per-thread, per-bot, and environment overrides), the thread’s persisted soft_limit_tokens property when set, the resolved model’s hard context limit, or — only when all three steps fail — a conservative 200000 default. data.context_limit_source records which step produced the limit:

`context_limit_source`	Meaning
`live_trimmer_soft_limit`	Limit from the in-process intelligent trimmer.
`thread_soft_limit_tokens`	Limit from the thread’s persisted `soft_limit_tokens` property.
`model_context_limit`	Limit from the resolved model name (for example `300000` for Claude Opus 4.x).
`unresolved_default`	No earlier step produced a limit; `context_limit_tokens` is the `200000` last-resort default.

`GET /api/context-control/threads/{bot_id}/{thread_id}/budget`

Returns the always-polled context-budget payload for the Thread Details panel. To keep large or heavily compressed threads responsive, Genesis omits heavy modal-only arrays from this response:

data.compression_history carries summary fields (count, total_event_count, visible_event_count, latest_event, average_reduction_pct) but not the per-event list. count matches visible_event_count (rows returned). total_event_count is the monotonic lifetime compression count for the thread (from persisted compression_history_event_count when set).
data.thread_cost_summary carries thread cost totals but not pricing_details. estimated_cost_usd is known-priced cost: calls without a known price add nothing, so when unpriced_call_count is greater than zero, render the cost as partial beside that count. The summary also includes pricing_details_available (boolean, default false) to signal whether GET .../budget-history will return per-model pricing rows, and unavailable (boolean, default false), which is true when a dependency required to determine the totals failed; in that case the numeric fields are schema-default zeros and clients must render them as unknown rather than as a zero cost.

Other notable data fields include bot_id, thread_id, source, context_limit_tokens, context_limit_source, current_usage_pct, current_total_tokens, usage buckets such as system_prompt and conversation, compression_history, projected_next_call, last_actual_call, and thread_cost_summary totals (input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, cache_total_tokens, cache_rate_pct, estimated_cost_usd, unpriced_call_count). The payload also includes reactive_effective_ceiling_tokens, the ceiling targeted by reactive compression after applying the resolved hard limit and configured or default soft limit, plus reactive_effective_ceiling_source identifying how that ceiling was resolved.

`GET /api/context-control/threads/{bot_id}/{thread_id}/budget-history`

Returns modal-only history payloads. Clients should call this lazily when opening the Pricing Used for Estimated Cost or compression-history modals, not on every panel refresh.

Field	Type	Description
`data.compression_history`	object	Compression overview: `count` (integer, default `0`, matches visible rows), `total_event_count` (integer, default `0`, lifetime passes for the thread), `visible_event_count` (integer, default `0`), `latest_event` (object or null), `average_reduction_pct` (float, default `0.0`, clamped to `>= 0` when returned). Does not include the per-event list.
`data.compression_events`	array	Compression event list (same shape as each `latest_event` entry). Default `[]`. Each event’s top-level `reduction_pct` is clamped to `>= 0`. Top-level `event_sequence` (integer or null, `>= 1`) is the monotonic pass number; `compression_number` mirrors it when set. Optional nested `raw` diagnostics use the compact persisted schema (`schema=compact_v1`) and can include `chat_model` (or legacy `thread_effective_model_name`), `thread_model_tier`, `thread_model_provider`, `summary_llm_model` (or `summary_llm_model_override`), `summary_llm_engine` (or `summary_llm_engine_override`), `summary_rollup_fallback_used`, `llm_summary_used_delta`, and `llm_summary_fallback_delta`.
`data.thread_cost_summary`	object	Thread cost totals with the same scalar fields as `/budget`, plus `pricing_details_available` (`boolean`, default `false`) and `unavailable` (`boolean`, default `false`). When `unavailable` is `true`, a dependency required to determine the totals failed; numeric fields are schema-default zeros and must be treated as unknown, not as a zero cost. Does not embed `pricing_details`.
`data.pricing_details`	array	Per-model pricing rows. Default `[]`. Each item includes `model` (string, default `"default"`), `provider` (string or null), `source` (string, default `"default"`), `pricing_per_million` (`input`, `output`, `cache_read`, `cache_write` floats per 1M tokens), token counts (`input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens`), and `estimated_cost_usd` (float, default `0.0`). `source` is one of `config` (operator-set `pricing.model_overrides`), `litellm`, `override` (Genesis hardcoded gap-fill), or `default`.

`GET /api/context-control/threads/{bot_id}/{thread_id}/budget-details`

Returns request-breakdown buckets for the request-details modal (for example system_prompt, tool_specifications_effective, tool_calls_and_results, and related entry counts). This route is separate from /budget-history and is not trimmed for modal lazy loading. data.context_limit_tokens and data.context_limit_source use the same resolution pipeline as /budget (see the table above). It also returns data.reactive_effective_ceiling_tokens and data.reactive_effective_ceiling_source, which expose the ceiling actually targeted by reactive compression after the hard and configured or default soft limits are resolved.

Document index management endpoints

These routes are mounted under /api/indexes/... and require the manage_document_indexes permission.

Method	Path	Description	Required permission
`POST`	`/api/indexes/{index_name}/documents`	Accept a document for background indexing; returns HTTP `202` and an `operation_id`. See Manage Document Indexes over REST for request and response details.	`manage_document_indexes`
`GET`	`/api/indexes/{index_name}/uploads`	List queued, indexing, and recently finished uploads for an index.	`manage_document_indexes`
`DELETE`	`/api/indexes/{index_name}`	Start background deletion of a document index from every embedding-model collection that holds it, and return a delete-operation handle.	`manage_document_indexes`
`GET`	`/api/indexes/{index_name}/delete-impact`	Return which knowledge bases reference the index and which currently assigned agents would be affected by deleting it.	`manage_document_indexes`
`GET`	`/api/indexes/operations/{operation_id}`	Poll the status of a background document-index delete operation.	`manage_document_indexes`

Shared document-index path parameters

Field	In	Type	Default	Required	Description
`index_name`	path	string	none	Conditional	Document index name used by delete and delete-impact routes.
`operation_id`	path	string	none	Conditional	Background delete operation identifier used by the status route.

`DELETE /api/indexes/{index_name}`

This endpoint does not document any request body fields. It returns these top-level fields:

Field	Type	Description
`success`	boolean	Whether the delete request was accepted.
`operation_id`	string	Background delete operation identifier.
`index_name`	string	Index being deleted.
`status`	string	Initial operation status. Allowed values: `pending`, `in_progress`, `completed`, `failed`.
`progress`	integer	Initial progress percentage.
`current_step`	string	Human-readable delete stage.
`message`	string	Status message for the accepted delete request.

Status	Meaning
`202`	Delete accepted and queued or started in the background.
`404`	Index was not found in any active or stranded embedding-model collection.
`409`	A delete for the same index is already in progress.
`500`	Genesis failed to start the background delete.

`GET /api/indexes/{index_name}/delete-impact`

This endpoint does not document any request body or query fields. It returns success plus a data object with these fields:

Field	Type	Description
`success`	boolean	Whether the delete-impact lookup completed successfully.
`data.index_name`	string	Index being inspected.
`data.knowledge_base_count`	integer	Number of knowledge bases that reference this index.
`data.assigned_bot_count`	integer	Number of unique currently assigned agents affected through enabled knowledge-base assignments.
`data.assigned_bot_ids`	array	Agent IDs currently affected through enabled knowledge-base assignments.
`data.knowledge_bases`	array	Impacted knowledge bases. Each item includes `knowledge_base_id`, `title`, `enabled`, and `assigned_bot_ids`.

Status	Meaning
`200`	Delete-impact details returned successfully, including the zero-impact case.
`500`	Impact inspection failed on the server.

`GET /api/indexes/operations/{operation_id}`

This endpoint does not document any request body or query fields. It returns these top-level fields:

Field	Type	Description
`success`	boolean	Whether the status lookup completed successfully.
`operation_id`	string	Background delete operation identifier.
`index_name`	string	Index tied to the operation.
`status`	string	Current operation status. Allowed values: `pending`, `in_progress`, `completed`, `failed`.
`progress`	integer	Current progress percentage.
`current_step`	string	Human-readable current step.
`started_at`	string or null	ISO-8601 timestamp for when deletion started.
`completed_at`	string or null	ISO-8601 timestamp for when deletion completed.
`error_message`	string or null	Failure reason when `status` is `failed`. May list embedding-model collection names that still hold the index and instruct you to retry the delete.

Status	Meaning
`200`	Delete-operation status returned successfully.
`404`	Operation ID was not found.
`500`	Status lookup failed on the server.

Additional admin endpoints

These routes live outside the Blueprint and Git groups but are part of common RBAC, agent-import, and app-import flows.

User avatars

POST /api/avatars/upload uploads the signed-in user’s PNG, JPG, JPEG, GIF, or WebP image (maximum 2 MB). DELETE /api/avatars removes that user’s avatar; GET /api/avatars/{user_id} serves an image or returns 404 when none exists, and GET /api/avatars/{user_id}/info reports whether one is present. On Databricks Apps with durable storage enabled, uploaded avatars survive host replacement. See Deploying Genesis on Databricks — Durable SQLite stores. If durable storage cannot record avatar deletion during DELETE /api/rbac/users/{user_id}, Genesis returns 503 and does not delete the user; retry the request. Configuration profile names used with /api/config/profiles/{name} must be plain file names: they cannot start with ., or contain /, \, or ...

Method	Path	Description	Required permission
`GET`	`/api/rbac/users`	List users with their assigned roles and identity fields. The `display_name` field uses the provider-aware display identity; for Snowflake users, a stored placeholder is replaced by the provider username when available.	`manage_users`
`GET`	`/api/rbac/roles`	List all available roles with their permissions.	`manage_users`
`GET`	`/api/rbac/permissions`	List all available permissions with short descriptions and optional extended tooltip text.	Authentication only
`GET`	`/api/rbac/microapps`	List all microapps available for role access management, including unpublished apps. Each item includes `app_id`, `title`, `published`, `created_by`, and normalized `tags`.	`manage_users`
`POST`	`/api/bots/import/validate`	Validate an agent ZIP file before importing.	`manage_agents` or `create_agents`
`POST`	`/api/apps/import/validate`	Validate a GenesisApp ZIP file before importing.	`manage_skills`
`POST`	`/api/admin/demo-data/purge`	Hide bundled demo legacy database connections and evict their Twin demo entries.	`manage_all_connections`
`POST`	`/api/bot-directories/cleanup`	Clean up bot-thread directories that do not match the bot registry.	`manage_all_threads`
`POST`	`/api/admin/environment-snapshot/export`	Download an in-memory, scrubbed ZIP inventory of deployment configuration and topology.	`access_config_panel`, `view_agents`, `view_users`, and `view_connections`
`POST`	`/api/admin/state-snapshots`	Queue a full-fidelity S3 or GCS state snapshot while the instance pauses and hands the container to the exporter.	`access_config_panel`, `view_agents`, `view_users`, `view_connections`, `manage_secrets`, `manage_all_connections`, and `manage_scheduler`
`GET`	`/api/admin/state-snapshots`	List this instance’s state snapshot jobs, newest first.	`access_config_panel`, `view_agents`, `view_users`, and `view_connections`
`GET`	`/api/admin/state-snapshots/{job_id}`	Return one state snapshot job’s progress and outcome.	`access_config_panel`, `view_agents`, `view_users`, and `view_connections`
`POST`	`/api/admin/export-state`	Stream a RAW full-fidelity instance snapshot tar for the golden-image pipeline.	Demo mode; Genesis staff or valid internal token
`POST`	`/api/admin/export-content`	Stream a human-readable export of the instance’s work (JSON, YAML, Markdown, HTML, or tar.gz).	Demo mode; Genesis staff or valid internal token
`POST`	`/api/admin/export-microapps`	Stream a tar.gz of microapp workspaces (source-only by default).	Demo mode; Genesis staff or valid internal token
`GET`	`/api/admin/audit-log`	List admin audit events with cursor pagination and optional filters.	`access_config_panel`
`GET`	`/api/admin/audit-log/{audit_id}`	Fetch one admin audit event by `audit_id`.	`access_config_panel`
`GET`	`/api/admin/durability/report`	Report whether declared durable state came back after restore and list any findings.	Admin only
`POST`	`/api/admin/durability/confirm-deletes`	Confirm the exact refused deletes shown for a durable-storage root.	Admin only
`GET`	`/api/admin/slots`	Return full agent slot usage including user identity fields.	`access_config_panel`

`GET /api/rbac/users` response fields

The response contains success and a users array. Each user item includes the following identity and role fields:

Field	Type	Description
`user_id`	string	User’s unique identifier.
`email`	string or null	User’s email address.
`display_name`	string or null	Provider-aware display identity. For Snowflake users, Genesis uses `provider_data.username` when the stored display name is the subject or a `Snowflake User (...)` placeholder and a username is available.
`roles`	string[]	Roles assigned to the user.
`scim_managed`	boolean	Whether the user’s roles are managed by SCIM.
`scim_active`	boolean or null	Whether the SCIM-managed user is active.

`POST /api/admin/export-state`

Streams application/x-tar with Cache-Control: no-store, private. The archive is full-fidelity (no secret scrubbing) and contains metadata.json, a consistent SQLite backup as genesis.db, and directory trees bot_storage/ and bot_git/. Repository .git directories are stored under _dotgit_ arcnames (the golden-image build renames them back). Apply a downloaded archive locally with uv run import-state while the Genesis server is stopped. When packing bot_storage/ and bot_git/, Genesis omits regenerable microapp build artifacts: any member whose path includes a .microapp_venv, .microapp_home, or __pycache__ directory component is dropped, pruning the whole subtree. Authored source next to those directories is still included; virtualenvs are rebuilt on provision or first app start. For a workspace export that can optionally include packed virtualenvs, use POST /api/admin/export-microapps with include_venv=true. The export also omits the top-level bot_storage/upgrade-summaries/ directory. It contains the exporting installation’s post-upgrade-advisor baseline and summaries, which should not be carried into a golden image and treated as the new installation’s own upgrade state. When durable GenesisApp state is available, the export restores each registered app’s kept state into its local workspace before building the archive. An app whose workspace is not on disk, whose runtime is active, or whose state cannot be restored is not restored by this step; a restore failure is logged and does not prevent the export. Restoring state can add catalog checks and one volume download per state file to the export time.

Status	Meaning
`200`	Binary tar download (`Content-Disposition` attachment filename `genesis-state-<instance>-<utc>.tar`).
`403`	Deployment is not in demo mode, or the caller is not Genesis staff and did not present a valid internal token.

This endpoint remains the full-fidelity tar export for the golden-image pipeline. For incremental snapshots in the Helm chart’s PVC layout, use the uv run export-state CLI described in Incremental object-store snapshots.

`POST /api/admin/state-snapshots`

Queues a full-fidelity, incremental snapshot of this instance to an s3:// or gs:// destination and returns HTTP 202 with success: true and a job record. The request validates the destination and master key before it queues the job. For SQLite metadata, it also checks the available space needed for the database copy. Snowflake-mode instances have no local database for that check; Genesis converts their Snowflake metadata to genesis.db while the exporter runs. If that conversion fails, the job fails after the server has stopped and the instance starts again. After the response is sent, Genesis stops the server, runs the exporter while the state is quiescent, and starts the server again. The server may therefore be unavailable briefly while the snapshot runs; poll the job instead of retrying the request. See State Snapshots and Migration for the Snowflake migration workflow and conversion report. The caller must hold all seven permissions: access_config_panel, view_agents, view_users, view_connections, manage_secrets, manage_all_connections, and manage_scheduler. The confirm value must equal this instance’s name.

Field	In	Type	Default	Required	Description
`destination`	body	string	none	Yes	S3 or GCS prefix, for example `s3://bucket/genesis/<instance>` or `gs://bucket/genesis/<instance>`.
`region`	body	string or null	`null`	No	AWS region of an S3 bucket; unused for GCS.
`kms_key_id`	body	string or null	`null`	No	KMS key for S3 objects; required when restoring in another AWS account. GCS uses the bucket’s default encryption and rejects this field.
`aws_connection`	body	string or null	`null`	No	Genesis AWS connection used for an S3 upload. Omit it to use the pod’s own identity. Role-based AWS connections are not supported for this request, and this field requires an `s3://` destination.
`gcp_connection`	body	string or null	`null`	No	Genesis GCP service-account connection used for a GCS upload. Omit it to use the pod’s own identity, and provide this field only with a `gs://` destination.
`confirm`	body	string	none	Yes	This instance’s name; the request stops the server while the snapshot runs.

Example request:

curl -X POST https://<genesis-host>/api/admin/state-snapshots \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "destination": "s3://my-bucket/genesis-snapshots/<instance>",
    "region": "us-west-2",
    "kms_key_id": "<customer-managed-kms-key-id>",
    "confirm": "<instance>"
  }'

While the exporter owns the container, GET /api/healthcheck and GET /api/health/live remain available. GET /api/admin/state-snapshots/current returns unauthenticated progress for the running job; other requests receive 503 with Retry-After: 30. Once the server restarts, use the authenticated job endpoints below for the destination, transfer statistics, snapshot ID, object count, byte count and any error.

Status	Meaning
`202`	Job validated and queued; the server stops after sending the response.
`400`	Unsupported destination, invalid confirmation, unsupported metadata mode, or insufficient local space for a SQLite metadata copy.
`403`	Caller lacks one or more required permissions.
`409`	Another state snapshot is already waiting to run.
`503`	The destination, rclone, or master key is unavailable.

Completed snapshots can be restored into an empty Helm PVC with the chart’s restore.from setting; see Restoring an object-store snapshot for the deployment configuration and verification behavior.

`GET /api/admin/state-snapshots`

Returns success: true with a jobs array, newest first. Each job has a status of pending, running, succeeded, failed, or aborted, plus its request and completion timestamps, current phase, transfer statistics, and result fields when available. A job can include warning when Genesis cannot confirm that no stored secrets remain under a bound previous master key. The snapshot still completes, but restoring it requires that key to be bound too; wait until re-sealing leaves no secrets under the previous key and take a new snapshot to avoid that requirement. Genesis retains the newest 50 finished job records.

`GET /api/admin/state-snapshots/{job_id}`

Returns success: true with one job record using the same fields as the list response. A missing job ID returns 404.

`POST /api/admin/environment-snapshot/export`

Returns a timestamped application/zip download named genesis-environment-snapshot-<UTC timestamp>.zip. The archive is assembled in memory and is not written to deployment storage. Genesis also returns X-Genesis-Snapshot-Export-Id, a unique identifier for the export, and marks the response Cache-Control: no-store, private with Pragma: no-cache. The caller must hold all four permissions: access_config_panel, view_agents, view_users, and view_connections. The endpoint does not broaden access to any of the domains it inventories. The ZIP contains this fixed file set:

File	Contents
`manifest.json`	Schema and collector versions, export ID, timestamps, section availability and counts, file hashes and sizes, plus inclusions and exclusions.
`runtime.json`	Genesis version/build, deployment mode, SPCS indicator, metadata database mode, server environment and authentication state.
`agents.json`	Agent identity and status, effective LLM selection, runner ID, and a system-instruction hash; instruction bodies are excluded.
`skills.json`	Installed skill identity, versions, status, source, tool groups and default assignment; skill bodies are excluded.
`rbac.json`	Roles, permissions, role-to-agent access, role inheritance and pseudonymized principal-to-role relationships.
`connections.json`	Connection metadata, scope, auth/delegation mode, access intent, credential-category presence booleans and egress readiness; locator and OAuth material are excluded.
`approvals.json`	An explicit unavailable result because Genesis has no authoritative organization-wide approval-policy domain.
`blueprints.json`	Blueprint identity, source and version/deployment metadata; blueprint bodies and source repository URLs are excluded.
`app-config.redacted.json`	Schema-driven projection of non-secret scalar application configuration, with secret-marked and opaque fields listed as omitted.
`redaction-manifest.json`	Collector/redactor versions, allowlisted projection strategy, exclusion counts, scrub-match counts and section allowlists.
`README.md`	Scope, handling guidance and the v1 limitations.

The export contains no credentials, secret values or raw secret references; no conversation, mission, SQL, tool, log, attachment or database content; and no email addresses, usernames or session identifiers. It can include operator-chosen skill, agent, connection, role and blueprint names, hostnames, account identifiers, and other non-secret configuration values, so treat it as customer-confidential diagnostic material rather than an anonymized export or a backup. A section that is unavailable is represented with available: false and a reason; a collection failure aborts the export instead of producing a partial archive.

Status	Meaning
`200`	Binary ZIP download with the fixed v1 file set.
`403`	Caller does not hold all four required permissions.

GET /api/rbac/roles surfaces the same top-level workspace permissions used by the authenticated UI. Role payloads can therefore include permissions such as view_apps, view_context_graph, view_deployments, view_flows, view_scheduler, and view_sandboxes, which drive primary workspace visibility when authentication is enabled. Role payloads can also include opt-in permissions such as view_shared_role_resources, which lets members of the same team-style role see each other’s missions and apps without manual invitations; view_all_blueprints and manage_all_blueprints, which grant blueprint-wide access without per-blueprint grants; and the category-scoped PAT permissions (access_pat_connections_databases, access_pat_connections_git, access_pat_connections_cloud, access_pat_connections_pipelines, access_pat_connections_tools), which control PAT-class saved connection modes such as pat, api_token, and api_key for connectors in each category. Built-in roles do not include view_shared_role_resources by default.GET /api/rbac/permissions returns success plus a permissions array. Each permissions[] item includes name (string), description (string | null), and extended_description (string | null). The short description is what the Config → Users & Roles permissions panel renders under each permission name; extended_description, when present, is shown as a hover or keyboard-focus tooltip via a ? icon next to the short line. Permissions without a server-side description are displayed in the UI as readable text derived from the permission name. No RBAC permission is required beyond authentication.GET /api/rbac/microapps returns success plus a microapps array. Each microapps[] item includes app_id (string), title (string), published (boolean), created_by (string | null), and tags (string[]). Genesis normalizes tags to non-empty strings so API clients can offer tag-based bulk selection without additional cleanup.

Current user permissions

Method	Path	Description	Required permission
`GET`	`/api/rbac/me/permissions`	Return the authenticated user’s `user_id`, `roles`, `permissions`, `is_admin`, and access-onboarding fields (`onboarding_state`, `onboarding_locked`, `one_on_one_pending`, and related keys). Used by the UI shell and API clients to bootstrap navigation and permission gating.	Authentication only

When Access Preview is active for an admin caller, roles and permissions reflect the request-scoped preview role set (from the UI or X-Genesis-Access-Preview-Roles), and is_admin is false because the built-in admin role cannot be included in preview. user_id always returns the caller’s persisted identity. For the built-in user role’s source-contract grant, see the RBAC in Genesis → User.

Status	Meaning
`200`	Permissions payload returned successfully.
`401`	Caller is not authenticated.

One-on-one and agent-memory endpoints

These routes back onboarding check-ins, weekly one-on-one cadence, and the per-agent memory documents surfaced in chat. Checklist topic_key values are workspace-configured stable identifiers. Read them from GET /api/rbac/me/one-on-one-status before updating progress; unknown keys are rejected with an error that lists the valid required or optional keys.

Method	Path	Description	Required permission
`GET`	`/api/rbac/me/one-on-one-status`	Return the lead agent’s required and optional checklist topics (`topic_key`, `label`, `completed`, `required`), completion gates, weekly cadence fields, and onboarding lock state for the authenticated user.	Authentication only
`POST`	`/api/rbac/me/one-on-one/start`	Mark one-on-one as started and return a `route_hint` such as `/chat/eve/new?one_on_one=1` for opening the lead-agent chat.	Authentication only
`POST`	`/api/rbac/me/one-on-one/skip-optional`	Skip optional one-on-one topics after the required section is complete. Returns the updated status payload.	Authentication only
`POST`	`/api/rbac/me/onboarding/dismiss`	Admin-dismiss the onboarding lockbox and unlock the caller’s account.	Authentication only (admin dismiss flow)
`GET`	`/api/rbac/me/one-on-one/suggested-topics`	Generate personalized conversation topic suggestions for a check-in. Returns `{ success, topics }`.	Authentication only
`GET`	`/api/rbac/me/agent-memory`	List per-agent memory summaries for agents the caller can access.	Authentication only
`GET`	`/api/rbac/me/agent-memory/{agent_id}`	Return the full per-agent memory document for one agent.	Authentication only
`PUT`	`/api/rbac/me/agent-memory/{agent_id}/categories/{category_key}`	Upsert one memory category (`preferred_name`, `job_role`, `language`, list categories such as `main_data_sources`, and related keys).	Authentication only
`POST`	`/api/rbac/me/agent-memory/{agent_id}/notes`	Add a durable note to the memory document.	Authentication only
`PUT`	`/api/rbac/me/agent-memory/{agent_id}/notes/{note_id}`	Edit an existing memory note.	Authentication only
`DELETE`	`/api/rbac/me/agent-memory/{agent_id}/notes/{note_id}`	Delete one memory note.	Authentication only
`DELETE`	`/api/rbac/me/agent-memory/{agent_id}`	Reset the caller’s memory document for one agent to defaults.	Authentication only
`GET`	`/api/rbac/users/{user_id}/agent-memory`	Admin list of per-agent memory summaries for a user.	`manage_users`
`GET`	`/api/rbac/users/{user_id}/agent-memory/{agent_id}`	Admin view of one user’s full per-agent memory document.	`manage_users`

Default required topic_key values are name_and_language, job_role, data_sources, and validated_data_access. Default optional topic_key values are collaboration_preferences, short_term_objectives, and broader_goals. Workspace admins can customize these lists in Workspace Policies; agents in chat advance checklist progress through the user_memory_action tool (see user_memory_action_tools), which Genesis auto-admits during active onboarding or one-on-one threads.

RBAC read endpoints

These admin read routes require manage_users. Agent-keyed path identifiers must be the exact, case-sensitive bot_id (see Agent identifier validation below). The one-time startup backfill for Adam access on legacy built-in user roles is described in the RBAC Practical Guide.

Method	Path	Description	Required permission
`GET`	`/api/rbac/users/{user_id}/roles`	Return the roles assigned to one user.	`manage_users`
`GET`	`/api/rbac/roles/{role_name}/agents`	Return the agent IDs a role can access.	`manage_users`
`GET`	`/api/rbac/roles/{role_name}/agents/manage`	Return the agent IDs a role may edit without global `manage_agents`. For the built-in `admin` role, returns every agent ID.	`manage_users`
`GET`	`/api/rbac/agents/{agent_id}/roles`	Return the role names that can access one agent.	`manage_users`
`GET`	`/api/rbac/roles/{role_name}/members`	Return the users and agents assigned to one role.	`manage_users`
`GET`	`/api/rbac/bots/{bot_id}/roles`	Return the roles assigned to one bot.	`manage_users`
`GET`	`/api/rbac/roles/{role_name}/dashboards`	Return dashboard `view`/`refresh`/`edit`/`manage` grants for one role.	`manage_users`
`GET`	`/api/rbac/roles/{role_name}/microapps`	Return microapp `view`/`refresh`/`edit`/`manage` grants for one role.	`manage_users`
`GET`	`/api/rbac/roles/{role_name}/secrets`	Return the secret names a role can access.	`manage_users`
`GET`	`/api/rbac/roles/{role_name}/tools`	Return the tool names a role can use.	`manage_users`
`GET`	`/api/rbac/roles/{role_name}/tools/restricted`	Return whether a role is in explicit-tool-allowlist mode.	`manage_users`
`GET`	`/api/rbac/connection-profiles`	List reusable connection profile roles (non-built-in roles that grant one or more saved connections), including `connections[]`, `access_intent`, `is_role_default`, and `member_count`.	`manage_users`
`GET`	`/api/rbac/agents/{bot_id}/connection-access`	Return an agent’s role-derived connection access, including `connections[]`, `has_broad_secret_access`, and per-connection `access_intent`, `via_roles`, `is_role_default`, and `access_source` (`role` or `broad`).	`manage_users`
`GET`	`/api/rbac/agents/{agent_id}/creators`	Return users with creator ownership of one agent.	`manage_users`

Agent-management RBAC write endpoints

These endpoints manage per-agent editing grants and creator ownership. They do not grant chat access to an agent.

Method	Path	Description	Required permission
`PUT`	`/api/rbac/roles/{role_name}/agents/manage`	Replace the complete list of agents a role may edit. Chat access is configured separately.	`manage_users`
`POST`	`/api/rbac/agents/{agent_id}/creators/{user_id}`	Grant creator ownership of an agent to a user.	`manage_users`
`DELETE`	`/api/rbac/agents/{agent_id}/creators/{user_id}`	Revoke creator ownership of an agent from a user.	`manage_users`

Agent connection profile write endpoint

Method	Path	Description	Required permission
`POST`	`/api/rbac/agents/{bot_id}/connection-profile`	Create or update a connection profile role and assign it to an agent. When `connections` is empty, assigns an existing profile role without changing its grants.	`manage_users`

`POST /api/rbac/agents/{bot_id}/connection-profile`

Field	In	Type	Default	Required	Description
`bot_id`	path	string	none	Yes	Exact, case-sensitive agent identifier (`bot_id`) as returned by `GET /api/bots`. Validated per Agent identifier validation below.
`role_name`	body	string	none	Yes	Profile role name. Built-in or protected roles (`user`, `admin`, etc.) are rejected.
`connections`	body	object[]	`[]`	No	Connections to grant to the profile role. Each item requires `connection_type` and `name`; optional `is_default` marks the role default for that type. Empty assigns an existing profile as-is.
`restrict`	body	boolean	`false`	No	When `true`, revoke other non-built-in connection-granting roles from the agent.
`create_role_if_missing`	body	boolean	`true`	No	Create `role_name` when it does not exist (requires a non-empty `connections` list).

Returns AgentConnectionProfileResponse with bot_id, role_name, granted, revoked, defaults_set, removed_roles, protected_roles_still_granting, and role_created. Revoking a profile role from an agent uses the existing DELETE /api/rbac/bots/{bot_id}/roles/{role_name} route (or the agent-editor UI, which calls it when you uncheck a profile and click Apply). Assigning a profile role uses POST /api/rbac/bots/{bot_id}/roles. Both write routes validate bot_id the same way as the read routes below.

Agent identifier validation

Agent-keyed RBAC routes require the exact, case-sensitive bot_id as returned by GET /api/bots. Display names (bot_name) are not identifiers — passing a display name or a case variant of a known bot_id returns 404. UI-created agents store a uniqueness suffix on bot_id (for example, display name Cary → Cary-k7m2x9); use that full id in RBAC URLs and API calls, not the display name alone. When the agent is not found, Genesis can include a Did you mean: ...? suggestion in the error detail when it finds close bot_id matches (for example, a wrong-case input). Routes that validate the agent path parameter:

Method	Path
`GET`	`/api/rbac/agents/{agent_id}/roles`
`GET`	`/api/rbac/agents/{bot_id}/connection-access`
`POST`	`/api/rbac/agents/{bot_id}/connection-profile`
`GET`	`/api/rbac/bots/{bot_id}/roles`
`POST`	`/api/rbac/bots/{bot_id}/roles`
`DELETE`	`/api/rbac/bots/{bot_id}/roles/{role_name}`

Shared RBAC read path parameters

Field	In	Type	Default	Required	Description
`user_id`	path	string	none	Conditional	User identifier used by `GET /api/rbac/users/{user_id}/roles`.
`role_name`	path	string	none	Conditional	Role identifier used by the `/api/rbac/roles/{role_name}/...` read routes.
`agent_id`	path	string	none	Conditional	Exact, case-sensitive `bot_id` for `GET /api/rbac/agents/{agent_id}/roles`. Validated per Agent identifier validation above.
`bot_id`	path	string	none	Conditional	Exact, case-sensitive `bot_id` for bot-role and connection-access routes. Validated per Agent identifier validation above.

Status	Meaning
`200`	RBAC data returned successfully.
`403`	Caller lacks `manage_users`.
`404`	Requested user, role, or agent was not found. Agent lookups can include a `Did you mean: ...?` suggestion in the error detail when Genesis finds a close `bot_id` match (for example, a wrong-case input).

Global RBAC tool-policy endpoints

These admin routes require manage_users and back the system-wide tool-family controls shown in Workspace Policies → Tool Permissions. Workspace policy read and write routes also support SQLAlchemy metadata databases, alongside the legacy database connector.

Method	Path	Description	Required permission
`GET`	`/api/rbac/high-risk-tools`	List high-risk tools and whether that tool family is globally disabled.	`manage_users`
`PUT`	`/api/rbac/high-risk-tools/disabled`	Set whether high-risk tools are globally disabled.	`manage_users`
`GET`	`/api/rbac/coding-agent-tools`	List coding-agent tools and whether that tool family is globally disabled.	`manage_users`
`PUT`	`/api/rbac/coding-agent-tools/disabled`	Set whether coding-agent tools are globally disabled.	`manage_users`

Shared global tool-policy response fields

The GET list endpoints return these top-level fields:

Field	Type	Description
`success`	boolean	Whether the request completed successfully.
`tools`	object[]	Tool metadata entries for the requested family.
`disabled`	boolean	Whether that tool family is globally disabled. When `true`, those tools are blocked for all users and agents.
`forced`	boolean	Whether this deployment holds the policy fixed. High-risk tools are forced on in Genesis Desktop and hosted Try Me; coding-agent tools are forced off on Genesis Desktop.
`forced_reason`	string or null	Why the policy is forced: `desktop` for Genesis Desktop, `hosted` for hosted Try Me high-risk tools, or `null` when the policy can be changed.

Each tool entry in tools includes:

Field	Type	Description
`name`	string	Internal tool identifier.
`display_name`	string	Human-readable tool name.
`description`	string	One-line explanation of what the tool does.

Shared global tool-policy write field

Both PUT /api/rbac/high-risk-tools/disabled and PUT /api/rbac/coding-agent-tools/disabled accept the same request body field:

Field	In	Type	Default	Required	Description
`disabled`	body	boolean	none	Yes	Set to `true` to block the tool family globally, or `false` to allow it again subject to normal role permissions.

Status	Meaning
`200`	Returns `success: true` plus the current `disabled` state.
`409`	The requested change conflicts with a deployment-forced policy: high-risk tools cannot be disabled on Genesis Desktop or hosted Try Me, and coding-agent tools cannot be enabled on Genesis Desktop.
`400`	Genesis could not update the requested tool-family state.
`403`	Caller lacks `manage_users`.
`500`	RBAC manager was unavailable.

Admin audit log

Mutating RBAC routes (user/role lifecycle, role assignment matrices, bot-role mappings, workspace policy toggles under /api/rbac/settings/..., /api/rbac/high-risk-tools/..., and /api/rbac/coding-agent-tools/...) and advanced-config write routes (PUT /api/config/advanced/value, PUT /api/config/advanced/values, and reset endpoints) append best-effort rows to the ADMIN_AUDIT_LOG metadata table. Revoking a role from an agent (DELETE /api/rbac/bots/{bot_id}/roles/{role_name}), revoking a role from a user or agent principal (DELETE /api/rbac/users/{user_id}/roles/{role_name}), removing manage_agents from a custom role (PUT /api/rbac/roles/{role_name}), or deleting a role (DELETE /api/rbac/roles/{role_name}) can also return HTTP 409 with error_type last_agents_manager when the change would leave no other active agent holding manage_agents. Grant the permission to another active agent first, then repeat the change. Each row includes action, actor_user_id, actor_email (when the caller is a human admin), target_type, target_id, JSON details, source (typically api for REST), and timestamp. Advanced-config events record the config path and value type only — never the submitted value. Admins can read these rows through the dashboard (Config → Admin Audit Log) or the read-only endpoints below. Both require access_config_panel. For action names, source taxonomy, column definitions, and example SQL, see RBAC Practical Guide → Admin audit log.

Method	Path	Description	Required permission
`GET`	`/api/admin/audit-log`	Cursor-paginated list of admin audit events.	`access_config_panel`
`GET`	`/api/admin/audit-log/{audit_id}`	Return one event by `audit_id`.	`access_config_panel`

`GET /api/admin/audit-log`

Field	In	Type	Default	Required	Description
`since`	query	datetime (ISO-8601)	none	No	Include events with `timestamp` greater than or equal to this value. Date-only values such as `2026-05-01` are accepted.
`until`	query	datetime (ISO-8601)	none	No	Include events with `timestamp` strictly before this value. Date-only values such as `2026-05-21` are accepted.
`action`	query	string	none	No	Exact match on `action`. Mutually exclusive with `action_prefix`.
`action_prefix`	query	string	none	No	Literal prefix match on `action`; `%`, `_`, and `!` are treated as ordinary characters. Mutually exclusive with `action`.
`actor_user_id`	query	string	none	No	Filter by `actor_user_id`.
`target_type`	query	string	none	No	Filter by `target_type` (`user`, `role`, `bot`, `connection`, `workspace_policy`, `advanced_config`, `managed_skill_source`).
`target_id`	query	string	none	No	Filter by `target_id`.
`source`	query	string	none	No	Filter by `source` (`api`, `auth`, `bot`, `cli`, `managed_sources_api`, `scim`, `slack`, `system`).
`limit`	query	integer	`50`	No	Page size. Minimum `1`, maximum `500`.
`cursor`	query	string	none	No	Opaque pagination token from a prior response’s `next_cursor`.

Returns success: true with data containing:

Field	Type	Description
`items`	object[]	Matching audit events, newest first.
`next_cursor`	string or null	Pass as `cursor` on the next request when `has_more` is `true`.
`has_more`	boolean	`true` when additional rows match the filters beyond this page.

Each items[] entry includes:

Field	Type	Description
`audit_id`	string	Unique event identifier.
`action`	string	Event type (for example `role.granted`).
`actor_user_id`	string or null	Principal that performed the change.
`actor_email`	string or null	Email of the acting human admin when available.
`target_type`	string	Resource class.
`target_id`	string or null	Primary identifier for the target.
`details`	object	JSON metadata for the event (never includes secret or advanced-config values).
`source`	string	How the change was initiated.
`timestamp`	string	Event time in ISO-8601 form.

Status	Meaning
`200`	Page returned successfully.
`400`	Both `action` and `action_prefix` were supplied, or `cursor` is invalid.
`403`	Caller lacks `access_config_panel`.
`422`	`limit` is outside the allowed range.

`GET /api/admin/audit-log/{audit_id}`

Field	In	Type	Default	Required	Description
`audit_id`	path	string	none	Yes	Event identifier to fetch.

Returns success: true with data.item using the same fields as one items[] entry from the list endpoint.

Status	Meaning
`200`	Event returned successfully.
`403`	Caller lacks `access_config_panel`.
`404`	No event with the given `audit_id`.

Durable storage restore proof

These admin-only endpoints report what declared state came back after a restart and confirm deletes that the catch-all storage sweep refused. The report is a read-only status check; it does not set the server’s lasting degraded status. When durable storage is disabled (including deployments off the Databricks App), the report returns enabled: false with verdict not_enabled and performs no I/O. A proof is run at most once at a time, reused for 15 seconds, and may issue up to four Lakebase catalog queries plus one lstat per kept catalog row. While a previous master key is bound, it also streams every live durable-tree manifest, issuing a catalog query per page of rows.

`GET /api/admin/durability/report`

Returns success: true with data containing:

Field	Type	Description
`enabled`	boolean	Whether durable storage is enabled for this deployment.
`verdict`	string	`restored` when all declarations were fully checked without findings; `issues` when state is missing, lost, conflicted, or awaiting delete confirmation; `incomplete` when checks or restores remain incomplete; `not_enabled` when durable storage is off.
`declarations`	object[]	Check status for each kept declaration. Each item has `name`, `primitive`, `state` (`checked`, `partial`, or `not_checked`), and `reason` (empty when there is no reason).
`items`	object[]	Findings, at most 100 per finding. Each item has `finding` (`missing`, `lost_known`, `conflict`, or `secret_refused`), `declaration`, `root`, root-relative `key`, and `detail` (empty when there is no additional detail).
`counts`	object	Totals per finding, plus `checked`, `pending`, `lazy_absent`, `whiteouts`, `deletes_awaiting_confirmation`, `not_kept`, `undeclared`, `lost_unknown_amount`, and `lost_reported_at_startup`.
`degraded_roots`	object[]	Roots whose mass-delete guard refused deletes. Each item has `root`, `deletes_refused`, `refusal`, root-relative `sample` (at most 100 paths), and `confirmed`.
`git_restores_pending`	boolean	Whether git durability still has restores due.
`under_previous_key`	object	Counts of state kinds still requiring the previous master key. May contain `secrets` (integer), `git_repositories` (live repositories still holding bundles sealed with the previous key), `git_archived_incarnations` (archived incarnations sealed with the previous key; counted only, never re-sealed), `durable_trees` (units whose manifest still names a member blob sealed with the previous key), and `volume_files` (durable files whose volume blobs are still sealed with the previous key, as reported by the last complete re-seal cycle). The tree count is read from live manifests for each report; a tree is re-sealed on its next snapshot pass. A kind is absent before its first pass or when no previous key is bound.

The report compares the durable catalog and restore records with this instance’s state roots. A missing item is kept remotely, expected on this disk, but absent locally; lazy entries, pending entries, and whiteouts are not missing. For process-relative checks, this process begins at the start of its boot restore; when that timestamp is unavailable, its process start time is used. This keeps a previous process’s shutdown flush from being treated as state from this process during an overlapping redeploy. lost_known identifies state recorded as lost, while conflict means a local copy displaced restored bytes. secret_refused reports a secret by name only. A root with unconfirmed refused deletes is degraded; confirming it does not mark those deletes as missing. The proof also checks live durable-tree catalog rows against this process’s restore outcomes, and checks listed git-durable repositories for a restored .git directory. A failed tree restore is reported as lost_known; a tree whose restore has not yet been recorded is pending, or lazy_absent when it is lazily restored. For a listed repository with a valid path, an absent .git directory is pending while git restores are due and missing otherwise; an invalid path is missing. Git declarations are marked not_checked when git durability is off.

Status	Meaning
`200`	Report returned, including when durable storage is disabled.
`403`	Caller is not an admin.
`503`	A proof source could not be read; see the server log for the source error.

`POST /api/admin/durability/confirm-deletes`

Confirm only the refused delete set currently represented by the report’s refusal value. If the refused set changes, reload the report and confirm its current value. The next full sweep walk records the confirmed deletes.

Field	In	Type	Default	Required	Description
`root`	body	string	none	Yes	State root: `storage`, `git`, or `state_dir`.
`refusal`	body	string	none	Yes	The root’s `refusal` identifier from the report; exactly 32 lowercase hexadecimal characters.

Returns success: true with data.root and data.confirmed_deletes. The confirmation is audited with the acting admin’s identity.

Status	Meaning
`200`	The refused deletes were confirmed.
`403`	Caller is not an admin.
`404`	The root has no refused deletes awaiting confirmation.
`409`	The sweep has not run in this process, the refusal changed, or the deletes were already confirmed; reload the report.
`422`	The request body is invalid.
`501`	The catch-all storage sweep is not enabled on this deployment.

`POST /api/bots/import/validate`

The caller needs manage_agents or create_agents. Validation does not create an agent; the permission controls whether the caller may use the import flow.

Field	In	Type	Default	Required	Description
`file`	multipart form-data	file	none	Yes	Agent ZIP file to validate before import.

`POST /api/apps/import/validate`

Field	In	Type	Default	Required	Description
`file`	multipart form-data	file	none	Yes	GenesisApp ZIP file to validate before import.

Response fields (in addition to success, valid, app_id, id_collision, suggested_id, errors):

Field	Type	Description
`unresolved_dependencies`	object[]	Connection (and other) slots from the export manifest that are not yet satisfied on this instance. Each item can include `slot_id`, `fallback_name`, `kind`, `status`, `reason`, `dependency_id`.
`available_connections`	object[]	Local connection targets that can satisfy import-time mapping (`target`, `name`, `type`, `kind`, `is_default`).

`POST /api/apps/import`

Field	In	Type	Default	Required	Description
`file`	multipart form-data	file	none	Yes	GenesisApp ZIP file to import.
`published`	query	boolean	`true`	No	Publish after import. Forced to draft when `proceed_unresolved=true` and connection slots remain unmapped.
`display_name`	query	string	none	No	Optional display name (max 128 chars).
`thread_id`	query	string	`imported`	No	Workspace thread folder.
`source_mapping`	form or query	JSON object	`{}`	No	Maps export `slot_id` strings to local connection targets.
`proceed_unresolved`	form or query	boolean	`false`	No	When `true`, import with unresolved connection deps (degraded). When `false`, reject if required slots are unmapped.

Import response can include unresolved_dependencies for slots still unsatisfied after import.

`POST /api/apps/{app_id}/fork`

Field	In	Type	Default	Required	Description
`new_name`	body	string	none	Yes	App ID for the new standalone genesis-versioned copy (1–64 chars, sanitized).

Requires CREATE_APP. Caller must have manage on the source app. Returns 409 with ARTIFACT_IS_GIT_BACKED when the source is not git-backed, APP_NOT_FOUND when missing, or TARGET_NAME_EXISTS / NAME_COLLIDES_WITH_GIT_BACKED when new_name collides.

`POST /api/apps/{app_id}/export-to-managed/preview`

Requires manage_git and app-level manage. Returns a preview of the standalone app bundle that export-to-managed/commit would copy (excludes local state paths such as __pycache__, venv dirs, and dotfiles). Response includes success, files (each with path, size_bytes, is_text), and warnings. On failure, error is set.

`POST /api/apps/{app_id}/export-to-managed/commit`

Field	In	Type	Default	Required	Description
`source_id`	body	string or null	`null`	Conditional	Managed Apps source id. One of `source_id` or `repo_id` is required.
`repo_id`	body	string or null	`null`	Conditional	Managed repository id (alternative to `source_id`).
`title`	body	string or null	`null`	No	MR/PR title. Whitespace-only strings are treated as omitted.
`body`	body	string or null	`null`	No	MR/PR description.
`commit_message`	body	string or null	`null`	No	Git commit message for the export branch.

Requires manage_git and app-level manage. Returns 400 when both source_id and repo_id are missing. On success, includes success, source_id, repo_id, and pull-request metadata (pr_url and/or nested pull_request with pr_url, pr_number).

`POST /api/flows/{flow_id}/fork`

Field	In	Type	Default	Required	Description
`new_name`	body	string	none	Yes	Flow name for the new standalone genesis-versioned copy (1–200 chars).

Requires manage on the source flow. Returns 404 (FLOW_NOT_FOUND), 409 (ARTIFACT_IS_GIT_BACKED when source is not git-backed, NAME_COLLIDES_WITH_GIT_BACKED, or TARGET_NAME_EXISTS), or 400 for other failures. Git-backed flows and apps cannot use Genesis versioning endpoints (enable, promote, revert, discard, and related routes) until forked. PUT updates that only change is_enabled (pause/resume) remain allowed on git-backed flows.

AgentSkills self-add request review

These request-review routes require manage_skills:

Method	Path	Description
`GET`	`/api/agent-skills/requests`	List self-add requests.
`GET`	`/api/agent-skills/requests/{request_id}`	Read a request for review.
`POST`	`/api/agent-skills/requests/{request_id}/approve`	Approve a pending request.
`POST`	`/api/agent-skills/requests/{request_id}/reject`	Reject a pending request.

If a durable request record has malformed metadata, package content, or file paths, these routes return 400 with an error detail. Genesis validates the full record before restoring any package files.

AgentSkills package file endpoints

These routes are mounted under /api/agent-skills/... and back the Skills library package viewer for bundled files such as SKILL.md, examples, or supplementary docs.

Method	Path	Description
`GET`	`/api/agent-skills/{skill_name}/files`	List bundled package files.
`GET`	`/api/agent-skills/{skill_name}/files/{relative_path:path}`	Read one text-like bundled file with pagination metadata.
`GET`	`/api/agent-skills/{skill_name}/files/{relative_path:path}/raw`	Read one text-like bundled file as raw text.

Shared AgentSkills package file parameters

Field	In	Type	Default	Required	Description
`skill_name`	path	string	none	Conditional	Registered AgentSkills package name.
`relative_path`	path	string	none	Conditional	Package-relative file path to read. Used by the file-read routes.
`max_files`	query	integer	`200`	No	Maximum number of files returned by `GET /api/agent-skills/{skill_name}/files`.
`include_hidden`	query	boolean	`false`	No	Include hidden files in the package file listing.
`max_chars`	query	integer	`50000`	No	Maximum number of characters returned when reading one text-like file.
`start_char`	query	integer	`0`	No	Starting character offset for paginated file reads. Used only by `GET /api/agent-skills/{skill_name}/files/{relative_path:path}`.

GET /api/agent-skills/{skill_name}/files/{relative_path:path} returns success: true plus data with the same pagination metadata used by the Skills viewer, including continuation offsets when the file is truncated. The /raw variant returns text/plain directly instead of a JSON envelope.

Status	Meaning
`200`	The package file listing or file read completed successfully.
`400`	The file path or pagination parameters were invalid, or the target file was not readable as text.
`404`	The skill package or requested file was not found.

Agent rooms endpoints

These bearer-authenticated routes let separate development agents share a room through one Genesis server. Rooms are public to authenticated callers who can see them: joining and reading do not create a second access-control model. The caller’s participant name is derived from the authenticated email local part, or the user ID when no email is available; clients do not provide it. Configure the agent that owns room threads with rooms.bot_id before creating the first room.

Method	Path	Description
`GET`	`/api/rooms`	List rooms visible to the caller. Pass `limit=-1` to return the caller’s `you` participant name without enumerating rooms.
`POST`	`/api/rooms`	Create a room.
`DELETE`	`/api/rooms/{room_id}`	Archive a room. The room creator or an administrator may close it.
`POST`	`/api/rooms/{room_id}/join`	Return the room, current `tail_node`, roster, and the caller’s `you` participant name.
`POST`	`/api/rooms/{room_id}/messages`	Send a message into the room’s buffer.
`GET`	`/api/rooms/{room_id}/messages`	Read messages after an optional node, oldest first.
`GET`	`/api/rooms/{room_id}/who`	Return the room’s advisory presence roster and the caller’s `you` participant name.

Room request and response fields

Field	In	Type	Default	Required	Description
`name`	body	string	none	Yes	Display label when creating a room.
`to`	body	array[string]	none	Yes	Participant names, or `all`; this decides who is woken, not who can read.
`body`	body	string	none	Yes	Message text.
`subject`	body	string or `null`	`null`	No	Optional message subject.
`after`	query	string or `null`	`null`	No	Node ID after which to read messages.
`limit`	query	integer	`50`	No	Number of messages to return; valid range is `1`–`200`.
`X-Genesis-Room-Session`	header	string or `null`	`null`	No	Session identifier used to record the caller’s presence heartbeat during a successful read.
`archived`	response	boolean	`true`	—	Confirms that the room was archived; archiving retains the thread rather than erasing it.

DELETE /api/rooms/{room_id} closes the room and removes it from the room listing. Closed rooms stop answering, but their underlying thread is retained for operator access. This is an archive, not a deletion. GET /api/rooms and room creation return you alongside the room data. A message send returns message_id, recipients, and truncated, plus a status of appended when the message is already in the transcript or buffered while a turn is running. A read returns messages and tail_node; store that node ID and pass it as after on the next poll. Each roster entry contains name, attached, and optional last_seen presence data. Room messages addressed to the room’s agent are drained into the room thread by the background room sweep rather than the ordinary mailbox sweep. Direct chat writes to a room thread are rejected; send through these room endpoints so room attribution, ordering, truncation, and rate limits are preserved. Each participant can send up to 30 messages to one room in any rolling 300-second window. The limit is per sender and room, regardless of recipient; exceeding it refuses the send without recording it. Only messages successfully enqueued consume the allowance. The in-memory window resets when the server restarts.

Hosted MCP gateway endpoints

These routes expose the hosted remote MCP connectors plus the setup and readiness surfaces shown in Config → Agent Gateways.

Method	Path	Description	Required permission
`GET`	`/mcp`	Redirect to `/mcp/` with `307 Temporary Redirect`. `/mcp/` is the default public Genesis MCP v2 connector.	—
`GET/POST/DELETE/OPTIONS`	`/mcp/`	Default hosted stateless HTTP MCP transport for the interactive Genesis MCP v2 connector. When auth is enabled, Genesis accepts `Authorization: Bearer <token>` and, when `auth.provider` is `snowflake`, also accepts `Sf-Context-Current-User-Token: <token>` if no `Authorization` header is present. A Genesis personal access token (`gp_...`) can authenticate a headless client without browser OAuth; the request runs as the PAT owner. When `auth.provider` is `proxy`, Genesis also accepts bearer tokens validated as JWTs against the configured issuer when the standard session lookup does not resolve a user. Sandbox thread-runner requests may instead present their live thread token plus `x-genesis-thread-id`; Genesis resolves that token to the owning user and applies the sandbox capability contract. Requests missing a valid token return `401` with a `WWW-Authenticate` challenge that points clients at the protected-resource metadata. Clients may send the transport’s `mcp-session-id` header to keep implicit MCP thread state separate from other clients using the same identity. Genesis does not issue this header; without it, stateless callers share the identity-scoped session.	—
`GET`	`/mcp/v1`	Redirect to `/mcp/v1/` with `307 Temporary Redirect`.	—
`GET/POST/DELETE/OPTIONS`	`/mcp/v1/`	Legacy hosted stateless HTTP MCP transport. Use this versioned path only when a client still depends on the older `status` / `help` / `start_thread` / `ask` gateway flow.	—
`GET`	`/mcp/v2`	Redirect to `/mcp/v2/` with `307 Temporary Redirect`.	—
`GET/POST/DELETE/OPTIONS`	`/mcp/v2/`	Explicit hosted stateless HTTP MCP transport for the interactive Genesis MCP v2 connector. It uses the same auth contract as `/mcp/`.	—
`GET`	`/.well-known/oauth-protected-resource`	Return OAuth protected-resource metadata for the MCP gateway when auth is enabled. Deployments without an OAuth authorization server, including Snowflake SPCS and header-proxy ingress, still return this document but omit `authorization_servers` and `scopes_supported`.	—
`GET`	`/.well-known/oauth-authorization-server`	Return OAuth authorization-server metadata for the MCP gateway when `auth.enabled` and `auth.issuer` are configured. Return `404` when the deployment has no OAuth authorization server.	—
`GET`	`/.well-known/oauth-authorization-server/{issuer_path:path}`	Compatibility lookup for clients that append the requested resource path to the well-known authorization-server URL. It has the same `404` behavior when the deployment has no OAuth authorization server.	—
`GET`	`/authorize`	When `GENESIS_OAUTH_PROXY_ENABLED` is truthy (`true`, `1`, `yes`, or `on`), record the caller’s `redirect_uri`, `state` and PKCE challenge and redirect (`302`) to the upstream `authorization_endpoint` carrying Genesis’s own `redirect_uri` (`{base}/oauth/callback`), `state` and S256 `code_challenge`, with `audience` and default `scope` injected when missing. When Genesis has a configured `auth.client_id`, that value replaces any caller-supplied `client_id` on the redirect. The caller’s callback must be a loopback address, one of the built-in Claude, Cursor or VS Code callbacks, or an exact entry in `auth.mcp_client_redirect_uris`; unsafe `javascript:`, `data:`, `file:` and `vbscript:` callbacks are refused even when listed. Returns `400` when `redirect_uri` is absent or not permitted, when `client_id` is absent, or when `code_challenge` is absent or not S256. See Hosted MCP for Claude Code for the built-in callback list. Returns `404` when the OAuth proxy is disabled.	—
`GET`	`/oauth/callback`	When `GENESIS_OAUTH_PROXY_ENABLED` is truthy, receive the upstream provider’s redirect, match its `state` to the authorization Genesis started, mint a single-use short-lived Genesis authorization code bound to that request, and redirect (`302`) to the caller’s own `redirect_uri` with that code and the caller’s original `state` verbatim. An upstream `error` is relayed to the same callback. Returns `400` when the `state` is absent, unknown, expired or already used. Returns `404` when the OAuth proxy is disabled. Unrelated to `/api/oauth/callback`, which serves the in-app connection popup.	—
`POST`	`/oauth/token`	When `GENESIS_OAUTH_PROXY_ENABLED` is truthy, forward the form-encoded body to the upstream `token_endpoint` and return the upstream JSON response. An `authorization_code` grant presenting a Genesis-issued code is redeemed first — the caller’s `code_verifier` is checked against the stored challenge, the code is single use, and it must name the `redirect_uri` and `client_id` it was issued for, with `client_id` required. The client ID may be supplied in the form body or HTTP Basic `Authorization` header; if both are present, they must match or Genesis returns `400` with `{"error": "invalid_request", "error_description": "..."}`. Genesis uses the Basic header only to identify the client and does not forward it upstream. The upstream exchange then uses the upstream code with Genesis’s own verifier and callback. A code counts as Genesis-issued only when its signature verifies under the serving process’s key. A refresh-token grant, or any other authorization code — including one another Genesis replica issued, or one issued before a restart — is forwarded unchanged, and the identity provider answers it. When Genesis has a configured `auth.client_id`, that value replaces any caller-supplied `client_id` in the proxied form body. A refused redemption answers `400` in the RFC 6749 §5.2 shape (`{"error": "invalid_grant", "error_description": "..."}`) with `Cache-Control: no-store` and makes no upstream call. Returns `404` when the OAuth proxy is disabled.	—
`GET`	`/api/mcp/artifacts/{artifact_id}`	Download one hosted-MCP artifact using the signed `token` query parameter Genesis returned in `artifacts[].download_url`. The signed token authenticates the request, so the MCP client does not need a browser session or bearer credential. Links are HMAC-signed, single-use, and short-lived. Only this single-segment artifact path is exempt from the normal API authentication middleware.	—
`GET`	`/api/config/mcp/readiness`	Return the hosted MCP URL, auth mode and summary, readiness checks, deployment-aware Claude setup instructions, and copyable setup text.	Requires authentication when auth is enabled.
`GET`	`/api/config/mcp/cortex-code-skill`	Download the Genesis Cortex Code skill as a ZIP archive named `genesis-cortex-code-skill.zip`. Returns `404` if this deployment does not include the skill files.	Requires authentication when auth is enabled.
`GET`	`/api/config/mcp/config`	Return mutable hosted MCP defaults: `default_agent_id` and `default_agent_unavailable_policy`.	`access_config_panel`
`PUT`	`/api/config/mcp/config`	Persist hosted MCP default-agent settings from the Config UI.	`access_config_panel`
`POST`	`/api/config/mcp/smoke`	Run metadata/auth-challenge smoke checks and, when the caller has a bearer token, an authenticated `genesis(action="status")` probe.	`access_config_panel`

GET /api/config/mcp/cortex-code-skill returns application/zip with a Content-Disposition filename of genesis-cortex-code-skill.zip. When authentication is enabled, any signed-in user may download it. Requests for /.well-known or /.well-known/... paths that do not match a registered route return 404; they do not fall through to the React SPA. /api/config/mcp/readiness returns success: true plus data with mcp_url, protected_resource_metadata_url, authorization_server_metadata_url, auth_mode, auth, readiness, setup, copy, and notes. data.auth_mode identifies the hosted-MCP auth posture. It returns snowflake_spcs for Snowflake Native App / SPCS ingress, disabled when auth is off, header_proxy when auth.provider is proxy and no auth.issuer is configured, and otherwise the configured auth provider name (or unknown). data.auth also includes the optional client_id field. Genesis resolves that value from auth.client_id, auth0.client_id, AUTH0_CLIENT_ID, or AUTH_CLIENT_ID. The data.external block also includes the normalized forwarding inputs Genesis used for URL construction: forwarded_proto, forwarded_host, forwarded_port, configured_public_base_url, and using_configured_public_url. data.readiness now includes critical_failures, warnings, and per-check severity fields in checks[]. Each readiness check includes id, label, severity, status, message, and remediation. Readiness status values are pass, warn, fail, and not_applicable. When proxy headers are incomplete, Genesis can fall back to one of GENESIS_MCP_PUBLIC_URL, GENESIS_PUBLIC_URL, GENESIS_PUBLIC_BASE_URL, GENESIS_EXTERNAL_URL, SERVICE_BASE_URL, NGROK_BASE_URL, or FRONTEND_BASE_URL instead of deriving a localhost URL. In a Databricks App, Genesis ignores forwarded request headers and does not use NGROK_BASE_URL or FRONTEND_BASE_URL to construct MCP OAuth URLs. The MCP specific overrides remain first; Genesis then checks GENESIS_PUBLIC_BASE_URL, SERVICE_BASE_URL, DATABRICKS_APP_URL, and (on AWS commercial workspaces) the runtime-derived App URL. If none is available, OAuth metadata and URL-bearing WWW-Authenticate challenges return 503; other MCP requests do not require a public URL. See Deploying Genesis on Databricks — Public URL and OAuth callbacks. data.setup is the deployment-specific client setup payload used by Config → Agent Gateways. It includes deployment_kind, headline, recommended_path, claude_code, claude_desktop, cursor, cortex_code, test_prompts, and diagnostics_summary. It can also include network_exposure and enable_sign_in. data.setup.deployment_kind returns snowflake_spcs, hosted_oauth, header_proxy, auth_disabled, or unknown. Each of claude_code, claude_desktop, cursor and cortex_code includes title, summary, steps[], notes[] and, optionally, more[]. Each steps[] item is one numbered step with title, instruction, an optional command (label and value, the one copyable value for that step) and an optional one-line hint. Each more[] item is a section the page shows collapsed below the steps, with id, title, summary and commands[]; id admin_setup carries material only an admin acts on, such as the OAuth redirect URI to register. For hosted OAuth, Claude Code’s steps are Add, Sign in once (interactive claude, then /mcp) and Try it (the claude -p smoke test, which cannot sign in by itself). test_prompts includes interactive and command_line. When deployment_kind is auth_disabled, network_exposure is loopback for a loopback public base URL or network otherwise. The Agent Gateways page labels these states Local only and Sign-in off, respectively, and both provide no-credential setup commands. For the auth_disabled setup, enable_sign_in contains the same setup-section shape plus docs_path, which points to /docs/deployments/Hosted-MCP-For-Claude-Code#turn-on-sign-in. It is omitted when the authentication mode is unknown. data.setup.diagnostics_summary includes status, failure_count, warning_count, hidden_check_count, primary_blocker, and blockers[]. Each blocker uses id, label, message, and remediation. For hosted OAuth/OIDC deployments outside Snowflake SPCS, Genesis adds a client_id_configured blocker when no OAuth client ID is available for browser-based Claude setup instructions; headless PAT authentication remains available. That blocker is not raised in header_proxy mode, which has no OAuth client by design. When no client ID is configured, the setup payload omits the Client ID command and the --client-id flag rather than emitting a placeholder value, and the Claude Code and Cursor steps use a personal access token instead. When the redirect bridge runs with dynamic client registration, no client needs a client ID: the Claude Code command has no --client-id/--callback-port flags, the Cursor entry is just {"url": ...}, and Claude Desktop shows no Client ID. The hosted Claude Code Try it step carries a one-line hint on sending a PAT as Authorization: Bearer <token> for scripts and CI. For the default v2 connector, data.copy.coworker_invite, data.copy.first_prompt, and data.setup.test_prompts.interactive guide callers through call_tool(name="list_agents") and ask_agent(...) instead of the legacy status / help onboarding flow. data.copy.coworker_invite is worded for the deployment: browser sign-in on hosted OAuth, a personal access token on API-key deployments, the user’s own Snowflake credentials on Snowflake SPCS, and no credential when sign-in is off. Every deployment’s setup payload carries a data.setup.cortex_code section for Snowflake Cortex Code (cortex mcp add ... --type http). On Snowflake SPCS it adds --snowflake-connection <snow_cli_profile>, so Cortex Code signs each request with that Snow CLI connection’s Snowflake session. On hosted OAuth with the redirect bridge and dynamic client registration it signs in through the browser; on other authenticated deployments it sends a personal access token as -H "Authorization: Bearer <gp_...>"; with sign-in off it uses the bare URL. On Snowflake SPCS, the first (Add) step of data.setup.claude_code, data.setup.claude_desktop and data.setup.cursor carries a variants array: one entry per way the bridge signs in to Snowflake, in the order snow_cli_profile then private_key. The step’s own command stays set to the snow_cli_profile variant’s command, so a client that ignores variants still gets a working command. Each variant has id, label, instruction and command, and the private-key variant adds a hint. The profile variant passes --snow-connection <snow_cli_profile>; the private-key variant passes

--auth private-key --account <org-account> --user <snowflake-user> --role <snowflake-role> --private-key-file /path/to/rsa_key.p8

. Claude Code’s variants are claude mcp add commands; Claude Desktop’s and Cursor’s are mcpServers config entries. The second (Check) step of those three tabs also carries variants, keyed to the same credentials. Each variant has id, label, an empty instruction, and command; unlike Add, Check variants do not include the private-key hint. Each runs npx -y <bridge> test with that variant’s credential flags, and its own command is the snow_cli_profile check. The dashboard shows one credential switch per tab, on the first step with variants; later steps follow that choice. Every variant pins the same published bridge version (@genesiscomputing/[email protected]). No other deployment kind emits variants. /api/config/mcp/config returns success: true plus data.default_agent_id (string, default "") and data.default_agent_unavailable_policy (require_selection, first_available, or "" when not set; default ""), which are the in-app settings. It also returns data.effective_default_agent and data.effective_default_agent_unavailable_policy, what the MCP server actually uses: each has value, source (in_app, deployment_setting, default, or per_caller when no single default is set and Genesis picks per caller — Eve, then Adam, then the caller’s first accessible agent) and setting_name (the environment variable, such as GENESIS_MCP_DEFAULT_AGENT_ID, when source is deployment_setting). An in-app value overrides the deployment setting; clearing it falls back to the deployment setting again. PUT /api/config/mcp/config accepts the two in-app fields and returns the same payload. Genesis trims default_agent_id, and an invalid unavailable-policy value normalizes to "" (not set), so GENESIS_MCP_DEFAULT_AGENT_UNAVAILABLE_POLICY applies, and require_selection when that is unset too. When auth.provider is snowflake, /api/config/mcp/readiness reports data.auth_mode as snowflake_spcs. In that mode, readiness checks that do not apply to Snowflake SPCS ingress return not_applicable, including issuer_configured and audience_configured, and on Snowflake public ingress hosts the forwarded_headers and configured_public_url checks can also be not_applicable. When auth.provider is proxy and no auth.issuer is set, data.auth_mode and data.setup.deployment_kind are header_proxy. An authenticating ingress proxy signs users in and forwards the identity in a header, so Genesis holds no OIDC issuer: issuer_configured and audience_configured return not_applicable rather than failing, and the setup instructions use a Genesis personal access token. Setting auth.issuer (with auth.audience, auth.jwks_url and auth.client_id) opts the deployment back into browser OAuth, and the OIDC readiness checks apply again. For Microsoft Entra ID, Genesis recognises both issuer families and maps each to the endpoints of its own token version: https://login.microsoftonline.com/{tenant}/v2.0 to the v2.0 endpoints, and https://sts.windows.net/{tenant}/ to the v1.0 endpoints. Every other issuer keeps the default {issuer}/authorize and {issuer}/oauth/token shape. When GENESIS_OAUTH_PROXY_ENABLED is truthy and auth.issuer is configured, Genesis advertises itself in protected-resource metadata (authorization_servers points at the Genesis public base URL) and as the issuer in authorization-server metadata. authorization_endpoint is {base}/authorize, token_endpoint is {base}/oauth/token, jwks_uri and userinfo_endpoint still reference the upstream issuer, and client_id_metadata_document_supported is true. When the OAuth proxy is disabled, /authorize and /oauth/token return 404 and well-known metadata delegates to the configured upstream issuer (OPRM-style). When auth is enabled but no auth.issuer is configured, the deployment has no OAuth authorization server to advertise. This is the expected posture for Snowflake SPCS and header-proxy ingress: the ingress authenticates the request before Genesis receives it, so the protected-resource document remains available but omits authorization_servers and scopes_supported, while both authorization-server discovery routes return 404. Clients should use the Genesis personal access token described by the setup payload instead of starting an OAuth authorization-code flow. /api/config/mcp/smoke returns success: true plus data with mcp_url, aggregate status, and individual checks[] entries for protected-resource metadata, authorization-server metadata, the bearer-auth challenge, and the optional authenticated gateway status probe. When auth is disabled for local development, the auth_challenge check returns not_run instead of fail. When hosted identity delegation is unavailable, the authenticated_gateway_status check returns not_run with the message Gateway status was not run: hosted identity delegation is unavailable. rather than fail. The smoke response still returns success: true; its aggregate data.status is not_run unless another check has status fail. When auth.provider is snowflake, the hosted /mcp/ transport can use Sf-Context-Current-User-Token as the caller credential when no Authorization bearer is present. Genesis preserves that Snowflake current-user token in the hosted MCP request context for downstream gateway calls. Hosted assertions are used for application admission and are not forwarded as the caller bearer token to downstream gateway calls; the verified user context is used instead. Hosted-MCP artifacts[].download_url values point at /api/mcp/artifacts/{artifact_id}?token=... instead of browser-cookie-bound /git/... links. Genesis only signs image, JSON, PDF, CSV, and plain-text uploads for this route, and each link is rejected after it expires or is used once.

Export download responses

Several Genesis API routes stream export packages as binary downloads rather than JSON. On 200 responses, Genesis sets an RFC 6266 / RFC 5987 Content-Disposition header with two filename parameters:

Parameter	Description
`filename="..."`	ASCII-only fallback for legacy clients. HTTP response headers must be Latin-1 encodable, so non-ASCII characters from the source name are folded (for example `→` becomes `_`) and unsafe characters such as quotes, backslashes, and path separators are stripped.
`filename*=UTF-8''...`	Percent-encoded UTF-8 extended form. Modern browsers and HTTP clients prefer this value, which preserves the original Unicode filename when the export name includes characters such as arrows, em dashes, or CJK text.

This dual-parameter format prevents export requests from failing when a display name contains Unicode. Routes that use this header today include:

Method	Path
`POST`	`/api/bots/{bot_id}/export`
`GET`	`/api/blueprints/{blueprint_name}/export`
`GET`	`/api/agent-skills/{skill_name}/export`
`POST`	`/api/projects/{project_id}/export`
`POST`	`/api/bots/{bot_id}/threads/{thread_id}/export`

Typical attachment filenames:

Agent export: agent_{name}_{YYYY-MM-DD}.zip
Blueprint export: {blueprint_name}_export.zip
AgentSkills export: {skill_name}_export.zip
Mission export: mission_{name}_{YYYY-MM-DD}.zip
Thread export: derived from bot id, thread id, date, and format extension (for example .zip, .pdf, or .md)

Repository-backed ZIP exports omit .git metadata, including nested metadata directories and files reached through links; the archive contains working files, not Git commit history. See System Manager export tools.

Thread Export

`POST /api/bots/{bot_id}/threads/{thread_id}/export`

Export a thread as Markdown, PDF, or ZIP. The endpoint returns a binary file download rather than a JSON response body.

Parameter	Location	Type	Default	Description
`format`	Query	`string`	`zip`	Export format: `md`, `pdf`, or `zip`.
`include_files`	Query	`boolean`	`true`	Include file attachments and artifacts in ZIP exports.
`include_tool_calls`	Query	`boolean`	`false`	Include `tool_calls` arrays and tool messages in the exported thread data.
`include_pdf`	Query	`boolean`	`true`	Include `thread.pdf` in ZIP exports.
`include_query_results`	Query	`boolean` or `null`	`null`	Bundle cached query results as `query_results/results.json` so `query-result://` embeds resolve after cross-server import. When omitted, follows `threads.export_include_query_results` (default: `true`). Pass `false` to omit. Not included in scrubbed support bundles.
`bug_report`	Body	`string (optional)`	`null`	Optional Markdown bug report, sent as `{"bug_report":"..."}` and included as `bug_report.md` in ZIP exports.

ZIP exports also include scrub_manifest.json. For this public export endpoint, Genesis preserves original thread content by default, records tool_output_redaction: "none", and the manifest reports status: disabled, so the ZIP remains suitable for import. Support-bundle workflows build the same thread_export.zip shape but rewrite role: "tool" output content in thread.json and message_log.csv to schema-only descriptors by default, preserving columns, row counts, and value types without including raw values. The thread-export manifest records tool_output_redaction, tool_outputs_redacted, tool_output_redaction_fallback_drop_count, and tool_outputs_redacted_in_message_log_csv; binary attachments remain unchanged. The ZIP metadata.json records message_log_source for the rows used to create message_log.csv: message_log means the rows came from the MESSAGE_LOG table, while thread_store means Genesis synthesized them from the durable thread store. The synthesized form can contain placeholders for columns that the durable store does not provide. ZIP exports may also include query_results/results.json with cached query-result payloads keyed by their original query_id. Genesis records whether this file was bundled in metadata.json under contains.query_results. Results are included up to the threads.export_max_query_results_bytes cap (default: 25000000; env: THREAD_EXPORT_MAX_QUERY_RESULTS_BYTES). Oversized individual results are skipped rather than dropping the whole bundle. Support-bundle exports never include raw query data.

Thread exports follow the same thread access rules used elsewhere in Genesis. The authenticated caller can export only threads they are allowed to access, including owned threads, public threads, explicitly shared threads, threads allowed by view_all_threads, threads visible through a shared role carrying view_shared_role_resources, and legacy/system threads whose owner_id is null or system_default_user.

Responses

Status	Meaning
`200`	Binary download with `text/markdown`, `application/pdf`, or `application/zip`. Includes the RFC 6266 / RFC 5987 `Content-Disposition` header described in Export download responses.
`403`	Caller does not have access to the target thread.
`404`	Thread was not found.
`500`	Export failed on the server.

​Blueprint versioning and access

​HTTP authentication refusal responses

​Genesis Desktop sign-in errors

​Genesis Desktop sign-in dialog

​Genesis Desktop returning activation

​Genesis Desktop Genesis AI-only mode

​Genesis Desktop saved credential notice

​Genesis Desktop Genesis AI allowance

​Genesis Desktop trial status

​Genesis Desktop version policy

​Genesis Desktop release-channel updates

​Genesis Desktop diagnostics

​Genesis Desktop browser tools

​Genesis Desktop MCP clients

​Desktop CLI connections

​Hosted identity lifecycle

​POST /api/hosted-identities/initial-admin

​POST /api/hosted-identities/invitations

​POST /api/hosted-identities/{binding_id}/revoke

​Hosted WebSocket admission

​Blueprint library inventory endpoint

​GET /api/blueprints/

​Blueprint library response fields

​Key per-blueprint inventory fields

​Blueprint authoring short-description field

​Blueprint recommendation wizard endpoint

​POST /api/blueprints/wizard

​Blueprint wizard answer-context item fields

​Blueprint wizard response fields

​Blueprint wizard question fields

​Blueprint wizard recommendation fields

​Blueprint wizard error responses

​Blueprint path parameter

​Optional blueprint identity query parameter

​Blueprint export endpoint

​GET /api/blueprints/{blueprint_name}/export

​Blueprint ZIP import endpoints

​Blueprint detail endpoint

​GET /api/blueprints/{blueprint_name}

​Key Blueprint detail response fields

​Blueprint file endpoint

​Blueprint origin fields

​blueprint.source_view fields

​Blueprint rename endpoint

​POST /api/blueprints/{blueprint_name}/rename

​Blueprint rename response fields

​Blueprint rename status behavior

​Blueprint RBAC actions

​Blueprint-wide role permissions

​Blueprint delete endpoint

​Versioning endpoints

​Versioning summary fields

​Versioning request bodies

​POST /api/blueprints/{blueprint_name}/versioning/enable

​POST /api/blueprints/{blueprint_name}/versioning/versions

​POST /api/blueprints/{blueprint_name}/versioning/promote

​POST /api/blueprints/{blueprint_name}/versioning/restore

​Access-control endpoints

​GET /api/blueprints/{blueprint_name}/access

​POST /api/blueprints/{blueprint_name}/access/grant

​POST /api/blueprints/{blueprint_name}/access/revoke

​Action Review endpoints

​Action Review route summary

​POST /api/action-review/proposals request fields

​GET /api/action-review/proposals query fields

​POST /api/action-review/proposals/{proposal_id}/approve and /reject

​Decision hand-back to the agent

​Action Review response fields

​Blueprint history endpoint

​GET /api/blueprints/{blueprint_name}/history

​Blueprint import endpoint

​Blueprint repository sync and dev-session remediation

​Blueprint sync remediation payload fields

​Blueprint sync remediation action fields

​Blueprint mission-start sync warning fields

​Blueprint mission-start request fields

​Blueprint journey definitions

​GET /api/blueprints/journey-definitions/{journey_id}

​Blueprint mission-start execute access

​Blueprint mission-start tool policy preflight

Blueprint versioning and access

HTTP authentication refusal responses

Genesis Desktop sign-in errors

Genesis Desktop sign-in dialog

Genesis Desktop returning activation

Genesis Desktop Genesis AI-only mode

Genesis Desktop saved credential notice

Genesis Desktop Genesis AI allowance

Genesis Desktop trial status

Genesis Desktop version policy

Genesis Desktop release-channel updates

Genesis Desktop diagnostics

Genesis Desktop browser tools

Genesis Desktop MCP clients

Desktop CLI connections

Hosted identity lifecycle

`POST /api/hosted-identities/initial-admin`

`POST /api/hosted-identities/invitations`

`POST /api/hosted-identities/{binding_id}/revoke`

Hosted WebSocket admission

Blueprint library inventory endpoint

`GET /api/blueprints/`

Blueprint library response fields

Key per-blueprint inventory fields

Blueprint authoring short-description field

Blueprint recommendation wizard endpoint

`POST /api/blueprints/wizard`

Blueprint wizard answer-context item fields

Blueprint wizard response fields

Blueprint wizard question fields

Blueprint wizard recommendation fields

Blueprint wizard error responses

Blueprint path parameter

Optional blueprint identity query parameter

Blueprint export endpoint

`GET /api/blueprints/{blueprint_name}/export`

Blueprint ZIP import endpoints

Blueprint detail endpoint

`GET /api/blueprints/{blueprint_name}`

Key Blueprint detail response fields

Blueprint file endpoint

Blueprint origin fields

`blueprint.source_view` fields

Blueprint rename endpoint

`POST /api/blueprints/{blueprint_name}/rename`

Blueprint rename response fields

Blueprint rename status behavior

Blueprint RBAC actions

Blueprint-wide role permissions

Blueprint delete endpoint

Versioning endpoints

Versioning summary fields

Versioning request bodies

`POST /api/blueprints/{blueprint_name}/versioning/enable`

`POST /api/blueprints/{blueprint_name}/versioning/versions`

`POST /api/blueprints/{blueprint_name}/versioning/promote`

`POST /api/blueprints/{blueprint_name}/versioning/restore`

Access-control endpoints

`GET /api/blueprints/{blueprint_name}/access`

`POST /api/blueprints/{blueprint_name}/access/grant`

`POST /api/blueprints/{blueprint_name}/access/revoke`

Action Review endpoints

Action Review route summary

`POST /api/action-review/proposals` request fields

`GET /api/action-review/proposals` query fields

`POST /api/action-review/proposals/{proposal_id}/approve` and `/reject`

Decision hand-back to the agent

Action Review response fields

Blueprint history endpoint

`GET /api/blueprints/{blueprint_name}/history`

Blueprint import endpoint

Blueprint repository sync and dev-session remediation

Blueprint sync remediation payload fields

Blueprint sync remediation action fields

Blueprint mission-start sync warning fields

Blueprint mission-start request fields

Blueprint journey definitions

`GET /api/blueprints/journey-definitions/{journey_id}`

Blueprint mission-start execute access

Blueprint mission-start tool policy preflight