# Purge

The `azion/purge` module is the Azion Lib library for [Real-Time Purge](/en/documentation/platform/applications/cache/real-time-purge/). Its functions remove URLs, cache keys, and wildcard expressions from the cache through Azion API v4, so the next request fetches the current version from the origin. Each function takes a list of strings and returns a response envelope instead of throwing.

Install the package:

```bash
npm install azion
```

The `azion` package receives bug fixes only, and its maintenance ends in December 2026.

Every sample below is a TypeScript ES module with top-level `await`, run in Node.js. Types come in through `import type`, so the sample still loads after its type annotations are stripped.

---

## Authentication

Each purge request carries your [personal token](/en/documentation/fundamentals/personal-tokens/). The functions take it from the `AZION_TOKEN` environment variable, and a [createClient](#createclient) client takes it from its `token` field.

| Variable      | Description                       |
| ------------- | --------------------------------- |
| `AZION_TOKEN` | Your Azion personal token.        |
| `AZION_DEBUG` | With `true`, turns on debug mode. |

To see where each Azion Lib package looks for these values, refer to [How Azion Lib works](/en/documentation/devtools/azion-lib/how-it-works/).

---

## Response envelope

Every function returns an [AzionPurgeResponse](#azionpurgeresponse) object, `{ data?, error? }`. On success, `data` holds an [AzionPurge](#azionpurge) object: `items`, the list the purge received, and `state`. On failure, `error` holds `{ message, operation }`, and `operation` is `post purge`.

Each function sends one request to Azion API v4. The API answers with the items and the layer it purged, and the envelope keeps only `items` and `state`:

| Function                        | API request                         | Argument                       |
| ------------------------------- | ----------------------------------- | ------------------------------ |
| [purgeURL](#purgeurl)           | `POST /v4/workspace/purge/url`      | A list of URLs                 |
| [purgeCacheKey](#purgecachekey) | `POST /v4/workspace/purge/cachekey` | A list of cache keys           |
| [purgeWildCard](#purgewildcard) | `POST /v4/workspace/purge/wildcard` | A list of wildcard expressions |

The functions take no layer argument, and the API reports `layer: 'cache'` in its response. For the layers and the number of items each purge type accepts, refer to [Real-Time Purge](/en/documentation/platform/applications/cache/real-time-purge/#purge-types).

---

## createClient

Creates a client that holds a token and exposes the three purge functions as methods.

```typescript
function createClient(config?: Partial<{
  token: string;
  options?: AzionClientOptions;
}>): AzionPurgeClient;
```

| Parameter | Type                                        | Required | Description                |
| --------- | ------------------------------------------- | -------- | -------------------------- |
| `token`   | `string`                                    | No       | Your Azion personal token. |
| `options` | [`AzionClientOptions`](#azionclientoptions) | No       | Client options.            |

Returns an [AzionPurgeClient](#azionpurgeclient). Its methods take the same list as the matching function on this page, without `options`. To log the response the API returns, pass `{ debug: true }` to a function, as the [purgeURL](#purgeurl) sample does.

This sample creates a client and purges one URL with it:

```typescript
import { createClient } from 'azion/purge';
import type { AzionPurgeClient, AzionPurgeResponse, AzionPurge } from 'azion/purge';

const client: AzionPurgeClient = createClient({ token: process.env.AZION_TOKEN, options: { debug: true } });

const { data: purgeURLResponse, error }: AzionPurgeResponse<AzionPurge> = await client.purgeURL([
  'http://www.example.com/image.jpg',
]);
if (purgeURLResponse) {
  console.log('Purge successful:', purgeURLResponse);
} else {
  console.error('Purge failed', error);
}
```

Output:

```text
Purge successful: {
  items: [ 'http://www.example.com/image.jpg' ],
  state: 'executed'
}
```

---

## purgeURL

Purges a list of URLs from the cache. Only the URLs in the list leave the cache.

```typescript
function purgeURL(url: string[], options?: AzionClientOptions): Promise<AzionPurgeResponse<AzionPurge>>;
```

| Parameter | Type                                        | Required | Description                                                                          |
| --------- | ------------------------------------------- | -------- | ------------------------------------------------------------------------------------ |
| `url`     | `string[]`                                  | Yes      | The URLs to purge.                                                                   |
| `options` | [`AzionClientOptions`](#azionclientoptions) | No       | Request options. With `debug: true`, the function logs the response the API returns. |

Returns `data` as an [AzionPurge](#azionpurge) object with the purged URLs in `items`. A URL whose host belongs to no domain of your account returns `error`; the message is in [Errors](#errors).

This sample purges one URL in debug mode, so the output starts with the API response:

```typescript
import { purgeURL } from 'azion/purge';
import type { AzionPurgeResponse, AzionPurge } from 'azion/purge';

const url: string[] = ['http://www.example.com/image.jpg'];
const { data: response, error }: AzionPurgeResponse<AzionPurge> = await purgeURL(url, { debug: true });
if (response) {
  console.log('Purge successful:', response);
} else {
  console.error('Purge failed', error);
}
```

Output:

```text
Response: {
  state: 'executed',
  data: {
    items: [ 'http://www.example.com/image.jpg' ],
    layer: 'cache'
  }
}
Purge successful: {
  items: [ 'http://www.example.com/image.jpg' ],
  state: 'executed'
}
```

---

## purgeCacheKey

Purges a list of cache keys from the cache. A cache key names one variation of a cached object.

```typescript
function purgeCacheKey(cacheKey: string[], options?: AzionClientOptions): Promise<AzionPurgeResponse<AzionPurge>>;
```

| Parameter  | Type                                        | Required | Description                                                                          |
| ---------- | ------------------------------------------- | -------- | ------------------------------------------------------------------------------------ |
| `cacheKey` | `string[]`                                  | Yes      | The cache keys to purge, without a scheme.                                           |
| `options`  | [`AzionClientOptions`](#azionclientoptions) | No       | Request options. With `debug: true`, the function logs the response the API returns. |

Returns `data` as an [AzionPurge](#azionpurge) object with the purged keys in `items`. A key carries no scheme: the `host/path` form is accepted, and a key that starts with a scheme, such as `http://`, is refused with `error`. For the format of a key, refer to [Cache keys](/en/documentation/platform/applications/cache/cache-keys/).

This sample purges one cache key in debug mode:

```typescript
import { purgeCacheKey } from 'azion/purge';
import type { AzionPurgeResponse, AzionPurge } from 'azion/purge';

const cacheKey: string[] = ['www.example.com/image.jpg'];
const { data: response, error }: AzionPurgeResponse<AzionPurge> = await purgeCacheKey(cacheKey, { debug: true });
if (response) {
  console.log('Purge successful:', response);
} else {
  console.error('Purge failed', error);
}
```

Output:

```text
Response: {
  state: 'executed',
  data: {
    items: [ 'www.example.com/image.jpg' ],
    layer: 'cache'
  }
}
Purge successful: {
  items: [ 'www.example.com/image.jpg' ],
  state: 'executed'
}
```

---

## purgeWildCard

Purges the cached objects that match a wildcard expression: a URL with an asterisk (`*`) in the path or in the query string.

```typescript
function purgeWildCard(wildcard: string[], options?: AzionClientOptions): Promise<AzionPurgeResponse<AzionPurge>>;
```

| Parameter  | Type                                        | Required | Description                                                                          |
| ---------- | ------------------------------------------- | -------- | ------------------------------------------------------------------------------------ |
| `wildcard` | `string[]`                                  | Yes      | The wildcard expressions to purge.                                                   |
| `options`  | [`AzionClientOptions`](#azionclientoptions) | No       | Request options. With `debug: true`, the function logs the response the API returns. |

Returns `data` as an [AzionPurge](#azionpurge) object with the expression in `items`. The type takes a list, and Real-Time Purge accepts one wildcard expression per request. For the expressions it accepts, refer to [Wildcard purge](/en/documentation/platform/applications/cache/real-time-purge/#wildcard-purge).

This sample purges every cached object under one path prefix:

```typescript
import { purgeWildCard } from 'azion/purge';
import type { AzionPurgeResponse, AzionPurge } from 'azion/purge';

const wildcard: string[] = ['http://www.example.com/images/*'];
const { data: response, error }: AzionPurgeResponse<AzionPurge> = await purgeWildCard(wildcard, { debug: true });
if (response) {
  console.log('Purge successful:', response);
} else {
  console.error('Purge failed', error);
}
```

Output:

```text
Response: {
  state: 'executed',
  data: {
    items: [ 'http://www.example.com/images/*' ],
    layer: 'cache'
  }
}
Purge successful: {
  items: [ 'http://www.example.com/images/*' ],
  state: 'executed'
}
```

---

## Errors

A refused purge returns `error` with the HTTP status only. The reason the API gives, such as `The Content must be a valid cachekey.`, does not reach the envelope. `error.operation` is `post purge` for every function.

| Message                                        | Cause                                                                                          | What to do                                                |
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `Error: HTTP error! Status: 400 - Bad Request` | A cache key passed to [purgeCacheKey](#purgecachekey) starts with a scheme, such as `http://`. | Pass the key without the scheme, in the `host/path` form. |
| `Error: HTTP error! Status: 400 - Bad Request` | The host of a URL passed to [purgeURL](#purgeurl) belongs to no domain of your account.        | Purge a URL on a domain of your account.                  |

For the error codes the API returns for each purge type, refer to [Real-Time Purge](/en/documentation/platform/applications/cache/real-time-purge/#errors).

---

## Types

The `azion/purge` module exports these types. Import them with `import type`.

### AzionPurgeClient

The object [createClient](#createclient) returns, with one method per purge type. Each method takes one list.

| Method          | Argument              | Returns                                   |
| --------------- | --------------------- | ----------------------------------------- |
| `purgeURL`      | `urls: string[]`      | `Promise<AzionPurgeResponse<AzionPurge>>` |
| `purgeCacheKey` | `cacheKeys: string[]` | `Promise<AzionPurgeResponse<AzionPurge>>` |
| `purgeWildCard` | `wildcards: string[]` | `Promise<AzionPurgeResponse<AzionPurge>>` |

### CreateAzionPurgeClient

The type of [createClient](#createclient).

```typescript
type CreateAzionPurgeClient = (config?: Partial<{
  token: string;
  options?: AzionClientOptions;
}>) => AzionPurgeClient;
```

### AzionClientOptions

Request options that every function takes in `options`.

| Property | Type      | Required | Description                                                   |
| -------- | --------- | -------- | ------------------------------------------------------------- |
| `debug`  | `boolean` | No       | Logs the response the API returns, when passed to a function. |
| `force`  | `boolean` | No       | —                                                             |

### AzionPurgeResponse

The object each purge function returns. [Response envelope](#response-envelope) describes the success and failure forms.

| Property | Type                                     | Required | Description                                                               |
| -------- | ---------------------------------------- | -------- | ------------------------------------------------------------------------- |
| `data`   | `T`                                      | No       | The purge result, set on success.                                         |
| `error`  | `{ message: string; operation: string }` | No       | The failure message and the name of the failed operation, set on failure. |

### AzionPurge

The result of a purge.

| Property | Type                      | Required | Description                                                       |
| -------- | ------------------------- | -------- | ----------------------------------------------------------------- |
| `state`  | `'executed' \| 'pending'` | Yes      | The state of the purge request.                                   |
| `items`  | `string[]`                | Yes      | The URLs, cache keys, or wildcard expressions the purge received. |

---

## Related resources

- [Azion Lib](/en/documentation/devtools/azion-lib.md): Every Azion Lib library, with the npm package to install for it.
- [Client](/en/documentation/devtools/azion-lib/client.md): A single client that reaches the purge functions together with the other product modules.
- [Real-Time Purge](/en/documentation/platform/applications/cache/real-time-purge.md): Purge types, layers, request limits, and the errors the purge API returns.
- [Cache keys](/en/documentation/platform/applications/cache/cache-keys.md): How Azion builds the cache key that a cache key purge targets.