# Grundlagen

> Seitenaufteilung, kompakte Antworten, Takedown-Status und Fehlerantworten der nebty API.

Diese Regeln gelten für alle Endpunkte in der [API-Referenz](https://docs.nebty-id.com/api/reference/).

## Seitenaufteilung

Listen-Endpunkte liefern jeweils eine Seite:

```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` ist die Gesamtzahl der Einträge über alle Seiten.
- `next` und `previous` sind die vollständigen URLs der Nachbarseiten, oder `null`.
- `results` enthält die Einträge dieser Seite.

Die Seite steuern Sie mit zwei Query-Parametern:

| Parameter | Standard | Bedeutung |
| - | - | - |
| `page` | `1` | Seitennummer, beginnt bei 1 |
| `page_size` | `50` | Einträge pro Seite, höchstens `100` |

Bei Brand-, Domain- und Scan-Listen wird ein größerer `page_size` auf 100 gekürzt. Die Takedown-Liste gibt stattdessen `400` zurück, wenn `page_size` außerhalb von `1`–`100` liegt. Um eine ganze Liste zu lesen, folgen Sie `next`, bis es `null` ist.

Listen-Antworten tragen außerdem den Header `X-Total-Count` mit demselben Wert wie `count`.

## Kompakte Antworten

Hängen Sie `compact=true` an diese Listen-Endpunkte an:

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

Sie bekommen dann kurze Zeilen mit nur den wichtigsten Feldern und ohne eingebettete Scan-Historie. Wir empfehlen `compact=true` für Listen. Die vollständigen Belege zu einem Eintrag liefert sein Detail-Endpunkt, zum Beispiel `GET /brands/{id}/domains/{domain_id}/`.

## Takedown-Status

Ein neuer Takedown startet mit einem von zwei Status:

| Status | Wann |
| - | - |
| `OPEN` | Sie haben eine `brand` mit aktivem Monitoring mitgeschickt. Das nebty-Team beginnt mit der Arbeit. |
| `REQUESTED` | Sie haben keine `brand` mitgeschickt, oder die Brand hat kein aktives Monitoring. nebty gibt die Anfrage zuerst frei oder lehnt sie ab. |

Der `status` in der `201`-Antwort zeigt, was zutrifft. Danach lesen Sie den aktuellen Status mit `GET /takedowns/{id}/` und den Verlauf mit `GET /takedowns/{id}/events/`. Die Referenz listet alle Status-Werte.

## Fehler

Fehler kommen als JSON mit dem passenden HTTP-Statuscode zurück.

| Code | Bedeutung | Inhalt |
| - | - | - |
| `400` | Die Daten der Anfrage sind ungültig. | Ein Eintrag pro Feld, zum Beispiel `{"target_website": ["Enter a valid URL."]}` |
| `401` | Der API-Key fehlt, ist falsch oder inaktiv. | `{"detail": "Invalid or inactive API key."}` |
| `404` | Der Eintrag existiert nicht, oder Ihr Benutzer hat keinen Zugriff. | `{"detail": "No Brand matches the given query."}` |

Eine Brand oder ein Takedown eines anderen Kunden liefert `404`, nicht `403`. Fordern Sie einen Takedown für eine Brand an, in der Ihr Benutzer kein Mitglied ist, bekommen Sie `400` mit einem Fehler am Feld `brand`.