Create instances
Creates 1 to 16 instances of one shape in one location. Billable from
first boot. Requires Idempotency-Key.
Admission is all or nothing: the org's quotas, the caller's
explicitly configured limits and host capacity are checked for the
whole count, and on
success every instance is placed, addressed and returned in status
provisioning before the response is sent. After that each instance
boots, or fails, on its own. Instances of one request share a
location and a TEE, and with placement.policy: colocate a host.
The image's launch contract (GET /v1/images) decides which disks
the request must list, whether it takes access.sshKeys or
trust.launchKey with trust.initData, and which sizes it runs on.
A GPU size needs reservation, unless purchaseOption is spot,
and a CPU size must not have one.
Something the image or another field requires but the request
leaves out is 400 invalid_request; values that are each valid but
do not go together are 422 unsupported_combination (see Errors).
Disks whose encryption is guest read as empty after every boot,
and every disk is destroyed on delete.
AuthorizationBearer <cc_...>An API key of your org, sent as Authorization: Bearer cc_.... Keys
start with cc_ and are otherwise opaque. Treat a key as a password:
anyone holding it can act with its scopes until it expires or is
revoked. Each operation's security requirement lists the scopes it
needs; an empty list means any valid key. The MCP server at /mcp
accepts agent keys and no other kind.
Scope: instances:write
Idempotency-Key*stringA unique key for this intent, such as a UUID. Reuse it for every
retry of the same request. A missing key returns
400 idempotency_key_required. See Idempotency above.
^[!-~]+$1 <= length <= 255Api-Version*stringThe API version the request is written against. This document
describes 2026-10-15. A missing header returns
400 api_version_required, and a version the API does not serve
returns 400 unsupported_api_version.
X-Correlation-ID?stringAn id of your own for this request, or for a group of requests, to
find them in our logs and yours. Logged with the request and returned
unchanged in X-Correlation-ID. The request id itself is always the
API's own, in X-Request-ID.
^[A-Za-z0-9._:-]+$1 <= length <= 128Org-Context?stringAdmin keys only: the id of the org to act in. Required with an admin
key, together with Access-Reason; with any other credential it
returns 400 invalid_request. Every request that carries it is
recorded in that org's operator-access log.
^org-[a-z0-9]([-a-z0-9]*[a-z0-9])?$5 <= length <= 63Access-Reason?stringAdmin keys only: why the operator is acting in the org, such as a
support ticket. Required with Org-Context. Recorded, verbatim, in
the org's operator-access log.
^[^\x00-\x1F\x7F]+$10 <= length <= 500application/json- body
A request for 1 to 16 instances of one shape. Every instance gets the
same TEE, size, image, disks, network settings, keys and labels. The body
may be at most 256 KiB (413 payload_too_large). Something the image
requires but the request leaves out is 400 invalid_request; values
that are each valid but do not go together are
422 unsupported_combination.
name?InstanceNameSpecA name for the instance, unique among the live instances of its
project. With count above 1, each instance is named <name>-<n>,
counting from 0, and every one of those names must be free. Without
it, the instances have no name. A name may not be i or begin with
i-, so that no name looks like an instance id.
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$1 <= length <= 60count?integerHow many instances to create. All or none are admitted.
1 <= value <= 161tee?TeeThe TEE to run on. Without it, the platform picks one TEE for the
whole request, among those for which the image version has an
artifact that lists the size, in the request's location. A
reservation or a placement group implies its own TEE. Otherwise,
of the TEEs with room for every instance, it takes the one whose
hosts are fullest. The response's tee names the choice, which
holds for the instance's life. If no TEE offers the image and
size, the create returns 422 unsupported_combination; if none
has room for every instance, 409 insufficient_capacity.
location*LocationIdWhere to create the instances, from GET /v1/locations. The
platform never picks a location: a request without one returns
400 invalid_request with violation required. A reservation or
placement group the request names must be in it
(422 unsupported_combination). When the instances do not fit
there, 409 insufficient_capacity lists in alternatives the
other locations where they would fit now.
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$1 <= length <= 63size*SizeIdA size id from GET /v1/sizes. The image version must have an
artifact that lists it, for the request's tee or, without
tee, for any TEE (422 unsupported_combination). A GPU size
needs reservation (400 invalid_request, violation required
at /reservation), unless purchaseOption is spot.
^[a-z0-9]([-.a-z0-9]*[a-z0-9])?$1 <= length <= 63image*ImageRefAn image family, such as confos-cpu, which resolves to its newest
active version (or, until that version has passed the boot test on
the TEE, the newest active version that has, or if none has, the
newest deprecated version still accepting creates that has; among
those, the newest that sells the create's size comes first), or a
pinned version, <family>@<version>, such as
c8s-node@2026.10.1. A family or version that GET /v1/images does
not list returns 400 invalid_request with violation not_found.
The response always gives the version and digest that boots.
Or any public OCI container image, by a reference with a /, as
docker pull takes it: ghcr.io/org/app:1.2,
ghcr.io/org/app@sha256:… or docker.io/library/nginx:1.29. A
first part without a . or : (other than localhost) is a
Docker Hub repository. The instance then boots the newest active
image version your org can use whose launch contract has
containers: true, which pulls the image by digest and runs it as
its only workload (Instance.container). A tag is resolved to its
digest at create; an image the registry does not serve anonymously
returns 400 invalid_request with violation not_found.
^([a-z0-9]([-a-z0-9]{0,61}[a-z0-9])?(@[0-9A-Za-z][0-9A-Za-z._-]{0,63})?|([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*(:[0-9]{1,5})?/)?[a-z0-9]+(([._]|__|-+)[a-z0-9]+)*(/[a-z0-9]+(([._]|__|-+)[a-z0-9]+)*)+(:[A-Za-z0-9_][A-Za-z0-9._-]{0,127})?(@sha256:[0-9a-f]{64})?|[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)+(:[0-9]{1,5})?/[a-z0-9]+(([._]|__|-+)[a-z0-9]+)*(/[a-z0-9]+(([._]|__|-+)[a-z0-9]+)*)*(:[A-Za-z0-9_][A-Za-z0-9._-]{0,127})?(@sha256:[0-9a-f]{64})?)$1 <= length <= 512reservation?ResourceIdParamThe GPU reservation to launch against. Required with a GPU size
(400 invalid_request, violation required), unless
purchaseOption is spot, which takes none
(422 unsupported_combination). Not allowed with a CPU size, and it must be in the request's location and TEE
(422 unsupported_combination for each). It must be active
(409 reservation_not_active) and have enough unused GPUs for
every instance (409 reservation_exhausted). An id that is not a
reservation of your org returns 400 invalid_request with
violation not_found.
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$1 <= length <= 63purchaseOption?PurchaseOptionHow to buy the instances: one of the size's purchaseOptions in
GET /v1/sizes, or 422 unsupported_combination. Without it,
reservation for a GPU size and on-demand for a CPU size.
spot runs a GPU size on GPUs that no
active reservation holds, at the size's spotPrice, until
something of higher priority needs them
(Instance.purchaseOption); without
enough of them for every instance, the create returns
409 insufficient_capacity. reservation needs reservation
(400 invalid_request, violation required).
disks?array<>Writable disks, besides the image's read-only root. List every
disk the image's launch contract marks required (a missing one
is 400 invalid_request, violation required) and only disks it
names (another is 422 unsupported_combination). A disk whose
encryption is guest reads as empty after every boot, under a
new key; one whose encryption is none keeps its contents
until the instance is deleted.
items <= 8[]network?How the instances are reached.
readiness?The guest ports the platform waits on before Reachable is
True, fixed for the instance's life. Without it, the image's
launch.readiness. An empty tcpPorts waits on none: the
instance is Reachable once its VM reports ready, with reason
GuestReady, as a c8s agent node launches. A c8s server node
names its join and API ports, {"tcpPorts": [9345, 6443]}. The
ports need no ingress rule, since the platform dials them from
inside its own network. An image's private attestation port, where
launch.attestationPublic is false, cannot be one
(422 unsupported_combination, violation incompatible at its
index in /readiness/tcpPorts).
access?SSH keys, for images whose launch contract has access: sshKeys.
Required for those images (400 invalid_request, violation
required) and refused by the others (422 unsupported_combination).
Optional when image is an OCI image: without keys, nobody can log
in to the instance.
trust?Your launch key and signed launch document, for images whose launch
contract has access: launchKey. Required for those images
(400 invalid_request, violation required), and launchKey is
required in it. An image with access: sshKeys that lists
initDataFormats takes trust with initData alone, which binds
one line into its pubkey file, and refuses launchKey. A dedicated
access: launchFile image requires initData alone and measures
its exact decoded document as the entire pubkey file; it refuses
launchKey, signature, SSH keys and user data. A c8s-worker/1
image is a launch-file image that also requires bootstrapToken,
which no other image takes. Other
images refuse trust (422 unsupported_combination). initData is
required when the image lists initDataFormats, in one of those
formats.
container?How to run the OCI image image names. Only with an OCI image
(otherwise 422 unsupported_combination). The container runs on the
instance's own network, so it listens on guest ports directly: open
them with network.ingress, and name one in readiness to have
Reachable wait for it. Both fields are bound into the measurement
with the image digest (Instance.container.launchLine) and are
host-visible: never put a secret here.
userData?stringCloud-init user data, base64-encoded: the standard alphabet,
padded, with no line breaks (with GNU coreutils, base64 -w0).
Host-visible and not measured: never put a secret here. No image
in this version reads it, so every create that sends it returns
422 unsupported_combination. Check launch.userData on the
image.
^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$bytelength <= 87384placement?Physical placement. Instances that name the same group with policy
colocate run on one host, across requests; when that host is full,
the create returns 409 insufficient_capacity, and when it cannot run
the size or TEE, 422 unsupported_combination at /placement/group.
A group lives on the host of the instance that first names it, and
ends when its last member is terminated or when our operators
retire its host; a create that names it after that starts a new
group. Naming it in a create for another location returns
422 unsupported_combination.
labels?Up to 64 labels, as in Kubernetes. A key is an optional prefix and
/, then a name of up to 63 letters, digits, -, _ and .,
starting and ending with a letter or digit. The prefix is a DNS
subdomain of at most 253 characters, and prefixes in the domains
confidential.ai, kubernetes.io and k8s.io are reserved for the
platform. A value is empty or follows the same rule as the name.
Labels are not secret: never put a secret in one.
properties <= 64nodePool?stringOnly from a managed cluster's controller, which sends exactly one
of nodePool and cdsReplica on every create (400 invalid_request otherwise): the node pool the instance is a
node of. The instance records it for its life as role worker
and nodePool. From anyone else it is 400 invalid_request,
violation incompatible: no request of yours makes an instance
a node of a managed cluster, and no label does.
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$1 <= length <= 40cdsReplica?integerOnly from a managed cluster's controller, like nodePool: the
index of the replica of the cluster's CDS that the instance is,
for a create of one instance. The instance records it for its
life as role cds and cdsReplica.
0 <= value <= 99expiresAt?stringWhen the platform deletes the instances, as a delete request
would, leaving tombstones with reason expired. Without it, the
instances do not expire. A time that is not in the future
returns 400 invalid_request with violation out_of_range at
/expiresAt.
date-timegpuMetrics?booleanWhether Confidential Cloud reads the GPU metrics each instance's
guest serves on TCP 9400, for your org's metrics and Instances
dashboard (Metrics above). Without it, on when the size has GPUs
and the image's launch.gpuMetrics is true, and off
otherwise. false keeps them inside each guest for its life.
true with a CPU size, or an image that can serve no GPU
metrics, returns 422 unsupported_combination.
Accepted. Every instance is placed and addressed, in status
provisioning, and boots on its own from here. A replay returns the
current state of the same instances.
application/json- response
The instances a create made, in index order.
items*array<>curl -X POST 'https://api.cloud.confidential.ai/v1/instances' \ -H 'Idempotency-Key: 0b9d6c1e-5f8a-4c2e-9a51-2f7e0c3d4b18' \ -H 'Api-Version: 2026-10-15' \ -H 'X-Correlation-ID: rollout-2026-10-22' \ -H 'Access-Reason: Support ticket 4821: customer asked why i-6d3f9h2k8mzr failed' \ -H 'Content-Type: application/json' \ -d '{ "name": "poc", "count": 2, "location": "us-west-1", "size": "s1.4x", "image": "confos-cpu", "disks": [ { "name": "data", "type": "scratch", "sizeGiB": 20 }, { "name": "user-data", "type": "scratch", "sizeGiB": 40 } ], "network": { "publicIp": "shared", "ingress": [ { "name": "ssh", "port": 22 }, { "name": "https", "port": 443 } ] }, "access": { "sshKeys": [ "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHwcz1ZWdpesQj0g1D1Cdceg8JdZMFFgKA+foafqkkUg alice@example.com" ] }, "placement": { "group": "poc", "policy": "colocate" }, "labels": { "purpose": "poc" }}'{ "items": [ { "id": "i-7k2m9q4x1bfa", "name": "poc-0", "project": "default", "status": "provisioning", "statusReason": { "code": "starting", "message": "Starting on its host." }, "statusChangedAt": "2026-10-22T17:02:11Z", "conditions": [], "tee": "tdx", "location": "us-west-1", "size": "s1.4x", "compute": { "vcpus": 4, "memoryGiB": 16 }, "image": { "family": "confos-cpu", "version": "2026.10.2", "launch": "general-purpose/1", "digest": "sha256:8c780b3655fc55a663ed38174927e149157c6d2bedf81b9ce60a0a6d8ec33947" }, "disks": [ { "name": "data", "type": "scratch", "sizeGiB": 20, "encryption": "guest" }, { "name": "user-data", "type": "scratch", "sizeGiB": 40, "encryption": "none" } ], "network": { "publicIp": "shared", "ingress": [ { "name": "ssh", "port": 22 }, { "name": "https", "port": 443 } ] }, "endpoints": [ { "name": "ssh", "host": "203.0.113.10", "ipVersion": "ipv4", "port": 20022 }, { "name": "https", "host": "203.0.113.10", "ipVersion": "ipv4", "port": 20443 }, { "name": "attest", "host": "203.0.113.10", "ipVersion": "ipv4", "port": 29840 } ], "boot": { "count": 0 }, "access": { "sshKeys": [ "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHwcz1ZWdpesQj0g1D1Cdceg8JdZMFFgKA+foafqkkUg alice@example.com" ] }, "attestation": { "endpoint": "attest", "referenceManifest": { "uri": "https://measurements.example/confos-cpu/2026.10.2/tdx/manifest.json", "digest": "sha256:472d2826575f5b45c0b463738780a3200de086f98737e7b5bf5298b02a475308", "logEntry": "rekor:1293847" }, "launchBinding": { "file": "pubkey", "sha256": "e52aa028552af775a3aa80566fcf1ef2f9210870656859d03111f2359e8cd5f7", "sha384": "00cc08934f0fadc537830d00499abdec1da4271756307f822a8ee1cae83d30b0b3b8b4442bc7215e67e2d0751bd54ae5" } }, "placement": { "group": "poc", "policy": "colocate" }, "labels": { "purpose": "poc" }, "createdAt": "2026-10-22T17:02:11Z" }, { "id": "i-3w8n5r2c6ehd", "name": "poc-1", "project": "default", "status": "provisioning", "statusReason": { "code": "starting", "message": "Starting on its host." }, "statusChangedAt": "2026-10-22T17:02:11Z", "conditions": [], "tee": "tdx", "location": "us-west-1", "size": "s1.4x", "compute": { "vcpus": 4, "memoryGiB": 16 }, "image": { "family": "confos-cpu", "version": "2026.10.2", "launch": "general-purpose/1", "digest": "sha256:8c780b3655fc55a663ed38174927e149157c6d2bedf81b9ce60a0a6d8ec33947" }, "disks": [ { "name": "data", "type": "scratch", "sizeGiB": 20, "encryption": "guest" }, { "name": "user-data", "type": "scratch", "sizeGiB": 40, "encryption": "none" } ], "network": { "publicIp": "shared", "ingress": [ { "name": "ssh", "port": 22 }, { "name": "https", "port": 443 } ] }, "endpoints": [ { "name": "ssh", "host": "203.0.113.10", "ipVersion": "ipv4", "port": 20023 }, { "name": "https", "host": "203.0.113.10", "ipVersion": "ipv4", "port": 20444 }, { "name": "attest", "host": "203.0.113.10", "ipVersion": "ipv4", "port": 29841 } ], "boot": { "count": 0 }, "access": { "sshKeys": [ "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHwcz1ZWdpesQj0g1D1Cdceg8JdZMFFgKA+foafqkkUg alice@example.com" ] }, "attestation": { "endpoint": "attest", "referenceManifest": { "uri": "https://measurements.example/confos-cpu/2026.10.2/tdx/manifest.json", "digest": "sha256:472d2826575f5b45c0b463738780a3200de086f98737e7b5bf5298b02a475308", "logEntry": "rekor:1293847" }, "launchBinding": { "file": "pubkey", "sha256": "e52aa028552af775a3aa80566fcf1ef2f9210870656859d03111f2359e8cd5f7", "sha384": "00cc08934f0fadc537830d00499abdec1da4271756307f822a8ee1cae83d30b0b3b8b4442bc7215e67e2d0751bd54ae5" } }, "placement": { "group": "poc", "policy": "colocate" }, "labels": { "purpose": "poc" }, "createdAt": "2026-10-22T17:02:11Z" } ]}List instances GET
Lists the org's instances, newest first. `terminated` tombstones are left out unless `status` includes `terminated` or `idempotencyKey` is set. Filters combine with AND, and repeated values of one filter combine with OR, except `label`, where every selector must match.
Get an instance GET
Returns the instance, including a `terminated` tombstone for 90 days after it ended. With `waitFor`, the call holds for up to `timeoutSeconds` until the instance reaches the target, and returns early when it reaches `failed`, `stopped`, `terminated` or `unknown`. It returns `200` with the current state either way, so check `status` and `conditions` in the response. To wait longer, call again; while the instance is `unknown`, pause between calls.