Skip to main content
All TruLayer endpoints live under a single base URL and share one authentication scheme. The full endpoint list is auto-generated from our OpenAPI spec — use the sidebar to browse every route with request/response shapes and a live playground.

​
Base URL

https://api.trulayer.ai
All endpoints below this base use the /v1/ path prefix (e.g. /v1/ingest, /v1/traces).

​
Authentication

Every request requires a bearer token in the Authorization header. 
Authorization: Bearer <token>
Two token types are accepted:
ClientTokenHow to get it
SDKs / server codeAPI key (tl_...)Dashboard → Settings → API keys
Dashboard / browserClerk session JWTManaged automatically by the frontend — you do not construct these by hand
API keys are tenant-scoped. They have access to every project in your organisation and are long-lived until revoked. Never embed them in client-side code — always call the TruLayer API from your server, or use a short-lived Clerk session token from an authenticated browser.

​
Content type

All request and response bodies are JSON unless otherwise noted: 
Content-Type: application/json

​
Rate limits

Rate limits are per tenant, enforced via a sliding window:
Endpoint familyLimit (Free)Limit (Pro)
POST /v1/ingest, POST /v1/ingest/batch50,000 traces / month1,000,000 / month
POST /v1/feedback, POST /v1/evalScales with planScales with plan
GET /v1/traces, GET /v1/metrics60 rps600 rps
When a limit is exceeded you get HTTP 429. Check the X-RateLimit-* headers on every response for the current window state. Enterprise plans have no hard limits.

​
Error format

Errors always return a JSON body of this shape: 
{
  "error": {
    "code": "trace_not_found",
    "message": "Trace not found.",
    "request_id": "req_01j..."
  }
}
StatusMeaning
400Malformed request — body doesn’t match schema
401Missing or invalid token
403Token valid but not authorised for this resource (e.g. wrong tenant)
404Resource not found
409Conflict — e.g. submitting a trace with an ID that already exists
422Validation error on a required field
429Rate-limited
5xxServer-side issue — safe to retry with exponential backoff
Always log the request_id — it’s the fastest way for support to look up a failed request.

​
Versioning

The current API version is v1. Backwards-incompatible changes are shipped as a new version path (/v2/...); v1 is supported for at least 12 months after v2 release. Additive changes (new fields, new optional parameters) may land on v1 without a version bump — client code should ignore unknown response fields.

​
SDKs

For most apps, you should not hit these endpoints directly — the SDKs handle batching, retries, and serialisation for you.

Python SDK

pip install trulayer

TypeScript SDK

npm install @trulayer/sdk

​
Making a raw request

If you need to call the API from a language without an SDK, or for debugging: 
curl https://api.trulayer.ai/v1/traces \
  -H "Authorization: Bearer $TRULAYER_API_KEY"
Ready to explore? Pick an endpoint in the sidebar.