REST-API-Referenz

EmDash stellt eine REST-API unter /_emdash/api/ für Inhaltsverwaltung, Medien-Uploads und Schema-Operationen bereit.

Authentifizierung

API-Anfragen erfordern eine Authentifizierung über einen Bearer-Token:

Authorization: Bearer <token>

Generieren Sie Token über die Admin-Oberfläche oder programmatisch.

Antwortformat

Alle Antworten folgen einem einheitlichen Format:

// Erfolg
{
  "success": true,
  "data": { ... }
}

// Fehler
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Menschenlesbare Nachricht",
    "details": { ... }
  }
}

Inhalts-Endpunkte

Inhalte auflisten

GET /_emdash/api/content/:collection

Parameter

Parameter	Typ	Beschreibung
collection	string	Collection-Slug (Pfad)
cursor	string	Paginierungs-Cursor (Query)
limit	number	Elemente pro Seite (Query, Standard: 50)
status	string	Nach Status filtern (Query)
orderBy	string	Feld zum Sortieren (Query)
order	string	Sortierrichtung: asc oder desc (Query)

Antwort

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "01HXK5MZSN...",
        "type": "posts",
        "slug": "hello-world",
        "data": { "title": "Hallo Welt", ... },
        "status": "published",
        "createdAt": "2025-01-24T12:00:00Z",
        "updatedAt": "2025-01-24T12:00:00Z"
      }
    ],
    "nextCursor": "eyJpZCI6..."
  }
}

Inhalt abrufen

GET /_emdash/api/content/:collection/:id

Antwort

{
  "success": true,
  "data": {
    "item": {
      "id": "01HXK5MZSN...",
      "type": "posts",
      "slug": "hello-world",
      "data": { "title": "Hallo Welt", ... },
      "status": "published",
      "createdAt": "2025-01-24T12:00:00Z",
      "updatedAt": "2025-01-24T12:00:00Z"
    }
  }
}

Inhalt erstellen

POST /_emdash/api/content/:collection
Content-Type: application/json

Anfrage-Body

{
  "data": {
    "title": "Neuer Beitrag",
    "content": [...]
  },
  "slug": "new-post",
  "status": "draft"
}

Antwort

{
  "success": true,
  "data": {
    "item": { ... }
  }
}

Inhalt aktualisieren

PUT /_emdash/api/content/:collection/:id
Content-Type: application/json

Anfrage-Body

{
  "data": {
      "title": "Aktualisierter Titel"
  },
  "status": "published"
}

Inhalt löschen

DELETE /_emdash/api/content/:collection/:id

Antwort

{
  "success": true,
  "data": {
    "success": true
  }
}

Medien-Endpunkte

Medien auflisten

GET /_emdash/api/media

Parameter

Parameter	Typ	Beschreibung
cursor	string	Paginierungs-Cursor
limit	number	Elemente pro Seite (Standard: 20)
mimeType	string	Nach MIME-Typ-Präfix filtern

Antwort

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "01HXK5MZSN...",
        "filename": "photo.jpg",
        "mimeType": "image/jpeg",
        "size": 102400,
        "width": 1920,
        "height": 1080,
        "url": "https://cdn.example.com/photo.jpg",
        "createdAt": "2025-01-24T12:00:00Z"
      }
    ],
    "nextCursor": "eyJpZCI6..."
  }
}

Medium abrufen

GET /_emdash/api/media/:id

Medium erstellen

POST /_emdash/api/media
Content-Type: application/json

Anfrage-Body

{
  "filename": "photo.jpg",
  "mimeType": "image/jpeg",
  "size": 102400,
  "width": 1920,
  "height": 1080,
  "storageKey": "uploads/photo.jpg"
}

Hinweis

Dieser Endpunkt erfasst Medien-Metadaten nach dem Upload. Verwenden Sie den Upload-Endpunkt oder signierte URLs, um die eigentliche Datei hochzuladen.

Medium aktualisieren

PUT /_emdash/api/media/:id
Content-Type: application/json

Anfrage-Body

{
  "alt": "Bildbeschreibung",
  "caption": "Bildunterschrift"
}

Medium löschen

DELETE /_emdash/api/media/:id

Mediendatei abrufen

GET /_emdash/api/media/file/:key

