Endpoint
GET
/v1/stable/document

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

sitemapDocumentID
string

When provided, only the pages imported by the sitemap document with this ID are returned.

Minimum length: 1

Response

200 - application/json

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.

documents
object[]
required
StableDocument — see its attributes above
Endpoint
GET
/v1/stable/document/changes

List the pages that sitemap syncs added or removed, and that refreshes found changed, in a date range.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

from
string
required

Only changes recorded at or after this ISO 8601 timestamp are returned.

to
string
required

Only changes recorded before this ISO 8601 timestamp are returned.

sitemapDocumentID
string

When provided, only changes to the pages of the sitemap document with this ID are returned.

Minimum length: 1
type
object

When provided, only changes of this type are returned.

cursor
string

The nextCursor of the previous page. Leave it out for the first page.

limit
integer

The most changes to return. Defaults to 500.

Minimum: 1 · Maximum: 500

Response

200 - application/json
changes
object[]
required

Newest first.

StableDocumentChange — see its attributes above
nextCursor
string

Present when more changes follow. Send it as cursor.

Endpoint
POST
/v1/stable/document/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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

maxChunkSize
object

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.

overwrite
object

If set to true, the existing table with the same name will be overwritten.

markdownConversion
object

When enabled, HTML is automatically converted to markdown to generate better chunks.

llmBasedChunks
object

Whether to split the document into chunks with a model rather than by fixed size.

llmGeneratedQ
object

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.

llmContentSummarization
object

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.

llmPrependContext
object

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.

singleChunk
object

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

url
string
required

The URL of the web page to crawl and ingest into the knowledge base.

metadata
object[]

Metadata tags attached to the document, used to filter knowledge base retrieval at runtime.

refreshRate
enum<string>

How often the URL is automatically re-crawled to refresh the document content.

Available options: daily, weekly, monthly, never
folderID
string

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.

Minimum length: 1

Response

201 - application/json

Returns the newly created document, including the ID assigned to it and the status of the import from the URL.

document
object
required
StableDocument — see its attributes above
Endpoint
POST
/v1/stable/document/text

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

maxChunkSize
object

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.

overwrite
object

If set to true, the existing table with the same name will be overwritten.

markdownConversion
object

When enabled, HTML is automatically converted to markdown to generate better chunks.

llmBasedChunks
object

Whether to split the document into chunks with a model rather than by fixed size.

llmGeneratedQ
object

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.

llmContentSummarization
object

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.

llmPrependContext
object

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.

singleChunk
object

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

201 - application/json

Returns the document created from the supplied text, with its assigned ID, its status, and the smart chunking settings the query parameters selected.

document
object
required
StableDocument — see its attributes above
Current - 2026/07
Endpoint
POST
/v1/stable/document/table

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

maxChunkSize
object

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.

overwrite
object

If set to true, the existing table with the same name will be overwritten.

markdownConversion
object

When enabled, HTML is automatically converted to markdown to generate better chunks.

llmBasedChunks
object

Whether to split the document into chunks with a model rather than by fixed size.

llmGeneratedQ
object

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.

llmContentSummarization
object

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.

llmPrependContext
object

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.

singleChunk
object

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

url
string

An optional source URL to associate with the table document.

name
string
required
items
object[]
required

The table rows to ingest; each row is a flat object and becomes its own chunk.

schema
object
required

Declares which top-level keys of each row are full-text searchable versus row-level metadata.

metadata
object[]

Metadata tags attached to the document, used to filter knowledge base retrieval at runtime.

folderID
string

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.

Minimum length: 1

Response

201 - application/json

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.

document
object
required
StableDocument — see its attributes above
Endpoint
POST
/v1/stable/document/sitemap/preview

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Query parameters

projectID
string
required

The ID of the project to operate on.

Request body

sitemapURL
string
required

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.

exclude
string[]

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).

Maximum items: 100

Response

200 - application/json

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.

urls
string[]
required

The URLs that would be imported, in sitemap order, capped at limit entries.

total
number
required

How many URLs the sitemap yields once exclude is applied, before the cap.

