Ingest API reference
Routes, auth, and scopes for the Talaria ingest API on ingest-nz1.newtalaria.com.
Prefer an official SDK. This page is the HTTP contract.
Auth
Send Authorization: Bearer and one credential. Publishable keys are tal_pk_<env>_nz1_…. Secret keys are tal_sk_<env>_nz1_…. Monitor tokens are tal_mon_nz1_… and are valid only on POST /v1/check-ins.
<env> is prod, stg, test, or dev. Client SDKs (browser and Flutter) refuse a secret key or a monitor token at init. Server SDKs log one warning on a publishable key.
A new publishable key gets every publishable scope: events:write, spans:write, logs:write, metrics:write, analytics:write, replays:write, and flags:evaluate. A release key is a secret key. releases:write only is recommended for CI.
Host
Ingest is https://ingest-nz1.newtalaria.com. OTLP is https://ingest-nz1.newtalaria.com/otlp (HTTP only; gRPC is not supported). api.newtalaria.com serves no /v1 ingest and no /otlp. MCP stays at https://api.newtalaria.com/mcp.
If TALARIA_URL or url is set, the SDK uses it. Otherwise a self cell fails fast, and any other cell derives https://ingest-<cell>.newtalaria.com. Set TALARIA_URL only for self-host or a custom domain.
Environments and releases
Each API key is bound to one environment. The server stamps it. SDKs do not send an environment. setup_project mints a development publishable key. Production is a second key.
Send release as <ref>@<shortsha> with / in the ref replaced by - (for example main@a8f31c2). service.version uses the same string. Source-map upload uses that string too.
Routes
Bodies are plain JSON with no input wrapper. Batches are {"<plural>":[…]}. POST /v1/replays/segments and POST /v1/heatmaps/snapshots also accept application/octet-stream gzip.
| Method | Path | Auth | Scope |
|---|---|---|---|
| GET | /v1/sdk-config |
pk or sk | any valid key |
| POST | /v1/events |
pk or sk | events:write |
| POST | /v1/spans |
pk or sk | spans:write |
| POST | /v1/analytics |
pk or sk | analytics:write |
| POST | /v1/replays |
pk or sk | replays:write |
| POST | /v1/replays/segments |
pk or sk | replays:write ({"segments":[…]} or octet-stream gzip) |
| POST | /v1/replays/{replayId}/finish |
pk or sk | replays:write |
| POST | /v1/heatmaps |
pk or sk | analytics:write |
| POST | /v1/heatmaps/snapshots |
pk or sk | analytics:write (JSON or octet-stream gzip) |
| POST | /v1/screen-heatmaps |
pk or sk | analytics:write |
| POST | /v1/screen-heatmaps/snapshots |
pk or sk | analytics:write |
| POST | /v1/screen-heatmaps/recordings |
pk or sk | analytics:write |
| POST | /v1/monitors/{slug}/check-ins |
sk | monitors:write |
| POST | /v1/check-ins |
tal_mon_ |
monitor token |
| POST | /v1/releases |
sk | releases:write |
| POST | /v1/source-maps |
sk | releases:write |
| POST | /v1/flags/evaluate |
pk or sk | flags:evaluate |
| GET | /v1/flags?keys= |
sk | flags:read |
| POST | /v1/client-reports |
pk or sk | any valid key |
| POST | /otlp/v1/{traces,logs,metrics} |
pk or sk | spans:write / logs:write / metrics:write |
| POST | /v1/deploys |
n/a | 501 not_implemented (not available) |
SDKs and the CLI call /v1/releases and /v1/source-maps.
Feature flags
POST /v1/flags/evaluate takes a JSON body {anonymousId, userId, organizationId, sessionId, attributes, keys} and returns {"evaluations":[{"key","variationKey","valueJson","version","reason"}]}.
GET /v1/flags?keys= lists definitions for a secret key and returns {"flags":[…]}.
Source maps
POST /v1/source-maps takes plain JSON: release, fileName, optional debugId, and gzipBytes (base64 of the gzip bytes). The response includes id, release, fileName, and sizeBytes. See Upload JavaScript source maps.
Errors
/v1/* errors are application/problem+json: {type, title, status, detail, code, requestId}. The Request-Id response header is always present.
| Code | Status |
|---|---|
invalid_key |
401 |
insufficient_scope |
403 |
invalid_scope |
400 |
wrong_cell |
421, with cell and url |
not_found |
404 |
/otlp/v1/* keeps the OTLP status body.