Caching and Conditional Requests

The API uses standard HTTP caching headers to help you avoid unnecessary data transfer and reduce load.

Cache-Control

All successful GET responses include:

Cache-Control: public, max-age=30

This means:

• The response can be cached by intermediate proxies and CDNs
• The cached response is valid for 30 seconds
• After 30 seconds, you should re-fetch to check for updates

ETags and conditional requests

The GET /v1/collections/:id endpoint supports conditional requests using ETags. This is the recommended approach for polling.

How it works

1. First request — the response includes an ETag header:

curl -i -H "X-API-Key: your-api-key" \
  https://api.interplai.app/v1/collections/col_abc123

HTTP/1.1 200 OK
ETag: "2026-01-18T10:35:00.000Z"
Cache-Control: public, max-age=30
Content-Type: application/json

{ "id": "col_abc123", "name": "Match Day Social Feed", ... }

2. Subsequent request — send the ETag back in If-None-Match:

curl -i -H "X-API-Key: your-api-key" \
  -H 'If-None-Match: "2026-01-18T10:35:00.000Z"' \
  https://api.interplai.app/v1/collections/col_abc123

3. If unchanged — the API returns 304 Not Modified with no body:

HTTP/1.1 304 Not Modified
ETag: "2026-01-18T10:35:00.000Z"

4. If changed — the API returns 200 OK with the new data and a new ETag.

Implementation example

let etag = null;
let cachedData = null;

async function pollCollection(collectionId) {
  const headers = { 'X-API-Key': process.env.API_KEY };

  if (etag) {
    headers['If-None-Match'] = etag;
  }

  const response = await fetch(
    `https://api.interplai.app/v1/collections/${collectionId}`,
    { headers }
  );

  if (response.status === 304) {
    // Collection hasn't changed — use cached data
    return cachedData;
  }

  // Collection has changed — update cache
  etag = response.headers.get('ETag');
  cachedData = await response.json();
  return cachedData;
}

// Poll every 10 seconds
setInterval(() => pollCollection('col_abc123'), 10_000);

Benefits

Benefit	Description
Bandwidth savings	304 responses have no body — only a few bytes of headers
Lower latency	The server can skip serialising the full response
Reduced load	Less data to parse on the client side

Vary header

Responses include Vary: Authorization, Accept-Encoding, which means caches should store separate entries per API key and per encoding (gzip, etc.).

Recommendation

For live broadcast integrations polling every 5–10 seconds, always implement ETag-based conditional requests. Over a 90-minute match, this can save gigabytes of redundant data transfer.