limit
number
required

The most URL documents this plan allows in a single import.

truncated
boolean
required

True when total is above limit, meaning urls is only part of what the sitemap holds.

excluded
number
required

How many valid URLs the exclude patterns removed. Zero when no patterns were given.

dropped
number
required

How many entries the sitemap listed that are not usable URLs and were skipped.

Endpoint
POST
/v1/stable/document/sitemap

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

markdownConversion
object

When enabled, HTML is automatically converted to markdown to generate better chunks.

llmBasedChunks
object

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.

llmGeneratedQ
object

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.

llmContentSummarization
object

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.

llmPrependContext
object

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.

singleChunk
object

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

sitemapURL
string
required

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.

exclude
string[]

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).

Maximum items: 100
metadata
object[]

Metadata tags attached to the document, used to filter knowledge base retrieval at runtime.

refreshRate
enum<string>
default:"never"

How often the URL is automatically re-crawled to refresh the document content.

Available options: daily, weekly, monthly, never
folderID
string

The 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.

Minimum length: 1

Response

201 - application/json

Returns the documents the import created or reused, a total count, and how many URLs were excluded by your patterns or dropped as unusable.

documents
object[]
required
StableDocument — see its attributes above
total
number
required

How many documents the import produced, counting reused ones.

excluded
number
required

How many valid URLs the exclude patterns removed. Zero when no patterns were given.

dropped
number
required

How many entries the sitemap listed that are not usable URLs and were skipped.

Endpoint
POST
/v1/stable/document/managed-sitemap

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

markdownConversion
object

When enabled, HTML is automatically converted to markdown to generate better chunks.

llmBasedChunks
object

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.

llmGeneratedQ
object

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.

llmContentSummarization
object

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.

llmPrependContext
object

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.

singleChunk
object

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

sitemapURL
string
required

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
object

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).

refreshRate
enum<string>
default:"never"

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.

Available options: daily, weekly, monthly, never
metadata
object[]

Metadata tags attached to the sitemap and to every page it imports, used to filter knowledge base retrieval at runtime.

folderID
string

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.

Minimum length: 1

Response

202 - application/json

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.

document
object
required
StableDocument — see its attributes above
Endpoint
PATCH
/v1/stable/document/managed-sitemap/{documentID}

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

documentID
string
required

The ID of the managed sitemap document to operate on.

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

Request body

patterns
object

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).

refreshRate
enum<string>

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.

Available options: daily, weekly, monthly, never
markdownConversion
object

When enabled, HTML is automatically converted to markdown to generate better chunks.

llmBasedChunks
object

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.

llmGeneratedQ
object

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.

llmContentSummarization
object

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.

llmPrependContext
object

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.

singleChunk
object

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

200 - application/json

Returns the updated sitemap document with its ID, status, data, smart chunking settings, and folder ID.

document
object
required
StableDocument — see its attributes above
Current - 2026/07
Endpoint
GET
/v1/stable/document/{documentID}

Returns a single document by ID, with the fields that define it. A document is a source the knowledge base retrieves from.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

documentID
string
required

The ID of the knowledge base document to operate on.

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

Response

200 - application/json

Returns one knowledge base document in full, adding its chunks and metadata to the data, status, and chunking settings the list operation reports.

document
object
required
StableDocumentDetails — see its attributes above
Current - 2026/07
Endpoint
DELETE
/v1/stable/document/{documentID}

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

documentID
string
required

The ID of the knowledge base document to operate on.

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

Response

200 - application/json

Confirms the document was removed from the knowledge base. The body is a message only, not a copy of the deleted document.

message
string
required

A human-readable message confirming the deletion.

Current - 2026/10
Endpoint
PATCH
/v2/stable/document/{documentID}

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

documentID
string
required

The ID of the knowledge base document to operate on.

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

Request body

metadata
object[]

Replaces the document's metadata tags. Leave it out to keep them.

folderID
string

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.

Minimum length: 1
content
string

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.

Minimum length: 1

Response

200 - application/json

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.

message
string
required

A human-readable message confirming the update.

Schemas

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.