---
title: "Delete Deployment"
method: DELETE
path: "/deployment/{id}"
tags: ["deployments"]
---

# Delete Deployment

`DELETE /deployment/{id}`

## Request

- Base URL: `https://api.faable.com`
- URL: `https://api.faable.com/deployment/{id}`
- Auth: one of:
  - OAuth 2 (authorization code, authorization URL `https://faable.auth.faable.link/authorize`, token URL `https://faable.auth.faable.link/oauth/token`)
  - HTTP bearer
  - OAuth 2 (client credentials, token URL `https://faable.auth.faable.link/oauth/token`)
  - HTTP bearer
  - HTTP basic
  - API key in query parameter `apikey`

Delete Deployment

## Path parameters

- `id` string, required

## Response `200`

Deployment

- object: Deployment
  - `id` string, required: Deployment ID
  - `team` string, required
  - `app_id` string, required
  - `image` string
  - `release` string
  - `github_commit` string
  - `github_ref` string
  - `github_actor` string
  - `github_commit_message` string
  - `artifact_id` string
  - `artifact_ready_at` string, date-time
  - `build_started_at` string, date-time
  - `build_ms` integer
  - `redeploy_of` string
  - `rebuild_of` string
  - `runtime_fallback` object
    - `name` string, required
    - `from` string, required
    - `to` string, required
    - `of` string, required
  - `runtime_fallback_retry` object
    - `to` string, required
    - `at` string, date-time, required
    - `deployment_id` string
  - `runtime_upgrade` object
    - `name` string, required
    - `to` string, required
    - `previous` object, required
      - `name` string, required
      - `version` string, required
      - `pinned_at` string, date-time, required
      - `source` string, required
  - `quota_released_at` string, date-time
  - `trigger` string
  - `detected` DeploymentDetected
    - `buildpack` string, required
    - `framework` string
    - `runtime` object, required
      - `name` string, required
      - `version` string
      - `source` string
    - `dockerfile_ignored` boolean
    - `process_type` 'worker'
  - `status` DeploymentStatus, required
    - `phase` 'UNKNOWN' | 'QUEUED' | 'BUILDING' | 'ERROR' | 'BUILD_ERROR' | 'INITIALIZING' | 'READY' | 'CANCELED' | 'TERMINATING' | 'SUPERSEDED' | 'QUOTA_HOLD', required: High-level summary of where the Deployment is in its lifecycle
    - `controlled_at` string, date-time: When a controller took control of this deployment
    - `controlled_by` string: INSTANCE_NAME of the controller that claimed it
    - `reason` string: Why the deployment failed (shown to the user on ERROR)
    - `failure_code` string: Producer's own name for what failed (e.g. detect_no_buildpack). Not the fault taxonomy.
    - `failure_detail` object: Structured context the producer had before writing `reason` (found_files, subdir_hits, workdir, root_dir…). Never free build output: it must carry no repository paths beyond the entry names detection already lists.
    - `cold_state` union: Scale-to-zero sub-state (admin-only): asleep, waking or null
      - 'asleep'
      - 'waking'
    - `resource_limit` object: Last hard resource limit (memory or disk) this deployment hit
      - `state` union, required: Which limit was hit
        - 'memory_exceeded'
        - 'disk_exceeded'
      - `at` string, required: ISO time the limit was last hit
      - `count` integer, required: How many times this deployment hit it
    - `runtime_image` string: Runtime image (immutable version tag) this artifact deployment runs
    - `fetcher_image` string: Fetcher image (immutable version tag) of the artifact-prepare initContainer
    - `builder_image` string: Builder image (immutable version tag) that built this deployment
  - `metadata` object, required
  - `createdAt` string, required: Deployment creation date
  - `updatedAt` string: Deployment updated date

## Other responses

- `400`: `invalid_id` — The id in the path is not a valid id for this resource. `validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.
- `401`: `access_denied` — The row exists but does not belong to the caller. `unauthorized` — The request carries no valid credentials. `invalid_token` — The bearer token is missing, malformed or expired.
- `403`: `forbidden` — The credentials are valid but do not allow this operation. `user_suspended` — The account is suspended. Contact support@faable.com.
- `404`: `not_found` — The resource does not exist, or not in the caller’s project.
- `429`: `too_many_requests` — Rate limit exceeded. Honour the `Retry-After` header.
- `500`: `internal_error` — Unexpected server error. Retry later; the request id is logged.
- `503`: `database_unavailable` — Faable cannot reach its database right now. Transient: retry after the `Retry-After` header.

---

[API](https://skmtc.dev/faable/apis/faablecloud-api.md) · [All operations](https://skmtc.dev/faable/apis/faablecloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/faable/apis/faablecloud-api/revisions/e2fc93da3c49?raw)