# Basics

> Pagination, compact responses, takedown status and error responses in the nebty API.

These rules apply to all endpoints in the [API reference](https://docs.nebty-id.com/api/reference/).

## Pagination

List endpoints return one page at a time:

```json
{
  "count": 3,
  "next": "https://app.nebty.de/core/api/brands/f5705d11-6786-4f60-b52c-59a882ecf305/domains/?page=2&page_size=2",
  "previous": null,
  "results": []
}
```

- `count` is the total number of items in all pages.
- `next` and `previous` are the full URLs of the neighbouring pages, or `null`.
- `results` holds the items of this page.

Control the page with two query parameters:

| Parameter | Default | Meaning |
| - | - | - |
| `page` | `1` | Page number, starting at 1 |
| `page_size` | `50` | Items per page, at most `100` |

A larger `page_size` is cut down to 100 on the brand, domain and scan lists. The takedown list instead returns `400` if `page_size` is outside `1`–`100`. To read a whole list, follow `next` until it is `null`.

List responses also carry the header `X-Total-Count` with the same value as `count`.

## Compact responses

Add `compact=true` to these list endpoints:

- `GET /brands/`
- `GET /brands/{id}/domains/`
- `GET /brands/{id}/scans/`

You then get short rows with only the main fields and without embedded scan history. We recommend `compact=true` for lists. To get the full evidence for one item, call its detail endpoint, for example `GET /brands/{id}/domains/{domain_id}/`.

## Takedown status

A new takedown starts with one of two statuses:

| Status | When |
| - | - |
| `OPEN` | You sent a `brand` that has active monitoring. The nebty team starts work. |
| `REQUESTED` | You sent no `brand`, or the brand has no active monitoring. nebty approves or rejects the request first. |

The `status` in the `201` response tells you which one applies. After that, read the current status with `GET /takedowns/{id}/` and the history with `GET /takedowns/{id}/events/`. The reference lists all status values.

## Errors

Errors come back as JSON with a matching HTTP status code.

| Code | Meaning | Body |
| - | - | - |
| `400` | The request data is not valid. | One entry per field, for example `{"target_website": ["Enter a valid URL."]}` |
| `401` | The API key is missing, wrong or inactive. | `{"detail": "Invalid or inactive API key."}` |
| `404` | The item does not exist, or your user has no access to it. | `{"detail": "No Brand matches the given query."}` |

A brand or takedown that belongs to another customer returns `404`, not `403`. When you request a takedown for a brand that your user is not a member of, you get `400` with an error on the `brand` field.