# Cache API

> Recache or purge pages when you publish changes, from your deployment, CMS or a script.

Source page: https://docs.jazui.com/api/cache/en

When you change your website, cached pages keep showing the previous version until the next automatic recache. With this API you tell Jazui to render them again (or remove them) right away. Requests create a **task** processed in the background, whose status you can check.

> Included in plans with the **Cache API** ([Plans and limits](https://docs.jazui.com/llms/en/plans.txt)). Use the account render token or a site token (with a site token, you can only touch that site).

## Endpoints

| Method | Path | What it does |
|---|---|---|
| `POST` | `/v2/cache/recache` | Renders the pages again. Pages that weren't cached are rendered for the first time. |
| `POST` | `/v2/cache/purge` | Removes the pages from the cache (the next bot triggers a new render). |
| `GET` | `/v2/cache/tasks/{id}` | Status of a task. |
| `GET` | `/v2/cache/tasks?limit=20` | Latest tasks (1 to 100). With a site token, only that site's. |

## Which pages

The body has **exactly one** of these three options:

- `urls`: a list of up to 1,000 full addresses (normalized, duplicates removed).
- `prefix`: every cached page that starts with that address (also the address without the trailing slash). Useful for a section: `/blog/`, `/products/`…
- `site`: every cached page of a site.

With `prefix` and `site`, at most 10,000 pages are processed per task.

`urls`:

```json
{ "urls": ["https://misitio.com/", "https://misitio.com/precios"] }
```

`prefix`:

```json
{ "prefix": "https://misitio.com/blog/" }
```

`site`:

```json
{ "site": "misitio.com" }
```

## Example

```bash
curl -X POST https://api.jazui.com/v2/cache/recache \
  -H "Authorization: Bearer $JAZUI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://misitio.com/","https://misitio.com/precios"]}'
```

`202 Accepted`:

```json
{
  "id": "01a1842d-5d0b-4d6e-9a7f-2c3b4d5e6f70",
  "action": "Recache",
  "scope": "Urls",
  "target": null,
  "state": "Queued",
  "total": 2,
  "processed": 0,
  "failed": 0,
  "createdAt": "2026-11-03T20:22:17Z",
  "startedAt": null,
  "finishedAt": null,
  "error": null,
  "statusUrl": "https://api.jazui.com/v2/cache/tasks/01a1842d-5d0b-4d6e-9a7f-2c3b4d5e6f70"
}
```

```bash
curl https://api.jazui.com/v2/cache/tasks/01a1842d-5d0b-4d6e-9a7f-2c3b4d5e6f70 \
  -H "Authorization: Bearer $JAZUI_TOKEN"
```

```json
{
  "id": "01a1842d-5d0b-4d6e-9a7f-2c3b4d5e6f70",
  "action": "Recache",
  "scope": "Urls",
  "state": "Done",
  "total": 2,
  "processed": 2,
  "failed": 0,
  "createdAt": "2026-11-03T20:22:17Z",
  "startedAt": "2026-11-03T20:22:18Z",
  "finishedAt": "2026-11-03T20:22:31Z",
  "error": null
}
```

## The task

| Field | Description |
|---|---|
| `action` | `Recache` or `Purge`. |
| `scope` and `target` | `Urls`, `Prefix` or `Site`, with the prefix or site. |
| `state` | `Queued`, `Running`, `Done` or `Failed` (with the reason in `error`). |
| `total`, `processed`, `failed` | Total pages, done and failed. Progress is saved every 10 pages. |
| `statusUrl` | Address to check the task (also in the `Location` header). |

Tasks are processed one at a time, in arrival order. Recaching **uses renders** from your plan like any other render; if they run out, those pages count as failed.

## Errors

| Code | `code` | Reason |
|---|---|---|
| `400` | `invalid_request` | Not exactly one option, more than 1,000 addresses, or one isn't absolute. |
| `403` | `plan` | Your plan doesn't include the cache API. |
| `403` | `forbidden` | The domain isn't in your account (or the token's site), or the site isn't verified. |
| `429` | `too_many_tasks` | You already have 10 queued or running tasks: wait for them to finish. |

## On deployment

The usual approach is to recache the whole site (or the section that changed) at the end of your deployment. Store the token as a CI secret:

`GitHub Actions`:

```bash
# .github/workflows/deploy.yml (después de publicar la web)
- name: Recachear en Jazui
  run: |
    curl -fsS -X POST https://api.jazui.com/v2/cache/recache \
      -H "Authorization: Bearer ${{ secrets.JAZUI_TOKEN }}" \
      -H "Content-Type: application/json" \
      -d '{"site":"misitio.com"}'
```