Docs
Instances

Get an instance's maintenance

GET
/v1/instances/{id}/maintenance

Returns the instance's open maintenance event, which the instance's maintenanceEventId names: maintenance the platform needs the instance to take. Restart the instance before the event's deadline to take it when it suits you. An instance with no open event returns 404 not_found.

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:read

Path Parameters

id*string

The instance id.

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

Header Parameters

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

Response Body

The instance's open maintenance event.

application/json
  1. response

Maintenance the platform needs an instance to take. Restart the instance (POST /v1/instances/{id}/restart) before deadline to take it when it suits you; at deadline the platform restarts it, as that restart would, if it is still running with no reason (one whose host is silent then restarts once it runs again). A host's instances restart one at a time, at least two minutes apart, so one may restart some minutes after its deadline. The event is over once a later boot runs, or the instance is deleted. An instance has at most one open event, and its maintenanceEventId names it.

id*string

Opaque. Starts with mnt-.

Lengthlength <= 63
instanceId*InstanceId

Opaque. Starts with i-, is a lowercase DNS label of at most 63 characters, and may change length or form within those rules.

Match^i-[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Lengthlength <= 63
reason*MaintenanceReason

Open set; accept values not listed. host_software_update: the host's virtualization software, or its settings for the instance, were updated, and the instance's boot still runs as it started. A restart runs it on the update. gpu_failure: the host found a GPU the instance's boot holds faulty: fallen off its bus, or a fatal PCIe error. A restart resets the instance's GPUs.

description*string

What the reason means for the instance, in a sentence.

createdAt*string
Formatdate-time
deadline*string

By when to restart the instance onto the maintenance: seven days after createdAt. The platform restarts it then.

Formatdate-time
Example Request
curl -X GET 'https://api.cloud.confidential.ai/v1/instances/i-7k2m9q4x1bfa/maintenance' \  -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'
Example Response
{  "id": "mnt-6ak4v2rqz7b3nxw5hc9dmf8tpe",  "instanceId": "i-2h6c9w4m8tnb",  "reason": "host_software_update",  "description": "The host's virtualization software or its settings for this instance were updated. Restart the instance to run it on the update.",  "createdAt": "2026-11-07T10:00:00Z",  "deadline": "2026-11-14T10:00:00Z"}