Mit Dateien arbeiten

Premium-Funktion

Wie Sie einem Agenten über die API ein Dokument zur Verfügung stellen, hängt davon ab, ob der Agent das Dokument dauerhaft kennen oder es nur für eine Unterhaltung ansehen soll.

Lesen Sie zuerst die Übersicht – sie zeigt den schnellsten Weg für jeden Anwendungsfall.

Was Sie möchten	Über die API
Der Agent soll diese Dokumente dauerhaft kennen	Ja – Upload in eine Wissenssammlung
Eine ganze Wissenssammlung zwischen Instanzen verschieben	Teilweise – Import ja, das Export-Archiv lässt sich mit einem Schlüssel aber nicht herunterladen
Eine Audiodatei transkribieren	Ja – `/v1/audio/transcriptions`
Eine Datei an eine einzelne Unterhaltung anhängen	Ja – Upload in den Thread-Arbeitsbereich
Eine vom Agenten erzeugte Datei herunterladen	Ja – Download aus dem Thread-Arbeitsbereich
Die dauerhaften Dateien des Agenten verwalten	Ja – Upload/Download im Agenten-Arbeitsbereich
Ein Bild zum Ansehen senden	Nein – die Chat-Schnittstellen sind reiner Text

Wissenssammlungen: der unterstützte Weg

Eine Wissenssammlung ist eine Sammlung von Dokumenten, die eingelesen, eingebettet und für jeden zugeordneten Agenten durchsuchbar gemacht wird. Das ist der von der API unterstützte Weg, einem Agenten Dokumente zu geben.

Der Ablauf:

Eine Wissenssammlung anlegen (oder eine bestehende verwenden).
Dateien hineinladen.
Die Sammlung dem Agenten zuordnen.
Chatten – der Agent ruft automatisch daraus ab.

Schritte 1–3 sind Aufrufe der Management-API und benötigen Management-Scopes auf Ihrem Schlüssel:

Schritt	Route	Benötigter Scope
Sammlung anlegen	`POST /api/knowledge-sets`	`knowledgeset:manage:*`
Datei hochladen	`POST /api/knowledge-sets/{id}/knowledge-files/{path}`	`knowledgeset:manage:*`
Einem Agenten zuordnen	`POST /api/agents/{id}/knowledge-sets/{ks}/attach`	`agent:update:*` oder `agent:update:{id}`

Ein reiner Chat-Schlüssel (agent:chat:…) kann davon nichts – er kann nur mit einem Agenten sprechen, dessen Wissenssammlungen bereits eingerichtet sind.

Eine Datei hochladen

Der Anfragekörper ist die rohe Datei – kein Multipart-Formular

Der Dateiname kommt aus dem URL-Pfad, und der Anfragekörper enthält die rohen Bytes der Datei. Bauen Sie hier keine multipart/form-data-Anfrage.

curl -sS -X POST \
  "https://your-instance.platform.basepeak.ai/api/knowledge-sets/ks1abc/knowledge-files/q3-bericht.pdf" \
  -H "Authorization: Bearer sk-bpai-1-42-…" \
  -H "Content-Type: application/pdf" \
  --data-binary @q3-bericht.pdf

Antwortet mit 201 Created und dem Objekt der Wissensdatei.

Detail	Wert
Maximale Größe	100 MB pro Datei
Virenprüfung	Jeder Upload wird geprüft; eine infizierte Datei wird mit `400` abgelehnt
Freigabe	So hochgeladene Dateien sind automatisch freigegeben und zur Verarbeitung eingeplant
Unterverzeichnisse	Der Pfad ist ein Platzhalter am Ende, `…/knowledge-files/2026/q3/bericht.pdf` funktioniert also

Die Verarbeitung läuft asynchron – ein 201 bedeutet, dass die Datei gespeichert ist, nicht dass sie schon durchsuchbar ist. Fragen Sie die Dateiliste ab und beobachten Sie den Status, wenn Sie den Zeitpunkt der Verfügbarkeit brauchen.

import pathlib, httpx

path = pathlib.Path("q3-bericht.pdf")

r = httpx.post(
    f"{BASE}/api/knowledge-sets/ks1abc/knowledge-files/{path.name}",
    headers={"Authorization": f"Bearer {TOKEN}",
             "Content-Type": "application/pdf"},
    content=path.read_bytes(),      # rohe Bytes, kein Multipart
    timeout=120,
)
r.raise_for_status()
print(r.json())

Auflisten und löschen

# Auflisten
curl -sS "$BASE/api/knowledge-sets/ks1abc/knowledge-files" \
  -H "Authorization: Bearer $TOKEN"

