biome-lifecycle

Operations of the Biome Host API. Paths are relative to your deployment's API host.

POST /api/biome-host-api/biome-lifecycle/apply

Converge the installed biomes of the target to a biome install request (biome-install-request@1): the plan apply/plan showed, executed. Call POST /biome-lifecycle/apply/plan first and pass the planDigest it returns. A plan that changed since (another planDigest) is refused (409 LIFECYCLE_PLAN_CHANGED) and nothing is written. Unlisted biomes are removed (deactivated, data kept) only with prune. A refused entry is excluded and listed, with the entries that depend on it; unless allowPartial is set, any excluded entry refuses the whole apply (409, listing them) and nothing is written, and with it the rest applies as one plan. The operation completes when each installed or updated biome serves or has failed to serve, or readyWithinSeconds passed (recorded as timeout). Idempotent on operationId; the request and the typed result are recorded on the operation (GET /biome-lifecycle/operations/{operationId}). Admits only a person's own token (UserJwt) or a service principal (ServiceJwt): a delegation token always gets 403, TOKEN_CLASS_NOT_PERMITTED for the OrganizationDelegation class or ORG_AUTHORITY_INSTRUMENT_NOT_ACCEPTED for a recorded delegation context. The request is not a biome-install-request@1 document (400), targets another org (400 BIOME_INSTALL_TARGET_NOT_ADMITTED_ORG) or another user's space (403 BIOME_INSTALL_TARGET_NOT_SELF), targets a user space from anything but a person acting directly (403 BIOME_INSTALL_PERSONAL_TARGET_REFUSED), or names what this host cannot install: a target tier other than the platform, the org or the caller's own user space (422 BIOME_INSTALL_TARGET_UNSUPPORTED), a prune at a user space (422 BIOME_INSTALL_PERSONAL_OPERATION_UNSUPPORTED), a version without an npm source (422 BIOME_INSTALL_VERSION_UNSUPPORTED). At a user space (biome:install.personal@1), a server biome is refused at plan time (personal-server-biome-unsupported), and so is a web biome the org has installed (personal-biome-held-by-org).

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json LifecycleApplyRequestDto

POST /api/biome-host-api/biome-lifecycle/apply/plan

Plan the convergence of the installed biomes of the target to a biome install request (biome-install-request@1) without writing anything: what it would install, update or leave, and with prune what it would remove (deactivate, data kept). A refused entry is excluded and listed, with the entries that depend on it; the rest is planned as one plan. Read-only: nothing is written. Returns the plan's planDigest, which POST /biome-lifecycle/apply requires: run this first, show the plan (each entry carries the permissions it requests, permissionSummary, and the digest covers them), then apply with the digest. A delegation token always gets 403, TOKEN_CLASS_NOT_PERMITTED for the OrganizationDelegation class or ORG_AUTHORITY_INSTRUMENT_NOT_ACCEPTED for a recorded delegation context. The request is not a biome-install-request@1 document (400), targets another org (400 BIOME_INSTALL_TARGET_NOT_ADMITTED_ORG) or another user's space (403 BIOME_INSTALL_TARGET_NOT_SELF), targets a user space from anything but a person acting directly (403 BIOME_INSTALL_PERSONAL_TARGET_REFUSED), or names what this host cannot install: a target tier other than the platform, the org or the caller's own user space (422 BIOME_INSTALL_TARGET_UNSUPPORTED), a prune at a user space (422 BIOME_INSTALL_PERSONAL_OPERATION_UNSUPPORTED), a version without an npm source (422 BIOME_INSTALL_VERSION_UNSUPPORTED). At a user space (biome:install.personal@1), a server biome is refused at plan time (personal-server-biome-unsupported), and so is a web biome the org has installed (personal-biome-held-by-org).

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json BiomeInstallRequestDto

POST /api/biome-host-api/biome-lifecycle/install

Install biomes with their dependencies: the plan, executed. Idempotent on operationId. Pass the planDigest that POST /biome-lifecycle/plan returned as expectedPlanDigest: a plan that changed since (another digest) is refused (409 LIFECYCLE_PLAN_CHANGED) and nothing is written.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json LifecycleRequestDto

