# REST-API

> Überblick über die Endpunkte der Docsello-API für Bereiche, Seiten, Import, Medien und Screenshots.

Mit der REST-API steuerst du Docsello aus CI-Pipelines, Skripten und eigenen Anwendungen. Alle Endpunkte liegen unter
`/api/v1` deiner Docsello-Adresse und erwarten einen [API-Token](doc:api-tokens):

```bash
curl "https://docs.example.com/api/v1/spaces" -H "Authorization: Bearer $DOCSELLO_TOKEN"
```

Anfragen und Antworten sind JSON (Ausnahme: Datei-Uploads als `multipart/form-data`). Die vollständige Beschreibung
als OpenAPI 3.1 gibt es öffentlich unter `/api/v1/openapi.json` – du kannst sie z. B. in Postman importieren oder
als [OpenAPI-Referenz](doc:openapi-referenz) in Docsello selbst anzeigen.

## Endpunkte

Bereiche werden über ihr Kürzel (oder ihre ID) angesprochen, Seiten über ihren Pfad im Bereich (z. B.
`zahlungen/stripe`, leer = Startseite des Bereichs) oder über ihre ID.

| Methode und Pfad | Wofür |
|---|---|
| `GET /me` | Workspace, Rolle des Tokens und Tarif |
| `GET /spaces` | Alle Bereiche, die der Token sehen darf |
| `POST /spaces` | Bereich anlegen (`name`, optional `slug`, `type`, `visibility`, `description`, `icon`, `defaultLocale` …) |
| `GET /spaces/{space}` | Einen Bereich lesen |
| `PATCH /spaces/{space}` | Bereich ändern (Name, Beschreibung, Symbol, Sichtbarkeit, Review-Pflicht …) |
| `GET /spaces/{space}/pages` | Seitenbaum eines Bereichs (optional `?locale=`) |
| `POST /spaces/{space}/pages` | Seite, Gruppe oder Link anlegen |
| `GET /spaces/{space}/page?path=…` | Seite über ihren Pfad lesen |
| `PUT /spaces/{space}/page?path=…` | Seite über ihren Pfad anlegen oder aktualisieren – der Baustein für CI |
| `GET /pages/{id}` | Seite über ihre ID lesen |
| `PATCH /pages/{id}` | Seite ändern |
| `DELETE /pages/{id}` | Seite samt Unterseiten in den Papierkorb |
| `POST /pages/{id}/publish` | Den aktuellen Entwurf veröffentlichen |
| `GET /pages/{id}/revisions` | Verlauf einer Seite |
| `POST /spaces/{space}/import` | Einen ganzen Ordner mit Markdown-Dateien abgleichen |
| `POST /spaces/{space}/changelog` | Eine `CHANGELOG.md` in einen Changelog-Bereich importieren |
| `GET`, `PUT /spaces/{space}/openapi` | OpenAPI-Spezifikation eines API-Referenz-Bereichs lesen oder setzen |
| `GET /search?q=…` | Volltextsuche über alle lesbaren Seiten |
| `GET`, `POST /media` | Medien auflisten (`q`, `kind`, `limit`) bzw. hochladen |
| `GET`, `PATCH`, `DELETE /media/{id}` | Eine Datei lesen, ändern (z. B. Alt-Text) oder löschen |
| `GET /screenshots` | Alle Screenshot-Definitionen |
| `GET`, `PUT`, `DELETE /screenshots/{key}` | Eine Screenshot-Definition lesen, anlegen/ändern oder löschen |
| `POST /screenshots/capture` | Screenshots neu aufnehmen (`keys` oder `all: true`) |
| `POST /sites/{site}/publish` | Die ganze Website neu generieren |

## Seite anlegen oder aktualisieren

`PUT …/page?path=…` ist idempotent: Gibt es die Seite schon, wird sie aktualisiert, sonst angelegt. Fehlende
übergeordnete Ordner werden zu Gruppen. Ohne `"publish": true` entsteht nur ein Entwurf.

```bash
curl -X PUT "$DOCSELLO_URL/api/v1/spaces/handbuch/page?path=einrichtung/start" \
  -H "Authorization: Bearer $DOCSELLO_TOKEN" -H "content-type: application/json" \
  -d '{"title": "Start", "markdown": "Hallo **Welt**", "publish": true, "message": "Aus der CI"}'
```

Weitere Felder: `description`, `icon`, `sort`, `locale`, `visibility`, `date` (für Changelog-Einträge).

## Ordner importieren

`POST /spaces/{space}/import` nimmt eine Liste von Dateien (`[{ "path": "01-start.md", "content": "…" }]`) und
macht den Bereich zum Abbild des Ordners. Unterstützt werden `index.md`/`README.md`, `NN-`-Präfixe für die Reihenfolge,
Frontmatter und `_category_.json` (Docusaurus). Optionen: `publish` (Standard `true`), `prune` (fehlende Seiten in den
Papierkorb), `dryRun` (nur zeigen, was passieren würde), `message`, `locale`. Unveränderte Dateien erzeugen keine neue
Fassung. Bequemer geht es mit der [CLI](doc:cli).

## Fehler

| Status | Bedeutung |
|---|---|
| `401` | Token fehlt, ist ungültig, abgelaufen oder widerrufen |
| `402` | Funktion oder Limit nicht im Tarif enthalten |
| `403` | Rolle oder Bereichs-Beschränkung des Tokens erlauben das nicht |
| `404` | Nicht gefunden – oder für diesen Token nicht sichtbar |
| `409` | Konflikt, z. B. eine Datei, die noch verwendet wird |
| `413` | Anfrage zu groß |
| `422` | Ungültige Eingabe; `issues` nennt die betroffenen Felder |
| `429` | Zu viele Anfragen – kurz warten und erneut versuchen |

Fehler kommen als JSON: `{ "error": "space not found" }`.