Response Headers

Every request to and response from the Cachecore gateway uses HTTP headers for authentication, dependency tagging, and cache diagnostics.

Request headers (you send these)

| Header | Required | Description | |--------|----------|-------------| | Authorization | Yes* | Bearer cc_live_xxxxx.eyJ... Preferred auth method | | X-Cachecore-Token | Yes* | Alternative auth header (backward compatibility) | | X-Cachecore-Deps | No | Base64url-encoded JSON array of dependency declarations |

*One of Authorization or X-Cachecore-Token is required. Authorization: Bearer is preferred.

Bypass mode: To skip caching entirely for a request, omit the auth token. The gateway treats a missing token as bypass mode, routing the request directly to OpenAI without cache lookup or write. When using the Python client, request_context(bypass=True) handles this automatically.

Response headers (Cachecore returns these)

| Header | Values | Description | |--------|--------|-------------| | X-Cache | HIT_L1, HIT_L1_STALE, HIT_L2, MISS, BYPASS | Cache result for this request | | X-Cache-Similarity | 0.00–1.00 | Cosine similarity score (L2 hits); 1.00 for L1, 0.00 for MISS/BYPASS | | X-Cache-Age | integer (seconds) | Age of the cached entry; 0 for MISS/BYPASS |

Reading X-Cache

The X-Cache header encodes both the cache result and the tier in a single value:

| Value | Latency | Description | |-------|---------|-------------| | HIT_L1 | ~5ms | Exact hash match. Response served from Redis L1 | | HIT_L1_STALE | ~5ms | Stale L1 match. Served from cache; background refresh triggered | | HIT_L2 | ~15ms | Semantic match. Response served from Redis L2 HNSW index | | MISS | 1-3s | No match. Request forwarded to OpenAI, response cached | | BYPASS | 1-3s | No auth token. Request forwarded to OpenAI, response not cached |

Dependency declaration format

The X-Cachecore-Deps header is a base64url-encoded JSON array:

[
  {"dep_id": "doc:contract-123", "expected_hash": "v1"},
  {"dep_id": "table:products", "expected_hash": "2024-01-15"}
]

dep_id is an arbitrary string identifying a data resource. Convention: <type>:<identifier>.

expected_hash is the data version at cache-write time. If the dependency's current hash has been updated via /v1/invalidate, cached entries tagged with it are rejected on lookup.

Debug headers

When debug mode is enabled on your project, an additional header is returned:

| Header | Description | |--------|-------------| | X-Cachecore-Namespace-Hint | First 12 hex characters of the namespace hash |

Useful for verifying that two requests derive the same namespace across environments.