API-Referenz

Voraussetzungen

• Plan: Business oder Enterprise. Andere Pläne erhalten bei API-Key-Aufrufen 402 plan required.
• Shop-Status: Dein Shop muss active sein. Inaktive Shops erhalten 403 shop_inactive.
• API-Key: Wird im Dashboard erzeugt (siehe unten). Der vollständige Key ist nur einmal – direkt beim Erstellen – sichtbar.
• Feature-Gates: Einzelne Endpunkte benötigen zusätzlich ein Feature deines Plans (z. B. inbox, tickets, contacts_basic). Fehlt das Feature, antwortet der Server mit 402.

API in 4 Schritten anbinden

1. Key erstellen: im Dashboard unter /dashboard/api-keys.
2. Key serverseitig speichern: z. B. als Umgebungsvariable – niemals im Browser-Frontend.
3. Request authentifizieren: per Authorization: Bearer <key> (empfohlen) oder X-API-Key: <key>.
4. Mit Test-Call prüfen: zuerst GET /api/me, danach die fachlichen Endpunkte.

Authentifizierung

Jeder API-Aufruf wird über einen Shop-API-Key authentifiziert. Der Server liest den Key aus einem von zwei Headern – zuerst wird der Authorization-Header geprüft, danach X-API-Key:

• Authorization: Bearer <key>  (empfohlen)
• X-API-Key: <key>

API-Keys haben das Präfix sb_live_. Die Basis-URL deiner Integration ist https://docs.alpheris.com. Alternativ kann derselbe Endpunkt auch über eine angemeldete Dashboard-Session aufgerufen werden (Cookie statt Key) – für externe Integrationen ist jedoch ausschließlich der API-Key vorgesehen.

# Key serverseitig als Umgebungsvariable ablegen
export ALPHERIS_API_KEY="sb_live_xxxxxxxxxxxxxxxxxxxxxxxx"
export ALPHERIS_BASE_URL="https://docs.alpheris.com"

# Authentifizierter Test-Call (empfohlener Header)
curl -sS "$ALPHERIS_BASE_URL/api/me" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY"

# Alternativ mit X-API-Key
curl -sS "$ALPHERIS_BASE_URL/api/me" \
  -H "X-API-Key: $ALPHERIS_API_KEY"

import os, requests

base_url = "https://docs.alpheris.com"
api_key = os.environ["ALPHERIS_API_KEY"]  # sb_live_...

r = requests.get(
    f"{base_url}/api/me",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=20,
)
print(r.status_code, r.json())

Beispiel-Antwort: GET /api/me

Bestätigt Authentifizierung, Shop, Plan und den genutzten Auth-Modus (api_key oder session).

{
  "user_id": 0,
  "email": "api@integration",
  "shop_id": 42,
  "shop_name": "Mein Shop",
  "plan": "business",
  "role": "integration",
  "auth_mode": "api_key",
  "acl": { }
}

API-Keys verwalten

API-Keys werden im Dashboard unter Dashboard → API Keys (/dashboard/api-keys) verwaltet. Die Verwaltung selbst ist nur über eine angemeldete Dashboard-Session und mit Manager-/Owner-Rolle möglich – nicht über einen API-Key. Voraussetzung ist ein aktiver Shop im Business- oder Enterprise-Plan.

Hinweis: Die obigen Verwaltungs-Endpunkte erwarten eine Dashboard-Session (Cookie) und sind nicht per API-Key aufrufbar. In der Praxis genügt die Verwaltung über die Dashboard-Seite /dashboard/api-keys.

Rechte (Scopes) je API-Key

Beim Erstellen eines Keys wählst du Vollzugriff (alles, was ein API-Key kann – so verhalten sich auch alle Keys, die vor dem 27.10.2026 erstellt wurden) oder nur ausgewählte Rechte. Ein eingeschränkter Key erreicht nur die Endpunkte seiner Rechte; alles andere beantwortet die API mit 403 und {"detail": {"error": "missing_scope", "scope": "…", "message": "…"}}.

