cURL

Cachecore exposes the standard OpenAI HTTP API. Any HTTP client works.

Basic request

curl -X POST https://api.cachecore.it/v1/chat/completions \
  -H "Authorization: Bearer cc_live_xxxxx.eyJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      {"role": "user", "content": "What is semantic caching?"}
    ]
  }'

Inspecting cache headers

Use -i to print response headers:

curl -i -X POST https://api.cachecore.it/v1/chat/completions \
  -H "Authorization: Bearer cc_live_xxxxx.eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.4-mini","messages":[{"role":"user","content":"Hello"}]}'

Look for:

X-Cache: HIT_L1
X-Cache-Similarity: 1.00
X-Cache-Age: 42

With a system prompt

curl -X POST https://api.cachecore.it/v1/chat/completions \
  -H "Authorization: Bearer cc_live_xxxxx.eyJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      {"role": "system", "content": "You are a legal assistant."},
      {"role": "user", "content": "Summarise this NDA in plain English."}
    ]
  }'

Attaching dependency tags

Tag a cache entry with a data dependency so it can be invalidated when the data changes:

# Encode the deps header value
DEPS=$(echo '[{"dep_id":"doc:contract-123","expected_hash":"v1"}]' | base64 | tr '+/' '-_' | tr -d '=')

curl -X POST https://api.cachecore.it/v1/chat/completions \
  -H "Authorization: Bearer cc_live_xxxxx.eyJ..." \
  -H "Content-Type: application/json" \
  -H "X-Cachecore-Deps: $DEPS" \
  -d '{"model":"gpt-5.4-mini","messages":[{"role":"user","content":"Summarise contract #123"}]}'

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

[{"dep_id": "doc:contract-123", "expected_hash": "v1"}]

Bypassing cache

To skip cache lookup and write, omit the Authorization header. The gateway routes the request directly to OpenAI (BYPASS mode):

curl -X POST https://api.cachecore.it/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.4-mini","messages":[{"role":"user","content":"Hello"}]}'

Note: bypass requests are rate-limited by IP (100 req/min by default) and are not cached.

Invalidating a dependency

Delete all cache entries tagged with a specific dependency:

curl -X POST https://api.cachecore.it/v1/invalidate \
  -H "Authorization: Bearer cc_live_xxxxx.eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"dep_id": "doc:contract-123", "new_hash": "v2"}'