Create a log drain
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).
bearerAuthAuthorizationBearer <token>A secret API key from the dashboard: coss_live_… for production environments, coss_test_… for sandbox environments.
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.
"2026-10-10"application/json- body
- body
- …
url*stringAn https:// URL coss.com posts batches of log lines to.
1 <= length <= 2048description?|A note for your own reference. null clears it.
length <= 256sources?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.
items <= 11format?stringHow 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.
"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.
The drain and its signing secret.
application/json- response
- response
- …
object*"log_drain""log_drain"id*stringurl*stringWhere 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*LogDrainFormatHow 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…).
"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*booleanA 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.
"manual""failing"nulldisabled_at*|When it was disabled. null while enabled.
date-timecreated_at*stringdate-timeupdated_at*stringdate-timesecret*stringThe 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…"}