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

# FiveMesh CDN API

> Manage CDN objects, uploads and scoped upload URLs from server-side integrations.

Use the FiveMesh CDN API when a server-side integration needs to list, upload or delete CDN objects without opening the dashboard.

The API manages objects only. Public file delivery happens through the `publicUrl` returned by object responses.

<Warning>
  Do not call these endpoints with a service key from client-side Lua, browser code or NUI bundles. Keep service keys on the server side.
</Warning>

## Base URL

```text theme={null}
https://api.fivemesh.io/v1
```

All authenticated CDN routes require a service key with the matching `cdn` permission.

```http theme={null}
Authorization: Bearer YOUR_FIVEMESH_API_KEY
```

Every response includes `success` and `requestId`. The same request ID is returned as the `X-Request-Id` header.

## Permissions

| Permission   | Allows                                        |
| ------------ | --------------------------------------------- |
| `cdn:read`   | List objects under allowed paths.             |
| `cdn:write`  | Upload objects and create scoped upload URLs. |
| `cdn:delete` | Delete one object or a batch of objects.      |

Service keys can be limited to CDN path prefixes such as `/phone`, `/tablet` or `/uploads`.

<Info>
  Path checks run against the final normalized object path. Encoded traversal, backslashes, absolute paths and dot-prefixed path segments are rejected or hidden from customer-facing listings.
</Info>

## Endpoints

| Endpoint                      | Use it for                                                        |
| ----------------------------- | ----------------------------------------------------------------- |
| `GET /objects`                | Read objects under an allowed CDN path.                           |
| `POST /objects`               | Upload a single file from a server-side integration.              |
| `POST /objects/base64`        | Upload a Base64-encoded file in a JSON request.                   |
| `POST /objects/bulk`          | Upload multiple files and receive per-file results.               |
| `DELETE /objects`             | Remove a single object by path.                                   |
| `POST /objects/bulk-delete`   | Remove multiple objects and receive per-path results.             |
| `GET /presigned-url`          | Create a short-lived upload URL without exposing the service key. |
| `POST /presigned-url/{token}` | Send files to a scoped upload URL.                                |

## Object shape

```json theme={null}
{
  "key": "screenshots/a.png",
  "size": 12345,
  "contentType": "image/png",
  "etag": "3f2a...",
  "lastModified": "2026-06-16T11:00:00.000Z",
  "metadata": {},
  "publicUrl": "https://cdn.fivemesh.io/acme/screenshots/a.png"
}
```

## Idempotency

Upload and delete routes accept `Idempotency-Key`.

Use this header when retrying a request after a network timeout. Reusing the same idempotency key with a different request returns `CONFLICT`.

```http theme={null}
Idempotency-Key: upload-screenshot-001
```

## Error format

```json theme={null}
{
  "success": false,
  "error": {
    "code": "PATH_NOT_ALLOWED",
    "message": "This API key cannot access the requested path."
  },
  "requestId": "req_..."
}
```

Common CDN error codes:

| Code                       | Meaning                                                       |
| -------------------------- | ------------------------------------------------------------- |
| `UNAUTHORIZED`             | The service key is missing, invalid, disabled or expired.     |
| `FORBIDDEN`                | The service key does not include the required permission.     |
| `INVALID_PATH`             | The path or filename is not accepted.                         |
| `PATH_NOT_ALLOWED`         | The path is outside the key or upload URL scope.              |
| `FILE_TOO_LARGE`           | The uploaded file is over the allowed size.                   |
| `TOO_MANY_FILES`           | The request exceeds the file or path count limit.             |
| `CONTENT_TYPE_NOT_ALLOWED` | The file MIME type is not allowed.                            |
| `TOKEN_INVALID`            | The upload URL token is invalid.                              |
| `TOKEN_EXPIRED`            | The upload URL token expired or reached its file limit.       |
| `RATE_LIMITED`             | Retry after the `Retry-After` header.                         |
| `CONFLICT`                 | An idempotency key was reused with different request content. |

## Related pages

* [Authentication](/api-reference/authentication)
* [API keys](/account/api-keys)
* [Set up FiveMesh CDN](/cdn/setup)
* [CDN object browser](/cdn/object-browser)
* [LB-Scripts integration](/integrations/lb-scripts)