Hilfe-Center

Verwalten Sie die Hilfe-Center-Artikel eines Projekts und deren Kategorien. Voraussetzung ist, dass das Hilfe-Center für das Projekt aktiviert ist — ist es aus, antworten alle Endpunkte unten mit 404.

Artikelinhalte sind Markdown, nicht HTML. Das Portal rendert sie mit einem Viewer, der rohes HTML niemals auswertet — gesendetes HTML sehen Leser also als wörtlichen Text.

GET/v1/articles

Parameter	Type	Description
`status`	`string`	Nach Status filtern: draft, published oder archived.
`category_id`	`string`	Nur Artikel in dieser Kategorie.
`limit`	`integer`	Seitengröße. Standard 25, max. 100.
`offset`	`integer`	Zu überspringende Einträge. Standard 0.

GET/v1/articles/search

Parameter	Type	Description
`q`required	`string`	Suchanfrage. Unterstützt Phrasen in Anführungszeichen, OR und -Negation.
`limit`	`integer`	Anzahl Treffer. Standard 25, max. 100.

GET/v1/articles/:id

POST/v1/articles

Parameter	Type	Description
`title`required	`string`	Bis zu 200 Zeichen.
`body`	`string`	Markdown. Bis zu 50.000 Zeichen.
`excerpt`	`string`	Einzeilige Zusammenfassung, bis 300 Zeichen. Wird sonst aus dem Inhalt erzeugt.
`slug`	`string`	URL-Segment, bis 80 Zeichen. Wird sonst aus dem Titel erzeugt.
`category_id`	`string`	Kategorie, unter der der Artikel abgelegt wird.

PATCH/v1/articles/:id

Parameter	Type	Description
`title`	`string`	Neuer Titel.
`body`	`string`	Neuer Markdown-Inhalt.
`excerpt`	`string`	Neue Zusammenfassung; null löscht sie.
`slug`	`string`	Neues URL-Segment.
`category_id`	`string`	Neue Kategorie; null entfernt die Zuordnung.
`status`	`string`	draft, published oder archived.

DELETE/v1/articles/:id

Artikel entstehen immer als Entwurf — das Veröffentlichen ist ein eigener PATCH, damit nichts versehentlich in Ihrem Portal landet. Das Anlegen erfordert Schreibzugriff eines Bezahltarifs, ebenso jede andere schreibende Methode hier.

Artikel auflisten


curl "https://api.supdesk.app/v1/articles?status=published&limit=10" \
  -H "Authorization: Bearer sd_live_..."


{
  "data": [
    {
      "id": "8f7a...",
      "title": "Wie setze ich mein Passwort zurück?",
      "slug": "wie-setze-ich-mein-passwort-zurueck",
      "body": "Öffnen Sie **Einstellungen** und wählen Sie *Passwort zurücksetzen*.",
      "excerpt": "Öffnen Sie Einstellungen und wählen Sie Passwort zurücksetzen.",
      "status": "published",
      "category_id": "3c2b...",
      "published_at": "2026-07-01T09:12:00Z",
      "helpful_count": 12,
      "not_helpful_count": 1,
      "created_at": "2026-06-28T14:03:00Z",
      "updated_at": "2026-07-01T09:12:00Z"
    }
  ],
  "pagination": { "limit": 10, "offset": 0, "has_more": false }
}

Ohne Filter kommen auch Entwürfe und archivierte Artikel zurück, zuletzt bearbeitete zuerst. status=published liefert das, was Kunden tatsächlich sehen.

Artikel durchsuchen


curl "https://api.supdesk.app/v1/articles/search?q=passwort+zurücksetzen&limit=5" \
  -H "Authorization: Bearer sd_live_..."


{
  "data": [
    {
      "id": "8f7a...",
      "title": "Wie setze ich mein Passwort zurück?",
      "slug": "wie-setze-ich-mein-passwort-zurueck",
      "category_slug": "erste-schritte",
      "category_name": "Erste Schritte",
      "snippet": "Öffnen Sie Einstellungen und wählen Sie Passwort zurücksetzen.",
      "rank": 0.6079
    }
  ]
}

Volltextsuche ausschließlich über veröffentlichte Artikel, nach Relevanz sortiert, mit einem Textauszug rund um den Treffer. Titel wiegen schwerer als Zusammenfassungen, Zusammenfassungen schwerer als Inhalte. Eine leere oder nicht auswertbare Anfrage liefert eine leere Liste statt eines Fehlers.

Einen Artikel abrufen


curl "https://api.supdesk.app/v1/articles/8f7a..." \
  -H "Authorization: Bearer sd_live_..."

