Create a log drain

POST
/v1/log_drains

Streams the environment's logs to a URL: every line GET /v1/logs returns (API requests, email events, webhook attempts) and the environment's audit events, posted as signed batches of up to 500 lines or 1 MB, usually within seconds. format picks the body: NDJSON for your own endpoint, or the intake API of Loki (Grafana Cloud), Datadog or an OTLP/HTTP collector, with auth_header carrying its key. Log drains belong to the API key's own environment: a coss_test_… key only ever sees sandbox drains, and a coss_live_… key only production ones. The response carries the signing secret, which is returned only here: store it, and verify every NDJSON batch with it (verifyLogDrainBatch in the SDK).

Authorization

bearerAuth
headerAuthorizationBearer <token>

A secret API key from the dashboard: coss_live_… for production environments, coss_test_… for sandbox environments.

Header Parameters

Coss-Version?"2026-10-10"

The API version (a date) to use for this request. Defaults to your organization's version, pinned to the latest one when it first used the API and upgraded from the dashboard. The SDK always sends the version it was built for.

Value in"2026-10-10"

Request Body

application/json
  1. body
url*string

An https:// URL coss.com posts batches of log lines to.

Length1 <= length <= 2048
description?|

A note for your own reference. null clears it.

Lengthlength <= 256
sources?array<>

What the drain forwards: api (requests made with the environment's API keys), email (email events), webhook (webhook delivery attempts) and audit (changes to the environment, from the organization's audit log). An empty array means every source, including ones added later. Defaults to every source.

Itemsitems <= 11
format?string

How batches are encoded. ndjson: one JSON object per line (application/x-ndjson), for your own endpoint. loki: Loki's push API (/loki/api/v1/push, Grafana Cloud Logs). datadog: Datadog's log intake (/api/v2/logs). otlp: OTLP/HTTP logs in JSON (/v1/logs, Grafana Cloud, Honeycomb, an OpenTelemetry Collector…). Defaults to ndjson.

Value in"ndjson""loki""datadog""otlp"
auth_header?|

A header sent with every batch, for intake APIs that take a key: Authorization (Basic …, Bearer …), DD-API-KEY… Its value is stored encrypted and never returned. null removes it.

Response Body

The drain and its signing secret.

application/json
  1. response
object*"log_drain"
Value in"log_drain"
id*string
url*string

Where batches are posted.

description*|

Your note about it. null: none.

sources*array<>

What the drain forwards: api (requests made with the environment's API keys), email (email events), webhook (webhook delivery attempts) and audit (changes to the environment, from the organization's audit log). An empty array means every source, including ones added later.

format*LogDrainFormat

How batches are encoded. ndjson: one JSON object per line (application/x-ndjson), for your own endpoint. loki: Loki's push API (/loki/api/v1/push, Grafana Cloud Logs). datadog: Datadog's log intake (/api/v2/logs). otlp: OTLP/HTTP logs in JSON (/v1/logs, Grafana Cloud, Honeycomb, an OpenTelemetry Collector…).

Value in"ndjson""loki""datadog""otlp"
auth_header_name*|

The header sent with every batch to authenticate it (e.g. Authorization, DD-API-KEY), or null. Its value is never returned.

enabled*boolean

A disabled drain receives nothing, and lines logged while it is disabled are not kept for it.

disabled_reason*|

manual: someone disabled it. failing: a batch failed every attempt, so coss.com disabled it. null while enabled.

Value in"manual""failing"null
disabled_at*|

When it was disabled. null while enabled.

Formatdate-time
created_at*string
Formatdate-time
updated_at*string
Formatdate-time
secret*string

The drain's whsec_… signing secret, used to verify the batches coss.com sends. Returned only when the drain is created — store it now; it cannot be read back through the API.

import { Coss } from "coss";const coss = new Coss({  apiKey: process.env.COSS_API_KEY,  baseUrl: "https://api.coss.com",});const { data, error } = await coss.logDrains.create({  url: "https://logs.example.com/coss",  description: "Production logs",  sources: [    "api",    "email",  ],});
{  "object": "log_drain",  "id": "drain_01k7c8m4q2f3e9v6t5r1n0p8yz",  "url": "https://logs.example.com/coss",  "description": "Production logs",  "sources": [    "api",    "email"  ],  "format": "ndjson",  "auth_header_name": null,  "enabled": true,  "disabled_reason": null,  "disabled_at": null,  "created_at": "2026-01-15T09:30:00.000Z",  "updated_at": "2026-01-15T09:30:00.000Z",  "secret": "whsec_6Jk…"}