GET /v1/config/:projectId

Returns the config bundle for a project. The bundle contains all parameters, layers, policies, and allocations needed for local SDK resolution.

Request

GET /v1/config/:projectId

Path parameters

Parameter	Type	Description
`projectId`	`string`	Your Traffical project ID

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer traffical_sk_...` (requires `sdk:read` scope)
`If-None-Match`	No	ETag from a previous response. Returns `304 Not Modified` if the bundle hasn’t changed.

Query parameters

Parameter	Type	Default	Description
`env`	`string`	`production`	Environment name

Response

200 OK

Returns the config bundle as JSON. Headers:

Header	Description
`ETag`	Version identifier for the bundle. Use with `If-None-Match` on subsequent requests.
`Cache-Control`	`public, max-age=60, must-revalidate`

Body:

{
  "version": "2026-05-21T09:58:11Z",
  "orgId": "org_acme",
  "projectId": "proj_marketplace",
  "env": "production",
  "hashing": {
    "unitKey": "userId",
    "bucketCount": 1000,
    "algorithm": "sha256-v2"
  },
  "parameters": [
    {
      "key": "checkout.button.color",
      "type": "string",
      "default": "#1E6EFB",
      "layerId": "layer_checkout",
      "namespace": "checkout"
    },
    {
      "key": "checkout.show_trust_badges",
      "type": "boolean",
      "default": false,
      "layerId": "layer_checkout",
      "namespace": "checkout"
    }
  ],
  "layers": [
    {
      "id": "layer_checkout",
      "policies": [
        {
          "id": "policy_color_test",
          "key": "color_test",
          "state": "running",
          "kind": "static",
          "allocations": [
            {
              "id": "alloc_a",
              "name": "control",
              "key": "control",
              "bucketRange": [0, 499],
              "overrides": { "checkout.button.color": "#1E6EFB" }
            },
            {
              "id": "alloc_b",
              "name": "treatment",
              "key": "treatment",
              "bucketRange": [500, 999],
              "overrides": { "checkout.button.color": "#22C55E" }
            }
          ],
          "conditions": []
        }
      ]
    }
  ],
  "eventDefinitions": [
    { "name": "purchase", "valueType": "currency", "unit": "USD" }
  ]
}

Key fields:

Field	Description
`version`	ISO timestamp of the bundle build. Also the basis of the `ETag`.
`hashing.unitKey`	Context field used as the bucketing unit (for example, `userId`).
`hashing.bucketCount`	Number of buckets per layer. Defaults to `1000`; allocation `bucketRange` values are `[0, bucketCount − 1]` inclusive.
`hashing.algorithm`	Assignment-hash version identifier. Currently always `"sha256-v2"`; SDKs assume `"sha256-v2"` when the field is absent in older bundles.
`parameters`	All parameters with their type, default (environment overrides applied), owning `layerId`, and `namespace`.
`layers`	Layers with their running policies. Draft, paused, and completed policies are not included.
`eventDefinitions`	Event names and value types defined for the project. Only present when the project defines events.

304 Not Modified

Returned when the If-None-Match header matches the current bundle version. No body is returned.

401 Unauthorized

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

403 Forbidden

Returned when the key is valid but lacks the sdk:read scope:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "SDK read scope required"
  }
}

404 Not found

Returned when no bundle exists for the project and environment:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Bundle not found for proj_marketplace/production"
  }
}

503 Service unavailable

Returned when the config store is temporarily unavailable and no cached copy can be served. The response includes a Retry-After header (currently 5 seconds); keep your cached bundle or defaults and retry.

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Config store temporarily unavailable, retry shortly"
  }
}

When the store is briefly unavailable but a recent copy exists, the endpoint keeps serving that copy instead: the response is a normal 200 with an X-Traffical-Bundle-Stale: true header and a shorter cache TTL, so clients revalidate aggressively.

ETag caching

The SDKs use ETag caching to poll for bundle updates efficiently:

First request — No If-None-Match header. The response contains the full bundle with an ETag header.
Subsequent requests — Include If-None-Match: <previous-etag>. If the bundle hasn’t changed, the response is 304 Not Modified with no body.
When the bundle changes — The ETag changes, and the response contains the full updated bundle.

This minimizes bandwidth when the bundle hasn’t changed, which is the common case.

Overview

SDK API

GET /v1/config/:projectId

Request

Path parameters

Headers

Query parameters

Response

200 OK

304 Not Modified

401 Unauthorized

403 Forbidden

404 Not found

503 Service unavailable

ETag caching

​Request

​Path parameters

​Headers

​Query parameters

​Response

​200 OK

​304 Not Modified

​401 Unauthorized

​403 Forbidden

​404 Not found

​503 Service unavailable

​ETag caching

Request

Path parameters

Headers

Query parameters

Response

200 OK

304 Not Modified

401 Unauthorized

403 Forbidden

404 Not found

503 Service unavailable

ETag caching