api - OperoGuide - Plattform

API Reference – OperoGuide

REST API v1 · Version 2.4.1

API Reference

Integrieren Sie OperoGuide's KI-gestützte Dokumentationssuche in Ihre Anwendungen

Einführung

Die OperoGuide API ermöglicht es Ihnen, KI-gestützte Dokumentationssuche in Ihre eigenen Anwendungen, Workflows und Tools zu integrieren. Nutzen Sie sie, um Ihre Dokumenten-Collections programmatisch abzufragen und intelligente, kontextbezogene Antworten zu erhalten.

Die API folgt REST-Konventionen und verwendet JSON für Request- und Response-Bodies. Alle Endpoints werden über HTTPS bereitgestellt.

Base URL

Alle API-Requests sollten an folgende URL gesendet werden: https://app.operoguide.ai/wp-json/ogss/v1

Authentifizierung

Die OperoGuide API verwendet Bearer Token zur Authentifizierung. Fügen Sie Ihren Token in den Authorization-Header aller Requests ein.

HTTP Header

Authorization: Bearer YOUR_API_TOKEN

Token erhalten

Sie können einen Token auf zwei Wegen erhalten:

1. Über das Portal:

Melden Sie sich im OperoGuide Portal an
Gehen Sie zu Einstellungen → API
Klicken Sie auf Token anzeigen

2. Über die Login-API:

cURL

curl -X POST https://app.operoguide.ai/wp-json/ogss/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ihre@email.de",
    "password": "IhrPasswort"
  }'

Token sicher aufbewahren

Geben Sie Ihren Token niemals in clientseitigem Code oder öffentlichen Repositories preis. Nutzen Sie Umgebungsvariablen.

Schnellstart

Machen Sie Ihren ersten API-Call. Hier ein einfaches Beispiel zur Abfrage Ihrer Dokumentation:

cURL - Chat Query

curl -X POST https://app.operoguide.ai/wp-json/ogss/v1/chat \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Wie erstelle ich eine Bestellung in P4210?",
    "conversation_history": []
  }'

Response

{
  "success": true,
  "answer": "Um eine Bestellung in P4210 zu erstellen:\n\n1. Öffnen Sie das Programm P4210 (Sales Order Entry)\n2. Klicken Sie auf 'Hinzufügen'...",
  "sources": [
    {
      "document_id": 123,
      "filename": "JDE_Sales_Order_Guide.pdf",
      "page": 24,
      "relevance": 0.94
    }
  ],
  "session_id": "sess_abc123"
}

Rate Limits

API Rate Limits basieren auf Ihrem Abonnement-Plan:

Plan	Requests/Minute	Queries/Monat
Free	30	100
Professional	60	1.000
Business	120	5.000
Enterprise	300	Unbegrenzt

Bei Überschreitung erhalten Sie HTTP 429:

Rate Limit Error

{
  "code": "rate_limit_exceeded",
  "message": "Rate limit überschritten. Bitte warten Sie.",
  "data": { "status": 429, "retry_after": 60 }
}

Fehlerbehandlung

Die API verwendet Standard-HTTP-Statuscodes:

200Erfolg

400Ungültige Anfrage - Fehlende/falsche Parameter

401Nicht autorisiert - Token ungültig/fehlt

403Verboten - Keine Berechtigung

429Zu viele Anfragen - Rate Limit

500Serverfehler

Authentifizierung Endpoints

POST /auth/register

Neuen Benutzer registrieren.

Parameter	Beschreibung
emailstringrequired	E-Mail-Adresse
passwordstringrequired	Passwort (min. 8 Zeichen)
display_namestringoptional	Anzeigename
referral_codestringoptional	Empfehlungscode

POST /auth/login

Benutzer anmelden und Token erhalten.

Parameter	Beschreibung
emailstringrequired	E-Mail-Adresse
passwordstringrequired	Passwort

2FA

Falls 2FA aktiviert ist, erhalten Sie requires_2fa: true und einen temp_token. Verifizieren Sie dann mit /2fa/verify.

POST /auth/logout

Session beenden. Auth erforderlich.

POST /auth/forgot-password