Liefert einen einzelnen Artikel in derselben Form wie die Liste — oder 404, wenn die ID in Ihrem Projekt unbekannt ist.

Einen Artikel anlegen


curl -X POST https://api.supdesk.app/v1/articles \
  -H "Authorization: Bearer sd_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Wie setze ich mein Passwort zurück?",
    "body": "Öffnen Sie **Einstellungen** und wählen Sie *Passwort zurücksetzen*.",
    "category_id": "3c2b..."
  }'


{
  "data": {
    "id": "8f7a...",
    "title": "Wie setze ich mein Passwort zurück?",
    "slug": "wie-setze-ich-mein-passwort-zurueck",
    "body": "Öffnen Sie **Einstellungen** und wählen Sie *Passwort zurücksetzen*.",
    "excerpt": "Öffnen Sie Einstellungen und wählen Sie Passwort zurücksetzen.",
    "status": "draft",
    "category_id": "3c2b...",
    "published_at": null,
    "helpful_count": 0,
    "not_helpful_count": 0,
    "created_at": "2026-07-01T09:12:00Z",
    "updated_at": "2026-07-01T09:12:00Z"
  }
}

Liefert 201. Ohne slug wird einer aus dem Titel gebildet, mit Suffix -2, -3… falls die Adresse belegt ist. Ohne excerpt wird eine Zusammenfassung aus dem Inhalt erzeugt.

Ihr Tarif begrenzt, wie viele Artikel ein Projekt führen kann — Free 5, Pro 50, Team unbegrenzt. Darüber hinaus kommt limit_reached (429) zurück. Archivierte Artikel zählen nicht mit; Archivieren gibt also einen Platz frei.

Einen Artikel aktualisieren


curl -X PATCH https://api.supdesk.app/v1/articles/8f7a... \
  -H "Authorization: Bearer sd_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "published" }'

Geschrieben werden nur die gesendeten Felder; ein PATCH leert also nie etwas, das Sie weggelassen haben. Wird status auf published gesetzt, wird published_at beim ersten Mal gestempelt und danach beibehalten — ein korrigierter Tippfehler lässt einen alten Artikel nicht neu aussehen. archived nimmt den Artikel aus dem Portal, ohne ihn zu löschen.

Beim Wiederherstellen aus dem Archiv wird das Tariflimit erneut geprüft; auch das kann limit_reached liefern.

Einen Artikel löschen


curl -X DELETE https://api.supdesk.app/v1/articles/8f7a... \
  -H "Authorization: Bearer sd_live_..."

Löscht den Artikel und sein Leser-Feedback dauerhaft und liefert 204. Wenn Sie einen Artikel nur aus dem Portal nehmen wollen, setzen Sie stattdessen den Status auf archived.

Kategorien

GET/v1/article-categories

Parameter	Type	Description
`limit`	`integer`	Seitengröße. Standard 25, max. 100.
`offset`	`integer`	Zu überspringende Einträge. Standard 0.

GET/v1/article-categories/:id

POST/v1/article-categories

Parameter	Type	Description
`name`required	`string`	Bis zu 80 Zeichen.
`description`	`string`	Im Portal angezeigt, bis 300 Zeichen.
`sort_order`	`integer`	Anzeigeposition. Standard 0.

PATCH/v1/article-categories/:id

Parameter	Type	Description
`name`	`string`	Neuer Name.
`description`	`string`	Neue Beschreibung; null löscht sie.
`sort_order`	`integer`	Neue Anzeigeposition.

DELETE/v1/article-categories/:id


curl -X POST https://api.supdesk.app/v1/article-categories \
  -H "Authorization: Bearer sd_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Erste Schritte", "sort_order": 1 }'


{
  "data": {
    "id": "3c2b...",
    "name": "Erste Schritte",
    "slug": "erste-schritte",
    "description": null,
    "sort_order": 1,
    "created_at": "2026-07-01T09:12:00Z"
  }
}

Kategorien werden nach sort_order, dann nach Namen ausgegeben. Slugs entstehen aus dem Namen genauso wie Artikel-Slugs aus dem Titel.

Eine Kategorie zu löschen liefert 204 und löscht nicht ihre Artikel — diese verlieren nur ihre Zuordnung und bleiben über die Suche und die Startseite des Hilfe-Centers erreichbar.

Fehler

Zusätzlich zu den Standardcodes:

Code	Status	Wann
`not_found`	404	Unbekannte ID — oder das Hilfe-Center ist für dieses Projekt abgeschaltet.
`forbidden`	403	Schreibzugriff in einem Tarif ohne API-Schreibrechte.
`limit_reached`	429	Das Artikel-Kontingent des Tarifs ist aufgebraucht.