Knowledge Base
Upload, search, and manage knowledge base files in the Talkturo workspace library — attach documents to assistants for retrieval-based answers during voice calls.
curl --request POST \
--url "https://app.talkturo.com/api/kb/files" \
--header "Authorization: Bearer tk_live_example_7f3a9c2d" \
--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",
body: formData,
credentials: "include",
});
const data = await response.json();
console.log(data);
{
"success": true,
"credits_charged": 0,
"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"
}
}
{
"success": true,
"file": {
"id": "6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714",
"status": "ready"
},
"deduplicated": true,
"message": "File already exists"
}
curl --request GET \
--url "https://app.talkturo.com/api/kb/files?include=attachment_count" \
--header "Authorization: Bearer tk_live_example_7f3a9c2d"
const response = await fetch(
"https://app.talkturo.com/api/kb/files?include=attachment_count",
{
method: "GET",
credentials: "include",
}
);
const data = await response.json();
console.log(data);
{
"success": true,
"files": [
{
"id": "6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714",
"filename": "acme-support-playbook.pdf",
"mime_type": "application/pdf",
"size_bytes": 248193,
"status": "ready",
"status_error": null,
"char_count": 18422,
"chunk_count": 47,
"created_at": "2026-02-11T14:22:09.000Z",
"updated_at": "2026-02-11T14:25:31.000Z",
"attachment_count": 2
}
]
}
curl --request GET \
--url "https://app.talkturo.com/api/kb/files/6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714" \
--header "Authorization: Bearer tk_live_example_7f3a9c2d"
const fileId = "6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714";
const response = await fetch(
`https://app.talkturo.com/api/kb/files/${fileId}`,
{
method: "GET",
credentials: "include",
}
);
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": "ready",
"status_error": null,
"char_count": 18422,
"chunk_count": 47,
"created_at": "2026-02-11T14:22:09.000Z",
"updated_at": "2026-02-11T14:25:31.000Z"
}
}
curl --request DELETE \
--url "https://app.talkturo.com/api/kb/files/6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714" \
--header "Authorization: Bearer tk_live_example_7f3a9c2d"
const fileId = "6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714";
const response = await fetch(
`https://app.talkturo.com/api/kb/files/${fileId}`,
{
method: "DELETE",
credentials: "include",
}
);
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 tk_live_example_7f3a9c2d"
const fileId = "6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714";
const response = await fetch(
`https://app.talkturo.com/api/kb/files/${fileId}/download`,
{
method: "GET",
credentials: "include",
}
);
const data = await response.json();
window.location.href = data.url;
{
"url": "https://storage.talkturo.com/signed/acme-support-playbook.pdf?token=example_signed_token_8c4d2f&expires=1770820029",
"filename": "acme-support-playbook.pdf"
}
curl --request POST \
--url "https://app.talkturo.com/api/kb/files/6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714/reprocess" \
--header "Authorization: Bearer tk_live_example_7f3a9c2d"
const fileId = "6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714";
const response = await fetch(
`https://app.talkturo.com/api/kb/files/${fileId}/reprocess`,
{
method: "POST",
credentials: "include",
}
);
const data = await response.json();
console.log(data);
{
"success": true
}
curl --request POST \
--url "https://app.talkturo.com/api/kb/search" \
--header "Authorization: Bearer tk_live_example_7f3a9c2d" \
--header "Content-Type: application/json" \
--data '{
"assistant_id": "9d3f6cf5-3c12-4e60-bd8a-1b1d57a8c4d2",
"query": "What is the return window for unopened equipment?",
"top_k": 6
}'
const response = await fetch("https://app.talkturo.com/api/kb/search", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
credentials: "include",
body: JSON.stringify({
assistant_id: "9d3f6cf5-3c12-4e60-bd8a-1b1d57a8c4d2",
query: "What is the return window for unopened equipment?",
top_k: 6,
}),
});
const data = await response.json();
console.log(data);
{
"success": true,
"hits": [
{
"rank": 1,
"file_id": "6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714",
"filename": "acme-support-playbook.pdf",
"chunk_index": 12,
"page_number": 4,
"content": "Unopened equipment may be returned within 30 days of delivery.",
"similarity": 0.9241,
"match_type": "semantic",
"adjacent": false
}
]
}
{
"success": true,
"hits": [],
"reason": "no_ready_files"
}
curl --request GET \
--url "https://app.talkturo.com/api/assistants/9d3f6cf5-3c12-4e60-bd8a-1b1d57a8c4d2/knowledge-base" \
--header "Authorization: Bearer tk_live_example_7f3a9c2d"
const assistantId = "9d3f6cf5-3c12-4e60-bd8a-1b1d57a8c4d2";
const response = await fetch(
`https://app.talkturo.com/api/assistants/${assistantId}/knowledge-base`,
{
method: "GET",
credentials: "include",
}
);
const data = await response.json();
console.log(data);
{
"success": true,
"files": [
{
"id": "6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714",
"filename": "acme-support-playbook.pdf",
"mime_type": "application/pdf",
"size_bytes": 248193,
"status": "ready",
"status_error": null,
"char_count": 18422,
"chunk_count": 47,
"created_at": "2026-02-11T14:22:09.000Z",
"updated_at": "2026-02-11T14:25:31.000Z"
}
]
}
curl --request POST \
--url "https://app.talkturo.com/api/assistants/9d3f6cf5-3c12-4e60-bd8a-1b1d57a8c4d2/knowledge-base" \
--header "Authorization: Bearer tk_live_example_7f3a9c2d" \
--header "Content-Type: application/json" \
--data '{
"file_id": "6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714"
}'
const assistantId = "9d3f6cf5-3c12-4e60-bd8a-1b1d57a8c4d2";
const response = await fetch(
`https://app.talkturo.com/api/assistants/${assistantId}/knowledge-base`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
},
credentials: "include",
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 tk_live_example_7f3a9c2d"
const assistantId = "9d3f6cf5-3c12-4e60-bd8a-1b1d57a8c4d2";
const fileId = "6b9d58b9-4b43-4f94-8cb8-2d3d9f18d714";
const response = await fetch(
`https://app.talkturo.com/api/assistants/${assistantId}/knowledge-base/${fileId}`,
{
method: "DELETE",
credentials: "include",
}
);
const data = await response.json();
console.log(data);
{
"success": true
}
Knowledge base API
Use the Knowledge Base API to upload, search, download, reprocess, and delete files in your workspace library. Attach existing library files to assistants so they can use ready documents when answering questions during voice calls.
The API exposes two related surfaces:
- Workspace library:
/api/kb/*manages files and searches attached, processed documents. - Assistant attachments:
/api/assistants/{assistantId}/knowledge-baseattaches or detaches existing library files from an assistant.
Both session JWT authentication and API key authentication are supported. API keys require kb:read for file listing, metadata, downloads, and search. They require kb:write for uploads, deletion, reprocessing, and assistant attachment changes.
Endpoint summary
| Method | Path | Purpose | Required API key scope |
|---|---|---|---|
POST | /api/kb/files | Upload a file to the workspace library | kb:write |
GET | /api/kb/files | List workspace library files | kb:read |
GET | /api/kb/files/{fileId} | Get file metadata | kb:read |
DELETE | /api/kb/files/{fileId} | Permanently delete a file | kb:write |
GET | /api/kb/files/{fileId}/download | Create a signed download URL | kb:read |
POST | /api/kb/files/{fileId}/reprocess | Reprocess a file | kb:write |
POST | /api/kb/search | Search ready files attached to an assistant | kb:read |
GET | /api/assistants/{assistantId}/knowledge-base | List files attached to an assistant | kb:read |
POST | /api/assistants/{assistantId}/knowledge-base | Attach an existing library file | kb:write |
DELETE | /api/assistants/{assistantId}/knowledge-base/{fileId} | Detach a file from an assistant | kb:write |
File object
File endpoints return a file object with the following fields.
Unique identifier for the file in the workspace library.
Original name of the uploaded file.
MIME type detected for the uploaded file.
File size in bytes.
Processing status. Possible values are pending, parsing, embedding, indexing, ready, and failed.
Processing error details when status is failed. Returns null when no processing error exists.
Number of extracted characters. Returns null before extraction completes or when extraction does not produce a count.
Number of chunks generated for retrieval. Returns null before chunking completes or when no chunks are available.
Timestamp when the file was added to the workspace library.
Timestamp when the file metadata or processing state was last updated.
File processing follows this status flow: pending → parsing → embedding → indexing → ready. A processing error changes the status to failed, and status_error contains the failure details when available.
Upload a file
Upload a PDF, DOCX, TXT, or MD file to the workspace knowledge base library.
The endpoint accepts one file field in a multipart/form-data request. Files can be up to 1 GiB. The first 50 MiB of stored files is free; each additional 50 MiB costs 1 storage credit.
A new upload returns credits_charged and a complete file object. The file remains unavailable to search until its status becomes ready.
If the library already contains the same file, the API avoids storing a duplicate and returns deduplicated: true. The deduplicated response includes the existing file identifier and current status instead of charging storage for another copy.
Body parameters
PDF, DOCX, TXT, or MD file to add to the workspace library. The maximum file size is 1 GiB.
List files
List files in the workspace knowledge base library.
Query parameters
Set to attachment_count to include the number of assistants currently using each file.
attachment_countResponse fields
Returns true when the request succeeds.
Files in the workspace knowledge base library. Each item is a file object.
Get file metadata
Retrieve metadata and processing details for one file.
Path parameters
Identifier of the file to retrieve.
Response fields
Returns true when the request succeeds.
Metadata and processing details for the requested file.
Delete a file
Permanently delete a file from the workspace library.
Path parameters
Identifier of the file to delete.
A delete is a hard delete. It removes the file metadata, chunks, embeddings, storage object, and all assistant attachments for the file.
Deleting a file does not refund storage credits that were charged when the file was uploaded.
Download a file
Create a signed URL for downloading a file from the workspace library. The URL expires after 5 minutes.
Path parameters
Identifier of the file to download.
Response fields
Five-minute signed URL for downloading the file.
Original filename to use for the download.
The download response does not include a success field. Use the returned url to retrieve the file before the signed URL expires.
Reprocess a file
Reset a file's processing state and enqueue it for processing again.
Path parameters
Identifier of the file to reprocess.
Reprocessing resets the status to pending, clears existing chunks, and enqueues the file for parsing, embedding, and indexing again.
Search the knowledge base
Search files attached to a specific assistant. Search only considers files with a ready status.
The search is restricted to files attached to the specified assistant. A file must have status set to ready before it can produce a hit.
Body parameters
Assistant whose attached knowledge base files should be searched.
Search query with 1 to 2000 characters.
Maximum number of results to return. Accepts values from 1 to 20 and defaults to 6.
Response fields
Returns true when the search request succeeds.
Ranked search results. The array is empty when no attached files are ready or no files are attached.
One-based ranking of the result.
Identifier of the file containing the matching chunk.
Filename containing the matching chunk.
Zero-based index of the matching chunk within the file.
Page number associated with the matching content when available.
Text content of the matching chunk.
Similarity score for the match.
Matching strategy used for the result.
Indicates whether the result represents adjacent context included with a primary match.
Reason returned with an empty result set. Possible values include no_files_attached and no_ready_files.
Manage assistant knowledge base attachments
Attach existing workspace library files to an assistant without uploading them again. Detaching a file removes the assistant relationship but keeps the file in the workspace library.
List attached files
Attach an existing file
Attach a file already present in the workspace library by sending its file identifier.
Sending the same file identifier again is safe. If the file is already attached, the endpoint returns idempotent: true.
Detach a file
Detach a file from an assistant without deleting it from the workspace library.
Path parameters
Identifier of the assistant whose attachments should be managed.
Identifier of the workspace library file to detach.
Attachment request body
Identifier of an existing file in the workspace knowledge base library.
Attachment response fields
Returns true when the attachment or detachment succeeds.
Returns true when an attach request found that the file was already attached.
The assistant attachment DELETE endpoint only detaches the file. To permanently remove the file, use DELETE /api/kb/files/{fileId}. A library deletion also removes every assistant attachment for that file.
Typical workflow
Use the workspace library and assistant attachment endpoints together when preparing retrieval content for a voice assistant.
Upload the file
Send POST /api/kb/files with the document in the file multipart field.
A successful response returns a file object with status: pending, or a deduplicated response for an existing file.
Poll the processing status
Call GET /api/kb/files/{fileId} or GET /api/kb/files and inspect the file status.
Continue when the status becomes ready. If the status becomes failed, inspect status_error before retrying or reprocessing the file.
Search the knowledge base
Call POST /api/kb/search with the assistant identifier and a query.
Search returns chunks only from ready files attached to the specified assistant.
Attach the file to an assistant
Send POST /api/assistants/{assistantId}/knowledge-base with the existing file_id.
The endpoint returns idempotent: true when the relationship already exists.
Detach the file when needed
Send DELETE /api/assistants/{assistantId}/knowledge-base/{fileId} to remove the file from the assistant.
The file remains in the workspace library and can be attached to another assistant.