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_obs_<your-key>

Ingest keys use the trf_obs_* 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. Set OTEL_EXPORTER_OTLP_PROTOCOL=http/json (or the equivalent exporter option) so they send JSON to these endpoints.

POST /v1/traces

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

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

POST /v1/metrics

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

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

POST /v1/logs

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

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

Rate limits

Ingest endpoints have generous per-workspace default limits that comfortably cover typical SDK and collector traffic. If you expect sustained high-volume ingest or hit a limit, higher limits are available — contact us.

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.

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.