# Client API: Deployments: Drains

> The 5 Client API operations for drains.

Source: https://www.coritan.com/docs/api/reference/client/deployments/deployments-drains/

Part of [Deployments](/docs/api/reference/client/deployments/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/deployments/{deployment_uuid}/drains`](#op-get-api-v1-client-deployments-deployment-uuid-drains) | List drains |
| POST | [`/api/v1/client/deployments/{deployment_uuid}/drains`](#op-post-api-v1-client-deployments-deployment-uuid-drains) | A drain that forwards the lines collected from now on |
| PATCH | [`/api/v1/client/deployments/{deployment_uuid}/drains/{drain_id}`](#op-patch-api-v1-client-deployments-deployment-uuid-drains-drain-id) | Update drain |
| DELETE | [`/api/v1/client/deployments/{deployment_uuid}/drains/{drain_id}`](#op-delete-api-v1-client-deployments-deployment-uuid-drains-drain-id) | Remove the drain; nothing more is sent to it |
| POST | [`/api/v1/client/deployments/{deployment_uuid}/drains/{drain_id}/test`](#op-post-api-v1-client-deployments-deployment-uuid-drains-drain-id-test) | Test drain |

### List drains {#op-get-api-v1-client-deployments-deployment-uuid-drains}

`GET /api/v1/client/deployments/{deployment_uuid}/drains`

The deployment's drains, oldest first, and ``limit``: ``allowed``
(the plan's ``deploy_log_drains`` for the account, null when no plan
limits it), ``used`` (drains on the account's deployments),
``plans_apply``, ``deployment_used`` and ``deployment_max``. A drain's
``url`` hides its query values; its secret is never shown again.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### A drain that forwards the lines collected from now on {#op-post-api-v1-client-deployments-deployment-uuid-drains}

`POST /api/v1/client/deployments/{deployment_uuid}/drains`

A drain that forwards the lines collected from now on. ``http``: an
``https://`` address that receives ``POST``s of NDJSON signed with
``X-Coritan-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret,
"<t>." + body)>``; without ``secret`` one is generated and returned
this once as ``secret``. ``syslog``: ``syslog+tls://host:port``, RFC
5424 over TLS, with no secret. The address may not be private,
reserved or the platform's own. 402 past ``deploy_log_drains``; 409
past the per-deployment cap.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | string | yes | http (HTTPS, signed) or syslog (over TLS) |
| `url` | string | yes | https://... for http; syslog+tls://host:port for syslog |
| `secret` | string or null | no | http only: the signing secret; left out, one is generated and shown once |
| `filters` | DrainFilters or null | no |  |
| `filters.processes` | array of string | no | Process names (web, worker, ...); empty: every process |
| `filters.environments` | array of string | no | production and/or preview; empty: both |
| `enabled` | boolean | no |  |

#### Responses

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

### Update drain {#op-patch-api-v1-client-deployments-deployment-uuid-drains-drain-id}

`PATCH /api/v1/client/deployments/{deployment_uuid}/drains/{drain_id}`

Change what was sent: ``url`` (checked as on creation), ``enabled``,
``filters``, and for an http drain ``secret`` or ``rotate_secret``
(a generated secret, returned this once). A new address or a drain
enabled again starts with no failures counted and no error.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string or null | no |  |
| `enabled` | boolean or null | no |  |
| `filters` | DrainFilters or null | no |  |
| `filters.processes` | array of string | no | Process names (web, worker, ...); empty: every process |
| `filters.environments` | array of string | no | production and/or preview; empty: both |
| `secret` | string or null | no | http only: a new signing secret |
| `rotate_secret` | boolean | no | http only: generate a new secret, shown once |

#### Responses

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

### Remove the drain; nothing more is sent to it {#op-delete-api-v1-client-deployments-deployment-uuid-drains-drain-id}

`DELETE /api/v1/client/deployments/{deployment_uuid}/drains/{drain_id}`

Remove the drain; nothing more is sent to it.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Test drain {#op-post-api-v1-client-deployments-deployment-uuid-drains-drain-id-test}

`POST /api/v1/client/deployments/{deployment_uuid}/drains/{drain_id}/test`

Send one sample line now, shaped as the forwarded ones (``test``:
true), and keep the outcome on the drain: ``delivered``, ``status``
(the HTTP answer, when there was one), ``error``. A disabled drain may
be tested before it is enabled again.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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