OpenAPI Specification

Telemetry publishes a machine-readable OpenAPI 3.1 specification for the documented HTTP API. Use it to inspect endpoint contracts, generate a typed client as a starting point, configure an API explorer, or validate example requests in CI.

The specification covers:

• structured event ingestion with POST /log;
• synchronous SQL with POST /query;
• asynchronous JSON and Parquet exports with POST /query/async and GET /query/async/{job_id};
• table listing, schema inspection, retention, partition columns, and deletion;
• dashboard listing, creation, replacement updates, and deletion;
• the legacy row-delete endpoint, marked as deprecated.

Download the specification

curl -fsS https://telemetry.sh/openapi.json -o telemetry-openapi.json

The document uses https://api.telemetry.sh as its server and describes both supported authorization-header forms:

Authorization: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

Do not put a real API key in the specification, source control, generated documentation, examples, logs, or client configuration committed to a repository.

Validate the document

Use an OpenAPI 3.1-compatible validator. For example, with a locally installed Redocly CLI:

npx @redocly/cli lint telemetry-openapi.json

Pin the validator version in CI so a tool upgrade does not change release behavior unexpectedly. Treat warnings about ambiguous schemas as review items rather than automatically suppressing them.

Generate clients carefully

Generated clients are scaffolding, not a substitute for the endpoint guides. Before production use:

1. verify authentication and API-key scope;
2. configure connection and response timeouts;
3. retry only temporary failures with bounded exponential backoff and jitter;
4. preserve an event identifier when retrying ingestion;
5. impose a total polling deadline on asynchronous query jobs;
6. keep telemetry failures from exhausting application workers;
7. review destructive table and row-delete methods separately.

The OpenAPI schema intentionally leaves flexible event payloads and query result rows open-ended because their fields depend on your event contract and SQL projection. Generate domain types for those payloads in your application rather than assuming one global event shape.

Source-of-truth boundary

The specification mirrors the public API documentation in this repository. Human-readable pages remain the source for operational guidance, normalization behavior, examples, and failure modes:

• Log API
• Query API
• Tables API
• Dashboard API
• Delete API
• Rate limits and errors

Plan-specific quotas can change and are not encoded as a global numeric rate in the specification. Check product and billing settings for the current account limits. If the OpenAPI document and a live API response disagree, capture a minimal safe reproduction and report it to [email protected]; do not work around the mismatch by logging credentials or private payloads.