GET /api/biome-host-api/biome-lifecycle/installed-set

The installed biomes of the org, each with its intended digest, the digest its process runs, its health and the digest its last applied move replaced.

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/biome-host-api/biome-lifecycle/operations

The lifecycle operations that installed in a target Space, newest first (at most 100): each with what it was asked (request, an apply's biome-install-request@1) and how it ended (result, per entry, with each failed or excluded entry's error). A caller with the lifecycle authority sees every one; anyone else only the ones it asked for.

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/biome-host-api/biome-lifecycle/operations/{operationId}

One lifecycle operation: what it was asked (request), how it ended (result: the status, and per entry the action, status and error), and every step in order. Its requester reads it; anyone else needs the lifecycle authority. 404 for an id the org did not record, to a caller with the authority (without it, 403).

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/biome-host-api/biome-lifecycle/operations/{operationId}/progress

Follow a lifecycle operation (SSE).

Server-sent step frames in ordinal order, each once, from the first step; the stream ends after the operation completed or failed. The requester follows its own operation; anyone else needs the lifecycle authority.

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/biome-host-api/biome-lifecycle/plan

Plan an install, update or uninstall without writing anything: the biomes it would install, update, remove or leave, each with its host ABI grade and the permissions it requests (permissionSummary), or the refusals that refuse the whole plan. Returns the plan's planDigest (it covers the permissions): show the plan, then pass the digest as expectedPlanDigest to install, update or uninstall so that exactly this plan runs. A delegation token always gets 403, TOKEN_CLASS_NOT_PERMITTED for the OrganizationDelegation class or ORG_AUTHORITY_INSTRUMENT_NOT_ACCEPTED for a recorded delegation context.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json LifecyclePlanRequestDto

POST /api/biome-host-api/biome-lifecycle/serving-status

Read whether the organisation's installed biomes serve: for each, its pinned bundle digest and channel, its serving state, and serving, pending or failed with the reason. Changes no installation. A biome of the image's seed is serving with source seed; the response also carries the seed's boot record (the image digest and chart it last booted from, each known or unknown). A named biome that is neither installed nor a seed member is failed. It first finalizes the overdue open applies of the organisation: a biome that had not served by the deadline of its apply is failed with reason timeout. The requester of operationId reads the biomes that operation planned (without the lifecycle authority: those biomes only, no overdue finalization and no seed boot record); anyone else needs the lifecycle authority. With target your own user space (xema://users/<you>, your own token acting directly), it reads the biomes installed there, without the lifecycle authority (no overdue finalization, no seed boot record); another user is a 403 BIOME_INSTALL_TARGET_NOT_SELF. operationId and target together are a 400.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json ServingStatusRequestDto

POST /api/biome-host-api/biome-lifecycle/uninstall

Uninstall biomes: deactivated with their data kept, or deleted with purge once no replica runs them. A biome other installed biomes depend on is refused unless cascade removes them with it. Idempotent on operationId. Pass the planDigest that POST /biome-lifecycle/plan returned as expectedPlanDigest: a plan that changed since (another digest) is refused (409 LIFECYCLE_PLAN_CHANGED) and nothing is written. A person acting with their own token uninstalls only from their own user space (target: xema://users/<you>, asked as biome:install.personal@1; a biome not installed there is left unchanged); any other target, such as the org Space, is decided by the same install capability check as install on the target Space. The System target (xema://system) is admitted by the same install capability as any other target: a caller whose grant covers it may uninstall a System biome, and the next apply reinstalls it while the deployment still lists it.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json LifecycleRequestDto

POST /api/biome-host-api/biome-lifecycle/update

Update installed biomes to the bundle their source resolves to now (or the named digest or channel): the plan, executed. Idempotent on operationId. Pass the planDigest that POST /biome-lifecycle/plan returned as expectedPlanDigest: a plan that changed since (another digest) is refused (409 LIFECYCLE_PLAN_CHANGED) and nothing is written. A person acting with their own token is decided by the same install capability check as install on the target Space (their own user space is asked as biome:install.personal@1).

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json LifecycleRequestDto