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

# CDN integration

> How to use team files on a website, in Next.js or in CI/CD.

The CDN stores team files and serves them at public addresses. You manage files through API V3 with a key; serving files needs no key.

| Task | How |
| - | - |
| Images, documents, video | Upload with `POST /v3/cdn/assets` and use the public address |
| File from a URL | `POST /v3/cdn/assets/external` downloads it into the CDN |
| Plain HTML/CSS | Full CDN addresses in `src`, `href` and `url()` |
| Next.js | [Next.js guide](https://apidocs.erlcrussia.com/en/tutorials/nextjs-cdn-integration.md) |
| Custom domain | [Custom CDN domains](https://apidocs.erlcrussia.com/en/tutorials/cdn-custom-domains.md) |
| Releases from CI/CD | [CI/CD and cache purge](https://apidocs.erlcrussia.com/en/tutorials/cdn-cache-purge-cicd.md) |

## Access

First bind your key to a team:

```bash theme={null}
curl -X PUT https://api.erlcrussia.com/v3/cdn/team \
  -H 'erlcrussia-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"teamId":"YOUR_TEAM_ID"}'
```

The key owner needs a team role with CDN access; membership is checked on every request. Send the key only in the `erlcrussia-api-key` header.

## File addresses

Each file is identified by a namespace and a path. The namespace is the team slug or a verified [custom domain](https://apidocs.erlcrussia.com/en/tutorials/cdn-custom-domains.md).

* Shared domain: `https://cdn.erlcrussia.com/YOUR_TEAM_SLUG/images/logo.png`
* Custom domain: `https://files.example.com/images/logo.png`

On the shared domain a team can only use `/{slug}/...`. If `path` is omitted on upload, it is generated from the file type.

If a file with the same `path` already exists, the response is 409 and the file is not overwritten. Use a new path for new versions.

## Folders

| Action | What happens to files |
| - | - |
| Create, rename or delete a folder | Nothing: file addresses stay the same |
| `PATCH /cdn/assets` with `folderId` | The file moves to another folder in the UI |
| `PATCH /cdn/assets` with `path` | The file gets a new address |
| Folder with `pathEnabled: true` | New uploads without `path` get the folder prefix |

## Common parameters

| Parameter | Meaning |
| - | - |
| `domain` | Namespace. Defaults to the key team namespace |
| `ids` | Comma-separated file IDs |
| `path` | Exact file path |
| `prefix` | Path prefix for a group of files |
| `folderId` | Folder: `root` for no folder, `all` for all |
| `page, limit` | List pages, `limit` up to 100 |

## Cache

CDN responses include `X-Cache` (CDN cache) and `CF-Cache-Status` (Cloudflare). A purge (`POST /cdn/assets/purge`) is accepted at once and runs in the background. Publishing new versions at new addresses is more reliable than replacing old files. See [CI/CD and cache purge](https://apidocs.erlcrussia.com/en/tutorials/cdn-cache-purge-cicd.md).

## Common responses

| Response | Meaning |
| - | - |
| 401, code 5007 | No key |
| 403, code 5009 | No access to the team CDN |
| 409, code 5135 | The path is taken |
| 429, code 5016 | Rate limit exceeded |

Personal files of website users are covered in [Personal files](https://apidocs.erlcrussia.com/en/other/user-assets.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.