Docs
Instances

List open maintenance events

GET
/v1/maintenance-events

Lists the open maintenance events of the org's instances, newest first: the instances the platform needs restarted, and by when.

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

Query Parameters

pageSize?integer

The most items to return.

Range1 <= value <= 100
Default50
pageToken?string

The nextPageToken of the previous page, unchanged. Send the same filters with it.

Length1 <= length <= 2048

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

A page of the org's open maintenance events, newest first.

application/json
  1. response
items*array<>
nextPageToken?NextPageToken

Pass it back as pageToken for the next page. Absent on the last page.

Example Request
curl -X GET 'https://api.cloud.confidential.ai/v1/maintenance-events?pageSize=50&pageToken=eyJjIjoiMjAyNi0xMC0yMlQxNzowMjoxMVoiLCJpIjoiaS03azJtOXE0eDFiZmEifQ' \  -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
{  "items": [    {      "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"    }  ]}

Get an instance's maintenance GET

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

Add a dedicated IPv4 to an existing instance POST

Allocates a dedicated public IPv4 on the instance's current host and activates it without recreating the VM or its disks. Requires Idempotency-Key. The address is used for ingress on the guest's own ports and for outbound connections. Existing connections may need to reconnect when the source address changes. The address belongs to this VM until explicitly removed or the VM is deleted; an existing allocation is returned without acquiring another address. Returns 202 while activation is pending, and 200 once active. network.ipv4Activating is true while waiting for an address and until the location's network routes the new address to the instance. With an enabled automatic IPv4 pool, an empty pool queues the request durably and returns 202. The VM keeps publicIp shared and its current endpoints while waiting for stock. Its previous shared ports remain reserved until activation completes. Without an automatic pool, or when the pool is at its spending ceiling, no free address returns 409 insufficient_capacity. A request past the org's dedicated IPv4 quota returns 403 quota_exceeded with `details.quota` `org.dedicatedIpv4`; `GET /v1/limits` returns the quota. A terminating or terminated instance returns 409 invalid_state, as does one not on a host yet: add the address once it is running.