Automating Voiceflow Knowledge
Voiceflow is arguably the most powerful visual builder for conversational AI. However, a chatbot is only as intelligent as its Knowledge Base (KB). If your KB is populated by manually uploading PDFs through the Voiceflow UI, your chatbot's intelligence will inevitably drift out of sync with your company's actual operating procedures.
To build a production-grade AI assistant, you must interact with the Voiceflow Knowledge Base programmatically via their REST API.
The Upload Endpoint and Multipart Data
The primary endpoint for injecting documents is:
POST https://api.voiceflow.com/v1/knowledge-base/docs/upload
Because you are transmitting a file (PDF, DOCX, TXT), you cannot send a standard JSON payload. You must format the request as multipart/form-data.
Here is the implementation in Python using the requests library:
import requests
import os
url = "https://api.voiceflow.com/v1/knowledge-base/docs/upload?overwrite=true"
headers = {
"Authorization": f"Bearer {os.getenv('VOICEFLOW_API_KEY')}",
"Accept": "application/json"
}
file_path = "clinical_playbook_v2.pdf"
files = {
"file": (file_path, open(file_path, "rb"), "application/pdf")
}
response = requests.post(url, headers=headers, files=files)
The Power of overwrite=true
Notice the ?overwrite=true query parameter in the URL.
This is a critical architectural feature. If you upload a file named playbook.pdf, and next week you upload an updated version also named playbook.pdf, Voiceflow will—by default—create two separate documents in the KB. Your chatbot will now retrieve conflicting information.
By appending overwrite=true, the API becomes idempotent. Voiceflow automatically deletes the old version and replaces it with the new payload based purely on the filename. This eliminates the need to build complex deduplication or DELETE logic in your pipeline.
Async Indexing and Polling
A successful 200 OK from the upload endpoint does not mean the document is ready for retrieval.
Voiceflow processes documents asynchronously. It must extract the text, chunk it into appropriate token lengths, and embed it into a vector database. For a 50-page PDF, this can take 30 to 60 seconds.
If you have a downstream process that relies on this document being ready, you must implement a polling mechanism.
You query the document status endpoint:
GET https://api.voiceflow.com/v1/knowledge-base/docs
This returns a list of your documents. You must loop through the response, match your specific document name, and check the status field. Your code should sleep and retry until the status transitions from "PROCESSING" to "READY".
Rate Limits and Error Handling
When automating high-volume uploads, you must respect the API rate limits. Voiceflow typically restricts KB operations. If you attempt to upload 50 PDFs in a tight loop, you will receive 429 Too Many Requests errors.
Your ingestion pipeline must implement exponential backoff. If you are using Make.com, this is handled via an Error Route set to "Break" or "Resume" after a designated sleep interval. If you are in Python, the tenacity library is highly recommended to wrap your upload function with automatic retry logic.