Menu

API Übersicht

hermine.ai API: Ihr Schlüssel zur KI-Automatisierung

Die hermine.ai-Plattform bietet im Frontend eine Vielzahl von Funktionen, von Agenten-Workflows über Wissensdatenbanken bis zu Website-Chatbots. Mit der REST-API öffnen Sie diese Features für Ihre eigenen Systeme: CRM, ERP, Data Warehouse, Low-Code-Tools oder klassische Backend-Services. So orchestrieren Sie KI-gestützte Prozesse genau dort, wo sie den größten Mehrwert liefern.

Warum die API nutzen?

Vorteil Kurz erklärt
End-to-End-Automatisierung Verbinden Sie Dokumentanalyse, Agenten-Logik und generative Ausgabe in einem durchgängigen Flow.
Flexible Trigger & Callbacks Starten Sie KI-Jobs per Cron, Event oder User-Aktion und erhalten Sie Ergebnisse per Callback, sobald sie fertig sind.
Skalierbar & fair limitiert Rate-Limiting von 1000 Requests pro Minute und IP sorgt für verlässliche Abläufe.
Voller Funktionszugriff Agenten-Runs, Conversations, Deep Research, Uploads und Suche stehen auch per API bereit.
Pay-as-you-go Identisches Abrechnungsmodell wie im Frontend: Token-Kosten plus Tool-Kosten, transparent im usage-Objekt.

Die drei API-Bereiche im Überblick

API Zweck Authentifizierung
API v1 (Integrations-API) Agenten-Runs (Building-Block-Requests), Conversations und Messages, Datenquellen, Suche, Tags Header X-API-Key mit dem Account-API-Key
API v2 (Mobile/App-API) Chat-Client-Funktionen: Auth, Conversations, Messages, Deep Research, Uploads, Transkriptionen, Agenten, Suche, Theme JWT: Authorization: Bearer <token>, Access-Token 15 Minuten, Refresh-Token
Usage-Export-API Verbrauchs- und Abrechnungsdaten für Buchhaltungssysteme, OpenAPI-Spezifikation verfügbar Dedizierter API-Token (Scopes account/all_accounts, Gültigkeit 1 Jahr)

Der API-Zugang ist in allen aktuellen Lizenzen enthalten.

Typische Einsatzszenarien

  • Lead-Enrichment: Ein neuer Kontakt kommt ins CRM, die API ruft einen Recherche-Agenten auf, Felder wie Branche und Website werden automatisch gefüllt.
  • Automatisierte Reports: Die Data-Pipeline schließt einen ETL-Batch ab, die API triggert einen Agenten, das Ergebnis landet per Callback im BI-Ordner.
  • Conversational Support: Ihr Chat-Frontend sendet Nachrichten an die Conversation-Endpoints, hermine.ai verarbeitet sie mit Wissensdatenbank und Tools und liefert die fertige Antwort zurück.
  • Quality-Gate in der Content-Pipeline: Ein CMS-Hook löst vor Publikation eine Fakten- und Stilprüfung aus, die API liefert OK oder Korrekturvorschläge.

Grundprinzipien

  1. Authentifizierung: API v1 nutzt den Account-API-Key im Header X-API-Key. API v2 arbeitet mit JWT-Bearer-Tokens (Access-Token 15 Minuten gültig, Erneuerung über den Refresh-Flow).
  2. Ressourcen-First-Design: Die zentralen Ressourcen sind Conversations, Messages, Building-Block-Requests, Datasources und Agents.
  3. Asynchrone Callbacks: An Building-Block-Requests und Messages können Sie eine response_callback_url und eine logger_callback_url übergeben. Der Response-Callback liefert status, response, usage und error_log, Ihr App-Thread muss also nicht blockieren.
  4. Usage-Objekt: Jeder Callback enthält den Tokenverbrauch und die Tool-Kosten der Anfrage, ideal für Ihr Kosten-Controlling.
  5. Einheitliches v2-Response-Format: Antworten folgen dem Schema status/data/meta mit Cursor-Pagination. Fehler kommen mit sprechenden Codes (z. B. TOKEN_EXPIRED, VALIDATION_ERROR, NOT_FOUND) und einer documentation_url.

API v2 Endpunkt-Referenz (Kurzliste)

  • Auth: POST /api/v2/auth/sign_in, POST /api/v2/auth/oauth/exchange, POST /api/v2/auth/refresh, DELETE /api/v2/auth/sign_out, GET /api/v2/auth/me, POST /api/v2/auth/consent
  • Conversations: GET/POST/PATCH/DELETE /api/v2/conversations, dazu POST .../mark_read, GET .../llm_models, POST .../stop, POST/DELETE .../share
  • Messages: GET/POST /api/v2/conversations/:id/messages, POST .../regenerate, POST .../feedback; Deep Research: POST .../research/confirm, POST .../research/cancel, POST .../research/refine, PUT .../research/plan
  • Uploads & Transkriptionen: POST /api/v2/conversations/:id/uploads, POST/GET /api/v2/conversations/:id/transcriptions
  • Agenten: GET /api/v2/agents, GET /api/v2/agents/:id, GET .../tools, GET .../conversations
  • Suche, Theme, Deep Research: GET /api/v2/search, GET /api/v2/theme, GET /api/v2/deep_research/quota

Zugriff erhalten (Schritt für Schritt)

  1. Kontakt aufnehmen: Schreiben Sie an hello@hermine.ai mit Ihrem Anwendungsfall und der gewünschten Umgebung (Test/Produktion). Wir schalten den Zugang frei und stellen die Endpunkt-Dokumentation bereit.

  2. API-Key verwalten: Ihren Account-API-Key sehen Sie auf der Seite API Zugriff unter Ihr API-Key. Bei Bedarf erzeugen Sie über Neuen API-Key Erstellen und alten verwerfen einen neuen Key; der alte wird sofort ungültig.

  3. Ersten Call testen: Prüfen Sie die Verbindung mit einem einfachen Request, zum Beispiel:

    curl https://app.hermine.ai/api/v1/tags \
  -H "X-API-Key: IHR_API_KEY" \
  -H "Content-Type: application/json"

  4. Callbacks und Monitoring einrichten: Hinterlegen Sie Ihre Callback-URLs, überwachen Sie Fehler und Kosten, dann Go-Live.

Abrechnung

Die API rechnet identisch zum Frontend ab: Token-Kosten plus Tool-Kosten, transparent im usage-Objekt jedes Callbacks. Auch das monatliche Kostenlimit und die Budgets pro Nutzer:in gelten für API-Nutzung, Details unter Abrechnung. Für den maschinellen Export der Verbrauchsdaten gibt es die Usage-Export-API.

Tipp: Starten Sie mit einem einzelnen, klar umrissenen Workflow (z. B. einem Agenten-Run per Building-Block-Request mit Callback). Sobald der läuft, lassen sich weitere Prozesse nach demselben Muster in wenigen Stunden anbinden.

War diese Seite hilfreich?