sdk.traffical.io. SDKs use it to fetch config bundles, send events, and (in server evaluation mode) request resolutions. You can also call it directly for server-to-server integrations.
Base URL
baseUrl option — useful for testing.
Authentication
All requests require an API key in theAuthorization header:
API key types
Every key has the sametraffical_sk_... prefix. What a key can do — and whether it is browser-safe — depends on its scopes, not its prefix:
| Scopes | Type | Capabilities | Browser-safe? |
|---|---|---|---|
sdk:read, sdk:write | SDK key | Fetch bundles, request resolutions, send events | Yes — ship in client code |
mgmt:read, mgmt:write, or admin | Management key | Create and modify projects, layers, policies | No — must stay secret |
sdk:read— fetch bundles, request resolutionssdk:write— send eventsmgmt:read/mgmt:write/admin— read and modify configuration
mgmt:read key also authenticates AI agents against the read-only MCP server.
Managing keys
Create and revoke keys under Settings → API keys in the dashboard. Keys can be scoped to a project and environment, given an expiry, or revoked at any time.Endpoints
| Method | Path | Description | Scope |
|---|---|---|---|
GET | /v1/config/:projectId | Fetch the config bundle | sdk:read |
POST | /v1/resolve | Server-side resolution (for evaluationMode: "server") | sdk:read |
POST | /v1/decide/:policyId | Per-entity adaptive decision | sdk:read |
POST | /v1/events | Send exposure, decision, and track events | sdk:write |
/v1/events/batch endpoint is an alias for POST /v1/events for clients that prefer the explicit “batch” naming.
Caching
GET /v1/config/:projectId is served with Cache-Control: public, max-age=60, must-revalidate and an ETag per bundle version. SDKs send If-None-Match on subsequent requests — unchanged bundles return 304 Not Modified with no body. Use the same pattern in any custom client that polls the bundle.
Error responses
All errors share a consistent shape:| Status | Description |
|---|---|
400 | Bad request — invalid payload or missing required fields |
401 | Unauthorized — missing or invalid API key |
403 | Forbidden — API key lacks required scope |
404 | Not found — resource does not exist |
429 | Rate limited |
500 | Internal server error |
Rate limits
Limits are generous for SDK traffic and scale with your plan. Two things to know:GET /v1/config/:projectIdresponses are heavily cached at the edge — most SDK refreshes never reach an origin.POST /v1/eventsaccepts batches of up to 1000 events per request. Always batch; never send one event per request from a server.