API reference

The Trefur API is intentionally small. Most teams never call it directly — they use one of the SDKs, the collector, or 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 code? Start with the Python, JavaScript, or Go quickstarts. 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. The /api/v1/auth/oauth/providers list also requires a bearer token (see below).

Authorization: Bearer trf_live_<your-key>

Ingest keys use the trf_live_* prefix (Observe agent keys, used by the SDKs and the collector). Generate one in the dashboard under Settings → Platform → API keys.

OpenTelemetry ingest

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

Stock OpenTelemetry SDKs default their OTLP/HTTP exporter to binary protobuf and to the /v1/traces path. Set OTEL_EXPORTER_OTLP_PROTOCOL=http/json and point each signal's endpoint at the full path below (for example OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.trefur.com/platform/v1/ingest/otel). On api.trefur.com the bare /v1/traces, /v1/metrics and /v1/logs paths answer 410 Gone with a body naming the served path; the same three paths ARE served on observe.trefur.com if you prefer to keep an exporter's default path and change only the host.

POST /platform/v1/ingest/otel

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

curl -X POST https://api.trefur.com/platform/v1/ingest/otel \
  -H "Authorization: Bearer trf_live_<your-key>" \
  -H "Content-Type: application/json" \
  --data @traces.json

POST /platform/v1/ingest/otel/metrics

OTLP/HTTP metric ingest. Body: standard ExportMetricsServiceRequest, JSON-encoded.

curl -X POST https://api.trefur.com/platform/v1/ingest/otel/metrics \
  -H "Authorization: Bearer trf_live_<your-key>" \
  -H "Content-Type: application/json" \
  --data @metrics.json

POST /platform/v1/ingest/otel/logs

OTLP/HTTP log ingest. Body: standard ExportLogsServiceRequest, JSON-encoded.

curl -X POST https://api.trefur.com/platform/v1/ingest/otel/logs \
  -H "Authorization: Bearer trf_live_<your-key>" \
  -H "Content-Type: application/json" \
  --data @logs.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 Settings → Platform → API keys). Past the limit the gateway answers 429 with a Retry-After header; the SDKs and the collector back off and retry on their own. 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 endpoints accept the OTLP message JSON-encoded with Content-Type: application/json. Binary protobuf over OTLP/HTTP is not accepted on these endpoints — if your exporter defaults to protobuf, switch it to http/json. The Trefur SDKs and the collector already emit JSON, so no configuration is needed when you use them.

OAuth providers list

Read-only. Returns the OAuth providers the deployment has enabled. The dashboard uses this to render the integrations picker. Requires a bearer token.

GET /api/v1/auth/oauth/providers

curl https://api.trefur.com/api/v1/auth/oauth/providers \
  -H "Authorization: Bearer <your-token>"

Response:

{
  "providers": ["github", "google", "slack"],
  "total": 3
}

providers is an alphabetised array of provider keys. The exact set depends on which providers the operator has configured — only providers with both a client ID and client secret set are returned.

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 covering the endpoints above will be available at:

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

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

The document is in scaffolding and will be live at launch. Until then, this page is the source of truth for the public API surface.

SDKs and collector

Most teams adopt Trefur through the SDK or the collector, not the raw API. The SDK does the right batching, retries, and OTel-canonical span construction; the collector lets you batch and redact on-network. The endpoints above are what they call under the hood.

Quickstart — install an SDK and ship your first trace in under five minutes.
Python SDK
JavaScript / TypeScript SDK
Go SDK
Collector — single binary, eight inputs, OTel-conformant.

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.