> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signa.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Caching & ETags

> Reduce redundant requests with conditional fetching and cache strategies

Trademark data changes infrequently for most records. By leveraging ETags and conditional requests, you can avoid re-downloading unchanged data and speed up your application.

## How ETags Work

When you fetch a resource, the response includes an `ETag` header containing a content fingerprint:

```
HTTP/1.1 200 OK
ETag: "a3f2b7c8d1e4"
Cache-Control: private, max-age=300
Content-Type: application/json

{
  "id": "tm_7d4e1f2a",
  "object": "trademark",
  "mark_text": "SIGNA",
  ...
}
```

On subsequent requests, send the ETag back via `If-None-Match`. If the resource has not changed, you get a `304 Not Modified` with no body, saving bandwidth and processing time:

```
GET /v1/trademarks/tm_7d4e1f2a
If-None-Match: "a3f2b7c8d1e4"

HTTP/1.1 304 Not Modified
ETag: "a3f2b7c8d1e4"
```

<Note>
  Rate limiting is enforced before the route runs, based on the endpoint's type and transport tier, not on the response status it eventually returns. A `304 Not Modified` counts against your rate limit exactly the same as the `200` it would have returned. ETags save you bandwidth and latency, not rate-limit budget, so they are still worth using on hot reads, just don't rely on them to raise your effective request ceiling.
</Note>

***

## Endpoints That Support ETags

| Endpoint                           | ETag Support | Typical `max-age` |
| ---------------------------------- | ------------ | ----------------- |
| `GET /v1/trademarks/:id`           | Yes          | 300 s (5 min)     |
| `GET /v1/owners/:id`               | Yes          | 300 s             |
| `GET /v1/attorneys/:id`            | Yes          | 300 s             |
| `GET /v1/firms/:id`                | Yes          | 300 s             |
| `GET /v1/offices`                  | Yes          | 3600 s (1 hour)   |
| `GET /v1/jurisdictions`            | Yes          | 3600 s            |
| `GET /v1/trademarks` (list/search) | No           | -                 |
| `POST /v1/trademarks` (search)     | No           | -                 |
| `POST /v1/trademarks/batch`        | No           | -                 |

<Tip>
  Reference data endpoints (offices, jurisdictions, classifications) change very rarely. Cache these aggressively with a long TTL.
</Tip>

***

## Cache-Control Headers

Every cacheable response includes a `Cache-Control` header:

```
Cache-Control: private, max-age=300
```

| Directive   | Meaning                                                                                       |
| ----------- | --------------------------------------------------------------------------------------------- |
| `private`   | Response is specific to this API key and must not be stored by shared caches (CDNs, proxies). |
| `max-age=N` | The response is considered fresh for N seconds. After that, revalidate with `If-None-Match`.  |
| `no-store`  | Present on mutation responses (POST, PATCH, DELETE). Do not cache.                            |

<Warning>
  All Signa responses include `private` because they are scoped to your organization. Never cache API responses in a shared/public cache.
</Warning>

***

## Conditional Request Flow

```typescript TypeScript theme={null}
const cache = new Map<string, { etag: string; data: any }>();

async function getTrademarkCached(id: string, apiKey: string) {
  const url = `https://api.signa.so/v1/trademarks/${id}`;
  const headers: Record<string, string> = {
    Authorization: `Bearer ${apiKey}`,
  };

  // Send ETag if we have a cached version
  const cached = cache.get(id);
  if (cached) {
    headers['If-None-Match'] = cached.etag;
  }

  const response = await fetch(url, { headers });

  if (response.status === 304 && cached) {
    // Not modified, return cached data
    return cached.data;
  }

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  const data = await response.json();
  const etag = response.headers.get('ETag');

  // Store in cache
  if (etag) {
    cache.set(id, { etag, data });
  }

  return data;
}
```

***

## Caching Strategies for Trademark Data

Different types of trademark data have different change frequencies. Tailor your caching strategy accordingly.

### Reference Data (offices, jurisdictions, classifications)

These change only when Signa adds a new office or jurisdiction.

* **Strategy**: Cache locally with a 24-hour TTL. Revalidate with ETags daily.
* **Storage**: In-memory or local file.

### Individual Trademarks

Most trademark records change infrequently (a few times per year), but some change during active prosecution.

* **Strategy**: Cache with the `max-age` value from the response (typically 5 min). Revalidate with ETags after expiry.
* **Storage**: In-memory cache (Redis, local Map) keyed by trademark ID.

### Search Results

Search results are dynamic and depend on query parameters, so they are not ETag-cacheable.

* **Strategy**: Client-side TTL cache keyed by the full query hash. A 30-60 second TTL works well for typeahead and repeated searches.
* **Storage**: In-memory only. Do not persist search result caches.

### List Endpoints

Paginated lists may change as new records are added.

* **Strategy**: Short TTL (60 s from `max-age`). Revalidate with ETags. Note that the cursor itself provides consistency within a pagination session.
* **Storage**: In-memory, keyed by the full URL including query parameters.

***

## Cache Invalidation

### Analytics freshness

Analytics reports use a 24-hour cache TTL as a backstop. Owner, attorney, firm, and entity updates invalidate affected reports through the search-indexer, so freshness is event-driven rather than sweep-based. Inspect `Server-Timing: cache;dur=0;desc="hit"` (or `desc="miss"`) to see whether a report was served from cache; this signal is not included in the response body.

ETags handle revalidation automatically: a conditional `GET` against the same resource returns `304 Not Modified` when the record is unchanged, so your cache entry stays valid. As noted above, that request still counts against your rate limit like any other call to the endpoint, so revalidating on every read is a latency and bandwidth optimization, not a way to make more requests than your plan allows.

For records you display in hot UI surfaces, complement ETag revalidation with a background poll of the [Trademark Changes](/api-reference/trademarks/trademark-changes) endpoint, it returns the versioned change log for a specific mark, letting you invalidate a cache entry the moment a new version is detected without waiting for the next ETag check.

<Tip>
  Pair ETags for normal traffic with a low-frequency poll of `trademark-changes` for your hottest marks. You get efficient revalidation on every read plus proactive busting on the small set of records that actually churn.
</Tip>

***

## Multi-Tier Caching

For applications that display trademark data to end users, consider a two-tier approach:

| Tier                      | TTL      | Purpose                                                                          |
| ------------------------- | -------- | -------------------------------------------------------------------------------- |
| **L1: In-process**        | 30-60 s  | Eliminates redundant API calls within a single request cycle.                    |
| **L2: Redis / Memcached** | 5-15 min | Shares cached data across application instances. Uses ETag revalidation on miss. |

```typescript theme={null}
async function getTrademark(id: string): Promise<Trademark> {
  // L1: Check in-process cache
  const l1 = memoryCache.get(id);
  if (l1) return l1;

  // L2: Check Redis
  const l2 = await redis.get(`tm:${id}`);
  if (l2) {
    const parsed = JSON.parse(l2);
    memoryCache.set(id, parsed, { ttl: 30_000 });
    return parsed;
  }

  // L3: Fetch from API with ETag revalidation
  const data = await getTrademarkCached(id, apiKey);
  memoryCache.set(id, data, { ttl: 30_000 });
  await redis.set(`tm:${id}`, JSON.stringify(data), 'EX', 900);

  return data;
}
```