curl --request POST \ --url https://realtime-api.voiceflow.com/v1/stable/document/sitemap \ --header 'Authorization: Bearer <token>' --header 'Content-Type: application/json' \ --data '{ "sitemapURL": "<string>", "exclude": [ "<string>" ], "metadata": [], "refreshRate": "never", "folderID": "<string>" }'

{ "documents": [ { "id": "<string>", "data": "<KBDocumentData>", "status": { "type": "<KnowledgeBaseDocumentStatus>", "data": null }, "smartChunking": "<SmartChunking>", "folderID": "<string>" } ], "total": 0, "excluded": 0, "dropped": 0 }

Authorizations

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.

Show child attributes

Option 1

boolean

Option 2

enum<string>

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.

Show child attributes

Option 1

boolean

Option 2

enum<string>

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.

Show child attributes

Option 1

boolean

Option 2

enum<string>

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.

Show child attributes

Option 1

boolean

Option 2

enum<string>

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.

Show child attributes

Option 1

boolean

Option 2

enum<string>

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.

Show child attributes

Option 1

boolean

Option 2

enum<string>

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

metadata

object[]

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

Show child attributes

key

string

required

The name of the metadata field.

values

string[]

required

The values assigned to this metadata field.

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.

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

Show child attributes

string

required

data

object

required

Show child attributes

status

object

required

Show child attributes

type

object

required

Available options: ERROR, PENDING, SUCCESS, INITIALIZED

data

any

smartChunking

object

required

Show child attributes

markdownConversion

object

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

Show child attributes

Option 1

boolean

Option 2

enum<string>

llmBasedChunks

object

Show child attributes

Option 1

boolean

Option 2

enum<string>

llmGeneratedQ

object

Show child attributes

Option 1

boolean

Option 2

enum<string>

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.

Show child attributes

Option 1

boolean

Option 2

enum<string>

llmPrependContext

object

Show child attributes

Option 1

boolean

Option 2

enum<string>

singleChunk

object

Show child attributes

Option 1

boolean

Option 2

enum<string>

folderID

string

required

The ID of the Knowledge Base folder the document is filed under, or null when it sits at the top level.

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.

Getting started

Running agents

Build

Manage

Publishing

Observe

Insights

QA

Analytics

Webhooks

Create documents from sitemap

Authorizations

Query Parameters

Body

Response

Getting started

Running agents

Build

Manage

Publishing

Observe

Insights

QA

Analytics

Webhooks