# Organization API: Organization deployments: Deployments

> The 20 Organization API operations for deployments.

Source: https://www.coritan.com/docs/api/reference/organizations/organization-deployments/deployments/

Part of [Organization deployments](/docs/api/reference/organizations/organization-deployments/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/deployments`](#op-get-api-v1-orgs-org-slug-deployments) | The caller's deployments of every kind, newest first |
| GET | [`/api/v1/orgs/{org_slug}/deployments/{deployment_uuid}`](#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid) | Get deployment |
| PATCH | [`/api/v1/orgs/{org_slug}/deployments/{deployment_uuid}`](#op-patch-api-v1-orgs-org-slug-deployments-deployment-uuid) | Update deployment |
| DELETE | [`/api/v1/orgs/{org_slug}/deployments/{deployment_uuid}`](#op-delete-api-v1-orgs-org-slug-deployments-deployment-uuid) | Delete a deployment |
| GET | [`/api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/alerts`](#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-alerts) | Get alerts |
| GET | [`/api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/analytics`](#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-analytics) | Get analytics |
| GET | [`/api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/instances`](#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-instances) | The deployment's running copies |
| GET | [`/api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/metrics`](#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-metrics) | Get metrics |
| GET | [`/api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/placements`](#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-placements) | Get placements |
| PUT | [`/api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/placements`](#op-put-api-v1-orgs-org-slug-deployments-deployment-uuid-placements) | Change where a deployment runs |
| GET | [`/api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/processes`](#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-processes) | Get processes |
| PUT | [`/api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/processes`](#op-put-api-v1-orgs-org-slug-deployments-deployment-uuid-processes) | Replace a deployment's processes |
| POST | [`/api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/redeploy`](#op-post-api-v1-orgs-org-slug-deployments-deployment-uuid-redeploy) | Redeploy |
| GET | [`/api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/requests`](#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-requests) | Get requests |
| GET | [`/api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/rules`](#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-rules) | Get rules |
| PUT | [`/api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/rules`](#op-put-api-v1-orgs-org-slug-deployments-deployment-uuid-rules) | Replace firewall rules |
| GET | [`/api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/scaling`](#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-scaling) | Get scaling |
| PUT | [`/api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/scaling`](#op-put-api-v1-orgs-org-slug-deployments-deployment-uuid-scaling) | Change a deployment's autoscaling |
| POST | [`/api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/uploads`](#op-post-api-v1-orgs-org-slug-deployments-deployment-uuid-uploads) | Upload release |
| GET | [`/api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/usage`](#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-usage) | Get usage |

### The caller's deployments of every kind, newest first {#op-get-api-v1-orgs-org-slug-deployments}

`GET /api/v1/orgs/{org_slug}/deployments`

The caller's deployments of every kind, newest first. ``counts``
holds how many each status has and ``kinds`` how many each kind has,
under the same filters (the one counted aside), so tiles and tabs add
up to what the list shows. A kind switched off lists none.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `kind` | query | string or null | no | template, git, image, static or hybrid; left out: every one |
| `status` | query | string or null | no | active, paused or suspended; left out: every one |
| `location` | query | string or null | no | Deployments with a placement there |
| `q` | query | string or null | no | Part of a name, slug or domain, or a uuid |
| `limit` | query | integer | no | How many deployments to return, 1 to 100 Default: `50`. |
| `offset` | query | integer | no | How many to skip, for the next page Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get deployment {#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid}

`GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}`

One deployment with its instances, its domains and its five newest
releases (``releases_total`` counts them all). A template's instances
are its servers, with their power state.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `deployment_uuid` | path | string (uuid) | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Update deployment {#op-patch-api-v1-orgs-org-slug-deployments-deployment-uuid}

`PATCH /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}`

Change a deployment's settings in the order's words: ``name`` for
every kind; ``build`` (preset, install_command, build_command,
start_command, output_dir) and ``runtime`` (port, health_check_path)
for the kinds that build or run; ``image.ref`` for an image
deployment. A ``build.dockerfile_path`` that names a file answers 422
``dockerfile_unsupported`` (Dockerfiles are not built: deploy the
image your CI builds as a container image); a null one clears an old
one. A template's servers change under
``/api/v1/client/servers`` (409 ``template_deployment``); placement,
git, processes and scaling have routes of their own (422 naming them).
``redeploy_required`` and ``rebuild_required`` say whether running
instances pick the change up only with a new release or a new build.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `deployment_uuid` | path | string (uuid) | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

Type: Body.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete a deployment {#op-delete-api-v1-orgs-org-slug-deployments-deployment-uuid}

`DELETE /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}`

Delete a deployment. One a service pays for (every template, and a
deployment ordered through the services page) cancels that service
now: its terminate job removes the servers or the replicas, its unpaid
invoices are voided and, for a template, ``keep_snapshot`` saves the
server's data first, as cancelling from the services page does. An
Apps app with no service is deleted at once: releases on their way
canceled, routes and domains removed, replicas drained, variables
erased. It cannot be undone. A deployment already ending answers 409
``already_ending``. What its bindings made is revoked once the
deletion commits (for one a service pays for, when that service
ends).

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `deployment_uuid` | path | string (uuid) | yes |  |
| `org_slug` | path | string | yes |  |
| `confirm` | query | string | yes | The deployment's name (or its slug), typed to confirm |
| `reason` | query | string or null | no | Why, kept in the audit log and on the canceled service |
| `keep_snapshot` | query | boolean | no | A template: save its server's data before it is deleted Default: `True`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get alerts {#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-alerts}

`GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/alerts`

What the deployment's owner was alerted about, newest first:
``kind``, ``at``, ``summary``, ``incident`` (the release, or the hour),
``emailed``, ``held`` (a failed release inside the hour after another
was emailed), ``webhooks`` (deliveries queued) and ``details``.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `deployment_uuid` | path | string (uuid) | yes |  |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Alerts listed: the newest Default: `50`. |
| `kind` | query | string or null | no | release_failed, error_spike or wake_storm |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get analytics {#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-analytics}

`GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/analytics`

Page views and distinct visitors per UTC day of ``window`` (``7d``,
``30d``, ``90d``) for the deployment's hostnames, as the tracking
collector saw them, with the totals per hostname. Only pages that load
the tracking script are counted, by the hostname they report;
``notes`` say what that can and cannot attribute.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `deployment_uuid` | path | string (uuid) | yes |  |
| `org_slug` | path | string | yes |  |
| `window` | query | string | no | 7d, 30d or 90d: the UTC days up to today that are counted Default: `30d`. |
| `hostname` | query | string or null | no | One of the deployment's addresses |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The deployment's running copies {#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-instances}

`GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/instances`

The deployment's running copies. A template's are its servers, each
with its power state and ``server_uuid`` (its power, console and files
are under ``/api/v1/client/servers/{server_uuid}``); a stateless
deployment's are its live replicas with the release each runs; a
static deployment has none.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `deployment_uuid` | path | string (uuid) | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get metrics {#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-metrics}

`GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/metrics`

Every hour of ``window`` (``24h``, ``7d``, ``30d``): ``requests``,
``blocked``, ``status`` (2xx to 5xx), ``bytes_in``, ``bytes_out``,
``latency_avg_ms``, ``latency_p99_ms``, ``websockets``; the
``totals`` with ``error_rate``; and each running or sleeping
instance's ``cpu`` (percent of one core: ``now``, ``avg_15m``,
``avg_1h``) and ``memory_bytes``, from its latest reading, with its
``history``: every step of ``instance_window`` (``1h`` in five
minutes, ``24h`` in fifteen, ``7d`` in hours), oldest first, each
``at``, ``samples``, ``cpu_avg``, ``cpu_max``, ``memory_avg_bytes`` and
``memory_max_bytes`` (0 samples and nulls where nothing was read).
``instance_history`` says the ``window``, ``step_seconds``, ``from``,
``to`` and ``kept_days``. ``notes`` say what the figures cannot
show.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `deployment_uuid` | path | string (uuid) | yes |  |
| `org_slug` | path | string | yes |  |
| `window` | query | string | no | 24h, 7d or 30d: the hours up to now that the counts cover Default: `24h`. |
| `hostname` | query | string or null | no | One of the deployment's addresses |
| `instance_window` | query | string or null | no | 1h, 24h or 7d: the span of each instance's CPU and memory history; left out, window's (7d for 30d) |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get placements {#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-placements}

`GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/placements`

Where the deployment runs (``placement``), whether it can be changed
here and the locations it could run in now.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `deployment_uuid` | path | string (uuid) | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Change where a deployment runs {#op-put-api-v1-orgs-org-slug-deployments-deployment-uuid-placements}

`PUT /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/placements`

Change where the deployment runs, checked exactly as an order's
``placement`` is (422 naming the field, 402 past the plan's locations
or autoscaling). The current release is re-placed at once: locations
added get instances, instances beyond a location's count and those of a
location left drain once another location serves. A template answers
409 ``template_placement``; a static deployment takes only
``{"mode": "all"}``.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `deployment_uuid` | path | string (uuid) | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

Type: Body.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get processes {#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-processes}

`GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/processes`

The deployment's processes, each with its kind, command, schedule,
instances per location and whether it is enabled, and what the
production release runs of it: a worker's running instances; a cron's
next time, its last run and whether one is going now. With none,
the release runs its web only. A template or a static deployment has
none (``changeable`` false).

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `deployment_uuid` | path | string (uuid) | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Replace a deployment's processes {#op-put-api-v1-orgs-org-slug-deployments-deployment-uuid-processes}

`PUT /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/processes`

Replace the deployment's processes with the list in ``processes``,
each checked as an order's ``runtime.processes`` are (422 naming the
field) and taking ``enabled`` (true when left out). ``web`` serves the
port, running its ``command`` instead of the image's own when it names
one, as many as the placement says; a ``worker`` runs ``instances``
copies in every location; a ``cron`` runs at each time its
``schedule`` names, in the first location. The production release's
heal is queued at once: the workers and crons it lacks start, and
those removed, disabled or beyond their count drain. A changed command
reaches a cron at its next run, and a worker or the web when it starts
again (``redeploy_required``). A template or a static deployment
answers 409.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `deployment_uuid` | path | string (uuid) | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

Type: Body.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Redeploy {#op-post-api-v1-orgs-org-slug-deployments-deployment-uuid-redeploy}

`POST /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/redeploy`

Release the current build again (picking up variables, size,
placement and scaling changes), or build the branch afresh with
``rebuild``.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `deployment_uuid` | path | string (uuid) | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rebuild` | boolean | no | Build the branch again instead of reusing the current image |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get requests {#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-requests}

`GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/requests`

The requests every edge location sampled on the deployment's
addresses in the last ``retention_days`` (3), newest first, the
newest ``limit`` that match every filter given: ``status`` (a class),
``path`` (a prefix, without the query string), ``release``,
``location`` and ``hostname``. ``next`` is the cursor of the page after
them (pass it as ``before``), null at the oldest. Each: ``id``,
``ts``, ``hostname``, ``method``, ``path``, ``status``, ``latency_ms``,
``bytes_out``, ``release``, ``location``, ``cache`` (hit, miss, static
or bypass), ``client_ip`` and ``country``. ``sample`` says what an edge
process keeps: every request up to ``full_per_second`` a second per
address, then 1 in ``then_one_in`` and every 5xx, at most
``most_per_second``. 422 ``invalid_cursor`` for a ``before`` that is
not a page's ``next``; 404 ``unknown_hostname``; 429 past 120 pages
a minute.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `deployment_uuid` | path | string (uuid) | yes |  |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Requests on the page: the newest that match Default: `100`. |
| `hostname` | query | string or null | no | One of the deployment's addresses |
| `status` | query | string or null | no | 1xx, 2xx, 3xx, 4xx or 5xx |
| `path` | query | string or null | no | Paths starting with this, ignoring case: /api |
| `release` | query | string (uuid) or null | no | The id of the release that answered |
| `location` | query | string or null | no | The edge location that answered: fra, iad, ... |
| `before` | query | string or null | no | A page's next: the requests older than it |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get rules {#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-rules}

`GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/rules`

The deployment's own firewall rules and rate limits, oldest first, in
the Websites shape (``id`` is the rule's name). ``managed_rules``
counts the managed set's enabled rules; ``account`` counts the enabled
rules of the owner's own across their websites and deployments, which
is what the plan counts; ``limits`` is the plan's allowance while
plans cover the account, else null (-1 is no limit).

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `deployment_uuid` | path | string (uuid) | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Replace firewall rules {#op-put-api-v1-orgs-org-slug-deployments-deployment-uuid-rules}

`PUT /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/rules`

Make ``rules`` the deployment's own set on every one of its
addresses. 409 while it has no address; 422 for a rule that does not
check out (``index`` names it) or past 200 rules or 50 rate limits;
402 when the owner's plan leaves no room, counted with their websites.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `deployment_uuid` | path | string (uuid) | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rules` | array of any | yes | The whole set, each in the Websites shape; a rule sent back with its id keeps its name |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get scaling {#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-scaling}

`GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/scaling`

How the deployment scales: the targets one instance should carry
(``targets`` as set, ``effective_targets`` as applied: CPU 70% when it
sets none), until when billing caps its bursts, ``sleep_after_seconds``
and the ``idle_seconds`` that apply, and each location's counts and
``sleep`` (under ``/placements``), between which it scales and which
decide whether a location sleeps. A template or a static deployment
has none (``changeable`` false).

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `deployment_uuid` | path | string (uuid) | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Change a deployment's autoscaling {#op-put-api-v1-orgs-org-slug-deployments-deployment-uuid-scaling}

`PUT /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/scaling`

Change the autoscaling targets and the idle time, checked as an
order's ``scaling`` is: the whole block, a key left out being null
(no targets: CPU 70%; no idle time: 15 minutes where a location
sleeps). Targets need autoscaling on the plan (402). A cap billing
holds on the bursts stays. The sweeps read the change within a minute;
nothing starts or stops here. A location scales only when its
``max`` is above its ``min``, and sleeps only when its ``sleep`` is
``idle``: both change under ``/placements``. A template or a static
deployment answers 409.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `deployment_uuid` | path | string (uuid) | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

Type: Body.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Upload release {#op-post-api-v1-orgs-org-slug-deployments-deployment-uuid-uploads}

`POST /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/uploads`

Release the uploaded archive: it is checked, a release is created and
its build queued, and the archive is stored for the build container.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `deployment_uuid` | path | string (uuid) | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get usage {#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-usage}

`GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/usage`

The deployment's metered use in a month (this month so far when
``month`` is left out), by meter and in each meter's ``unit``: what it
used, what its allowances included and what was billable. No money:
what it cost is under ``/api/v1/billing/deployments/{uuid}``, for the
account's Billing role. A template is billed by its plan and meters
nothing.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `deployment_uuid` | path | string (uuid) | yes |  |
| `org_slug` | path | string | yes |  |
| `month` | query | string or null | no | YYYY-MM; this month when left out |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |