API-Dokumentation

Authentifizierung

Schreibende Zugriffe brauchen den Header «Authorization: Bearer <Token>». Nur der SHA-256-Hash des Tokens liegt auf dem Server; ausserhalb von HTTPS werden solche Zugriffe abgelehnt (ausser im Debug-Modus). Nach 10 fehlgeschlagenen Versuchen je IP sperrt die Schnittstelle 15 Minuten (429, «Retry-After»).

Endpunkte

Methode	Pfad	Auth	Zweck
GET	/api/v1/health	–	Status, Version, Speicherart
GET	/api/v1/openapi.json	–	Diese Beschreibung als OpenAPI 3.1
GET	/api/v1/posts	–	veröffentlichte Beiträge (?lang=, ?limit=, ?offset=, ?format=jsonld)
GET	/api/v1/posts?status=draft|all	✓	inklusive Entwürfe/geplanter Beiträge
GET	/api/v1/posts/{id}	(✓ für Entwürfe)	einzelner Beitrag (?format=jsonld)
POST	/api/v1/posts	✓	Beitrag anlegen
PATCH	/api/v1/posts/{id}	✓	Beitrag ändern (PUT als Alias)
DELETE	/api/v1/posts/{id}	✓	Beitrag löschen

Felder

lang (de/en, Pflicht) · title (Pflicht, 1–200 Zeichen) · body_md (Markdown, Pflicht) · slug (optional, sonst aus dem Titel) · excerpt (optional, sonst aus dem Text) · tags (Array, max. 12) · translation_key (verknüpft DE- und EN-Fassung) · author · cover_url (https:// oder Pfad) · status (draft/published) · published_at (ISO 8601; in der Zukunft = geplante Veröffentlichung).

Fehlercodes

HTTP	Bedeutung
400	ungültiger Query-Parameter oder kein JSON-Objekt im Body
401	Token fehlt oder ist ungültig
403	kein HTTPS oder IP nicht in der Allowlist
404	Beitrag nicht gefunden
405	Methode für diese Route nicht erlaubt
413	Body grösser als 512 kB
415	Content-Type ist nicht application/json
422	Validierungsfehler, Details unter fields
429	zu viele fehlgeschlagene Anmeldeversuche, 15 Min. Sperre

Beispiel

curl -X POST https://dataveritas.bitblade.io/api/v1/posts \
  -H "Authorization: Bearer $DV_TOKEN" -H "Content-Type: application/json" \
  -d '{"lang":"de","title":"Neuer Beitrag","body_md":"## Abschnitt\n\nText …","tags":["qualität"],"status":"published"}'

curl https://dataveritas.bitblade.io/api/v1/posts?lang=de&limit=5

Schema.org-Ausgabe

Mit ?format=jsonld liefert /posts ein schema.org ItemList und /posts/{id} ein vollständiges BlogPosting-Objekt statt des Standardformats.

curl "https://dataveritas.bitblade.io/api/v1/posts/3?format=jsonld"