Voiceflow bearer token
Documents
Manage the documents your agent searches.
See Authentication for credentials and permissions.
Returns every document in the knowledge base. A document is a source the knowledge base retrieves from. The call takes no paging parameters, so one request yields the whole set.
Authentication
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
When provided, only the pages imported by the sitemap document with this ID are returned.
Response
Returns every document in the project's knowledge base, each with its source data, status, and smart chunking settings. Chunks and metadata are left out, so read a document by ID for those.
List the pages that sitemap syncs added or removed, and that refreshes found changed, in a date range.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Only changes recorded at or after this ISO 8601 timestamp are returned.
Only changes recorded before this ISO 8601 timestamp are returned.
When provided, only changes to the pages of the sitemap document with this ID are returned.
When provided, only changes of this type are returned.
The nextCursor of the previous page. Leave it out for the first page.
The most changes to return. Defaults to 500.
Response
Present when more changes follow. Send it as cursor.
Adds a document to the knowledge base, a source the knowledge base retrieves from. The response carries the ID that later calls address it by.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Determines how granularly each document is broken up. Range available is 500-1500 tokens, default is 1000. Smaller chunk size means narrower context, faster response, less tokens consumed, and greater risk of less accurate answers. Max chunk size affects the total amount of chunks parsed from a document - i.e., larger chunks means less chunks retrieved.
If set to true, the existing table with the same name will be overwritten.
When enabled, HTML is automatically converted to markdown to generate better chunks.
Whether to split the document into chunks with a model rather than by fixed size.
When enabled, an LLM will be used to generate a question based on the document context and specific chunk, then prepend it to the chunk. This enhances retrieval by aligning chunks with potential user queries.
When enabled, an LLM summarizes and rewrites the content, removing unnecessary information and focusing on important parts to optimize for retrieval. Limited to 15 rows per table upload.
When enabled, an LLM generates a context summary based on the document and chunk context, and prepends it to each chunk. This improves retrieval by providing additional context to each chunk. Note: If both llmGeneratedQ and llmPrependContext are set to true, llmGeneratedQ takes precedence, and the context summarization will not be applied.
When enabled, the whole document is stored as a single chunk, so retrieval returns it in full. Documents above the embedding model input limit (about 30,000 characters) are split into chunks as usual. Takes precedence over llmBasedChunks.
Request body
The URL of the web page to crawl and ingest into the knowledge base.
Metadata tags attached to the document, used to filter knowledge base retrieval at runtime.
How often the URL is automatically re-crawled to refresh the document content.
daily, weekly, monthly, neverThe ID of the Knowledge Base folder to file the document under. Without it, a new document starts at the top level and a document this overwrites keeps its folder; move one to the top level with folderID: null on the document update. File names and URLs are unique across the whole Knowledge Base, not per folder, so an overwrite replaces the one document with that name or URL and, with folderID, moves it into this folder.
Response
Returns the newly created document, including the ID assigned to it and the status of the import from the URL.
Adds a document to the knowledge base, a source the knowledge base retrieves from. The response carries the ID that later calls address it by.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Determines how granularly each document is broken up. Range available is 500-1500 tokens, default is 1000. Smaller chunk size means narrower context, faster response, less tokens consumed, and greater risk of less accurate answers. Max chunk size affects the total amount of chunks parsed from a document - i.e., larger chunks means less chunks retrieved.
If set to true, the existing table with the same name will be overwritten.
When enabled, HTML is automatically converted to markdown to generate better chunks.
Whether to split the document into chunks with a model rather than by fixed size.
When enabled, an LLM will be used to generate a question based on the document context and specific chunk, then prepend it to the chunk. This enhances retrieval by aligning chunks with potential user queries.
When enabled, an LLM summarizes and rewrites the content, removing unnecessary information and focusing on important parts to optimize for retrieval. Limited to 15 rows per table upload.
When enabled, an LLM generates a context summary based on the document and chunk context, and prepends it to each chunk. This improves retrieval by providing additional context to each chunk. Note: If both llmGeneratedQ and llmPrependContext are set to true, llmGeneratedQ takes precedence, and the context summarization will not be applied.
When enabled, the whole document is stored as a single chunk, so retrieval returns it in full. Documents above the embedding model input limit (about 30,000 characters) are split into chunks as usual. Takes precedence over llmBasedChunks.
Response
Returns the document created from the supplied text, with its assigned ID, its status, and the smart chunking settings the query parameters selected.
Current - 2026/07
Adds a document to the knowledge base, a source the knowledge base retrieves from. The response carries the ID that later calls address it by.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Determines how granularly each document is broken up. Range available is 500-1500 tokens, default is 1000. Smaller chunk size means narrower context, faster response, less tokens consumed, and greater risk of less accurate answers. Max chunk size affects the total amount of chunks parsed from a document - i.e., larger chunks means less chunks retrieved.
If set to true, the existing table with the same name will be overwritten.
When enabled, HTML is automatically converted to markdown to generate better chunks.
Whether to split the document into chunks with a model rather than by fixed size.
When enabled, an LLM will be used to generate a question based on the document context and specific chunk, then prepend it to the chunk. This enhances retrieval by aligning chunks with potential user queries.
When enabled, an LLM summarizes and rewrites the content, removing unnecessary information and focusing on important parts to optimize for retrieval. Limited to 15 rows per table upload.
When enabled, an LLM generates a context summary based on the document and chunk context, and prepends it to each chunk. This improves retrieval by providing additional context to each chunk. Note: If both llmGeneratedQ and llmPrependContext are set to true, llmGeneratedQ takes precedence, and the context summarization will not be applied.
When enabled, the whole document is stored as a single chunk, so retrieval returns it in full. Documents above the embedding model input limit (about 30,000 characters) are split into chunks as usual. Takes precedence over llmBasedChunks.
Request body
An optional source URL to associate with the table document.
The table rows to ingest; each row is a flat object and becomes its own chunk.
Declares which top-level keys of each row are full-text searchable versus row-level metadata.
Metadata tags attached to the document, used to filter knowledge base retrieval at runtime.
The ID of the Knowledge Base folder to file the document under. Without it, a new document starts at the top level and a document this overwrites keeps its folder; move one to the top level with folderID: null on the document update. File names and URLs are unique across the whole Knowledge Base, not per folder, so an overwrite replaces the one document with that name or URL and, with folderID, moves it into this folder.
Response
Returns the document created from the structured data, with its assigned ID and status. The chunks it was split into are not in this response.
Reads a sitemap and returns the page URLs an import would turn into documents, without creating anything. Call it before creating from the sitemap to see the set, the plan's per-import limit, and whether the list was truncated.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
Request body
The HTTPS URL of the sitemap to read. A bare site URL works too — when it does not end in .xml, /sitemap.xml, /sitemap_index.xml and /sitemap/sitemap.xml are probed in turn.
Patterns that drop a URL from the import when any one of them matches. Matching is case-insensitive and unanchored: a pattern with no * matches any URL containing it as a substring (/blog/), while * matches any run of characters (*/tag/*, *.pdf).
Response
Returns the URLs an import would create, the total the sitemap yields after exclude, the per-import limit, whether the list was truncated, and the counts excluded and dropped.
The URLs that would be imported, in sitemap order, capped at limit entries.
How many URLs the sitemap yields once exclude is applied, before the cap.
The most URL documents this plan allows in a single import.
True when total is above limit, meaning urls is only part of what the sitemap holds.
How many valid URLs the exclude patterns removed. Zero when no patterns were given.
How many entries the sitemap listed that are not usable URLs and were skipped.
Reads a sitemap and creates one URL document for each page it lists, applying the same refreshRate, metadata, and folder to every document. These documents do not re-read the sitemap afterward; create a managed sitemap for a site that should stay current.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
When enabled, HTML is automatically converted to markdown to generate better chunks.
When enabled, an LLM groups the content into logical sections by topic instead of splitting it on a fixed size. Best for complex documents covering varied topics.
When enabled, an LLM will be used to generate a question based on the document context and specific chunk, then prepend it to the chunk. This enhances retrieval by aligning chunks with potential user queries.
When enabled, an LLM summarizes and rewrites the content, removing unnecessary information and focusing on important parts to optimize for retrieval. Limited to 15 rows per table upload.
When enabled, an LLM generates a context summary based on the document and chunk context, and prepends it to each chunk. This improves retrieval by providing additional context to each chunk. Note: If both llmGeneratedQ and llmPrependContext are set to true, llmGeneratedQ takes precedence, and the context summarization will not be applied.
When enabled, the whole document is stored as a single chunk, so retrieval returns it in full. Documents above the embedding model input limit (about 30,000 characters) are split into chunks as usual. Takes precedence over llmBasedChunks.
Request body
The HTTPS URL of the sitemap to read. A bare site URL works too — when it does not end in .xml, /sitemap.xml, /sitemap_index.xml and /sitemap/sitemap.xml are probed in turn.
Patterns that drop a URL from the import when any one of them matches. Matching is case-insensitive and unanchored: a pattern with no * matches any URL containing it as a substring (/blog/), while * matches any run of characters (*/tag/*, *.pdf).
Metadata tags attached to the document, used to filter knowledge base retrieval at runtime.
How often the URL is automatically re-crawled to refresh the document content.
daily, weekly, monthly, neverThe ID of the Knowledge Base folder to file every document the import creates or reuses under. Without it, new documents start at the top level and reused ones keep their folder.
Response
Returns the documents the import created or reused, a total count, and how many URLs were excluded by your patterns or dropped as unusable.
How many documents the import produced, counting reused ones.
How many valid URLs the exclude patterns removed. Zero when no patterns were given.
How many entries the sitemap listed that are not usable URLs and were skipped.
Creates one sitemap document that imports the pages its sitemap lists as URL documents and re-syncs them on refreshRate, adding newly listed pages and removing dropped ones. The response is the sitemap document with status PENDING; fetch it by ID to read its status and, on ERROR, data.sync.failure.message.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
When enabled, HTML is automatically converted to markdown to generate better chunks.
When enabled, an LLM groups the content into logical sections by topic instead of splitting it on a fixed size. Best for complex documents covering varied topics.
When enabled, an LLM will be used to generate a question based on the document context and specific chunk, then prepend it to the chunk. This enhances retrieval by aligning chunks with potential user queries.
When enabled, an LLM summarizes and rewrites the content, removing unnecessary information and focusing on important parts to optimize for retrieval. Limited to 15 rows per table upload.
When enabled, an LLM generates a context summary based on the document and chunk context, and prepends it to each chunk. This improves retrieval by providing additional context to each chunk. Note: If both llmGeneratedQ and llmPrependContext are set to true, llmGeneratedQ takes precedence, and the context summarization will not be applied.
When enabled, the whole document is stored as a single chunk, so retrieval returns it in full. Documents above the embedding model input limit (about 30,000 characters) are split into chunks as usual. Takes precedence over llmBasedChunks.
Request body
The HTTPS URL of the sitemap to read. A bare site URL works too — when it does not end in .xml, /sitemap.xml, /sitemap_index.xml and /sitemap/sitemap.xml are probed in turn.
Which of the pages the sitemap lists it keeps. Matching is case-insensitive and unanchored: a pattern with no * matches any URL containing it as a substring (/blog/), while * matches any run of characters (*/tag/*, *.pdf).
How often the sitemap is re-read to add the pages it newly lists and remove the ones it no longer does. Its pages are re-crawled on the same schedule.
daily, weekly, monthly, neverMetadata tags attached to the sitemap and to every page it imports, used to filter knowledge base retrieval at runtime.
The ID of the Knowledge Base folder to file the sitemap and the pages it imports under. Omit to create them at the top level.
Response
Returns the sitemap document with status PENDING; its pages are imported after the response, so fetch the document by ID to read its final status.
Changes the import settings of an existing managed sitemap: its include and exclude patterns, its refresh rate, and its smart chunking. A new set of patterns replaces the stored set whole and applies from the sitemap's next sync.
Authentication
Voiceflow bearer token
Path parameters
The ID of the managed sitemap document to operate on.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
Replaces the stored patterns whole, so send both lists even when changing one. Matching is case-insensitive and unanchored: a pattern with no * matches any URL containing it as a substring (/blog/), while * matches any run of characters (*/tag/*, *.pdf).
How often the sitemap is re-read to add the pages it newly lists and remove the ones it no longer does. Its pages are re-crawled on the same schedule. Also applied to the pages it has already imported.
daily, weekly, monthly, neverWhen enabled, HTML is automatically converted to markdown to generate better chunks.
When enabled, an LLM groups the content into logical sections by topic instead of splitting it on a fixed size. Best for complex documents covering varied topics.
When enabled, an LLM will be used to generate a question based on the document context and specific chunk, then prepend it to the chunk. This enhances retrieval by aligning chunks with potential user queries.
When enabled, an LLM summarizes and rewrites the content, removing unnecessary information and focusing on important parts to optimize for retrieval. Limited to 15 rows per table upload.
When enabled, an LLM generates a context summary based on the document and chunk context, and prepends it to each chunk. This improves retrieval by providing additional context to each chunk. Note: If both llmGeneratedQ and llmPrependContext are set to true, llmGeneratedQ takes precedence, and the context summarization will not be applied.
When enabled, the whole document is stored as a single chunk, so retrieval returns it in full. Documents above the embedding model input limit (about 30,000 characters) are split into chunks as usual. Takes precedence over llmBasedChunks.
Response
Returns the updated sitemap document with its ID, status, data, smart chunking settings, and folder ID.
Current - 2026/07
Returns a single document by ID, with the fields that define it. A document is a source the knowledge base retrieves from.
Authentication
Voiceflow bearer token
Path parameters
The ID of the knowledge base document to operate on.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Response
Returns one knowledge base document in full, adding its chunks and metadata to the data, status, and chunking settings the list operation reports.
Legacy - 2026/07
Changes an existing document in place. The response carries only a confirmation message, so refetch the document to read its new values.
Authentication
Voiceflow bearer token
Path parameters
The ID of the knowledge base document to operate on.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
Metadata tags attached to the document, used to filter knowledge base retrieval at runtime.
The ID of the Knowledge Base folder to move the document into, or null to move it to the top level.
Response
Confirms the document was updated. The response is a message rather than the revised document, so fetch it again to check its status or read the resulting chunks.
A human-readable message confirming the update.
Current - 2026/07
Deletes a single document by ID. A document is a source the knowledge base retrieves from. The response carries only a confirmation message, so refetch the documents to see what is left.
Authentication
Voiceflow bearer token
Path parameters
The ID of the knowledge base document to operate on.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Response
Confirms the document was removed from the knowledge base. The body is a message only, not a copy of the deleted document.
A human-readable message confirming the deletion.
Current - 2026/10
Replaces a text or markdown document's content or metadata tags, or moves it into another knowledge base folder (folderID null for the top level). New content replaces the whole text and is processed again under the same ID, so fetch the document until its status is SUCCESS.
Authentication
Voiceflow bearer token
Path parameters
The ID of the knowledge base document to operate on.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
Replaces the document's metadata tags. Leave it out to keep them.
The ID of the Knowledge Base folder to move the document into, or null to move it to the top level. Leave it out to keep its folder.
The whole new text of a text or markdown document. It replaces the stored text; the document keeps its ID and name and is processed again. Refused for every other document type.
Response
Confirms the update with a message. When content was replaced, the message says the document is being processed again, so fetch it by ID to see when it is searchable.
A human-readable message confirming the update.
Legacy - 2024/05
Fetch all chunks and metadata for the specified document.
Authentication
Voiceflow API key
Path parameters
ID of the document to target.
Query parameters
The alias of the environment to target (ie. main). You can find this in the environments page of your agent.
> 💡 Tip: Learn more about Environments.
Response
The target document was found.
Legacy - 2024/05
Remove a document from the knowledge base.
Authentication
Voiceflow API key
Path parameters
ID of the document to target.
Query parameters
The alias of the environment to target (ie. main). You can find this in the environments page of your agent.
> 💡 Tip: Learn more about Environments.
Response
The target document was deleted successfully.
Legacy - 2024/05
Upload a structured document to the knowledge base.
Authentication
Voiceflow API key
Query parameters
If set to true, the existing table with the same name will be overwritten.
When enabled, HTML is automatically converted to markdown to generate better chunks.
When enabled, an LLM will be used to generate a question based on the document context and specific chunk, then prepend it to the chunk. This enhances retrieval by aligning chunks with potential user queries.
When enabled, an LLM summarizes and rewrites the content, removing unnecessary information and focusing on important parts to optimize for retrieval. Limited to 15 rows per table upload.
When enabled, an LLM generates a context summary based on the document and chunk context, and prepends it to each chunk. This improves retrieval by providing additional context to each chunk. Note: If both llmGeneratedQ and llmPrependContext are set to true, llmGeneratedQ takes precedence, and the context summarization will not be applied.
Request body
Response
The document was uploaded successfully.