Skip to main content
PATCH

Authorizations

​
Authorization
string
header
required

Primary scheme: Authorization: Key <key_id>:<secret>.

Path Parameters

​
drain_id
string
required

The drain's id (drain_<uuid>).

Body

application/json
​
name
string | null

New label; omitted means unchanged.

Required string length: 1 - 100
​
url
string | null

New destination; omitted means unchanged.

Required string length: 1 - 8192
​
format
enum<string> | null

New wire format; omitted means unchanged.

Available options:
ndjson,
otlp
​
secret
string<password> | null
write-only

Rotates the signing secret. No conditional applies here: the drain may already hold one. Switching format to ndjson on a drain with no stored secret requires supplying one in the same request.

Required string length: 64 - 4096
​
headers
Headers · object | null

Replaces the full header set; {} clears it. Omitted means unchanged.

​
enabled
boolean | null

Pause (false) or resume (true) the drain; omitted means unchanged. Re-enabling clears the auto-disable failure count.

​
batch_size
integer | null

New maximum log lines per post; omitted means unchanged.

Required range: 1 <= x <= 5000

Response

Successful Response

​
id
string
required

The drain's id (drain_<uuid>).

​
name
string
required

Human-readable label.

​
url
string
required

The destination endpoint.

​
format
enum<string>
required

Wire encoding for one log drain endpoint's HTTP posts.

Available options:
ndjson,
otlp
​
enabled
boolean
required

Whether the drain receives batches.

​
batch_size
integer
required

Maximum log lines per post.

​
consecutive_failures
integer
required

Failed batches since the last success; the drain auto-disables when it crosses the failure threshold.

​
created_at
string<date-time>
required

ISO-8601 instant the drain was created.

​
updated_at
string<date-time>
required

ISO-8601 instant the config last changed.

​
header_names
string[]

Names of the configured extra headers. Values are write-only and never echoed back.

​
last_success_at
string<date-time> | null

ISO-8601 instant of the last delivered batch.

​
last_failure_at
string<date-time> | null

ISO-8601 instant of the last failed batch.

​
last_failure_status
integer | null

HTTP status of the last failed batch; null when it never got a response.

​
last_error
ErrorEnvelope · object | null

Why the most recent batch delivery failed, in the same error envelope GET /jobs/{job_id} returns for a failed job: a stable code from the shared error vocabulary, a fixed operator-facing message, and retryable. Null while no batch has failed, and cleared on the next success. Destination URLs, headers, credentials, response bodies, and internal exception text are never included. Nor is your drain URL written to Hedra's own logs, since it may carry authentication in its query string. retryable describes the condition, not what Hedra did: every failed batch is requeued until the drain auto-disables, so it answers whether fixing the destination and re-enabling is likely to help. Drains that last failed before this field became structured report UNKNOWN.

​
disabled_reason
string | null

Why the drain is off (consecutive_failures for auto-disable, disabled_by_user); null while enabled.

​
updated_by_key_id
string | null

The API key that last changed the config.