Liefert den eigentlichen Dateiinhalt. Nur für lokalen Speicher.

Revisions-Endpunkte

Revisionen auflisten

GET /_emdash/api/content/:collection/:entryId/revisions

Parameter

Parameter	Typ	Beschreibung
limit	number	Maximale zurückzugebende Revisionen (Standard: 50)

Antwort

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "01HXK5MZSN...",
        "collection": "posts",
        "entryId": "01HXK5MZSN...",
        "data": { ... },
        "createdAt": "2025-01-24T12:00:00Z"
      }
    ],
    "total": 5
  }
}

Revision abrufen

GET /_emdash/api/revisions/:revisionId

Revision wiederherstellen

POST /_emdash/api/revisions/:revisionId/restore

Stellt den Inhalt auf den Zustand dieser Revision wieder her und erstellt eine neue Revision.

Schema-Endpunkte

Collections auflisten

GET /_emdash/api/schema/collections

Antwort

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "01HXK5MZSN...",
        "slug": "posts",
        "label": "Beiträge",
        "labelSingular": "Beitrag",
        "supports": ["drafts", "revisions", "preview"]
      }
    ]
  }
}

Collection abrufen

GET /_emdash/api/schema/collections/:slug

Parameter

Parameter	Typ	Beschreibung
includeFields	boolean	Felddefinitionen einbeziehen (Query)

Collection erstellen

POST /_emdash/api/schema/collections
Content-Type: application/json

Anfrage-Body

{
  "slug": "products",
  "label": "Products",
  "labelSingular": "Product",
  "description": "Product catalog",
  "supports": ["drafts", "revisions"]
}

Collection aktualisieren

PATCH /_emdash/api/schema/collections/:slug
Content-Type: application/json

Collection löschen

DELETE /_emdash/api/schema/collections/:slug

Parameter

Parameter	Typ	Beschreibung
force	boolean	Löschen auch wenn Collection Inhalte hat (Query)

Felder auflisten

GET /_emdash/api/schema/collections/:slug/fields

Feld erstellen

POST /_emdash/api/schema/collections/:slug/fields
Content-Type: application/json

Anfrage-Body

{
  "slug": "price",
  "label": "Price",
  "type": "number",
  "required": true,
  "validation": {
    "min": 0
  }
}

Feld aktualisieren

PATCH /_emdash/api/schema/collections/:collectionSlug/fields/:fieldSlug
Content-Type: application/json

Feld löschen

DELETE /_emdash/api/schema/collections/:collectionSlug/fields/:fieldSlug

Felder neu anordnen

POST /_emdash/api/schema/collections/:slug/fields/reorder
Content-Type: application/json

Anfrage-Body

{
  "fieldSlugs": ["title", "content", "author", "publishedAt"]
}

Schema-Export

Schema exportieren (JSON)

GET /_emdash/api/schema
Accept: application/json

Schema exportieren (TypeScript)

GET /_emdash/api/schema?format=typescript
Accept: text/typescript

Gibt TypeScript-Interfaces für alle Collections zurück.

Plugin-Endpunkte

Plugins auflisten

GET /_emdash/api/plugins

Plugin abrufen

GET /_emdash/api/plugins/:pluginId

Plugin aktivieren

POST /_emdash/api/plugins/:pluginId/enable

Plugin deaktivieren

POST /_emdash/api/plugins/:pluginId/disable

Fehlercodes

Code	HTTP-Status	Beschreibung
NOT_FOUND	404	Ressource nicht gefunden
VALIDATION_ERROR	400	Ungültige Eingabedaten
UNAUTHORIZED	401	Fehlender oder ungültiger Token
FORBIDDEN	403	Unzureichende Berechtigungen
CONTENT_LIST_ERROR	500	Inhaltsauflistung fehlgeschlagen
CONTENT_CREATE_ERROR	500	Inhaltserstellung fehlgeschlagen
CONTENT_UPDATE_ERROR	500	Inhaltsaktualisierung fehlgeschlagen
CONTENT_DELETE_ERROR	500	Inhaltslöschung fehlgeschlagen
MEDIA_LIST_ERROR	500	Medienauflistung fehlgeschlagen
MEDIA_CREATE_ERROR	500	Medienerstellung fehlgeschlagen
SCHEMA_ERROR	400	Schema-Operation fehlgeschlagen
DUPLICATE_SLUG	409	Slug existiert bereits
RESERVED_SLUG	400	Slug ist reserviert

