Docs
Instances

Create instances

POST
/v1/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.

Authorization

headerAuthorizationBearer <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

Header Parameters

Idempotency-Key*string

A 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.

Match^[!-~]+$
Length1 <= length <= 255
Api-Version*string

The 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?string

An 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.

Match^[A-Za-z0-9._:-]+$
Length1 <= length <= 128
Org-Context?string

Admin 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.

Match^org-[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length5 <= length <= 63
Access-Reason?string

Admin 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.

Match^[^\x00-\x1F\x7F]+$
Length10 <= length <= 500

Request Body

application/json
  1. 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?InstanceNameSpec

A 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.

Match^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length1 <= length <= 60
count?integer

How many instances to create. All or none are admitted.

Range1 <= value <= 16
Default1
tee?Tee

The 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*LocationId

Where 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.

Match^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length1 <= length <= 63
size*SizeId

A 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.

Match^[a-z0-9]([-.a-z0-9]*[a-z0-9])?$
Length1 <= length <= 63
image*ImageRef

An 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.

Match^([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})?)$
Length1 <= length <= 512
reservation?ResourceIdParam

The 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.

Match^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length1 <= length <= 63
purchaseOption?PurchaseOption

How 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.

Itemsitems <= 8
Default[]
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?string

Cloud-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.

Match^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
Formatbyte
Lengthlength <= 87384
placement?

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.

Propertiesproperties <= 64
nodePool?string

Only 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.

Match^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length1 <= length <= 40
cdsReplica?integer

Only 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.

Range0 <= value <= 99
expiresAt?string

When 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.

Formatdate-time
gpuMetrics?boolean

Whether 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.

Response Body

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
  1. 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"  }}'
Example Response
{  "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"    }  ]}