#Caching

VibeCode caches responses for /v1/users (60 s) and /v1/statuses (5 min) when using an APP-mode API key. This dramatically speeds up dashboards that fetch these endpoints on every load.

#How to opt out per-request

Send Cache-Control: no-cache header. The request bypasses the cache and hits Bitrix24 directly.

Terminal 
curl -H "X-Api-Key: vibe_api_..." -H "Cache-Control: no-cache" https://vibecode.bitrix24.tech/v1/users

#Response headers

  • X-Cache: HIT — served from cache
  • X-Cache: MISS — fetched from Bitrix24, now cached
  • X-Cache: COALESCED — joined an in-flight fetch started by another request
  • X-Cache: BYPASS — cache was skipped (OAuth mode, no-cache header, or cache disabled platform-wide)

#What about OAuth-app mode?

OAuth-app keys bypass the cache — different users may see different data based on their portal permissions.

#Freshness after writes

Writes via the platform (POST /v1/users, PATCH /v1/users/:id, etc.) invalidate the cache immediately. Writes made directly in the Bitrix24 UI are not seen — expect up to TTL (60 s for users, 5 min for statuses) of staleness.

#HTTP cache for discovery endpoints (`/v1/openapi.json`, `/v1/guide`)

The two discovery endpoints carry standard HTTP cache validators so clients don't re-download the whole document on every startup. GET /v1/openapi.json (~422 KB OpenAPI spec) and GET /v1/guide (~247 KB) both respond with Cache-Control and an ETag:

  • /v1/openapi.json → Cache-Control: public, max-age=300 — the spec is identical for every client, so any cache may store it.
  • /v1/guide → Cache-Control: private, max-age=300 — the body depends on the key's scopes, so it must not be stored in a shared cache.
  • ETag — a content fingerprint that changes only when the spec or the set of scopes changes.

Keep the ETag from the first response and send it back in an If-None-Match header on repeat calls. When the content hasn't changed, the endpoint answers 304 Not Modified with an empty body instead of re-sending the full document.

Terminal 
# First call — full body + ETag (openapi.json needs no auth)
curl -i https://vibecode.bitrix24.tech/v1/openapi.json
# ... ETag: "a1b2c3d4e5f6a7b8"

# Repeat call — 304 Not Modified, no body transferred
curl -i -H 'If-None-Match: "a1b2c3d4e5f6a7b8"' \
  https://vibecode.bitrix24.tech/v1/openapi.json

max-age=300 also lets the client (and any intermediate cache) reuse the response for 5 minutes without contacting the server at all.