Alle Endpunkte gelten auch unter /api/v1/…. GET /api/me geht mit jedem gültigen Key. Löschen in der Inbox (Papierkorb, Kundendaten löschen), Chatbot-Einstellungen und Shopify-/Zendesk-Abgleiche gehen nur mit Vollzugriff. Rechte lassen sich nicht nachträglich ändern: neuen Key mit passenden Rechten erstellen, alten widerrufen. Über die Session-Verwaltung geht das mit POST /api/inbox/integration-keys und {"label": "Wissen-Sync", "scopes": ["wissen:write"]} (ohne scopes = Vollzugriff).

Chat-API (KI-Antworten)

Mit der Chat-API bindest du den Paldra-Chatbot direkt in deine eigene Website, App oder dein Backend ein – ohne unser JS-Widget. Du sendest eine Nachricht, Paldra antwortet mit einer auf deine echten Shop-Daten gegroundeten Antwort (kein Halluzinieren) plus den verwendeten Quellen. Basis-URL: $ALPHERIS_BASE_URL/v1/…. Verfügbar in Enterprise oder in Business mit dem Branding-Add-on – sonst antwortet die Chat-API mit 402 plan_required. Der Export unten geht ab Business.

POST /v1/chat

Eine Nachricht rein – eine vollständige Antwort raus. Der Shop-Bezug kommt aus dem Key (keine shop_id mitsenden). conversation_id weglassen startet eine neue Konversation; denselben Wert erneut senden führt den Gesprächsfaden fort.

curl -sS -X POST "$ALPHERIS_BASE_URL/v1/chat" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Wie lange dauert der Versand nach Österreich?" }'

{
  "reply": "Der Versand nach Österreich dauert in der Regel 2-4 Werktage.",
  "conversation_id": "conv_ab12...",
  "message_id": "msg_00987",
  "sources": [
    { "url": "https://deinshop.de/faq/versand", "title": "Versand & Lieferzeiten", "snippet": "Lieferung nach AT: 2-4 Werktage ...", "type": "faq" }
  ],
  "confidence": 0.82,
  "plan": "business"
}

const res = await fetch(`${process.env.ALPHERIS_BASE_URL}/v1/chat`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.ALPHERIS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ message: "Habt ihr das in Größe M?" }),
});
const data = await res.json();
console.log(data.reply, data.sources);

POST /v1/chat/stream

Wie /v1/chat, aber als Server-Sent-Events (SSE): die Antwort kommt Token für Token für ein Live-Tipp-Gefühl. Jede Zeile ist ein data: {…}-Frame – Token-Frames tragen {"t":"…"}, der Abschluss-Frame {"done":true, …} enthält die volle Antwort inkl. Quellen.

curl -sS -N -X POST "$ALPHERIS_BASE_URL/v1/chat/stream" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Seid ihr gerade erreichbar?" }'

# data: {"t": "Hey! Ja, "}
# data: {"t": "wir sind hier ..."}
# data: {"done": true, "reply": "...", "conversation_id": "...", "sources": [...]}

Daten-Export (auf ein anderes System übertragen)

Zieh deine Daten programmatisch aus Paldra – für eine einmalige Migration oder laufenden Sync in dein CRM/Helpdesk. Blätterbar per Cursor (keine 500er-Grenze), sodass auch die komplette Historie erreichbar ist. Business/Enterprise.

GET /v1/export/{entity}

{entity} ist eines von contacts, tickets, conversations, messages, leads. Query-Parameter: limit (1–1000, Standard 200), cursor (die next_cursor der vorigen Seite), bei messages zusätzlich optional thread_id.

curl -sS "$ALPHERIS_BASE_URL/v1/export/contacts?limit=200" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY"

{
  "entity": "contacts",
  "data": [
    { "id": 51, "name": "Erika Musterfrau", "email": "[email protected]", "phone": "", "company": "", "tags": [], "created_at": 1718700000 }
  ],
  "count": 1,
  "next_cursor": 51,
  "has_more": false
}

Paginierung: Solange has_more: true ist, den nächsten Aufruf mit ?cursor=<next_cursor> wiederholen, bis next_cursor: null zurückkommt.

// Alle Kontakte seitenweise abrufen
let cursor = 0, all = [];
while (true) {
  const r = await fetch(`${process.env.ALPHERIS_BASE_URL}/v1/export/contacts?limit=500&cursor=${cursor}`, {
    headers: { "Authorization": `Bearer ${process.env.ALPHERIS_API_KEY}` },
  });
  const page = await r.json();
  all.push(...page.data);
  if (!page.has_more) break;
  cursor = page.next_cursor;
}

Aktionen (eigene Systeme anbinden)

Legt Eigene Aktionen an, die der Chatbot im Gespräch aufruft – wie im Dashboard unter Integrationen, nur per Schlüssel. Ab Business (bis zu 3 Aktionen und MCP-Werkzeuge zusammen), Enterprise bis 10. Wie dein System die Aufrufe prüft, steht unter Eigene Systeme: Für Entwickler.

GET /v1/aktionen

Alle aktiven Aktionen: domain, name, beschreibung, url, methode, parameter, antwort_felder, stufe.

POST /v1/aktionen

Anlegen oder ändern (gleicher Name = gleiche Aktion). Felder: name, beschreibung (wann der Chatbot sie benutzt), url (https), methode (GET|POST), optional kopf_name/kopf_wert, parameter (bis 8: name, beschreibung, pflicht, typ = text|zahl|ganzzahl|janein|auswahl|datum|email, bei auswahl werte), antwort_felder, stufe (ki|kunde|entwurf|mitarbeiter, nur POST). Antwort: {"ok": true, "domain": "…", "stufe": "…", "geheimnis": "…"} – geheimnis nur beim ersten Anlegen.

curl -X POST "$ALPHERIS_BASE_URL/v1/aktionen" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Businessplan erstellen", "beschreibung": "Wenn ein Kunde einen Businessplan möchte",
       "url": "https://dein-system.de/alpheris/businessplan", "methode": "POST", "stufe": "kunde",
       "parameter": [{"name": "Branche", "typ": "auswahl", "werte": ["Café", "Handwerk"], "pflicht": true},
                     {"name": "Budget", "typ": "zahl"}],
       "antwort_felder": ["status", "plan.titel"]}'

DELETE /v1/aktionen/{domain}

Trennt die Aktion.

Wissen (eigene Inhalte in die Wissensbasis schreiben)

Dein System schreibt Inhalte direkt in die Wissensbasis – FAQ, Produktdaten, Bedingungen, Doku. Jeder Eintrag hat deine eigene kennung: derselbe Aufruf ersetzt ihn, nichts wird doppelt. Lange Inhalte (bis 50.000 Zeichen) teilt Paldra in Abschnitte; der Chatbot und der Mail-Agent finden sie wie manuelle Einträge. Business/Enterprise.

POST /v1/wissen

Felder: kennung (Pflicht, A–Z a–z 0–9 _ . : -, bis 80 Zeichen), titel, inhalt, optional art (faq|page|product|manual), sprache (de|en|fr|it|es|nl), url. Antwort: {"ok": true, "kennung": "…", "abschnitte": 1}. Bis 5.000 Einträge je Shop.

curl -X POST "$ALPHERIS_BASE_URL/v1/wissen" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY" -H "Content-Type: application/json" \
  -d '{"kennung": "faq-lieferzeit", "titel": "Wie lange dauert die Lieferung?",
       "inhalt": "Innerhalb Deutschlands 1–3 Werktage, nach Österreich und in die Schweiz 3–6 Werktage.",
       "art": "faq", "sprache": "de", "url": "https://deinshop.de/versand"}'

GET /v1/wissen

Alle per API geschriebenen Einträge: kennung, titel, art, sprache, url, aktualisiert, abschnitte.

DELETE /v1/wissen/{kennung}

Löscht den Eintrag mit allen Abschnitten.

Auslöser für Zapier, Make und n8n (REST-Hooks)

Automatisierungen melden ihre Empfangsadresse selbst an, wenn ein Zap bzw. Szenario eingeschaltet wird, und wieder ab, wenn es aus ist. Zugestellt und signiert wird wie bei jedem Webhook (Abschnitt Webhooks). Ereignisse: lead.created, ticket.created, ticket.closed, conversation.created, conversation.handoff_requested, conversation.closed, message.received. Höchstens 10 Webhooks je Shop (zusammen mit denen aus dem Dashboard). Business/Enterprise.

POST /v1/hooks

url (öffentliches https) und events (Liste) bzw. event. Antwort: id, events, secret (für die Signaturprüfung, nur hier).

DELETE /v1/hooks/{id}

GET /v1/hooks/beispiel/{event}

Ein Beispiel-Ereignis in der Form der Zustellung – für Testdaten beim Einrichten.

curl -X POST "$ALPHERIS_BASE_URL/v1/hooks" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.zapier.com/hooks/standard/123/abc", "events": ["lead.created"]}'
# -> {"id": 17, "events": ["lead.created"], "secret": "whsec_…"}
curl -X DELETE "$ALPHERIS_BASE_URL/v1/hooks/17" -H "Authorization: Bearer $ALPHERIS_API_KEY"

Endpunkt-Referenz

Die folgenden Endpunkte sind per API-Key erreichbar. Alle erwarten den Authentifizierungs-Header (Authorization: Bearer oder X-API-Key); POST-Endpunkte mit Body erwarten zusätzlich Content-Type: application/json. Der Shop-Bezug ergibt sich automatisch aus dem Key – eine shop_id musst du nicht mitsenden.

GET /api/me

Prüft Authentifizierung und liefert Shop-, Plan- und Rollen-Kontext. Idealer erster Test-Call.

curl -sS "$ALPHERIS_BASE_URL/api/me" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY"

GET /api/inbox/tickets

Lädt die Tickets des Shops (bis zu 500, neueste zuerst). Benötigt das Feature tickets. Optionaler Query-Parameter status (z. B. open, closed, all); ein unbekannter Wert führt zu 400 invalid_status_filter.

curl -sS "$ALPHERIS_BASE_URL/api/inbox/tickets?status=open" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY"

GET /api/inbox/threads

Listet die Konversations-Threads des Shops auf (E-Mail, Chat, Social) – die zentrale Inbox-Sicht. Benötigt das Feature inbox. Threads werden mandantengetrennt nur für den eigenen Shop geliefert. Nützliche Query-Parameter: source (z. B. all, email, chat, instagram), thread_limit (10–300), message_limit (1–120) sowie fast=1 bzw. minimal=1 für schlankere Antworten.

curl -sS "$ALPHERIS_BASE_URL/api/inbox/threads?source=all&thread_limit=50" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY"

{
  "ok": true,
  "threads": [
    {
      "id": "abc123",
      "subject": "Frage zur Bestellung #1234",
      "channel": "email",
      "status": "open",
      "customer_name": "Erika Musterfrau",
      "customer_email": "[email protected]",
      "last_message": "Wann wird meine Bestellung versandt?",
      "unread_count": 1,
      "updated_at": 1718700000
    }
  ]
}

POST /api/inbox/tickets

Erstellt ein neues Ticket. Benötigt das Feature tickets. Pflichtfeld ist subject (mindestens 3 Zeichen).

curl -sS -X POST "$ALPHERIS_BASE_URL/api/inbox/tickets" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Lieferung verspätet",
    "description": "Bestellung #1234 ist noch nicht angekommen.",
    "customer_email": "[email protected]",
    "priority": "high",
    "tags": ["versand", "reklamation"]
  }'

GET /api/inbox/leads

Lädt erfasste Leads. Benötigt das Feature inbox. Optionaler Query-Parameter limit (1–500, Standard 120).

curl -sS "$ALPHERIS_BASE_URL/api/inbox/leads?limit=50" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY"

POST /api/inbox/leads

Legt einen neuen Lead an. Benötigt das Feature inbox. Wird kein source mitgegeben, setzt der Server lead_form_manual.

curl -sS -X POST "$ALPHERIS_BASE_URL/api/inbox/leads" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Erika Musterfrau",
    "email": "[email protected]",
    "source": "website_kontaktformular"
  }'