Such-Endpunkte

Globale Suche

GET /_emdash/api/search?q=hello+world

Parameter

Parameter	Typ	Beschreibung
q	string	Suchanfrage (erforderlich)
collections	string	Kommagetrennte Collection-Slugs
status	string	Nach Status filtern (Standard: published)
limit	number	Maximale Ergebnisse (Standard: 20)
cursor	string	Paginierungs-Cursor

Antwort

{
  "results": [
    {
      "collection": "posts",
      "id": "01HXK5MZSN...",
      "slug": "hello-world",
      "title": "Hallo Welt",
      "snippet": "...this is a <mark>hello</mark>
 <mark>world</mark>
 example...",
      "score": 0.95
    }
  ],
  "nextCursor": "eyJvZmZzZXQiOjIwfQ"
}

Suchvorschläge

GET /_emdash/api/search/suggest?q=hel&limit=5

Gibt präfix-gematchte Titel für die Autovervollständigung zurück.

Suchindex neu aufbauen

POST /_emdash/api/search/rebuild

Baut den FTS-Index für alle oder bestimmte Collections neu auf.

Suchstatistiken

GET /_emdash/api/search/stats

Gibt die Anzahl der indizierten Dokumente pro Collection zurück.

Abschnitts-Endpunkte

Abschnitte auflisten

GET /_emdash/api/sections
GET /_emdash/api/sections?source=theme
GET /_emdash/api/sections?search=newsletter

Abschnitt abrufen

GET /_emdash/api/sections/:slug

Abschnitt erstellen

POST /_emdash/api/sections
Content-Type: application/json

{
  "slug": "my-section",
  "title": "My Section",
  "keywords": ["keyword1"],
  "content": [...]
}

Abschnitt aktualisieren

PUT /_emdash/api/sections/:slug

Abschnitt löschen

DELETE /_emdash/api/sections/:slug

Einstellungs-Endpunkte

Alle Einstellungen abrufen

GET /_emdash/api/settings

Einstellungen aktualisieren

POST /_emdash/api/settings
Content-Type: application/json

{
  "siteTitle": "Meine Website",
  "tagline": "Eine grossartige Website",
  "postsPerPage": 10
}

Menü-Endpunkte

Menüs auflisten

GET /_emdash/api/menus

Menü abrufen

GET /_emdash/api/menus/:name

Menü erstellen

POST /_emdash/api/menus
Content-Type: application/json

{
  "name": "footer",
  "label": "Footer Navigation"
}

Menü aktualisieren

PUT /_emdash/api/menus/:name

Menü löschen

DELETE /_emdash/api/menus/:name

Menüpunkt hinzufügen

POST /_emdash/api/menus/:name/items
Content-Type: application/json

{
  "type": "page",
  "referenceCollection": "pages",
  "referenceId": "page_about",
  "label": "About Us"
}

Menüpunkte neu anordnen

POST /_emdash/api/menus/:name/reorder
Content-Type: application/json

{
  "items": [
    { "id": "item_1", "parentId": null, "sortOrder": 0 },
    { "id": "item_2", "parentId": null, "sortOrder": 1 },
    { "id": "item_3", "parentId": "item_2", "sortOrder": 0 }
  ]
}

Taxonomie-Endpunkte

Taxonomie-Definitionen auflisten

GET /_emdash/api/taxonomies

Taxonomie erstellen

POST /_emdash/api/taxonomies
Content-Type: application/json

{
  "name": "genre",
  "label": "Genres",
  "labelSingular": "Genre",
  "hierarchical": true,
  "collections": ["books", "movies"]
}

Begriffe auflisten

GET /_emdash/api/taxonomies/:name/terms

Begriff erstellen

POST /_emdash/api/taxonomies/:name/terms
Content-Type: application/json

{
  "slug": "tutorials",
  "label": "Tutorials",
  "parentId": "term_abc",
  "description": "How-to guides"
}

Begriff aktualisieren

PUT /_emdash/api/taxonomies/:name/terms/:slug

