---
title: "Delete a policy by ID"
method: DELETE
path: "/v1/workspaces/{workspaceId}/policies/{policyId}"
---

# Delete a policy by ID

`DELETE /v1/workspaces/{workspaceId}/policies/{policyId}`

## Path parameters

- `workspaceId` string, required
- `policyId` string, required

## Response `202`

Policy deleted

- Policy
  - `createdAt` string, required
  - `description` string
  - `enabled` boolean, required
  - `id` string, required
  - `metadata` object, required — Arbitrary metadata for the policy (record<string, string>)
  - `name` string, required
  - `priority` integer, required
  - `rules` PolicyRule[], required
    - `anyApproval` AnyApprovalRule
      - `minApprovals` integer, required
    - `createdAt` string, required
    - `deploymentDependency` DeploymentDependencyRule
      - `dependsOn` string, required — CEL expression to match upstream deployment(s) that must have a successful release before this deployment can proceed. The expression can reference both deployment properties (deployment.id, deployment.name, deployment.slug, deployment.metadata) and the currently deployed version properties (version.id, version.tag, version.name, version.status, version.metadata, version.createdAt). For example: deployment.name == 'db-migration' && version.tag.startsWith('v2.').
    - `deploymentWindow` DeploymentWindowRule
      - `allowWindow` boolean, required — If true, deployments are only allowed during the window. If false, deployments are blocked during the window (deny window)
      - `durationMinutes` integer, required — Duration of each deployment window in minutes
      - `rrule` string, required — RFC 5545 recurrence rule defining when deployment windows start (e.g., FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9)
      - `timezone` string — IANA timezone for the rrule (e.g., America/New_York). Defaults to UTC if not specified
    - `environmentProgression` EnvironmentProgressionRule
      - `dependsOnEnvironmentSelector` string, required — CEL expression to match the environment(s) that must have a successful release before this environment can proceed.
      - `maximumAgeHours` integer — Maximum age of dependency deployment before blocking progression (prevents stale promotions)
      - `minimumSoakTimeMinutes` integer — Minimum time to wait after the depends on environment is in a success state before the current environment can be deployed. Defaults to 0 if not provided.
      - `minimumSuccessPercentage` number, float
      - `requireVerificationPassed` boolean — If true, jobs must also have passed verification to count toward the success percentage
      - `successStatuses` JobStatus[]
    - `gradualRollout` GradualRolloutRule
      - `rolloutType` 'linear' | 'linear-normalized', required — Strategy for scheduling deployments to release targets. "linear": Each target is deployed at a fixed interval of timeScaleInterval seconds. "linear-normalized": Deployments are spaced evenly so that the last target is scheduled at or before timeScaleInterval seconds. See rolloutType algorithm documentation for details.
      - `timeScaleInterval` integer, required — Base time interval in seconds used to compute the delay between deployments to release targets.
    - `id` string, required
    - `planValidationOpa` PlanValidationOpaRule
      - `description` string
      - `name` string, required — Human-readable rule name; used in check output to identify which rule produced a violation.
      - `rego` string, required — Rego v1 source code. Must define a `deny` rule set following the Conftest convention (deny contains msg if { ... }).
    - `policyId` string, required
    - `retry` RetryRule
      - `backoffSeconds` integer — Minimum seconds to wait between retry attempts. If null, retries are allowed immediately after job completion.
      - `backoffStrategy` 'linear' | 'exponential' — Backoff strategy: "linear" uses constant backoffSeconds delay, "exponential" doubles the delay with each retry (backoffSeconds * 2^(attempt-1)).
      - `maxBackoffSeconds` integer — Maximum backoff time in seconds (cap for exponential backoff). If null, no maximum is enforced.
      - `maxRetries` integer, required — Maximum number of retries allowed. 0 means no retries (1 attempt total), 3 means up to 4 attempts (1 initial + 3 retries).
      - `retryOnStatuses` JobStatus[] — Job statuses that count toward the retry limit. If null or empty, defaults to ["failure", "invalidIntegration", "invalidJobAgent"] for maxRetries > 0, or ["failure", "invalidIntegration", "invalidJobAgent", "successful"] for maxRetries = 0. Cancelled and skipped jobs never count by default (allows redeployment after cancellation). Example: ["failure", "cancelled"] will only count failed/cancelled jobs.
    - `verification` VerificationRule
      - `metrics` VerificationMetricSpec[], required — Metrics to verify
        - `count` integer, required — Number of measurements to take
        - `failureCondition` string — CEL expression to evaluate measurement failure (e.g., "result.statusCode == 500"), if not provided, a failure is just the opposite of the success condition
        - `failureThreshold` integer — Stop after this many consecutive failures (0 = no limit)
        - `intervalSeconds` integer, required — Interval between measurements in seconds
        - `name` string, required — Name of the verification metric
        - `provider` union, required
          - HTTPMetricProvider
            - `body` string — Request body (supports Go templates)
            - `headers` object — HTTP headers (values support Go templates)
            - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' — HTTP method
            - `timeout` string — Request timeout (duration string, e.g., "30s")
            - `type` 'http', required — Provider type
            - `url` string, required — HTTP endpoint URL (supports Go templates)
          - SleepMetricProvider
            - `durationSeconds` integer, required
            - `type` 'sleep', required — Provider type
          - DatadogMetricProvider
            - `aggregator` 'avg' | 'min' | 'max' | 'sum' | 'last' | 'percentile' | 'mean' | 'l2norm' | 'area' — Datadog aggregator
            - `apiKey` string, required — Datadog API key (supports Go templates for variable references)
            - `appKey` string, required — Datadog Application key (supports Go templates for variable references)
            - `formula` string — Datadog formula (supports Go templates)
            - `intervalSeconds` integer
            - `queries` object, required — Datadog metrics queries (supports Go templates)
            - `site` string — Datadog site URL (e.g., datadoghq.com, datadoghq.eu, us3.datadoghq.com)
            - `type` 'datadog', required — Provider type
          - PrometheusMetricProvider
            - `address` string, required — Prometheus server address (supports Go templates)
            - `authentication` object — Authentication configuration for Prometheus
              - …
            - `headers` object[] — Additional HTTP headers for the Prometheus request (values support Go templates)
              - …
            - `insecure` boolean — Skip TLS certificate verification
            - `query` string, required — PromQL query expression (supports Go templates)
            - `rangeQuery` object — If provided, a range query (/api/v1/query_range) is used instead of an instant query (/api/v1/query)
              - …
            - `timeout` integer — Query timeout in seconds
            - `type` 'prometheus', required — Provider type
          - TerraformCloudRunMetricProvider
            - `address` string, required — Terraform Cloud address
            - `runId` string, required — Terraform Cloud run ID
            - `token` string, required — Terraform Cloud token
            - `type` 'terraformCloudRun', required — Provider type
        - `successCondition` string, required — CEL expression to evaluate measurement success (e.g., "result.statusCode == 200")
        - `successThreshold` integer — Minimum number of consecutive successful measurements required to consider the metric successful
      - `triggerOn` 'jobCreated' | 'jobStarted' | 'jobSuccess' | 'jobFailure' — When to trigger verification
    - `versionCooldown` VersionCooldownRule
      - `intervalSeconds` integer, required — Minimum time in seconds that must pass since the currently deployed (or in-progress) version was created before allowing another deployment. This enables batching of frequent upstream releases into periodic deployments.
    - `versionSelector` VersionSelectorRule
      - `description` string — Human-readable description of what this version selector does. Example: "Only deploy v2.x versions to staging environments"
      - `selector` string, required — CEL expression to select which versions are eligible for deployment.
  - `selector` string, required — CEL expression for matching release targets. Use "true" to match all targets.
  - `workspaceId` string, required

## Other responses

- `400` — Invalid request
- `404` — Resource not found

---

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