Update API

The update API implements the Pulumi Service API protocol for managing infrastructure deployments. See Update Lifecycle for the conceptual overview.

All endpoints require Accept: application/vnd.pulumi+8.

Create Update

POST /api/stacks/{org}/{project}/{stack}/{kind}

Where {kind} is one of: update, preview, refresh, destroy.

Auth: Authorization: token <api-token> Required role: member

Request body (apitype.UpdateProgramRequest):

{
  "name": "my-project",
  "runtime": "nodejs",
  "main": "",
  "description": "",
  "config": {},
  "metadata": {
    "kind": "update",
    "message": "",
    "environment": {}
  }
}

Response (200, apitype.UpdateProgramResponse):

{
  "updateID": "550e8400-e29b-41d4-a716-446655440000"
}

Errors:

• 404 Not Found — stack doesn’t exist
• 409 Conflict — another update is already active on this stack

Start Update

POST /api/stacks/{org}/{project}/{stack}/update/{updateID}

Transitions the update from not started to running and issues a lease token.

Auth: Authorization: token <api-token> Required role: member

Request body (apitype.StartUpdateRequest):

{}

Response (200, apitype.StartUpdateResponse):

{
  "version": 3,
  "token": "lease-token-uuid",
  "tokenExpiration": "2025-03-07T12:00:00Z"
}

• version — current checkpoint version (starting point for this update)
• token — lease token for execution-phase authentication
• tokenExpiration — when the lease expires (renew before this time)

Get Update Status

GET /api/stacks/{org}/{project}/{stack}/update/{updateID}

Returns the current status of an update.

Auth: Authorization: token <api-token> Required role: viewer

Response (200):

{
  "status": "succeeded",
  "kind": "update",
  "startTime": 1709827200,
  "endTime": 1709827260,
  "version": 4,
  "message": "",
  "result": "succeeded"
}

Get Update Events

GET /api/stacks/{org}/{project}/{stack}/update/{updateID}/events

Returns engine events for an update, optionally filtered by continuation token.

Auth: Authorization: token <api-token> Required role: viewer

Query parameters:

• continuationToken — return events after this sequence number

Response (200):

{
  "events": [
    {
      "sequence": 1,
      "timestamp": 1709827200,
      "type": "resourcePreEvent",
      "resourcePreEvent": { ... }
    }
  ],
  "continuationToken": "5"
}

Get Latest Update

GET /api/stacks/{org}/{project}/{stack}/updates/latest

Returns the most recent update for a stack.

Auth: Authorization: token <api-token> Required role: viewer

List Updates

GET /api/stacks/{org}/{project}/{stack}/updates

Returns all updates for a stack, ordered by creation time (newest first).

Auth: Authorization: token <api-token> Required role: viewer

Execution-Phase Endpoints

These endpoints use a different auth scheme: Authorization: update-token <lease-token>.

Patch Checkpoint

PATCH /api/stacks/{org}/{project}/{stack}/update/{updateID}/checkpoint

Saves a full checkpoint (infrastructure state snapshot).

Request body (apitype.PatchUpdateCheckpointRequest):

{
  "deployment": { ... },
  "sequenceNumber": 0,
  "version": 4
}

Patch Checkpoint Verbatim

PATCH /api/stacks/{org}/{project}/{stack}/update/{updateID}/checkpointverbatim

Saves a checkpoint preserving exact JSON formatting. Uses sequenceNumber for idempotency — duplicate sequence numbers are silently ignored.

Patch Checkpoint Delta

PATCH /api/stacks/{org}/{project}/{stack}/update/{updateID}/checkpointdelta

Saves only changed resources. The server applies the delta against the last full checkpoint.

Record Events

POST /api/stacks/{org}/{project}/{stack}/update/{updateID}/events/batch

Records a batch of engine events.

Request body (apitype.EngineEventBatch):

{
  "events": [
    {
      "sequence": 1,
      "timestamp": 1709827200,
      "resourcePreEvent": { ... }
    }
  ]
}

Renew Lease

POST /api/stacks/{org}/{project}/{stack}/update/{updateID}/renew_lease

Extends the lease token’s expiration time.

Request body (apitype.RenewUpdateLeaseRequest):

{
  "duration": 300
}

Response (200, apitype.RenewUpdateLeaseResponse):

{
  "token": "lease-token-uuid",
  "tokenExpiration": "2025-03-07T12:05:00Z"
}

Complete Update

POST /api/stacks/{org}/{project}/{stack}/update/{updateID}/complete

Marks the update as finished.

Request body (apitype.CompleteUpdateRequest):

{
  "status": "succeeded"
}

Status values: succeeded, failed, cancelled.

Cancel Update

POST /api/stacks/{org}/{project}/{stack}/update/{updateID}/cancel

Cancels a running update. Uses regular API token auth (not update-token).

Auth: Authorization: token <api-token> Required role: member

No request body. No response body.

The cancel operation runs in a transaction: sets status to cancelled, clears the lease token, and clears the stack’s current_operation_id. Idempotent — canceling an already-cancelled update returns success.