> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.kuudo.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.kuudo.com/_mcp/server.

# Deployments and storage

> Follow queued cloud operations through resources and recent jobs.

## Create an environment

Provider-specific creation endpoints live under `/api/aws/environments`,
`/api/azure/environments`, `/api/gcp/environments`, and
`/api/cloudflare/environments`. They require `environments:write` and provider
credentials in their documented request bodies.

Creation returns HTTP 201 with `environmentId` and `jobId`; provider provisioning
runs asynchronously. Inspect `GET /api/deployments/environments/{id}` and
`GET /api/deployments/{id}/jobs`, both requiring `deployments:read`.
The latter path's `id` identifies an **environment**.

`GET /api/deployments/environments` lists fresh environment summaries. Its
optional `X-Organization-Id` header must match the authenticated organization;
a mismatch returns 409.
`POST` at that same path is a compatibility listing of active environments and
requires `deployments:write`; it does not create an environment.

AWS list responses use a `deployments` wrapper and currently contain all
organization environments. Azure, GCP and Cloudflare use an `environments` wrapper
filtered to that provider.

## Deploy a server

Use `POST /api/integrations/{integrationId}/deploy` for a manifest integration,
or the documented ChromaDB, Openbridge, custom Docker, or MCP proxy endpoint.
An active environment and `deployments:write` are required; manifest defaults,
provider constraints, and entitlements apply.

Deployment returns HTTP 201 with `deploymentId` and `jobId`. `deploymentId` is the
created **server** ID. Inspect `GET /api/servers/{id}` and
`GET /api/servers/{id}/jobs` using `servers:read`. Server job listings return the
last 50 jobs; environment job listings return the last 10. Large stack events are omitted.

## Update, stop, start, or delete

Server changes can return HTTP 200 while a job is still running. Configuration
updates return `jobId`, `status`, and `diff` when changes are queued. An update
with no changes returns only success and a message. Concurrent deployment updates
can return 409.

Server deletion returns HTTP 200 with `status: "deleting"`; provider environment
deletion returns HTTP 202. Poll resources and jobs to observe completion.

## Storage

`POST /api/storage` supports registered resources and managed S3 Files.
Registered creation returns HTTP 201 with `resource`; managed creation returns
HTTP 202 with `storageId` and `status`. Managed availability depends on your
organization and AWS deployment prerequisites.

Registered S3 Files requires role-based filesystem/access-point metadata and
rejects static credentials. The `s3` request label is normalized to `s3-object`.

Attach active storage to a server in the same environment at
`POST /api/servers/{id}/storage`. Both `servers:write` and `storage:write` are
required. Detach with `DELETE` and the `storageResourceId` query parameter.

Inspect `/api/storage/{id}/affected-servers` before changes that affect attached
servers. Managed deletion requires `force=true`; `retain_bucket=true` preserves
the bucket and its contents while other managed resources are removed. Managed
deprovisioning returns 202 and remains asynchronous.