Extend an instance's expiry
Moves the instance's expiresAt later, and returns the instance.
Requires Idempotency-Key. The new time must be no earlier than
the current one. The time the instance already has changes nothing
and returns the instance as it is, so sending the same time again
is safe. An earlier time returns 400 invalid_request with
violation out_of_range at /expiresAt, and its message names the
earliest time allowed. An instance with no expiresAt returns
400 invalid_request with violation not_allowed at /expiresAt:
an instance gets its expiry only when it is created, so
instances:write never schedules the delete of an instance that
had none. Extending an instance whose reason is expiring clears
that reason.
An instance that is terminating or terminated cannot be
extended: the call returns 409 invalid_state.
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
id*stringThe instance id.
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$1 <= length <= 63Idempotency-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
The instance's new expiry.
expiresAt*stringThe new time: no earlier than the instance's current
expiresAt, and within the caller's limits (GET /v1/limits).
date-timeThe instance, with its new expiresAt. A replay returns its current state.
application/json- response
A confidential virtual machine.
id*InstanceIdOpaque. Starts with i-, is a lowercase DNS label of at most 63
characters, and may change length or form within those rules.
^i-[a-z0-9]([-a-z0-9]*[a-z0-9])?$length <= 63name?stringThe instance's name, from its create or its latest rename. Absent if neither gave one.
length <= 63project*ProjectNameThe project the instance belongs to. Every org has one project, default, in this version.
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$1 <= length <= 63status*InstanceStatusOnly when status is unknown, the status before the host stopped reporting.
statusReason?Why the instance is in its status. Absent when there is nothing to add.
statusChangedAt*stringWhen status last changed.
date-timelastKnownStatus?InstanceStatusOnly when status is unknown, the status before the host stopped reporting.
conditions*array<>Signals about the instance, Kubernetes style. A new instance has none. No condition ever says whether the instance can be trusted: verify that yourself.
tee*TeeThe trusted execution environment. Open set; accept values not listed.
location*LocationIdA location id from GET /v1/locations, such as us-west-1.
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$1 <= length <= 63size*SizeIdA size id from GET /v1/sizes, such as s1.4x. Read ids from that
list; do not build them.
^[a-z0-9]([-.a-z0-9]*[a-z0-9])?$1 <= length <= 63compute*The resolved size.
image*The image version and artifact the instance boots.
container?The OCI image the instance runs as its only workload, present when
the create's image named one. The instance's image pulls it by
digest at every boot and runs it on the instance's network.
disks*array<>The writable disks, in the order the create listed them.
network*How the instance is reached.
readiness?The guest ports Reachable waits on, as the create named them or the image's default.
endpoints*array<>Where to reach the instance: one entry per ingress rule and, when
the image's attestationPublic is true, one named attest for
its attestation service, on the public
IPv4 address, and the same again on the instance's IPv6 address
on the guest's own ports where the location routes IPv6. A rule
on port 443 has one more for each of the instance's hostnames, on
the name's port 443. An endpoint never changes while the instance
holds its address: the platform's ports on the shared address and
its names for the instance's life, and an address attached to it
until it is detached.
Those of the create are assigned when it is accepted, so the
202 response carries them. Empty once the instance is
terminated.
privateAddress?stringThe instance's address on its private network. Present only with
network.privateNetwork, from the moment the create is accepted
until the instance is terminated.
ipv4boot*Every boot is a fresh measured launch, and every disk whose
encryption is guest starts it empty, under a new key. If you
hold a session to an attested key, attest again when count moves.
access?The SSH keys written to the launch disk, in order, each normalised as
the create describes and without its line feed: the pubkey file is
these strings, each followed by a line feed.
trust?The launch key written to the launch disk, exactly as the create gave it, and the format of the launch document. The document itself is never returned.
attestation*What you need to verify the instance yourself. The API never says whether an instance can be trusted.
reservation?ReservationIdThe GPU reservation the instance draws on. Only for GPU sizes.
^r-[a-z0-9]([-a-z0-9]*[a-z0-9])?$length <= 63purchaseOption?PurchaseOptionHow the instance was bought: on-demand, reservation or
spot. A spot instance runs on GPUs that no active reservation
holds, and is stopped, never deleted, when something of higher
priority needs them (the Spot GPUs rules above).
maintenanceEventId?stringThe instance's open maintenance event, if it has one:
GET /v1/instances/{id}/maintenance returns it.
preemptAt?stringOnly while the reason is preempting: when the platform
will stop the instance, 60 seconds after its guest was asked to
shut down.
date-timeterminationAt?stringWhen the platform will delete the instance: the end of its reservation. Only for instances in a reservation.
date-timeexpiresAt?stringWhen the platform will delete the instance, as a delete request
would, leaving a tombstone with reason expired. Absent when the
instance does not expire; every instance an agent credential
creates has one. POST /v1/instances/{id}/extend moves it later.
date-timegpuMetrics?booleanWhether Confidential Cloud reads the GPU metrics this instance's
guest serves on TCP 9400, for your org's metrics and Instances
dashboard. On for an image whose launch.gpuMetrics is true
unless its create turned it off, and off for any other image;
fixed for the instance's life, and in its measured pubkey file
when on. Only for sizes with GPUs, and absent for the others.
placement?role?stringOnly on a node of a managed Kubernetes cluster, which the
cluster's controller created and only the cluster replaces or
deletes: worker for a node of a node pool, cds for a replica
of the cluster's CDS. Open set; accept values not listed. The
controller's create stated it and it never changes. No label
says this: role is absent on an instance you created, whatever
its labels.
cluster?ClusterIdThe managed cluster the instance is a node of, which its
controller's create recorded. Only with role. No label says
this.
^cl-[0-9a-f]{16}$nodePool?NodePoolNameThe node pool the instance is a node of. Only with the role worker.
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$1 <= length <= 40cdsReplica?integerWhich replica of its cluster's CDS the instance is, from 0. Only with the role cds.
0 <= value <= 99labels*Labels. May include keys with a reserved prefix, such as cloud.confidential.ai/, which the platform sets.
createdAt*stringWhen the create was accepted.
date-timecurl -X POST 'https://api.cloud.confidential.ai/v1/instances/i-7k2m9q4x1bfa/extend' \ -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 '{ "expiresAt": "2026-10-24T09:15:00Z"}'{ "id": "i-2h6c9w4m8tnb", "name": "sandbox", "project": "default", "status": "running", "statusChangedAt": "2026-10-22T09:16:02Z", "conditions": [ { "type": "Reachable", "status": "True", "reason": "TcpDialSucceeded", "message": "The guest's wait ports accepted connections from inside our network.", "lastTransitionTime": "2026-10-22T09:16:20Z" } ], "tee": "tdx", "location": "us-west-1", "size": "s1.2x", "compute": { "vcpus": 2, "memoryGiB": 8 }, "image": { "family": "confos-cpu", "version": "2026.10.2", "launch": "general-purpose/1", "digest": "sha256:8c780b3655fc55a663ed38174927e149157c6d2bedf81b9ce60a0a6d8ec33947" }, "disks": [ { "name": "user-data", "type": "scratch", "sizeGiB": 40, "encryption": "none" } ], "network": { "publicIp": "shared", "ingress": [ { "name": "ssh", "port": 22 } ] }, "endpoints": [ { "name": "ssh", "host": "203.0.113.10", "ipVersion": "ipv4", "port": 20024 }, { "name": "attest", "host": "203.0.113.10", "ipVersion": "ipv4", "port": 29842 } ], "boot": { "count": 1, "startedAt": "2026-10-22T09:16:02Z" }, "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" } }, "expiresAt": "2026-10-24T09:15:00Z", "labels": { "purpose": "sandbox" }, "createdAt": "2026-10-22T09:15:00Z"}Verify custom domain ownership POST
Checks the exact TXT challenge and atomically reserves the hostname. Only verified names appear in network.hostnames and shared TLS routing. The guest must provide its own TLS certificate; verification does not issue one or prove gateway readiness. Point the hostname at the instance managed name with a CNAME (or the regional gateway address for an apex). DNS lookup failures leave the registration pending. Removed registrations and terminating instances cannot be verified. A hostname previously verified for an org remains reserved to that org even after removal. The same org can verify a fresh registration on another instance once its prior registration is removed. Pending registrations may prepare for this move while the old registration is still active. To switch desired routing atomically, send replaceDomainId naming the exact active registration. Fresh DNS proof must succeed first; then both instance intents change in one transaction. A stale registration id, different hostname/org or deletion of either instance rejects the move without removing the old route. Gateway convergence remains asynchronous. A successful retry with the same Idempotency-Key returns current state without performing another DNS query.
Start a stopped instance POST
Starts a `stopped` instance again, such as a spot instance whose GPUs a reservation took, and returns it `provisioning`. Requires `Idempotency-Key`. It starts on the same host, where its disks are, with the same disks, addresses and endpoints, and a new boot. A spot instance needs GPUs on that host that no active reservation holds; without them, the call returns `409 insufficient_capacity` and the instance stays `stopped`. An instance in any other status returns `409 invalid_state`; a retry with the same `Idempotency-Key` returns the first answer.