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:
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 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.
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.
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" }.