/docs/api
REST API
The obsrv API speaks JSON over HTTPS. Every SDK feature is exposed as a public endpoint — there is no proprietary protocol, no client-only feature.
Base URL
https://api.obsrv.techAuthentication
Send your project API key with x-api-key. Bearer tokens are accepted for compatibility, but SDKs use x-api-key. See Authentication.
x-api-key: tk_live_…Endpoints
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/traces | Ingest a new trace |
| POST | /v1/traces/:id/steps | Append steps (NDJSON) |
| GET | /v1/traces | List traces (filter + cursor) |
| GET | /v1/traces/:id | Fetch a single trace |
| GET | /v1/traces/tail | Live tail (SSE) |
| POST | /v1/media/upload | Upload an artifact (multipart) |
| GET | /v1/media/serve | Stream an artifact (browser-safe) |
| GET | /v1/media/signed-url | Mint a signed PUT URL |
| POST | /v1/metrics | Create a metric definition |
| GET | /v1/metrics | List metric definitions |
| POST | /v1/metrics/events | Record a metric event |
| POST | /v1/search | Full-text search across traces |
| GET | /v1/clusters | List clusters |
| GET | /v1/clusters/:id | Get cluster detail |
| POST | /v1/clusters/discover | Trigger cluster discovery |
| POST | /v1/annotations | Annotate a trace or step |
| GET | /v1/saved-filters | List saved filters |
| POST | /v1/saved-filters | Create a saved filter |
| GET | /v1/orgs | List orgs the user belongs to |
| GET | /v1/orgs/:id/projects | List projects in an org |
| POST | /v1/projects/:id/keys | Create an API key |
| DELETE | /v1/projects/:id/keys/:keyId | Revoke an API key |
| GET | /v1/projects/:id/members | List members |
| POST | /v1/projects/:id/webhooks | Create a webhook |
| GET | /v1/usage | Usage summary |
| POST | /v1/otel/traces | OTLP ingest (HTTP) |
Pagination
List endpoints return a cursor in the response when more results are available. Pass it back as ?cursor=… to fetch the next page.
Rate limits
Default: 1,000 requests per second per project for ingest endpoints, 100/s for read endpoints. Enterprise customers can lift the cap. Rate-limit headers (X-RateLimit-*) accompany every response.
Errors
See Errors & limits for the complete error code reference.