Passwort-Reset E-Mail anfordern.

Parameter	Beschreibung
emailstringrequired	E-Mail-Adresse

POST /auth/reset-password

Neues Passwort mit Reset-Token setzen.

Parameter	Beschreibung
tokenstringrequired	Reset-Token aus E-Mail
passwordstringrequired	Neues Passwort

POST /auth/verify-email

E-Mail-Adresse bestätigen.

Parameter	Beschreibung
tokenstringrequired	Verifizierungs-Token aus E-Mail

User Endpoints

GET /user/profile

Eigenes Benutzerprofil abrufen. Auth erforderlich.

Response

{
  "id": 42,
  "email": "user@example.de",
  "display_name": "Max Mustermann",
  "plan": "professional",
  "queries_used": 150,
  "queries_limit": 1000,
  "documents_count": 12,
  "storage_used": 52428800,
  "two_factor_enabled": true,
  "organization_id": null
}

PUT /user/profile

Profil aktualisieren. Auth erforderlich.

Parameter	Beschreibung
display_namestringoptional	Neuer Anzeigename
current_passwordstringoptional	Aktuelles Passwort (für Passwortänderung)
new_passwordstringoptional	Neues Passwort

GET /user/stats

Nutzungsstatistiken abrufen. Auth erforderlich.

GET /user/api-key

API-Key Status und Ablaufdatum prüfen. Auth erforderlich.

Response

{
  "has_key": true,
  "expires_at": "2026-06-15 10:30:00",
  "days_remaining": 180,
  "status": "active"  // active, expiring, expiring_soon, expired
}

POST /user/api-key/renew

API-Key erneuern. Auth erforderlich.

Parameter	Beschreibung
validity_daysintegeroptional	Gültigkeit: 30, 90, 180, 365, 730 (default: 365)

Achtung

Der alte Token wird sofort ungültig!

Document Endpoints

GET /documents

Alle Dokumente auflisten. Auth erforderlich.

Query Parameter	Beschreibung
pageint	Seite (default: 1)
per_pageint	Pro Seite (default: 20, max: 100)
statusstring	Filter: pending, processing, completed, failed
typestring	Filter: pdf, docx, xlsx

POST /documents/upload

Dokument hochladen. Auth erforderlich. Content-Type: multipart/form-data

Form Data	Beschreibung
filefilerequired	PDF (max 50MB), DOCX (max 20MB), XLSX (max 10MB)
titlestringoptional	Dokumenttitel

cURL Example

curl -X POST https://app.operoguide.ai/wp-json/ogss/v1/documents/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@/path/to/document.pdf" \
  -F "title=JDE Handbuch"

GET /documents/{id}

Dokument-Details abrufen. Auth erforderlich.

DELETE /documents/{id}

Dokument löschen. Auth erforderlich. Diese Aktion ist nicht rückgängig zu machen!

POST /documents/export

Alle Dokumente als ZIP exportieren. Auth erforderlich.

Parameter	Beschreibung
include_filesbooleanoptional	Original-Dateien einschließen (default: true)

Chat Endpoints

POST /chat

Frage an die KI stellen. Auth erforderlich.

Parameter	Beschreibung
messagestringrequired	Die Frage (max 2000 Zeichen)
conversation_historyarrayoptional	Vorherige Nachrichten für Kontext

Response

{
  "success": true,
  "answer": "Die Antwort auf Ihre Frage...",
  "sources": [
    {
      "document_id": 123,
      "filename": "guide.pdf",
      "chunk_content": "Relevanter Abschnitt...",
      "relevance": 0.94
    }
  ],
  "session_id": "sess_abc123"
}

POST /chat/stream

Streaming Chat mit Server-Sent Events. Auth erforderlich.

Gleiche Parameter wie /chat. Die Antwort wird als SSE-Stream gesendet:

SSE Stream Events

event: token
data: {"token": "Die "}

event: token
data: {"token": "Antwort "}

event: token
data: {"token": "lautet..."}

event: sources
data: {"sources": [...]}

event: done
data: {"session_id": "sess_abc123"}

Organization Endpoints

