Wissensdatenbank
Laden Sie Dateien in die Talkturo-Arbeitsbereich-Bibliothek hoch, durchsuchen Sie sie und verwalten Sie sie — hängen Sie Dokumente an Assistenten an für retrievalbasierte Antworten während Sprachanrufen.
curl --request POST \
--url "https://app.talkturo.com/api/kb/files" \
--header "Authorization: Bearer sk_test_example_7Kp3mN8qL2" \
--form "file=@./docs/acme-support-playbook.pdf"
const formData = new FormData();
formData.append("file", fileInput.files[0]);
const response = await fetch("https://app.talkturo.com/api/kb/files", {
method: "POST",
headers: {
Authorization: "Bearer sk_test_example_7Kp3mN8qL2",
},
body: formData,
});
const data = await response.json();
console.log(data);
{
"success": true,
"file": {
"id": "6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714",
"filename": "acme-support-playbook.pdf",
"mime_type": "application/pdf",
"size_bytes": 248193,
"status": "pending",
"status_error": null,
"char_count": null,
"chunk_count": null,
"created_at": "2026-02-11T14:22:09.000Z",
"updated_at": "2026-02-11T14:22:09.000Z"
}
}
curl --request GET \
--url "https://app.talkturo.com/api/kb/files?include=attachment_count" \
--header "Authorization: Bearer sk_test_example_7Kp3mN8qL2"
const response = await fetch(
"https://app.talkturo.com/api/kb/files?include=attachment_count",
{
headers: {
Authorization: "Bearer sk_test_example_7Kp3mN8qL2",
},
}
);
const data = await response.json();
console.log(data);
{
"success": true,
"files": [
{
"id": "6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714",
"filename": "acme-pricing-guide.pdf",
"mime_type": "application/pdf",
"size_bytes": 248193,
"status": "ready",
"status_error": null,
"char_count": 18420,
"chunk_count": 47,
"created_at": "2026-02-11T14:22:09.000Z",
"updated_at": "2026-02-11T14:25:18.000Z",
"attachment_count": 2
}
]
}
curl --request GET \
--url "https://app.talkturo.com/api/kb/files/6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714" \
--header "Authorization: Bearer sk_test_example_7Kp3mN8qL2"
const response = await fetch(
"https://app.talkturo.com/api/kb/files/6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714",
{
headers: {
Authorization: "Bearer sk_test_example_7Kp3mN8qL2",
},
}
);
const data = await response.json();
console.log(data);
{
"success": true,
"file": {
"id": "6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714",
"filename": "acme-pricing-guide.pdf",
"mime_type": "application/pdf",
"size_bytes": 248193,
"status": "ready",
"status_error": null,
"char_count": 18420,
"chunk_count": 47,
"created_at": "2026-02-11T14:22:09.000Z",
"updated_at": "2026-02-11T14:25:18.000Z"
}
}
curl --request DELETE \
--url "https://app.talkturo.com/api/kb/files/6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714" \
--header "Authorization: Bearer sk_test_example_7Kp3mN8qL2"
const response = await fetch(
"https://app.talkturo.com/api/kb/files/6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714",
{
method: "DELETE",
headers: {
Authorization: "Bearer sk_test_example_7Kp3mN8qL2",
},
}
);
const data = await response.json();
console.log(data);
{
"success": true
}
curl --request GET \
--url "https://app.talkturo.com/api/kb/files/6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714/download" \
--header "Authorization: Bearer sk_test_example_7Kp3mN8qL2"
const response = await fetch(
"https://app.talkturo.com/api/kb/files/6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714/download",
{
headers: {
Authorization: "Bearer sk_test_example_7Kp3mN8qL2",
},
}
);
const data = await response.json();
console.log(data);
{
"success": true,
"url": "https://storage.talkturo.com/signed/kb/6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714?expires=1770820029&signature=example_signature",
"filename": "acme-pricing-guide.pdf"
}
curl --request POST \
--url "https://app.talkturo.com/api/kb/files/6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714/reprocess" \
--header "Authorization: Bearer sk_test_example_7Kp3mN8qL2"
const response = await fetch(
"https://app.talkturo.com/api/kb/files/6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714/reprocess",
{
method: "POST",
headers: {
Authorization: "Bearer sk_test_example_7Kp3mN8qL2",
},
}
);
const data = await response.json();
console.log(data);
{
"success": true,
"file": {
"id": "6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714",
"filename": "acme-pricing-guide.pdf",
"mime_type": "application/pdf",
"size_bytes": 248193,
"status": "pending",
"status_error": null,
"char_count": null,
"chunk_count": null,
"created_at": "2026-02-11T14:22:09.000Z",
"updated_at": "2026-02-11T14:31:42.000Z"
}
}
curl --request POST \
--url "https://app.talkturo.com/api/kb/search" \
--header "Authorization: Bearer sk_test_example_7Kp3mN8qL2" \
--header "Content-Type: application/json" \
--data '{
"assistant_id": "9d3f6cf5-3c12-4e60-bd8a-1b1d57a8c4d2",
"query": "What is the return window for annual subscriptions?",
"top_k": 5
}'
const response = await fetch("https://app.talkturo.com/api/kb/search", {
method: "POST",
headers: {
Authorization: "Bearer sk_test_example_7Kp3mN8qL2",
"Content-Type": "application/json",
},
body: JSON.stringify({
assistant_id: "9d3f6cf5-3c12-4e60-bd8a-1b1d57a8c4d2",
query: "What is the return window for annual subscriptions?",
top_k: 5,
}),
});
const data = await response.json();
console.log(data);
{
"success": true,
"hits": [
{
"file_id": "6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714",
"filename": "acme-pricing-guide.pdf",
"content": "Annual subscriptions may be returned within 30 days of purchase.",
"score": 0.9342
}
]
}
curl --request GET \
--url "https://app.talkturo.com/api/assistants/9d3f6cf5-3c12-4e60-bd8a-1b1d57a8c4d2/knowledge-base" \
--header "Authorization: Bearer sk_test_example_7Kp3mN8qL2"
const response = await fetch(
"https://app.talkturo.com/api/assistants/9d3f6cf5-3c12-4e60-bd8a-1b1d57a8c4d2/knowledge-base",
{
headers: {
Authorization: "Bearer sk_test_example_7Kp3mN8qL2",
},
}
);
const data = await response.json();
console.log(data);
{
"success": true,
"files": [
{
"id": "6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714",
"filename": "acme-pricing-guide.pdf",
"mime_type": "application/pdf",
"size_bytes": 248193,
"status": "ready",
"status_error": null,
"char_count": 18420,
"chunk_count": 47,
"created_at": "2026-02-11T14:22:09.000Z",
"updated_at": "2026-02-11T14:25:18.000Z"
}
]
}
curl --request POST \
--url "https://app.talkturo.com/api/assistants/9d3f6cf5-3c12-4e60-bd8a-1b1d57a8c4d2/knowledge-base" \
--header "Authorization: Bearer sk_test_example_7Kp3mN8qL2" \
--header "Content-Type: application/json" \
--data '{
"file_id": "6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714"
}'
const response = await fetch(
"https://app.talkturo.com/api/assistants/9d3f6cf5-3c12-4e60-bd8a-1b1d57a8c4d2/knowledge-base",
{
method: "POST",
headers: {
Authorization: "Bearer sk_test_example_7Kp3mN8qL2",
"Content-Type": "application/json",
},
body: JSON.stringify({
file_id: "6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714",
}),
}
);
const data = await response.json();
console.log(data);
{
"success": true
}
{
"success": true,
"idempotent": true
}
curl --request DELETE \
--url "https://app.talkturo.com/api/assistants/9d3f6cf5-3c12-4e60-bd8a-1b1d57a8c4d2/knowledge-base/6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714" \
--header "Authorization: Bearer sk_test_example_7Kp3mN8qL2"
const response = await fetch(
"https://app.talkturo.com/api/assistants/9d3f6cf5-3c12-4e60-bd8a-1b1d57a8c4d2/knowledge-base/6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714",
{
method: "DELETE",
headers: {
Authorization: "Bearer sk_test_example_7Kp3mN8qL2",
},
}
);
const data = await response.json();
console.log(data);
{
"success": true
}
Wissensdatenbank-Endpunkte
Verwalten Sie Dateien in der Wissensdatenbank Ihres Arbeitsbereichs und ordnen Sie vorhandene Bibliotheksdateien Ihren Assistenten zu. Die Endpunkte unterstützen Uploads, Suche, Downloads, Neuverarbeitung und das Entfernen von Zuordnungen für retrievalbasierte Antworten während Sprachanrufen.
Die Wissensdatenbank-API unterstützt Session-JWT- und API-Schlüssel-Authentifizierung. API-Schlüssel benötigen kb:read für Lese- und Suchvorgänge sowie kb:write für Uploads, Löschung, Neuverarbeitung und Änderungen an Assistenten-Zuordnungen.
Endpunktübersicht
| Methode | Pfad | Zweck | Berechtigung |
|---|---|---|---|
POST | /api/kb/files | Datei in die Arbeitsbereich-Bibliothek hochladen | kb:write |
GET | /api/kb/files | Dateien der Arbeitsbereich-Bibliothek auflisten | kb:read |
GET | /api/kb/files/{fileId} | Dateimetadaten abrufen | kb:read |
DELETE | /api/kb/files/{fileId} | Datei dauerhaft aus der Bibliothek löschen | kb:write |
GET | /api/kb/files/{fileId}/download | Signierte Download-URL abrufen | kb:read |
POST | /api/kb/files/{fileId}/reprocess | Datei erneut verarbeiten | kb:write |
POST | /api/kb/search | Wissensdatenbank durchsuchen | kb:read |
GET | /api/assistants/{assistantId}/knowledge-base | Dem Assistenten zugeordnete Dateien auflisten | kb:read |
POST | /api/assistants/{assistantId}/knowledge-base | Vorhandene Bibliotheksdatei einem Assistenten zuordnen | kb:write |
DELETE | /api/assistants/{assistantId}/knowledge-base/{fileId} | Datei vom Assistenten entfernen | kb:write |
Dateiobjekt
Die Datei-Endpunkte verwenden ein gemeinsames Dateiobjekt. Die Datei gehört zur Arbeitsbereich-Bibliothek und kann unabhängig davon einem oder mehreren Assistenten zugeordnet werden.
Eindeutige Kennung der Datei.
Ursprünglicher Dateiname.
MIME-Typ der Datei, zum Beispiel application/pdf.
Dateigröße in Bytes.
Verarbeitungsstatus der Datei. Mögliche Werte sind pending, parsing, embedding, indexing, ready und failed.
Fehlerbeschreibung, wenn die Verarbeitung fehlgeschlagen ist. Der Wert ist null, wenn kein Fehler vorliegt.
Anzahl der aus der Datei extrahierten Zeichen. Der Wert ist null, solange die Extraktion noch nicht abgeschlossen ist.
Anzahl der für die Suche erzeugten Textabschnitte. Der Wert ist null, solange die Verarbeitung noch nicht abgeschlossen ist.
Zeitstempel der Dateierstellung im ISO-8601-Format.
Zeitstempel der letzten Änderung am Dateiobjekt im ISO-8601-Format.
Die Verarbeitung durchläuft normalerweise pending, parsing, embedding und indexing, bevor sie ready erreicht. Bei einem Fehler wechselt der Status zu failed, und status_error enthält weitere Informationen.
Datei hochladen
Laden Sie eine PDF-, DOCX-, TXT- oder MD-Datei mit multipart/form-data in die Arbeitsbereich-Bibliothek hoch. Die maximale Dateigröße beträgt 1 GiB.
Body-Parameter
Die hochzuladende PDF-, DOCX-, TXT- oder MD-Datei. Senden Sie das Feld als multipart/form-data. Die Datei darf höchstens 1 GiB groß sein.
Der Upload dedupliziert Dateien anhand ihres Inhalts. Ein erneuter Upload derselben Datei erzeugt keine zusätzliche Bibliotheksdatei. Für den Speicherverbrauch sind die ersten 50 MiB kostenlos; jedes weitere 50-MiB-Intervall belastet ein Credit.
Dateien auflisten
Rufen Sie die Dateien der Arbeitsbereich-Bibliothek ab. Verwenden Sie include=attachment_count, um die Anzahl der Assistenten-Zuordnungen pro Datei einzuschließen.
Query-Parameter
Setzen Sie den Wert auf attachment_count, um das Feld attachment_count in jedem Dateiobjekt zurückzugeben.
attachment_countDateimetadaten abrufen
Rufen Sie die Metadaten einer einzelnen Bibliotheksdatei über ihre Kennung ab.
Pfadparameter
Kennung der abzurufenden Bibliotheksdatei.
Datei löschen
Löschen Sie eine Datei dauerhaft aus der Arbeitsbereich-Bibliothek. Das Löschen entfernt die Datei auch aus allen Assistenten-Zuordnungen. Bereits belastete Speichercredits werden nicht zurückgegeben.
Das Löschen ist endgültig. Laden Sie die Datei erneut hoch, wenn Sie sie später wieder benötigen.
Pfadparameter
Kennung der zu löschenden Bibliotheksdatei.
Datei herunterladen
Fordern Sie eine kurzlebige, signierte URL für den Download einer Bibliotheksdatei an. Die URL ist fünf Minuten gültig.
Pfadparameter
Kennung der herunterzuladenden Bibliotheksdatei.
Antwortfelder
Gibt true zurück, wenn die Download-URL erstellt wurde.
Signierte URL, die fünf Minuten gültig ist.
Dateiname für den Download.
Datei neu verarbeiten
Starten Sie die Verarbeitung einer vorhandenen Bibliotheksdatei erneut. Verwenden Sie diesen Endpunkt, wenn die Verarbeitung mit dem Status failed beendet wurde oder die Datei erneut indiziert werden soll.
Pfadparameter
Kennung der neu zu verarbeitenden Bibliotheksdatei.
Wissensdatenbank durchsuchen
Durchsuchen Sie die Wissensdatenbank mit einer Assistentenkennung und einer natürlichsprachlichen Anfrage. Die Suche liefert die relevantesten Textabschnitte aus den Dateien, die diesem Assistenten zugeordnet sind.
Body-Parameter
Kennung des Assistenten, dessen zugeordnete Dateien durchsucht werden.
Natürlichsprachliche Suchanfrage.
Maximale Anzahl der zurückgegebenen Treffer.
Antwortfelder
Gibt true zurück, wenn die Suche erfolgreich war.
Relevante Textabschnitte aus den für den Assistenten aktivierten Wissensdatenbank-Dateien.
Assistenten-Wissensdatenbank-Zuordnungen verwalten
Ordnen Sie vorhandene Dateien aus der Arbeitsbereich-Bibliothek einem Assistenten zu oder entfernen Sie diese Zuordnung. Der POST-Endpunkt lädt keine Datei hoch. Der DELETE-Endpunkt löscht keine Datei aus der Bibliothek.
Zugeordnete Dateien auflisten
Rufen Sie die Dateien ab, die einem Assistenten aktuell zugeordnet sind.
Vorhandene Datei anhängen
Ordnen Sie eine Datei mit file_id aus der Bibliothek einem Assistenten zu. Wiederholte Zuordnungen sind idempotent.
Pfadparameter
Kennung des Assistenten, dessen Wissensdatenbank-Zuordnungen verwaltet werden.
Body-Parameter
Kennung einer bereits in der Arbeitsbereich-Bibliothek vorhandenen Datei.
Zugeordnete Datei entfernen
Entfernen Sie eine Datei aus der Wissensdatenbank eines Assistenten, ohne die Datei aus der Arbeitsbereich-Bibliothek zu löschen.
Pfadparameter
Kennung des Assistenten, von dem die Datei entfernt wird.
Kennung der vom Assistenten zu entfernenden Datei.
Typischer Workflow
Verwenden Sie die beiden API-Oberflächen in dieser Reihenfolge, wenn Sie Dokumente für einen Assistenten bereitstellen:
Datei in die Bibliothek hochladen
Senden Sie die Datei mit POST /api/kb/files. Warten Sie, bis die Datei den Status ready erreicht, bevor Sie sie durchsuchen oder einem Assistenten zuordnen.
Verarbeitungsstatus prüfen
Rufen Sie GET /api/kb/files/{fileId} oder GET /api/kb/files auf. Bei failed finden Sie die Ursache in status_error; mit POST /api/kb/files/{fileId}/reprocess starten Sie die Verarbeitung erneut.
Datei dem Assistenten zuordnen
Senden Sie POST /api/assistants/{assistantId}/knowledge-base mit der vorhandenen Datei-ID im Feld file_id.
Die Antwort enthält success: true. Bei einer bereits bestehenden Zuordnung kann die Antwort zusätzlich idempotent: true enthalten.
Wissensdatenbank durchsuchen
Senden Sie POST /api/kb/search mit assistant_id, query und top_k. Die Antwort enthält die relevantesten Treffer aus den dem Assistenten zugeordneten Dateien.
Zuordnung oder Datei entfernen
Entfernen Sie eine Datei mit dem Assistenten-DELETE-Endpunkt, wenn sie nur für diesen Assistenten nicht mehr verfügbar sein soll. Verwenden Sie den Bibliotheks-DELETE-Endpunkt nur, wenn Sie die Datei dauerhaft aus dem Arbeitsbereich löschen möchten.