# Löschen
curl -sS -X DELETE \
  "$BASE/api/knowledge-sets/ks1abc/knowledge-files/q3-bericht.pdf" \
  -H "Authorization: Bearer $TOKEN"

Beides benötigt knowledgeset:manage:*.

Massen-Import und -Export

Um eine ganze Wissenssammlung zu verschieben – zwischen Instanzen oder als Sicherung – nutzen Sie die Transfer-Routen statt Datei für Datei hochzuladen.

# Export: liefert einen Auftrag, den Sie anschließend abfragen.
curl -sS -X POST "$BASE/api/knowledge-sets/ks1abc/exports" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{}'

# Import: das IST ein Multipart-Formular, Feldname "file".
curl -sS -X POST "$BASE/api/knowledge-set-imports" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@wissenssammlung.zip"

Beachten Sie die Asymmetrie zum Einzeldatei-Upload: Importe sind multipart/form-data mit einem Formularfeld namens file, Einzeluploads hingegen nutzen den rohen Anfragekörper. Importe sind über die Instanzkonfiguration größenbegrenzt und antworten mit 413, wenn das Archiv zu groß ist.

Das Export-Archiv selbst ist mit einem Schlüssel nicht abrufbar

Anlegen, Auflisten und Löschen von Exporten funktioniert, aber GET /api/knowledge-sets/{id}/exports/{export_id}/download steht nicht auf der Positivliste für API-Schlüssel – die Bytes abzuholen erfordert eine Browser-Sitzung. Ein Export lässt sich über die API also erzeugen, aber nicht einsammeln.

Audio-Transkription

Die einzige Route mit Binäreingabe auf der Chat-Seite ist OpenAI-kompatibel und Multipart – genau so, wie die OpenAI-SDKs sie senden:

curl -sS -X POST "$BASE/v1/audio/transcriptions" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@besprechung.mp3" \
  -F "model=speech-to-text"

Detail	Wert
Formate	flac, m4a, mp3, mp4, mpeg, mpga, oga, ogg, wav, webm
`model`	Optional; Standard ist der Alias `speech-to-text`
Scope	Jeder gültige Schlüssel – diese Route hat keine Scope-Prüfung

Alles andere antwortet mit 400 und der Liste der erlaubten Formate.

Dateien in Unterhaltungen, im Agenten und im Projekt

Drei Arbeitsbereiche sind mit einem Schlüssel erreichbar. Alle drei erwarten die rohen Bytes der Datei als Anfragekörper, mit dem Dateinamen im URL-Pfad – dieselbe Konvention wie beim Wissens-Upload, kein Multipart-Formular.

Arbeitsbereich	Routen	Scope
Der des Agenten – lesend (`GET`)	`/api/agents/{id}/files`, `/api/agents/{id}/files/{path}`	`agent:files` oder `agent:files-write`
Der des Agenten – schreibend (`POST`, `DELETE`)	`/api/agents/{id}/files/{path}`	`agent:files-write`
Der einer Unterhaltung (beide Richtungen)	`/api/threads/{id}/files`, `/api/threads/{id}/files/{path}`	`thread:files`
Der eines Projekts (beide Richtungen)	`/api/projects/{project_id}/files`, `/api/projects/{project_id}/files/{path}`	`project:files` (lesend) oder `project:files-write` (lesend + schreibend)

GET, POST und DELETE werden auf der {path}-Form unterstützt; GET auf der reinen /files-Form listet auf. Der Arbeitsbereich des Agenten trennt Lesen von Schreiben: agent:files-write ist eine Erweiterung von agent:files (deckt beides ab), und ihn auszustellen erfordert die Berechtigung agent:update – siehe API-Schlüssel. Der Arbeitsbereich einer Unterhaltung kennt diese Trennung nicht; thread:files deckt beide Richtungen ab. Der Arbeitsbereich eines Projekts trennt Lesen und Schreiben wieder wie der des Agenten (project:files-write als strikte Erweiterung von project:files) – anders als bei agent:files-write genügt dafür aber Projektmitgliedschaft, keine zusätzliche Berechtigung. Siehe Projekte.

Welchen Sie brauchen, hängt von der Lebensdauer und der Reichweite ab. Der Arbeitsbereich des Agenten wird in jede neue Unterhaltung kopiert – dort gehören dauerhafte Dateien hin, die zu keinem bestimmten Projekt gehören. Der Arbeitsbereich eines Threads gehört zu genau dieser Unterhaltung – dort legen Sie ein Dokument ab, das der Agent einmalig ansehen soll. Der Arbeitsbereich eines Projekts liegt dazwischen: Er ist von jeder Unterhaltung sichtbar, die im Projekt beginnt (POST /api/projects/{project_id}/invoke), aber nicht von Unterhaltungen außerhalb davon.

