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

# API response patterns

> Understand resources, collections, actions, downloads, and API errors.

## Resources

Single-resource endpoints commonly return the resource under a named field.

```json theme={null}
{
  "success": true,
  "database": {
    "id": "db_123",
    "name": "app-db",
    "status": "running"
  }
}
```

Some automation routes return the resource directly when no extra metadata is needed.

```json theme={null}
{
  "id": "cron_123",
  "name": "nightly cleanup",
  "status": "active"
}
```

## Collections

Collection keys describe the returned resource. Count and pagination fields can appear beside the array.

```json theme={null}
{
  "assets": [],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 0,
    "totalPages": 0
  }
}
```

## Actions

Start, stop, trigger, resync, and delete endpoints return the accepted state or an empty successful response.

```json theme={null}
{
  "success": true,
  "message": "Action accepted",
  "status": "starting"
}
```

## Downloads

Download endpoints return binary content. Read the `Content-Type` and `Content-Disposition` response headers instead of parsing JSON.

```bash theme={null}
curl --output asset.bin \
  https://server.pxxl.app/api/v3/cdn/assets/asset_123/download \
  --header "Authorization: Bearer $PXXL_API_KEY"
```

## Errors

Errors use the HTTP status code and a JSON body. Validation and plan-limit responses can include structured details.

```json theme={null}
{
  "code": "DOMAIN_LIMIT_EXCEEDED",
  "message": "Your current plan domain limit has been reached.",
  "limit": 5,
  "used": 5,
  "requestId": "req_123"
}
```

| Status | Meaning |
| - | - |
| `400` | Invalid parameters or body |
| `401` | Missing or invalid API key |
| `403` | Missing scope, write permission, or plan access |
| `404` | Resource not found in the selected user or team scope |
| `409` | Requested state conflicts with the current state |
| `413` | Upload exceeds the accepted limit |
| `422` | Valid JSON with unsupported values |
| `429` | Rate limit reached |
| `500` | Unexpected server failure |

Use `requestId` when contacting Pxxl support.

<Note>
  Examples show stable fields used by clients. Pxxl can add response fields without breaking existing integrations.
</Note>


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