1Basis-URL & Versionierung

Alle Public-Endpunkte liegen unter https://<instanz>/api/v1/. In der Demo: https://muster.auxdata.example/api/v1/. (AH 14.1)

Der konkrete Host hängt von deiner Instanz ab (das Handbuch nennt als Beispiel https://auxdata.ai). Gegen Swagger/Instanz prüfen. Die vollständige, aus dem Code generierte API-Referenz liegt unter https://<instanz>/swagger/index.html (BasePath /api/v1) und erlaubt direktes Ausprobieren.

2Was die API kann

Vier Aufgaben, jeweils gegen einen Agenten: Dokumente hochladen, semantische Suche, Chatbot-Anfragen und AI-Services ausführen.

3Endpunkt-Landkarte

Das Handbuch beschreibt sieben Kernrouten unter /api/v1. Die öffentliche Swagger-Datei listet zusätzlich einen Chat-Zusammenfassungs-Endpunkt. (AH 14.1, 15.8; Swagger-Abgleich 02.06.2026)

PUT …/document

PUT /agent/{agentid}/container/{containerid}/document — Datei-Upload (multipart/form-data).

PUT …/enhanced

PUT /agent/{agentid}/container/{containerid}/document/enhanced — Upload mit erweiterten Optionen (JSON + Base64).

POST Suche (alle)

POST /agent/{agentid}/document — semantische Suche über alle Container des Agenten.

POST Suche (einer)

POST /agent/{agentid}/container/{containerid}/document — Suche im angegebenen Container.

POST Chat (alle)

POST /agent/{agentid}/chat — Chat über alle Container.

POST Chat (einer)

POST /agent/{agentid}/container/{containerid}/chat — Chat mit einem Container als Wissensquelle.

POST Service

POST /agent/{agentid}/executeservice/{serviceid} — AI-Service ausführen.

POST Summarize

POST /agent/{agentid}/chat/{comUuid}/summarize — aktueller Swagger-Zusatz: Chat-Verlauf zu einem Wissensdokument zusammenfassen. Gegen die eigene Instanz prüfen.

1Pro Fähigkeit ein eigener UUID-Token

Jede Fähigkeit eines Agenten hat ihren eigenen UUID-Token plus einen „External Access“-Schalter. (AH 14.2.1)

Feldnamen/Schalter gegen Swagger/Instanz prüfen — die exakten Bezeichner können je Version abweichen. Token-Format: eine UUID (z. B. e185f043-d68c-4c51-bdf8-16cce6b49628), im Tutorial durchgehend als Platzhalter ${AUX_TOKEN}.

2Verwendung im Header

Den Token sendest du als Bearer-Token im Authorization-Header:

Authorization: Bearer ${AUX_TOKEN}

Den externen Zugriff schaltest du im Agenten frei (C1 Stufe 6 „Externer Zugriff“); auf Org-Ebene/Konnektor-Sicht vertieft das D2. Ist der externe Zugriff für die aufgerufene Fähigkeit nicht aktiv oder passt die UUID nicht → HTTP 401. Eine neue UUID lässt sich in den Agent-Einstellungen generieren (Rotation, vgl. Stufe 6).

1Chat

POST /agent/{agentid}/chat (alle Container) bzw. POST /agent/{agentid}/container/{containerid}/chat (ein Container). (AH 14.3.3)

Request-Body ChatCommand, Pflichtfeld question. Weitere Felder u. a. comuuid (Konversations-ID — leer = neue Konversation; den zurückgegebenen Wert beim nächsten Aufruf wieder mitgeben), internetsearch, files, orgid, anonymize, stream, followUpQuestionMode, answerMode, usermail, usePersonalKnowledgeDb.

curl -X POST "https://muster.auxdata.example/api/v1/agent/123/chat" \
  -H "Authorization: Bearer ${AUX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "question": "Wie setze ich das Gerät zurück?", "comuuid": "" }'

Response laut aktueller öffentlicher Swagger-Datei: ExecuteServiceStepResult (HTTP 200, gekürzt). Wichtigste Felder: answer, command, comuuid, context, documents, sources (SearchChunkResult[]), tokenusage, images, videos, error.

{
  "answer": "Halten Sie die Reset-Taste 10 Sekunden gedrückt ...",
  "comuuid": "8f2b1e...",
  "context": "...",
  "sources": [ /* SearchChunkResult[] */ ],
  "tokenusage": { /* TokenUsageStats */ },
  "error": ""
}

2Suche

POST /agent/{agentid}/document (alle Container) bzw. POST /agent/{agentid}/container/{containerid}/document (ein Container). (AH 14.3.4)

Request-Body SearchCommand: question (Pflicht), qualitygate (minimale Ähnlichkeitsschwelle 0–1, Chunks darunter werden verworfen), resultLimit (max. Anzahl Chunks). Response laut aktueller öffentlicher Swagger-Datei: VectorStoreAnalysisResult mit content, documentId, documentSource, score. Wenn deine Instanz ein anderes Detail-/Array-Schema zeigt, gilt deren Swagger.

curl -X POST "https://muster.auxdata.example/api/v1/agent/123/document" \
  -H "Authorization: Bearer ${AUX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "question": "Garantiebedingungen", "qualitygate": 0.7, "resultLimit": 10 }'

Schema-Felder gegen Swagger prüfen. In den cURL-Blöcken setzt die Zeilenfortsetzung mit \ mehrzeilige Befehle zusammen.

1AI-Service ausführen

POST /agent/{agentid}/executeservice/{serviceid}. Body = flache map[string]string; die erwarteten Parameter ergeben sich aus der Service-Definition. (AH 14.3.5)

curl -X POST "https://muster.auxdata.example/api/v1/agent/123/executeservice/789" \
  -H "Authorization: Bearer ${AUX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "topic": "Datenschutz", "sprache": "Deutsch" }'

Response ExecuteServiceResult (command, answer = AiServiceMultiResult, error, background, usageid, tokenusage).

Binärdatei als Parameter: Da der Body flach string→string ist, wird eine Datei als string-escaptes JSON in einem Parameterwert verpackt. Enthält ein Wert ein JSON-Objekt mit dem Feld content, interpretiert der Server ihn als Datei. Felder: content (Base64, Pflicht), type (Dateiendung ohne Punkt, Pflicht), name (Pflicht), vision (bool, Default false), imagelimit (int, Default 20).

{
  "anhang": "{\"name\":\"vertrag.pdf\",\"type\":\"pdf\",\"content\":\"JVBERi0xLjQ...\"}"
}

2Upload (multipart)

PUT /agent/{agentid}/container/{containerid}/document. Body multipart/form-data, Form-Feld files. (AH 14.3.1)

Optionaler Header laut aktueller öffentlicher Swagger-Datei: link (Basis-Herkunftslink; der Server hängt den Dateinamen an). Falls deine Instanz zusätzlich einen Ersetzen-Mechanismus wie documentid anbietet, gilt deren Swagger. Response (HTTP 200): Array UploadedFilesResult mit filename, filetype, documentid.

curl -X PUT "https://muster.auxdata.example/api/v1/agent/123/container/456/document" \
  -H "Authorization: Bearer ${AUX_TOKEN}" \
  -H "link: https://intranet.example.com/dokumente" \
  -F "files=@/pfad/zur/datei.pdf"

3Upload (enhanced, JSON/Base64)

PUT /agent/{agentid}/container/{containerid}/document/enhanced. Body UploadDocumentCommandApi. (AH 14.3.2)

Felder u. a.: id, name, link, type (BIN = binär, vom DataReader geparst / TXT = Text direkt), filecontent (Base64 bei BIN, UTF-8-Text bei TXT), filetype (z. B. application/pdf laut Swagger-Beispiel), readimagedata/imagelimit, manualcontextenrichmentdata. Response laut aktueller öffentlicher Swagger-Datei: Array von UploadDocumentResult (command, documentid, error).

{
  "name": "handbuch.pdf",
  "type": "BIN",
  "filecontent": "JVBERi0xLjQ...",
  "filetype": "application/pdf",
  "readimagedata": true,
  "imagelimit": 20
}

1Statuscodes

Die wichtigsten Rückgabecodes der Public API. (AH 14.4)

200 OK

erfolgreiche Anfrage.

400 Bad Request

fachlicher Fehler (z. B. keine Datei im Upload).

401 Unauthorized

Authorization-Header fehlt, ungültige Agent-UUID oder externer Zugriff nicht aktiviert.

403 Forbidden

Benutzer hat für das Feature keine Berechtigung.

422 Unprocessable Entity

Body nicht parsebar (ungültiges JSON, ungültige Pfadparameter).

429 Too Many Requests

Rate Limit überschritten.

501 Not Implemented

Feature nicht aktiv konfiguriert.

503 Service Unavailable

Initialisierungsfehler eines internen Dienstes (DB, LLM, Vector-DB …).

2Fehler-Response-Format

Fehler kommen als domain.Error mit code, message, errorObj, user, service. Der \n im message-String steht literal:

{
  "code": 401,
  "message": "Access Rights check failed\nuuid accesstoken rights check failed",
  "errorObj": {},
  "user": null,
  "service": ""
}

Sonderfall Rate-Limit: abweichend ein einfaches Objekt.

{ "error": "Rate limit exceeded" }

3Rate Limiting

Rate 100 Anfragen/Sekunde, Burst 200; Schlüssel ist der Bearer-Token (fehlt er, die Client-IP). (AH 14.5)

Limits gelten global über alle Routen, nicht pro Endpunkt. Inaktive Einträge werden nach 30 s aus dem Tracking entfernt. Bei Überschreitung → 429. Konkrete Zahlen gegen Instanz prüfen — sie stammen aus dem globalen Limiter und können je Deployment angepasst sein.

1Token-Sicherheit

Der Agent-UUID-Token ist ein Secret — behandle ihn so. (AH 14.6)

Nie im Code

Tokens über Umgebungsvariablen oder Secret-Manager, niemals im Repo.

Rotieren

regelmäßig und bei Verdacht auf Kompromittierung; neue UUID in den Agent-Einstellungen generieren.

HTTPS Pflicht

unverschlüsselte API-Kommunikation ist nicht zulässig.

Minimaler Scope

ein Agent-UUID-Token erlaubt nur seine eine Fähigkeit (Chat, Suche, Upload, AI-Service).

2Best Practices

1. Getrennte Tokens pro Integration — ein kompromittierter Token lässt sich zielgerichtet deaktivieren.
2. Retry mit Backoff für 429 und 5xx.
3. Logging der Aufrufe fürs Debugging — aber niemals das Bearer-Token mitloggen.
4. Timeouts setzen, gerade für Chat-Streaming (Server-Timeout: 5 Minuten).

Den Token liest dein Client aus der Umgebung, nie aus dem Quelltext:

# Token aus der Umgebung lesen, niemals im Code:
export AUX_TOKEN="<deine-agent-uuid>"
curl -H "Authorization: Bearer ${AUX_TOKEN}" ...

1Programmierbeispiel (Python)

Das Protokoll ist sprachunabhängig. Eine schlanke Client-Klasse kapselt Basis-URL + Bearer-Header. (AH 14.7)

import requests

class AuxDataAPI:
    def __init__(self, base_url, token):
        self.base_url = base_url.rstrip("/")
        self.headers = {
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
        }

    def chat(self, agent_id, question, comuuid=""):
        url = f"{self.base_url}/api/v1/agent/{agent_id}/chat"
        payload = {"question": question, "comuuid": comuuid}
        r = requests.post(url, json=payload, headers=self.headers)
        r.raise_for_status()
        return r.json()

# Token aus der Umgebung, niemals im Code:
api = AuxDataAPI("https://muster.auxdata.example", AUX_TOKEN)
print(api.chat(123, "Wie funktioniert die API?"))

JS und C# sind analog aufgebaut (gleiche Routen, gleicher Bearer-Header) — siehe Handbuch/Swagger. Kein echtes Token im Code: AUX_TOKEN kommt aus der Umgebung.

2Troubleshooting

Die typischen Fehlerbilder und ihre Lösung. (AH 14.8)

401 „authorization is required header“

Authorization: Bearer <token> setzen.

401 Rights check failed

passenden „External Access“-Schalter aktivieren und die UUID des richtigen Config-Bereichs senden.

403 Forbidden

bei JWT-Aufrufen prüfen, ob der Benutzer Mitglied des Agenten/der Organisation ist.

422 „could not parse ...“

Body gegen 15.3-Schema prüfen; Pfad-IDs müssen numerisch sein.

429

Backoff-Strategie; Limit gilt global pro Token bzw. IP.

500/503

Server-Logs auf Initialisierungsfehler interner Dienste (DB, LLM, Vector-DB) prüfen.

Zusammenfassung: 7 Kernendpunkte unter /api/v1 für Upload/Suche/Chat/AI-Service plus aktueller Swagger-Zusatz /chat/{comUuid}/summarize; Auth per Authorization: Bearer <token> — Agent-UUID (dieses Tutorial) oder Keycloak-JWT (instanz-/setup-abhängig, gegen Instanz prüfen); Schemata aus Go-Typen, in Swagger einsehbar; globales Rate Limiting 100 req/s, Burst 200.