Der Rundlauf: mit einem Schlüssel hochladen, dann in derselben Unterhaltung danach fragen.

# Datei in den geteilten Arbeitsbereich eines Projekts hochladen.
curl -sS -X POST "$BASE/api/projects/p1abc/files/report.csv" \
  -H "Authorization: Bearer $TOKEN" \
  --data-binary @report.csv

# Eine neue Unterhaltung in genau diesem Projekt beginnen und danach fragen.
curl -sS -X POST "$BASE/api/projects/p1abc/invoke" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: text/plain" \
  --data 'Was steht in report.csv?'

# Dem Agenten ein Dokument nur für diese Unterhaltung geben.
curl -sS -X POST "$BASE/api/threads/t1abcde/files/vertrag.pdf" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/pdf" \
  --data-binary @vertrag.pdf

# Etwas abholen, das der Agent erzeugt hat.
curl -sS "$BASE/api/threads/t1abcde/files/zusammenfassung.md" \
  -H "Authorization: Bearer $TOKEN" -o zusammenfassung.md

# Auflisten, was im Arbeitsbereich der Unterhaltung liegt.
curl -sS "$BASE/api/threads/t1abcde/files" -H "Authorization: Bearer $TOKEN"

Ein Schlüssel erreicht immer nur die Unterhaltungen des eigenen Kontos, und nur die eines Agenten, den sein Scope abdeckt.

Was über die API nicht verfügbar ist

Bilder und andere Nicht-Text-Inhalte im Chat

Beide Chat-Schnittstellen sind reiner Text:

Bei /v1/chat/completions werden strukturierte Content-Teile vom Typ text aneinandergefügt; Teile vom Typ image_url und input_audio werden stillschweigend übersprungen – ohne Fehler, sie erreichen den Agenten einfach nicht.
Bei /api/invoke/{id} ist der Anfragekörper die Eingabe.

Verlassen Sie sich nicht darauf, dass ein Bild in einem messages-Array das Modell erreicht.

Verbleibende Lücken umgehen

Für das, was weiterhin fehlt – ein Bild senden oder eine ganze Dokumentensammlung in großer Zahl bewegen – sind dies die praktikablen Ausweichlösungen:

1. Das Dokument in eine Wissenssammlung legen. Am besten, wenn dieselben Dokumente vielen Unterhaltungen dienen – Richtlinien, Produktdokumentation, Handbücher. Der Agent ruft je Frage ab, was er braucht.

2. Den Text in die Eingabe einbetten. Für ein einmaliges Dokument extrahieren Sie den Text selbst und senden ihn als Teil der Eingabe an /api/invoke/{id}. Begrenzt durch das Kontextfenster des Modells, benötigt aber überhaupt keine Datei-Infrastruktur:

document = pathlib.Path("vertrag.txt").read_text()
prompt = f"Prüfe diesen Vertrag und nenne unübliche Klauseln:\n\n{document}"

httpx.post(f"{BASE}/api/invoke/a17jlm7",
           headers={"Authorization": f"Bearer {TOKEN}",
                    "Accept": "application/json",
                    "Content-Type": "text/plain"},
           content=prompt, timeout=None)

3. Ein Werkzeug die Bytes bewegen lassen. Soll das Ergebnis direkt in einem System außerhalb von BasePeak.AI landen, geben Sie dem Agenten ein Werkzeug, das es dorthin liefert – per Mail, in einen Objektspeicher, an einen Webhook – statt es über den Thread-Arbeitsbereich hin- und herzureichen. Das erspart zugleich das Abfragen auf Fertigstellung.

4. Eine Wissenssammlung pro Unterhaltung. Soll der Agent innerhalb einer Unterhaltung über eine größere Dokumentenmenge suchen statt nur eine Datei zu lesen, legen Sie dafür eine Wissenssammlung an, ordnen sie zu und löschen sie danach. Aufwendiger als ein Upload in den Thread-Arbeitsbereich, liefert dafür aber gezielte Suche statt einer einzelnen Datei.

Weiterführende Dokumentation

Management-API – Wissenssammlungen und Scopes
Invoke-API – Eingaben senden
Threads – Zustand einer Unterhaltung
Projekte – der Arbeitsbereich eines Projekts im Detail

Wissenssammlungen: der unterstützte Weg​

Eine Datei hochladen​

Auflisten und löschen​

Massen-Import und -Export​

Audio-Transkription​

Dateien in Unterhaltungen, im Agenten und im Projekt​

Was über die API nicht verfügbar ist​

Bilder und andere Nicht-Text-Inhalte im Chat​

Verbleibende Lücken umgehen​

Weiterführende Dokumentation​