API overview - Traffical

The Traffical SDK API is served from 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. This section covers the SDK runtime endpoints only: config, resolve, decide, and events. Project and organization management — creating parameters, layers, and policies — happens through the dashboard, the CLI, and the MCP server.

Base URL

https://sdk.traffical.io

You can override this in any SDK with the baseUrl option — useful for testing.

Authentication

All requests require an API key in the Authorization header:

Authorization: Bearer traffical_pk_...

API key types

The prefix is the key’s type, and it is enforced server-side — a key of the wrong type is rejected before anything else is checked.

Prefix	Type	Belongs in	Can reach
`traffical_pk_`	Publishable SDK key	Client-facing apps — browsers, mobile, other client devices	`GET /v1/config`, `POST /v1/events`, `POST /v1/events/batch`
`traffical_sk_`	Server-side SDK key	Your backend only	Everything `pk` can, plus `POST /v1/resolve` and `POST /v1/decide/*`
`traffical_mk_`	Management key	CLI, CI/CD, Terraform, agents	Control plane reads and writes. No SDK endpoints.
`traffical_ak_`	Admin key	Organization administration	Everything `mk` can, plus operate, promote, members, billing and minting keys

All four are 59 characters and end in a checksum, so a truncated or mistyped key is rejected without a lookup.

Both SDK keys do local resolution. The SDK fetches the config bundle once and resolves on-device — no per-decision network call, and it works offline. That is the default and the recommended mode.The difference is server-side resolution: POST /v1/resolve and POST /v1/decide/* answer a per-unit question on the server, and those accept a server-side SDK key but not a publishable one.

Management and admin keys additionally carry permissions — the same vocabulary as organization roles. A key can never exceed the permissions of the person who created it. An mk or ak key carrying the mcp:invoke permission gives AI agents a connection to the MCP server. Note mcp:invoke is not part of the default management-key preset — grant it explicitly.

Legacy keys

Keys minted before typed prefixes are 45 characters and all begin traffical_sk_. They keep working indefinitely and are governed by their original scopes, not by the type system above — so a legacy key beginning sk may in fact carry management scopes. Check a legacy key’s scopes before assuming it is SDK-only.

Managing keys

Create, rotate and revoke keys on your organization’s API Keys page in the dashboard (from the account menu). Keys can be scoped to a project and given an expiry — by default they do not expire. Rotating a key issues a replacement immediately and keeps the old one valid for 7 days, so you can roll it out gradually and watch the old key’s traffic fall to zero before it expires. Revoking takes effect immediately on the control plane. SDK endpoints are served from the edge, where revocation propagates within about a minute.

Endpoints

Method	Path	Description	Key types
`GET`	`/v1/config/:projectId`	Fetch the config bundle	`pk`, `sk`
`POST`	`/v1/resolve`	Server-side resolution (for `evaluationMode: "server"`)	`sk` only
`POST`	`/v1/decide/:policyId`	Per-entity adaptive decision	`sk` only
`POST`	`/v1/decide/batch`	Batch of per-entity decisions	`sk` only
`POST`	`/v1/events`	Send exposure, decision, and track events	`pk`, `sk`
`POST`	`/v1/events/batch`	Identical to `/v1/events` — the path browser SDKs use to flush queued events	`pk`, `sk`

Legacy keys are governed by their scopes instead: sdk:read for config, resolve and decide; sdk:write for events.

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 — an error object with a stable machine-readable code and a human-readable message:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Status	Code	Description
`400`	`BAD_REQUEST`	Invalid payload or missing required fields
`401`	`UNAUTHORIZED`	Missing, invalid, expired, or revoked API key
`403`	`FORBIDDEN`	The key is the wrong type for the endpoint (for example a publishable key on `/v1/resolve`), a legacy key lacks the required scope, or a tenant header doesn’t match the key
`404`	`NOT_FOUND`	Resource does not exist (for example, no bundle for the project and environment)
`429`	`RATE_LIMITED`	Too many requests — retry after the `Retry-After` header
`500`	`INTERNAL_ERROR`	Internal server error
`503`	`SERVICE_UNAVAILABLE`, `EVENTS_NOT_STORED`	Transient storage unavailability — retry after the `Retry-After` header when present (config and events set it); otherwise retry shortly

503 responses are always safe to retry: they mean nothing was stored or served, so a retry cannot duplicate data.

Rate limits

Limits are generous for SDK traffic and scale with your plan. Rate-limited requests return 429 with a RATE_LIMITED error code and a Retry-After header (currently 10 seconds). Two things to know:

GET /v1/config/:projectId responses are heavily cached at the edge — most SDK refreshes never reach an origin.
POST /v1/events accepts batches of up to 1000 events per request. Always batch; never send one event per request from a server.

​Base URL

​Authentication

​API key types

​Legacy keys

​Managing keys

​Endpoints

​Caching

​Error responses

​Rate limits

Base URL

Authentication

API key types

Legacy keys

Managing keys

Endpoints

Caching

Error responses

Rate limits