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.
| Transport | How to send the key |
|---|---|
| HTTP | Authorization: Bearer <key> (preferred) or x-api-key: <key> |
| gRPC | metadata 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.
| Header | Value |
|---|---|
Content-Type | application/json |
Content-Encoding | gzip 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.
| Status | error | Meaning |
|---|---|---|
400 | invalid_json | The body is not valid JSON. |
400 | invalid_item | The body, or an array item, is not a JSON object. |
400 | item_too_large | An item is larger than 8 KiB. Includes max_bytes. |
400 | number_out_of_range | A number has more than 34 significant digits or an exponent beyond ±6144 (IEEE 754 decimal128). |
400 | invalid_encoding | The body cannot be decoded with its Content-Encoding. |
401 | unauthorized | Missing, unknown or revoked API key. |
409 | destination_not_ready | The stream has no verified destination. |
413 | body_too_large | The decompressed body is larger than 16 MiB. Includes max_bytes. |
415 | unsupported_encoding | Content-Encoding is not gzip or identity. |
429 | quota_exceeded | The organization's plan allowance would be exceeded. |
503 | buffer_full | Send2Bucket is temporarily at capacity. Retry-After: 30. |
503 | destination_backlog | The 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:
| Status | error | Meaning |
|---|---|---|
400 | invalid_batch | batch is not an array with at least one record, or a record lacks a string stream_id or a data field. |
400 | invalid_item, item_too_large | As above, with the record's index. |
403 | stream_forbidden | The key cannot write to stream_id. |
409 | destination_not_ready | As above, with the stream_id. |
503 | destination_backlog | As above, with the stream_id. Retry-After: 30. |
OTLP/HTTP
| Signal | Endpoint |
|---|---|
| Logs | POST /v1/logs |
| Traces | POST /v1/traces |
| Metrics | POST /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 status | Meaning |
|---|---|
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
| Limit | Value |
|---|---|
| JSON item | 8 KiB per object |
| OTLP item | 8 KiB per encoded log record, span or metric |
| Request body | 16 MiB after decompression, for JSON and OTLP |
| Destinations per stream | 1 |