# Operations and idempotency > Operation states, response behavior, and request replay rules > Nevia is in beta and open to selected teams. Public launch in Dec 2026. The CLI installs with `curl -fsSL https://get.nevia.cloud | sh`, and the MCP server is at https://api.nevia.cloud/mcp. A person signs in once in the browser. > Setup, sign-in and requesting access: [SKILL.md](https://nevia.cloud/SKILL.md). When Nevia fits and when it doesn't: [why.md](https://nevia.cloud/why.md). > For the complete documentation index, see [llms.txt](https://nevia.cloud/llms.txt). This page's HTML version: https://nevia.cloud/docs/reference/operations An operation records the outcome of work on a workspace, computer, database or checkpoint. An idempotency key identifies a request you may need to repeat. See [Track and wait for operations](https://nevia.cloud/docs/guides/operations.md) for CLI steps. ## Operation states | State | Meaning | | ---------- | -------------------------------------------------------------------------------------------- | | `running` | The operation has not reached an outcome. | | `finished` | The operation succeeded. This state is terminal. | | `failed` | The operation failed. Its `error` gives a code, message and details. This state is terminal. | `resource` identifies the affected resource. For a branch or checkpoint restore, it identifies the new computer or database. The resource's own `state`, `pending` and `error` describe its current condition; an operation describes the work that started it or changed it. Keep the returned operation ID, or find it with [List operations](https://nevia.cloud/docs/reference/api/operations/listOperations.md). A resource read can return `operations: []` while earlier work is still running. Use [Get operation](https://nevia.cloud/docs/reference/api/operations/getOperation.md) to read that work's outcome. For MCP call budgets and `outcome` results, see [MCP waiting behavior](https://nevia.cloud/docs/reference/mcp.md#waiting). ## Which requests return operations These are the current behaviors for successful requests. HTTP status alone does not establish whether the work is still running. | Action | Operation behavior | | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Create or branch a computer or database; restore a computer checkpoint | Returns an operation. HTTP 200 when it has reached a terminal state, including failure; HTTP 202 while creation continues. | | Create a computer checkpoint | HTTP 201 with a checkpoint creation operation. | | Delete a computer, database or checkpoint | HTTP 202 with a deletion operation. For an already `deleting` checkpoint, a repeat returns its running operation or an empty list if none is running. | | Delete a workspace | HTTP 202 with an operation already `finished`. | | Sleep or wake a computer or database | HTTP 200. Returns an operation only if the API's bounded wait runs out; otherwise `operations: []`. An idle resource already in the requested state also returns an empty list. | | Create a workspace or add a member | HTTP 201 with `operations: []`. | | Update computer, database or workspace settings; change or remove a member | HTTP 200 with `operations: []`. | | Exec | No operation. JSON responses have `operations: []`; streaming responses carry output and an exit or error event. | Unsupported actions, including computer restart and database creation from a checkpoint, return an error before starting an operation. The API reference owns request and response details: [computer creation](https://nevia.cloud/docs/reference/api/computers/createComputer.md), [checkpoint creation](https://nevia.cloud/docs/reference/api/checkpoints/createComputerCheckpoint.md), [sleep](https://nevia.cloud/docs/reference/api/computers/sleepComputer.md), and [workspace deletion](https://nevia.cloud/docs/reference/api/workspaces/deleteWorkspace.md). ## Waiting and conflicts Waiting polls an existing operation. Stopping the CLI wait or reaching its timeout does not cancel the operation. A failed operation stays failed; waiting again does not retry the action. The worker has a separate deadline for computer, database and checkpoint operations: 15 minutes by default. Expiry marks the operation failed; it does not undo the work or delete a resource that was created. Some lifecycle actions refuse to proceed while an operation runs on the resource. `423 operation_in_progress` includes `details.operation_id` and `Retry-After: 5`. Wait for that operation, then reconsider the action. A resource with a pending transition can instead return `409 invalid_state`. This is not a blanket lock on all mutations; live settings updates have their own checks. Listing operations requires access to the workspace. Reading one by ID also allows the principal who started it, even after workspace deletion. See [Workspace permissions](https://nevia.cloud/docs/reference/workspace-permissions.md). ## Idempotency Replay support depends on the action: | Action | `Idempotency-Key` behavior | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | Create a computer, database, computer checkpoint or workspace; add a member | Required; replays a stored response. | | Branch a computer or database; restore a computer checkpoint | Optional; replays a stored response when supplied. | | Settings updates, member changes/removal, deletes, sleep, wake and exec | Accepted but not replayed. Repeating exec runs the command again if its state checks pass. | The CLI supplies a key for commands that require one. Those commands accept `--idempotency-key`; without it, each invocation gets a new key. CLI branch and restore commands do not expose this flag or send a key. Keys contain 1–255 characters and belong to the authenticated principal, across workspaces and routes. The API retains a stored response for 24 hours. A retry must use the same method, path and validated request body. JSON object key order does not matter. Reusing a stored key for a different request returns `409 idempotency_conflict`. A replay returns the stored status and body, including the original operation IDs. It does not refresh resource state or rerun a failed operation. Database creation is an exception to an unchanged body: replays return `connection.password` and `connection.uri` as `null`. Retrieve them through [Get connection](https://nevia.cloud/docs/reference/api/databases/getConnection.md). Authentication, authorization and some resource checks run before replay. A changed source state or lost access can therefore prevent a retry from reaching the stored response. The API stores a response after the handler completes. It does not store thrown errors or combine simultaneous requests with the same key. A lost response does not prove that no work started. After a key expires, reusing it can start new work. `X-Request-ID` identifies the current HTTP request for diagnosis and matches `error.request_id` on failures. It does not replace an operation ID or an idempotency key.