API documentation

Authentication

Write access needs the header "Authorization: Bearer <token>". Only the SHA-256 hash of the token is stored on the server; such requests are rejected outside HTTPS (except in debug mode). After 10 failed attempts per IP the interface locks for 15 minutes (429, "Retry-After").

Endpoints

Method	Pfad	Auth	Purpose
GET	/api/v1/health	–	status, version, storage backend
GET	/api/v1/openapi.json	–	this description as OpenAPI 3.1
GET	/api/v1/posts	–	published posts (?lang=, ?limit=, ?offset=, ?format=jsonld)
GET	/api/v1/posts?status=draft|all	✓	including drafts/scheduled posts
GET	/api/v1/posts/{id}	(✓ for drafts)	a single post (?format=jsonld)
POST	/api/v1/posts	✓	create a post
PATCH	/api/v1/posts/{id}	✓	update a post (PUT accepted as alias)
DELETE	/api/v1/posts/{id}	✓	delete a post

Fields

lang (de/en, required) · title (required, 1–200 chars) · body_md (Markdown, required) · slug (optional, else derived from title) · excerpt (optional, else derived from body) · tags (array, max 12) · translation_key (links the DE and EN version) · author · cover_url (https:// or a site path) · status (draft/published) · published_at (ISO 8601; in the future = scheduled).

Error codes

HTTP	Meaning
400	invalid query parameter or body is not a JSON object
401	token missing or invalid
403	not HTTPS, or IP not on the allow-list
404	post not found
405	method not allowed for this route
413	body larger than 512 kB
415	Content-Type is not application/json
422	validation failed, see fields
429	too many failed attempts, 15 minute lock-out

Example

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 output

With ?format=jsonld, /posts returns a schema.org ItemList and /posts/{id} a full BlogPosting object instead of the default format.

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