Weitere Lead-Aktionen (ebenfalls Feature inbox): POST /api/inbox/leads/{lead_id}/close, POST /api/inbox/leads/{lead_id}/reopen und POST /api/inbox/leads/{lead_id}/delete.

GET /api/inbox/customers

Lädt die Kontakte/Kunden des Shops. Benötigt das Feature contacts_basic.

curl -sS "$ALPHERIS_BASE_URL/api/inbox/customers" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY"

{
  "ok": true,
  "customers": [
    {
      "name": "Erika Musterfrau",
      "email": "[email protected]"
    }
  ]
}

POST /api/inbox/customers

Legt einen Kontakt an. Benötigt das Feature contacts_basic. Pflichtfeld ist eine gültige email; fehlt sie, antwortet der Server mit 400 email_required.

curl -sS -X POST "$ALPHERIS_BASE_URL/api/inbox/customers" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "Max Mustermann",
    "company": "Muster GmbH",
    "tags": ["b2b", "newsletter"]
  }'

POST /api/inbox/threads/{conversation_id}/reply

Sendet eine Antwort in einen bestehenden Konversations-Thread (z. B. eine E-Mail-Konversation). Für idempotentes Senden immer eine eindeutige client_msg_id mitschicken – so erzeugen Wiederholungen bei Timeouts keine Duplikate (Server-Dedup beim Re-Sync).

curl -sS -X POST "$ALPHERIS_BASE_URL/api/inbox/threads/abc123/reply" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hallo, wir melden uns direkt bei dir.",
    "client_msg_id": "reply-2026-06-18-001"
  }'

{
  "ok": true,
  "provider": "outlook",
  "conversation_id": "abc123",
  "message": {
    "id": "sent:outlook:reply-2026-06-18-001",
    "sender": "agent",
    "type": "outgoing",
    "text": "Hallo, wir melden uns direkt bei dir.",
    "client_msg_id": "reply-2026-06-18-001"
  }
}

Weitere Thread-Aktionen über API-Key: POST /api/inbox/email/new (neue E-Mail starten), POST /api/inbox/threads/{conversation_id}/assign (Thread zuweisen), POST /api/inbox/threads/{conversation_id}/reopen (geschlossenen Thread wieder öffnen) sowie Ticket-Statuswechsel: POST /api/inbox/tickets/{ticket_id}/close, .../reopen und .../reroute.

POST /api/inbox/threads/{conversation_id}/close

Schließt einen Konversations-Thread. Benötigt das Feature inbox. Über .../reopen wird er wieder geöffnet, über .../delete dauerhaft gelöscht. Alle drei Aktionen sind mandantengetrennt auf den eigenen Shop beschränkt.

# Schließen
curl -sS -X POST "$ALPHERIS_BASE_URL/api/inbox/threads/abc123/close" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY"

# Wieder öffnen
curl -sS -X POST "$ALPHERIS_BASE_URL/api/inbox/threads/abc123/reopen" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY"

# Dauerhaft löschen
curl -sS -X POST "$ALPHERIS_BASE_URL/api/inbox/threads/abc123/delete" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY"

POST /api/inbox/tickets/{ticket_id}/delete

Löscht ein Ticket samt zugehöriger Nachrichten dauerhaft. Benötigt das Feature tickets. Ist das Ticket nicht im eigenen Shop vorhanden, antwortet der Server mit 404 ticket_not_found.

curl -sS -X POST "$ALPHERIS_BASE_URL/api/inbox/tickets/42/delete" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY"

DELETE /api/inbox/customers/{customer_id}

Löscht einen Kontakt/Kunden dauerhaft. Benötigt das Feature contacts_basic. Existiert der Kontakt nicht im eigenen Shop, antwortet der Server mit 404 customer_not_found.

curl -sS -X DELETE "$ALPHERIS_BASE_URL/api/inbox/customers/7" \
  -H "Authorization: Bearer $ALPHERIS_API_KEY"

Fehlercodes

Authentifizierung und Plan-Gating folgen einem festen Schema. Fachliche Fehler werden zusätzlich mit 4xx und einem error-Feld im JSON-Body zurückgegeben.