Changesets

What Is a Changeset?

A changeset represents one unit of change to infrastructure. It is created when a plan runs and can be:

• Applied — the plan is executed against your infrastructure
• Discarded — the plan is abandoned and cannot be applied

Each changeset can have multiple runs associated with it:

• One plan run (the plan itself)
• One apply run (executing the plan)
• One unlock run (if a force-unlock was needed)

Listing Changesets

GET /workspaces/{id}/changesets

Returns the last 50 changesets, ordered by created_at descending.

[{
  "id": "uuid",
  "workspace_id": "uuid",
  "source_type": "git",
  "source_ref": "abc123...",
  "pr_number": 42,
  "applied_at": null,
  "discarded_at": null,
  "created_at": "2026-01-15T10:00:00Z"
}]

Changesets with Embedded Runs

GET /workspaces/{id}/runs

Returns changesets with their associated plan, apply, and unlock runs embedded:

{
  "changesets": [{
    "id": "uuid",
    "source_type": "git",
    "source_ref": "abc123",
    "plan_run": { "id": "...", "status": "completed", "added_count": 2 },
    "apply_run": { "id": "...", "status": "completed" },
    "unlock_run": null
  }],
  "next_cursor": "2026-01-15T10:00:00.000000000Z:uuid"
}

Uses cursor-based pagination (page size: 20). Standalone unlock runs (no changeset) are also included.

PR Filtering

The runs list endpoint supports filtering by PR status:

Getting a Single Changeset

GET /workspaces/{workspaceId}/changesets/{changesetId}

Returns one changeset with embedded run summaries.

Discarding a Changeset

POST /workspaces/{workspaceId}/changesets/{changesetId}/discard

Prevents future applies. Returns 409 if already applied or discarded.

Source Reference

For git-triggered changesets, source_ref contains the resolved commit SHA. This is recorded by the runner after checkout via the POST /runs/{id}/source-ref callback.

Related API Endpoints

• GET /workspaces/{id}/changesets — List changesets
• GET /workspaces/{workspaceId}/changesets/{changesetId} — Get a single changeset
• POST /workspaces/{workspaceId}/changesets/{changesetId}/discard — Discard
• GET /workspaces/{id}/runs — List changesets with embedded runs