Begriff löschen

DELETE /_emdash/api/taxonomies/:name/terms/:slug

Eintragsbegriffe setzen

POST /_emdash/api/content/:collection/:id/terms/:taxonomy
Content-Type: application/json

{
  "termIds": ["term_news", "term_featured"]
}

Widget-Bereichs-Endpunkte

Widget-Bereiche auflisten

GET /_emdash/api/widget-areas

Widget-Bereich abrufen

GET /_emdash/api/widget-areas/:name

Widget-Bereich erstellen

POST /_emdash/api/widget-areas
Content-Type: application/json

{
  "name": "sidebar",
  "label": "Hauptseitenleiste",
  "description": "Appears on posts"
}

Widget-Bereich löschen

DELETE /_emdash/api/widget-areas/:name

Widget hinzufügen

POST /_emdash/api/widget-areas/:name/widgets
Content-Type: application/json

{
  "type": "content",
  "title": "Ueber",
  "content": [...]
}

Widget aktualisieren

PUT /_emdash/api/widget-areas/:name/widgets/:id

Widget löschen

DELETE /_emdash/api/widget-areas/:name/widgets/:id

Widgets neu anordnen

POST /_emdash/api/widget-areas/:name/reorder
Content-Type: application/json

{
  "widgetIds": ["widget_1", "widget_2", "widget_3"]
}

Benutzerverwaltungs-Endpunkte

Benutzer auflisten

GET /_emdash/api/admin/users
GET /_emdash/api/admin/users?role=40
GET /_emdash/api/admin/users?search=john

Benutzer abrufen

GET /_emdash/api/admin/users/:id

Benutzer aktualisieren

PATCH /_emdash/api/admin/users/:id
Content-Type: application/json

{
  "name": "John Doe",
  "role": 40
}

Benutzer aktivieren

POST /_emdash/api/admin/users/:id/enable

Benutzer deaktivieren

POST /_emdash/api/admin/users/:id/disable

Authentifizierungs-Endpunkte

Einrichtungsstatus

GET /_emdash/api/setup/status

Gibt zurück, ob die Einrichtung abgeschlossen ist und ob Benutzer existieren.

Passkey-Login

POST /_emdash/api/auth/passkey/options

WebAuthn-Authentifizierungsoptionen abrufen.

POST /_emdash/api/auth/passkey/verify
Content-Type: application/json

{
  "id": "credential-id",
  "rawId": "...",
  "response": {...},
  "type": "public-key"
}

Passkey verifizieren und Sitzung erstellen.

Magic Link

POST /_emdash/api/auth/magic-link/send
Content-Type: application/json

{
  "email": "user@example.com"
}

GET /_emdash/api/auth/magic-link/verify?token=xxx

Abmelden

POST /_emdash/api/auth/logout

Aktueller Benutzer

GET /_emdash/api/auth/me

Benutzer einladen

POST /_emdash/api/auth/invite
Content-Type: application/json

{
  "email": "newuser@example.com",
  "role": 30
}

Passkey-Verwaltung

GET /_emdash/api/auth/passkey

Passkeys des Benutzers auflisten.

POST /_emdash/api/auth/passkey/register/options
POST /_emdash/api/auth/passkey/register/verify

Neuen Passkey registrieren.

PATCH /_emdash/api/auth/passkey/:id
Content-Type: application/json

{
  "name": "MacBook Pro"
}

Passkey umbenennen.

DELETE /_emdash/api/auth/passkey/:id

Passkey löschen.

Import-Endpunkte

WordPress-Export analysieren

POST /_emdash/api/import/wordpress/analyze
Content-Type: multipart/form-data

file: <WXR-Datei>

WordPress-Import ausführen

POST /_emdash/api/import/wordpress/execute
Content-Type: application/json

{
  "analysisId": "...",
  "options": {
    "includeMedia": true,
    "includeTaxonomies": true,
    "includeMenus": true
  }
}

Ratenbegrenzung

API-Endpunkte können je nach Bereitstellungskonfiguration ratenbeschränkt sein. Bei Ratenbegrenzung enthalten Antworten:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

CORS

Die API unterstützt CORS für Browseranfragen. Konfigurieren Sie erlaubte Ursprünge in Ihrer Bereitstellung.