Organisation-Endpoints ermöglichen B2B-Funktionen wie Team-Verwaltung und gemeinsame Dokumentennutzung.

POST /org/create

Neue Organisation erstellen. Auth erforderlich.

Parameter	Beschreibung
namestringrequired	Organisationsname
domainstringoptional	E-Mail-Domain für Auto-Join

GET /org

Eigene Organisation abrufen. Auth erforderlich.

PUT /org

Organisation aktualisieren. Auth erforderlich. Admin-Rolle.

GET /org/members

Mitgliederliste abrufen. Auth erforderlich.

POST /org/invite

Neues Mitglied einladen. Auth erforderlich. Admin-Rolle.

Parameter	Beschreibung
emailstringrequired	E-Mail des einzuladenden Users
rolestringoptional	Rolle: admin, member (default: member)

POST /org/invite/accept

Einladung annehmen.

Parameter	Beschreibung
tokenstringrequired	Einladungs-Token aus E-Mail

DELETE /org/members/{user_id}

Mitglied entfernen. Auth erforderlich. Admin-Rolle.

PUT /org/members/{user_id}/role

Mitglieder-Rolle ändern. Auth erforderlich. Admin-Rolle.

Parameter	Beschreibung
rolestringrequired	Neue Rolle: admin, member

GET /org/stats

Organisations-Statistiken abrufen. Auth erforderlich.

2FA Endpoints

GET /2fa/status

2FA-Status prüfen. Auth erforderlich.

POST /2fa/setup

2FA einrichten - QR-Code und Secret generieren. Auth erforderlich.

POST /2fa/enable

2FA aktivieren. Auth erforderlich.

Parameter	Beschreibung
codestringrequired	6-stelliger TOTP-Code

POST /2fa/verify

2FA-Code bei Login verifizieren. Temp-Token erforderlich.

Parameter	Beschreibung
codestringrequired	6-stelliger TOTP-Code oder Backup-Code

POST /2fa/disable

2FA deaktivieren. Auth erforderlich.

Parameter	Beschreibung
codestringrequired	6-stelliger TOTP-Code
passwordstringrequired	Aktuelles Passwort

POST /2fa/backup-codes

Neue Backup-Codes generieren. Auth erforderlich.

Billing Endpoints

GET /billing/plans

Verfügbare Pläne abrufen. Öffentlich.

POST /billing/checkout

Stripe Checkout Session erstellen. Auth erforderlich.

Parameter	Beschreibung
planstringrequired	Plan: professional, business, enterprise
billing_cyclestringoptional	monthly oder yearly (default: monthly)

POST /billing/portal

Stripe Billing Portal URL erhalten. Auth erforderlich.

GET /billing/invoices

Rechnungen abrufen. Auth erforderlich.

DELETE /billing/subscription

Abo kündigen. Auth erforderlich.

Support Ticket Endpoints

GET /tickets

Eigene Tickets auflisten. Auth erforderlich.

POST /tickets

Neues Ticket erstellen. Auth erforderlich.

Parameter	Beschreibung
subjectstringrequired	Betreff
messagestringrequired	Nachricht
prioritystringoptional	low, normal, high, urgent (default: normal)

GET /tickets/{id}

Ticket-Details mit Verlauf. Auth erforderlich.

POST /tickets/{id}/reply

Auf Ticket antworten. Auth erforderlich.

Parameter	Beschreibung
messagestringrequired	Antwort-Nachricht

Weitere Endpoints

GET /health

API Health Check. Öffentlich.

POST /trial/start

Trial-Periode starten. Auth erforderlich.

GET /trial/status

Trial-Status prüfen. Auth erforderlich.

POST /extension/generate

Browser-Extension mit eigenem API-Key generieren. Auth erforderlich.

GET /referral/stats

Empfehlungs-Statistiken. Auth erforderlich.

api

API Reference

Einführung

Authentifizierung

Token erhalten

Schnellstart

Rate Limits

Fehlerbehandlung

Authentifizierung Endpoints

User Endpoints

Document Endpoints

Chat Endpoints

Organization Endpoints

2FA Endpoints

Billing Endpoints

Support Ticket Endpoints

GDPR Endpoints

Weitere Endpoints