Skip to main content

API reference

Base URL: https://api.s2b.tznc.dev. gRPC: api.s2b.tznc.dev:443 over TLS and HTTP/2. Timestamps are ISO 8601 in UTC with microseconds. Stream and organization IDs are UUIDs.

Authentication​

Every ingestion request carries a stream's API key. Keys look like s2b_ingest_ followed by 32 base62 characters.

TransportHow to send the key
HTTPAuthorization: Bearer <key> (preferred) or x-api-key: <key>
gRPCmetadata authorization: Bearer <key>

A key belongs to one ingestion stream (stream for short), and a stream writes to exactly one destination. The stream accepts data only once its destination is verified.

POST /v1/events​

Accepts one JSON object or a JSON array of objects, written to the key's stream, or the batch format to write to several streams in one request.

HeaderValue
Content-Typeapplication/json
Content-Encodinggzip or identity (the default)

The request is accepted or rejected as a whole. When any item is invalid, nothing is stored and nothing is billed.

A 200 means the batch is stored durably and will be delivered:

{"accepted":2,"bytes":106}

bytes is the decompressed UTF-8 body length, the number billed.

Errors​

Errors are JSON with an error code and, for some codes, more fields.

StatuserrorMeaning
400invalid_jsonThe body is not valid JSON.
400invalid_itemThe body, or an array item, is not a JSON object.
400item_too_largeAn item is larger than 8 KiB. Includes max_bytes.
400number_out_of_rangeA number has more than 34 significant digits or an exponent beyond ±6144 (IEEE 754 decimal128).
400invalid_encodingThe body cannot be decoded with its Content-Encoding.
401unauthorizedMissing, unknown or revoked API key.
409destination_not_readyThe stream has no verified destination.
413body_too_largeThe decompressed body is larger than 16 MiB. Includes max_bytes.
415unsupported_encodingContent-Encoding is not gzip or identity.
429quota_exceededThe organization's plan allowance would be exceeded.
503buffer_fullSend2Bucket is temporarily at capacity. Retry-After: 30.
503destination_backlogThe stream's undelivered backlog is at its limit. Retry-After: 30.

A 429 tells you what is left and when the allowance resets:

{"error":"quota_exceeded","plan":"free","remaining_bytes":1824,"resets_at":"2026-12-01T00:00:00.000000Z"}

A smaller request can still fit in remaining_bytes. Otherwise wait until resets_at or change plan.

Batch format​

A body that is an object with only a batch key uses the batch format: each record names its stream, and its data is one JSON object, as in a plain request. An object with batch and any other key is a plain event.

{"batch":[
{"stream_id":"3f6c2a9e-8b1d-4e7a-9c55-0d2b7e41a8f3","data":{"type":"click"}},
{"stream_id":"3f6c2a9e-8b1d-4e7a-9c55-0d2b7e41a8f3","data":{"type":"view"}}
]}

Records are committed as one batch per stream, all or none. A key can write only to its own stream for now.

{"accepted":2,"bytes":31,"batches":[
{"stream_id":"3f6c2a9e-8b1d-4e7a-9c55-0d2b7e41a8f3","accepted":2,"bytes":31}
]}

bytes is the length of each record's data as stored, without the batch wrapper, and is the number billed. Errors are those above, plus:

StatuserrorMeaning
400invalid_batchbatch is not an array with at least one record, or a record lacks a string stream_id or a data field.
400invalid_item, item_too_largeAs above, with the record's index.
403stream_forbiddenThe key cannot write to stream_id.
409destination_not_readyAs above, with the stream_id.
503destination_backlogAs above, with the stream_id. Retry-After: 30.

OTLP/HTTP​

SignalEndpoint
LogsPOST /v1/logs
TracesPOST /v1/traces
MetricsPOST /v1/metrics

Send Content-Type: application/x-protobuf with an ExportLogsServiceRequest, ExportTraceServiceRequest or ExportMetricsServiceRequest. Content-Encoding is gzip or identity. The OTLP JSON encoding is not supported and returns 415.

A 200 carries the matching Export*ServiceResponse. These items are rejected permanently and reported in its partial_success, while the rest of the request is accepted:

  • a log record, span or metric whose encoded protobuf is larger than 8 KiB;
  • a span or log record with a malformed trace ID or span ID.

rejected_log_records and rejected_spans count items; rejected_data_points counts the data points of rejected metrics. error_message says why.

Errors use the same HTTP status codes as /v1/events (400, 401, 409, 413 above 16 MiB decompressed, 415, 429, 503 with Retry-After), with a google.rpc.Status protobuf body. Standard OTLP exporters retry 429 and 503.

OTLP/gRPC​

Send2Bucket serves the Export RPCs of opentelemetry.proto.collector.logs.v1.LogsService, opentelemetry.proto.collector.trace.v1.TraceService and opentelemetry.proto.collector.metrics.v1.MetricsService at api.s2b.tznc.dev:443. Limits and partial_success match OTLP/HTTP.

gRPC statusMeaning
OK (0)Accepted, with partial_success for rejected items.
INVALID_ARGUMENT (3)The message cannot be decoded.
RESOURCE_EXHAUSTED (8)Quota exceeded, or the request is larger than 16 MiB.
FAILED_PRECONDITION (9)The stream has no verified destination.
UNAVAILABLE (14)Send2Bucket or the stream's backlog is at capacity. Retryable.
UNAUTHENTICATED (16)Missing, unknown or revoked API key.

Retries​

Send2Bucket does not deduplicate requests. A retry after a timeout or a lost response is a new batch: its records are stored and billed again. See Delivery semantics.

Limits​

LimitValue
JSON item8 KiB per object
OTLP item8 KiB per encoded log record, span or metric
Request body16 MiB after decompression, for JSON and OTLP
Destinations per stream1