---
title: "Create a deployment plan"
method: POST
path: "/v1/workspaces/{workspaceId}/deployments/{deploymentId}/plan"
---

# Create a deployment plan

`POST /v1/workspaces/{workspaceId}/deployments/{deploymentId}/plan`

Compute a dry-run plan showing rendered diffs for each release target without creating a version.

## Path parameters

- `workspaceId` string, required
- `deploymentId` string, required

## Request body

- CreateDeploymentPlanRequest
  - `metadata` object — Arbitrary key-value metadata for the plan (e.g. GitHub PR links, CI run URLs)
  - `version` DeploymentPlanVersion, required
    - `config` object
    - `jobAgentConfig` object
    - `metadata` object
    - `name` string — Display name for the proposed version (defaults to tag if omitted)
    - `tag` string, required — Version tag for the proposed deployment (e.g. pr-123-abc123)

## Response `200`

OK response

- DeploymentPlan
  - `id` string, required
  - `status` 'computing' | 'completed' | 'failed', required
  - `summary` DeploymentPlanSummary
    - `changed` integer, required
    - `errored` integer, required
    - `total` integer, required
    - `unchanged` integer, required
    - `unsupported` integer
  - `targets` DeploymentPlanTarget[], required
    - `environmentId` string, required
    - `environmentName` string, required
    - `hasChanges` boolean, required — True if any result for this target has changes
    - `resourceId` string, required
    - `resourceName` string, required
    - `results` DeploymentPlanTargetResult[], required
      - `contentHash` string, required — Hash of the rendered output for change detection
      - `current` string, required — Full rendered output of the currently deployed state
      - `hasChanges` boolean, required
      - `id` string, required
      - `message` string, required — Agent message (e.g. error explanation or summary)
      - `proposed` string, required — Full rendered output of the proposed version
      - `status` 'computing' | 'completed' | 'errored' | 'unsupported', required

## Other responses

- `202` — Accepted response
- `400` — Invalid request
- `404` — Resource not found

---

[API](https://skmtc.dev/ctrlplanedev/apis/ctrlplane-api.md) · [All operations](https://skmtc.dev/ctrlplanedev/apis/ctrlplane-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ctrlplanedev/ctrlplane-api/revisions/156e0d264995/schema)