# Cache-Control API
> Parse and build HTTP Cache-Control headers (RFC 9111). The parse endpoint turns a Cache-Control header into structured, named directives — public and private, no-store, no-cache, no-transform, max-age and s-maxage, must-revalidate and proxy-revalidate, immutable, stale-while-revalidate, stale-if-error, min-fresh and max-stale — together with a quick summary: whether the response is cacheable, whether it must be revalidated before use, its visibility (public or private) and its max-age in seconds. The build endpoint assembles a correct, canonically-ordered header from simple boolean and numeric fields, validating that the second-based directives are non-negative integers and quoting field-list forms of no-cache and private. Everything is computed locally and deterministically, so it is instant and private. Ideal for CDN and edge configuration, caching proxies and reverse proxies, API responses and static-asset tuning, and debugging why a response is (or is not) being cached. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This builds and parses the header string itself; it does not fetch a URL.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/cachecontrol-api/..."
```

## Pricing
- **Free** (Free) — 2,735 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 12,250 calls/Mo, 8 req/s
- **Pro** ($24/Mo) — 173,500 calls/Mo, 20 req/s
- **Mega** ($62/Mo) — 910,000 calls/Mo, 50 req/s

## Endpoints

### Cache

#### `GET /v1/build` — Build a Cache-Control header

**Parameters:**
- `public` (query, optional, string) — true for public Example: `true`
- `private` (query, optional, string) — true (or a quoted field list)
- `no_store` (query, optional, string) — true
- `no_cache` (query, optional, string) — true (or a quoted field list)
- `must_revalidate` (query, optional, string) — true
- `immutable` (query, optional, string) — true
- `max_age` (query, optional, string) — seconds Example: `3600`
- `s_maxage` (query, optional, string) — seconds (shared caches)
- `stale_while_revalidate` (query, optional, string) — seconds
- `stale_if_error` (query, optional, string) — seconds

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cachecontrol-api/v1/build?public=true&max_age=3600"
```

**Response:**
```json
{
    "data": {
        "count": 2,
        "cache_control": "public, max-age=3600"
    },
    "meta": {
        "timestamp": "2026-06-03T09:25:02.960Z",
        "request_id": "c795f523-b014-482b-ae8c-2f6ed9065ab7"
    },
    "status": "ok",
    "message": "Build a Cache-Control header",
    "success": true
}
```

#### `GET /v1/parse` — Parse a Cache-Control header

**Parameters:**
- `header` (query, required, string) — A Cache-Control header value Example: `public, max-age=3600, stale-while-revalidate=60`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cachecontrol-api/v1/parse?header=public%2C+max-age%3D3600%2C+stale-while-revalidate%3D60"
```

**Response:**
```json
{
    "data": {
        "count": 3,
        "max_age": 3600,
        "cacheable": true,
        "directives": {
            "public": true,
            "max_age": 3600,
            "stale_while_revalidate": 60
        },
        "visibility": "public",
        "revalidate_each_time": false
    },
    "meta": {
        "timestamp": "2026-06-03T09:25:03.072Z",
        "request_id": "9c7c4ec1-dcd2-4cd1-8948-b24c811bd449"
    },
    "status": "ok",
    "message": "Parse a Cache-Control header",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cachecontrol-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "name": "Cache-Control API",
        "notes": "Numeric directives are in seconds and must be non-negative integers. no-cache means revalidate before use (not 'do not cache'); no-store means do not store at all. This builds and parses the header string — it does not fetch a URL. Nothing is stored.",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/parse",
                "params": {
                    "header": "a Cache-Control header value (required)"
                },
                "returns": "the structured directives and a cacheability summary"
            },
            {
                "path": "/v1/build",
                "params": {
                    "public": "true for public",
                    "max_age": "seconds",
                    "private": "true (or a quoted field list)",
                    "no_cache": "true (or a quoted field list)",
                    "no_store": "true",
                    "s_maxage": "seconds (shared caches)",
                    "immutable": "true",
                    "max_stale": "seconds",
                    "min_fresh": "seconds",
                    "no_transform": "true",
                    "stale_if_error": "seconds",
                    "must_revalidate": "true",
                    "proxy_revalidate": "true",
                    "stale_while_revalidate": "seconds"
                },
                "returns": "the Cache-Control header string"
        
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/cachecontrol-api
OpenAPI spec: https://www.oanor.com/api/cachecontrol-api/openapi.json