API reference

The Trefur API is intentionally small. Most teams never call it directly — they send OpenTelemetry traces from an existing pipeline. This reference documents the public ingest surface and the small read-only endpoints used during integration setup.

Looking for a walkthrough? Start with the quickstart. Looking for OpenTelemetry? Point any OTLP exporter at the endpoints below.

Base URL and authentication

All endpoints below live on a single host:

https://api.trefur.com

Ingest endpoints require a bearer token in the Authorization header. Only the probe endpoints (/health, /ready) are open — no auth.

Authorization: Bearer trf_obs_...

The ingest key is an agent's telemetry key. Create one in the app: choose Add agent, then Advanced: use a telemetry key and Create a telemetry key. It is shown once and expires in 90 days.

OpenTelemetry ingest

Trefur speaks OTLP/HTTP traces, with a protobuf or JSON body. Any OpenTelemetry SDK or collector can point its OTLP/HTTP exporter at the endpoint below without custom attribute mapping. The wire format is the standard opentelemetry-proto export message, either JSON-encoded (Content-Type: application/json) or binary protobuf (Content-Type: application/x-protobuf).

Stock OpenTelemetry SDKs default their OTLP/HTTP exporter to binary protobuf, which Trefur accepts as is. Point the traces endpoint at the full path below (for example OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.trefur.com/v1/traces).

POST /v1/traces

OTLP/HTTP trace ingest. Body: standard ExportTraceServiceRequest, protobuf or JSON-encoded.

curl -X POST https://api.trefur.com/v1/traces \
  -H "Authorization: Bearer trf_obs_..." \
  -H "Content-Type: application/json" \
  --data @traces.json

Rate limits

Every key carries its own request rate limit, set when the key is minted (default 1,000 requests, adjustable per key up to 100,000 under Sources → Keys → API keys). Past the limit the gateway answers 429 with a Retry-After header. Limits are per minute and shared across all of our regions, so a burst is not admitted twice.

Calls made with a user session (the dashboard, the CLI signed in as you) are capped per user and per workspace as well — generous enough that normal use never meets them. The response is the same 429, with an X-RateLimit-Scope header naming whether the user or the workspace ceiling was reached.

Wire format

The OTLP/HTTP endpoint accepts the OTLP message either JSON-encoded (Content-Type: application/json) or as binary protobuf (Content-Type: application/x-protobuf). Both OTel exporter protocols, http/json and http/protobuf, work, so no configuration change is needed.

Health and readiness

Public, no auth. Useful for uptime checks and load-balancer probes.

GET /health

Liveness probe. 200 when the process is up.

curl https://api.trefur.com/health
# {"status":"healthy"}

GET /ready

Readiness probe. 200 when every internal probe (DB pool, etc.) passes; 503 with a JSON body listing the failing probes otherwise.

curl https://api.trefur.com/ready
# {"status":"ready","probes":{"db":"ok"}}

OpenAPI machine-readable spec

A curated OpenAPI 3.1 document is served at:

https://api.trefur.com/openapi.json

Render it with Redoc, Scalar, or any OpenAPI 3.1 client.

Discovery surfaces

Trefur exposes machine-readable mirrors for AI assistants that want to recommend or integrate with us:

  • /llms.txt — top-level index of documentation surfaces.
  • Every /docs/* page ships a TechArticle JSON-LD block plus a /docs/*.md Markdown twin so agents can pull clean text without parsing HTML.