> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gavai.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployments

> Track, cancel, and promote deployment records created when you publish pages or themes.

export const ErrorTable = ({errors}) => <div className="gv-error-table" role="table" aria-label="Errors and fixes">
    <div className="gv-error-table__head" role="row">
      <span className="gv-error-table__col-head" role="columnheader">Error</span>
      <span className="gv-error-table__col-head" role="columnheader">Cause</span>
      <span className="gv-error-table__col-head" role="columnheader">Fix</span>
    </div>
    {errors.map((err, i) => <div className="gv-error-table__row" role="row" key={i}>
        <code className="gv-error-table__code" role="cell">{err.code}</code>
        <div className="gv-error-table__cause" role="cell">{err.cause}</div>
        <div className="gv-error-table__fix" role="cell">{err.fix}</div>
      </div>)}
  </div>;

export const Def = ({term, type, defaultValue, required, children}) => <>
    <dt className="gv-def-list__term">
      <span className="gv-def-list__name">{term}</span>
      {type && <span className="gv-def-list__type">{type}</span>}
      {required && <span className="gv-def-list__required">required</span>}
      {defaultValue !== undefined && <span className="gv-def-list__default">
          default <code>{defaultValue}</code>
        </span>}
    </dt>
    <dd className="gv-def-list__description">{children}</dd>
  </>;

export const DefList = ({children}) => <dl className="gv-def-list">{children}</dl>;

export const ExpectedOutput = ({caption = "Expected output", children}) => <div className="gv-output">
    <div className="gv-output__label">
      <svg className="gv-output__icon" viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
        <polyline points="15 10 20 15 15 20" />
        <path d="M4 4v7a4 4 0 0 0 4 4h12" />
      </svg>
      <span>{caption}</span>
    </div>
    <div className="gv-output__body">{children}</div>
  </div>;

export const APIBadge = ({method = "GET", path, scope}) => {
  const m = method.toUpperCase();
  return <span className="gv-api-badge">
      <span className={`gv-api-badge__method gv-api-badge__method--${m.toLowerCase()}`}>
        {m}
      </span>
      <code className="gv-api-badge__path">{path}</code>
      {scope && <span className="gv-api-badge__scope">
          <span className="gv-api-badge__scope-label">scope</span>
          <code>{scope}</code>
        </span>}
    </span>;
};

export const Eyebrow = ({label, tone = "default"}) => <div className={`gv-eyebrow gv-eyebrow--${tone}`}>
    <span className="gv-eyebrow__bar" aria-hidden="true" />
    <span className="gv-eyebrow__label">{label}</span>
  </div>;

<Eyebrow label="RESOURCE" />

Every page publish or theme publish creates a deployment record that tracks the build through to live. The Deployments resource lets you list those records, inspect a single deployment, cancel a build still in flight, or promote a tested deployment. By the end of this page you will know the statuses a deployment moves through and which transitions you can drive.

## A deployment in shape

<ExpectedOutput>
  ```json theme={null}
  {
    "id":           "dep_01H...",
    "status":       "live",
    "created_at":   "2026-03-12T10:00:00Z",
    "completed_at": "2026-03-12T10:01:12Z"
  }
  ```
</ExpectedOutput>

## Endpoints

<APIBadge method="GET" path="/v1/workspaces/{slug}/deployments" scope="deployments:read" />

List all deployments for the workspace, newest first.

<APIBadge method="GET" path="/v1/workspaces/{slug}/deployments/{id}" scope="deployments:read" />

Fetch a single deployment record.

<APIBadge method="POST" path="/v1/workspaces/{slug}/deployments/{id}/cancel" scope="deployments:destructive" />

Cancel a deployment that is still in flight.

<APIBadge method="POST" path="/v1/workspaces/{slug}/deployments/{id}/promote" scope="deployments:write" />

Promote a deployment to live.

## Status values

<DefList>
  <Def term="pending">Created, not yet started. Non-terminal.</Def>
  <Def term="building">Build in progress. Non-terminal.</Def>
  <Def term="live">Promoted to production. Terminal.</Def>
  <Def term="failed">Build errored or rejected. Terminal.</Def>
  <Def term="cancelled">Stopped by an explicit `POST .../cancel`. Terminal.</Def>
</DefList>

`completed_at` is set when a deployment reaches any terminal status and is `null` until then.

## Allowed transitions

| From                  | Action             | Result                                          |
| --------------------- | ------------------ | ----------------------------------------------- |
| `pending`, `building` | `POST .../cancel`  | Moves to `cancelled`. Irreversible.             |
| `building`            | (server-driven)    | Moves to `live` on success or `failed` on error |
| Promotable state      | `POST .../promote` | Moves to `live`                                 |
| Any terminal state    | `POST .../cancel`  | `409 already_terminal`                          |

<Warning>
  Cancellation is irreversible. To undo a publish, run a fresh publish or roll back the page through [Pages](/api-reference/resources/pages) — do not rely on cancel for that.
</Warning>

## Common errors

<ErrorTable
  errors={[
{ code: "404 not_found", cause: "No deployment with this id in this workspace.", fix: "Verify the id; list `/deployments` to see what exists." },
{ code: "409 already_terminal", cause: "Cancel called on a deployment that has already completed.", fix: "Inspect the deployment first; only `pending` and `building` are cancellable." },
{ code: "409 not_promotable", cause: "Promote called on a deployment not in a promotable state.", fix: "Wait until the build reaches a promotable status, or pick a different deployment." },
]}
/>

## Related

<Card title="Pages" icon="file" href="/api-reference/resources/pages">
  Publishing a page or theme is what creates a deployment record.
</Card>