Zum Inhalt springen

REST-API ​

Alles, was der Admin kann, gibt es auch als JSON unter <APP_URL>/api: Sites, Projekte, Dateien und Aufrufe. Gedacht für Skripte, CI-Pipelines und alles, was kein MCP-Client ist.

Anmeldung ​

Die API nutzt dieselben Tokens wie MCP. Leg im Admin unter API & MCP eins an und schick es als Bearer-Token mit:

bash
curl -H "Authorization: Bearer <token>" https://preview.example.com/api/sites

Ein Token hat dieselben Rechte wie der Admin-Login. Ohne gültiges Token bekommt jede Anfrage 401.

Endpunkte ​

MethodePfadWas er tut
GET/api/sitesSites auflisten
POST/api/sitesSite anlegen: name, optional password, project_id
GET/api/sites/{id}Eine Site
PATCH/api/sites/{id}name, password, clear_password: true, project_id ändern (null nimmt sie aus dem Projekt)
DELETE/api/sites/{id}Site mit allen Dateien löschen
GET/api/sites/{id}/filesRelative Pfade aller Dateien
POST/api/sites/{id}/filesEine Datei oder ein Zip hochladen (Multipart file, optional path, replace)
DELETE/api/sites/{id}/files/{path}Eine Datei löschen
DELETE/api/sites/{id}/filesAlle Dateien löschen, die Site bleibt
GET/api/projectsProjekte auflisten
POST/api/projectsProjekt anlegen: name, optional password
GET/api/projects/{id}Ein Projekt mit seinen Sites
PATCH/api/projects/{id}name, password, clear_password: true ändern
DELETE/api/projects/{id}Projekt löschen, die Sites bleiben
GET/api/visitsSeitenaufrufe und Passworteingaben, siehe Aufrufe

Anfragen schicken JSON (Content-Type: application/json), außer beim Hochladen. Passwörter kommen nie zurück, nur has_password.

Eine Site sieht so aus:

json
{
  "data": {
    "id": 3,
    "name": "Relaunch v2",
    "url": "https://preview.example.com/s/k3j9x0aq1b/",
    "has_password": true,
    "project_id": 1,
    "file_count": 14,
    "has_html": true,
    "updated_at": "2026-10-28T13:12:00+00:00",
    "view_count": 4,
    "last_viewed_at": "2026-10-28T14:32:10+00:00"
  }
}

Hochladen ​

Eine Datei pro Anfrage, bis 100 MB. Ein Zip wird entpackt, ein einzelner umschließender Ordner fällt weg. path ist ohne Angabe der Dateiname. Mit replace=1 ersetzt der Upload die ganze Site in einem Schritt: Die Live-Site ist zwischendurch nie leer.

bash
curl -H "Authorization: Bearer <token>" \
  -F file=@dist.zip -F replace=1 \
  https://preview.example.com/api/sites/3/files

Prüf den Entwurf vorher gegen Was funktioniert.

Filtern, sortieren, blättern ​

Listen nehmen Query-Parameter:

ParameterBeispielGilt für
filter[name]filter[name]=relaunch (Teil des Namens)Sites, Projekte
filter[project_id]filter[project_id]=1Sites, Aufrufe
filter[site_id], filter[kind], filter[visitor]filter[kind]=unlock_failedAufrufe
filter[since], filter[until]filter[since]=2026-10-01Aufrufe
sortsort=name, sort=-updated_at (- = absteigend)alle
includeinclude=sitesProjekte
page, per_pageper_page=100 (Standard 30, höchstens 100)alle

Sites lassen sich nach name, created_at, updated_at, view_count oder last_viewed_at sortieren, Standard ist -updated_at. Listen liefern data, links und meta (mit total, last_page).

Fehler ​

Fehler folgen RFC 9457 (Content-Type: application/problem+json):

json
{
  "type": "about:blank",
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "The request data is invalid.",
  "violations": [{ "path": "name", "message": "The name field is required." }]
}

Die Fehlertexte sind immer Englisch.

StatusWann
400Unbekannter Filter, Sortierung oder Include
401Token fehlt oder wurde widerrufen
404Site, Projekt oder Datei gibt es nicht
422Ungültige Daten, violations nennt das Feld
429Mehr als 120 Anfragen pro Minute mit einem Token. Retry-After sagt, wann es weitergeht