> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Documents

API operations for documents. Browse the routes below for parameters, request examples, and responses.

API version: Selected per operation

## List documents

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.

### Endpoint

```http
GET /v1/stable/document
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

#### `sitemapDocumentID`

Optional · string

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

```json
{
  "description": "When provided, only the pages imported by the sitemap document with this ID are returned.",
  "type": "string",
  "minLength": 1
}
```

### Responses

#### 200

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.

Schema:

```json
{
  "$ref": "#/components/schemas/StableDocumentListResponse"
}
```

Example:

```json
{
  "documents": [
    {
      "id": "<string>",
      "data": "<KBDocumentData>",
      "status": {
        "type": "<KnowledgeBaseDocumentStatus>",
        "data": null
      },
      "smartChunking": "<SmartChunking>",
      "folderID": "<string>"
    }
  ]
}
```

### Request examples

#### cURL

```bash
curl --request GET \
  --url 'https://realtime-api.voiceflow.com/v1/stable/document?projectID=<projectID>&environmentAlias=<environmentAlias>&sitemapDocumentID=<sitemapDocumentID>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/document?projectID=<projectID>&environmentAlias=<environmentAlias>&sitemapDocumentID=<sitemapDocumentID>', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.get(
    'https://realtime-api.voiceflow.com/v1/stable/document?projectID=<projectID>&environmentAlias=<environmentAlias>&sitemapDocumentID=<sitemapDocumentID>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf document list --project-id <projectID> --environment-alias <environmentAlias> --sitemap-document-id <sitemapDocumentID>
```


## List document changes

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

### Endpoint

```http
GET /v1/stable/document/changes
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

#### `from`

Required · string

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

```json
{
  "type": "string",
  "format": "date-time",
  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
  "description": "Only changes recorded at or after this ISO 8601 timestamp are returned."
}
```

#### `to`

Required · string

Only changes recorded before this ISO 8601 timestamp are returned.

```json
{
  "type": "string",
  "format": "date-time",
  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
  "description": "Only changes recorded before this ISO 8601 timestamp are returned."
}
```

#### `sitemapDocumentID`

Optional · string

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

```json
{
  "description": "When provided, only changes to the pages of the sitemap document with this ID are returned.",
  "type": "string",
  "minLength": 1
}
```

#### `type`

Optional · object

When provided, only changes of this type are returned.

```json
{
  "description": "When provided, only changes of this type are returned.",
  "allOf": [
    {
      "$ref": "#/components/schemas/KnowledgeBaseDocumentChangeType"
    }
  ]
}
```

#### `cursor`

Optional · string

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

```json
{
  "description": "The nextCursor of the previous page. Leave it out for the first page.",
  "type": "string"
}
```

#### `limit`

Optional · integer

The most changes to return. Defaults to 500.

```json
{
  "description": "The most changes to return. Defaults to 500.",
  "type": "integer",
  "minimum": 1,
  "maximum": 500
}
```

### Responses

#### 200

Schema:

```json
{
  "$ref": "#/components/schemas/StableDocumentChangeListResponse"
}
```

Example:

```json
{
  "changes": [
    {
      "date": "2026-09-10T00:00:00.000Z",
      "type": "<KnowledgeBaseDocumentChangeType>",
      "documentID": "<string>",
      "url": "<string>",
      "sitemapDocumentID": "<string>"
    }
  ],
  "nextCursor": "<string>"
}
```

### Request examples

#### cURL

```bash
curl --request GET \
  --url 'https://realtime-api.voiceflow.com/v1/stable/document/changes?projectID=<projectID>&environmentAlias=<environmentAlias>&from=<from>&to=<to>&sitemapDocumentID=<sitemapDocumentID>&type=<type>&cursor=<cursor>&limit=<limit>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/document/changes?projectID=<projectID>&environmentAlias=<environmentAlias>&from=<from>&to=<to>&sitemapDocumentID=<sitemapDocumentID>&type=<type>&cursor=<cursor>&limit=<limit>', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.get(
    'https://realtime-api.voiceflow.com/v1/stable/document/changes?projectID=<projectID>&environmentAlias=<environmentAlias>&from=<from>&to=<to>&sitemapDocumentID=<sitemapDocumentID>&type=<type>&cursor=<cursor>&limit=<limit>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf document list-changes --project-id <projectID> --environment-alias <environmentAlias> --from <from> --to <to> --sitemap-document-id <sitemapDocumentID> --type <type> --cursor <cursor> --limit <limit>
```


## Create URL document

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.

### Endpoint

```http
POST /v1/stable/document/url
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

#### `maxChunkSize`

Optional · 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.

```json
{
  "description": "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.",
  "anyOf": [
    {
      "type": "string"
    },
    {
      "type": "number"
    }
  ]
}
```

#### `overwrite`

Optional · object

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

```json
{
  "description": "If set to true, the existing table with the same name will be overwritten.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `markdownConversion`

Optional · object

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

```json
{
  "description": "When enabled, HTML is automatically converted to markdown to generate better chunks.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `llmBasedChunks`

Optional · object

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

```json
{
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `llmGeneratedQ`

Optional · 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.

```json
{
  "description": "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.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `llmContentSummarization`

Optional · 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.

```json
{
  "description": "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.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `llmPrependContext`

Optional · 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.

```json
{
  "description": "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.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `singleChunk`

Optional · 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.

```json
{
  "description": "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.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/StableDocumentCreateURLRequest"
      }
    }
  }
}
```

### Responses

#### 201

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

Schema:

```json
{
  "$ref": "#/components/schemas/StableDocumentResponse"
}
```

Example:

```json
{
  "document": {
    "id": "<string>",
    "data": "<KBDocumentUrlData>",
    "status": {
      "type": "ERROR",
      "data": null
    },
    "smartChunking": {
      "markdownConversion": true,
      "llmBasedChunks": true,
      "llmGeneratedQ": true,
      "llmContentSummarization": true,
      "llmPrependContext": true,
      "singleChunk": true
    },
    "folderID": "<string>"
  }
}
```

### Request examples

#### cURL

```bash
curl --request POST \
  --url 'https://realtime-api.voiceflow.com/v1/stable/document/url?projectID=<projectID>&environmentAlias=<environmentAlias>&maxChunkSize=<maxChunkSize>&overwrite=<overwrite>&markdownConversion=<markdownConversion>&llmBasedChunks=<llmBasedChunks>&llmGeneratedQ=<llmGeneratedQ>&llmContentSummarization=<llmContentSummarization>&llmPrependContext=<llmPrependContext>&singleChunk=<singleChunk>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "<string>",
  "metadata": [],
  "refreshRate": "daily",
  "folderID": "<string>"
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/document/url?projectID=<projectID>&environmentAlias=<environmentAlias>&maxChunkSize=<maxChunkSize>&overwrite=<overwrite>&markdownConversion=<markdownConversion>&llmBasedChunks=<llmBasedChunks>&llmGeneratedQ=<llmGeneratedQ>&llmContentSummarization=<llmContentSummarization>&llmPrependContext=<llmPrependContext>&singleChunk=<singleChunk>', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "url": "<string>",
    "metadata": [],
    "refreshRate": "daily",
    "folderID": "<string>"
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v1/stable/document/url?projectID=<projectID>&environmentAlias=<environmentAlias>&maxChunkSize=<maxChunkSize>&overwrite=<overwrite>&markdownConversion=<markdownConversion>&llmBasedChunks=<llmBasedChunks>&llmGeneratedQ=<llmGeneratedQ>&llmContentSummarization=<llmContentSummarization>&llmPrependContext=<llmPrependContext>&singleChunk=<singleChunk>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "url": "<string>",
      "metadata": [],
      "refreshRate": "daily",
      "folderID": "<string>"
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf document create-url --project-id <projectID> --environment-alias <environmentAlias> --max-chunk-size <maxChunkSize> --overwrite <overwrite> --markdown-conversion <markdownConversion> --llm-based-chunks <llmBasedChunks> --llm-generated-q <llmGeneratedQ> --llm-content-summarization <llmContentSummarization> --llm-prepend-context <llmPrependContext> --single-chunk <singleChunk> <<'JSON'
{
  "url": "<string>",
  "metadata": [],
  "refreshRate": "daily",
  "folderID": "<string>"
}
JSON
```


## Create text document

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.

### Endpoint

```http
POST /v1/stable/document/text
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

#### `maxChunkSize`

Optional · 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.

```json
{
  "description": "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.",
  "anyOf": [
    {
      "type": "string"
    },
    {
      "type": "number"
    }
  ]
}
```

#### `overwrite`

Optional · object

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

```json
{
  "description": "If set to true, the existing table with the same name will be overwritten.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `markdownConversion`

Optional · object

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

```json
{
  "description": "When enabled, HTML is automatically converted to markdown to generate better chunks.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `llmBasedChunks`

Optional · object

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

```json
{
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `llmGeneratedQ`

Optional · 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.

```json
{
  "description": "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.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `llmContentSummarization`

Optional · 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.

```json
{
  "description": "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.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `llmPrependContext`

Optional · 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.

```json
{
  "description": "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.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `singleChunk`

Optional · 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.

```json
{
  "description": "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.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "multipart/form-data": {
      "schema": {
        "type": "object",
        "properties": {
          "url": {
            "description": "An optional source URL to associate with the uploaded document.",
            "type": "string"
          },
          "canEdit": {
            "default": false,
            "description": "If true, the document content can be edited in the Creator after upload.",
            "type": "boolean"
          },
          "metadata": {
            "description": "A JSON-encoded array of `{ key, values }` metadata tags attached to the document, used to filter knowledge base retrieval at runtime.",
            "type": "string"
          },
          "folderID": {
            "description": "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.",
            "type": "string",
            "minLength": 1
          },
          "file": {
            "type": "string",
            "format": "binary"
          }
        },
        "required": [
          "file"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Responses

#### 201

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

Schema:

```json
{
  "$ref": "#/components/schemas/StableDocumentResponse"
}
```

Example:

```json
{
  "document": {
    "id": "<string>",
    "data": "<KBDocumentUrlData>",
    "status": {
      "type": "ERROR",
      "data": null
    },
    "smartChunking": {
      "markdownConversion": true,
      "llmBasedChunks": true,
      "llmGeneratedQ": true,
      "llmContentSummarization": true,
      "llmPrependContext": true,
      "singleChunk": true
    },
    "folderID": "<string>"
  }
}
```

### Request examples

#### cURL

```bash
curl --request POST \
  --url 'https://realtime-api.voiceflow.com/v1/stable/document/text?projectID=<projectID>&environmentAlias=<environmentAlias>&maxChunkSize=<maxChunkSize>&overwrite=<overwrite>&markdownConversion=<markdownConversion>&llmBasedChunks=<llmBasedChunks>&llmGeneratedQ=<llmGeneratedQ>&llmContentSummarization=<llmContentSummarization>&llmPrependContext=<llmPrependContext>&singleChunk=<singleChunk>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/document/text?projectID=<projectID>&environmentAlias=<environmentAlias>&maxChunkSize=<maxChunkSize>&overwrite=<overwrite>&markdownConversion=<markdownConversion>&llmBasedChunks=<llmBasedChunks>&llmGeneratedQ=<llmGeneratedQ>&llmContentSummarization=<llmContentSummarization>&llmPrependContext=<llmPrependContext>&singleChunk=<singleChunk>', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v1/stable/document/text?projectID=<projectID>&environmentAlias=<environmentAlias>&maxChunkSize=<maxChunkSize>&overwrite=<overwrite>&markdownConversion=<markdownConversion>&llmBasedChunks=<llmBasedChunks>&llmGeneratedQ=<llmGeneratedQ>&llmContentSummarization=<llmContentSummarization>&llmPrependContext=<llmPrependContext>&singleChunk=<singleChunk>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf document create-text --project-id <projectID> --environment-alias <environmentAlias> --max-chunk-size <maxChunkSize> --overwrite <overwrite> --markdown-conversion <markdownConversion> --llm-based-chunks <llmBasedChunks> --llm-generated-q <llmGeneratedQ> --llm-content-summarization <llmContentSummarization> --llm-prepend-context <llmPrependContext> --single-chunk <singleChunk>
```


## Create table document

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.

### Endpoint

```http
POST /v1/stable/document/table
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

#### `maxChunkSize`

Optional · 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.

```json
{
  "description": "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.",
  "anyOf": [
    {
      "type": "string"
    },
    {
      "type": "number"
    }
  ]
}
```

#### `overwrite`

Optional · object

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

```json
{
  "description": "If set to true, the existing table with the same name will be overwritten.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `markdownConversion`

Optional · object

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

```json
{
  "description": "When enabled, HTML is automatically converted to markdown to generate better chunks.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `llmBasedChunks`

Optional · object

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

```json
{
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `llmGeneratedQ`

Optional · 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.

```json
{
  "description": "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.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `llmContentSummarization`

Optional · 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.

```json
{
  "description": "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.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `llmPrependContext`

Optional · 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.

```json
{
  "description": "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.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `singleChunk`

Optional · 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.

```json
{
  "description": "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.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/StableDocumentCreateTableRequest"
      }
    }
  }
}
```

### Responses

#### 201

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.

Schema:

```json
{
  "$ref": "#/components/schemas/StableDocumentResponse"
}
```

Example:

```json
{
  "document": {
    "id": "<string>",
    "data": "<KBDocumentUrlData>",
    "status": {
      "type": "ERROR",
      "data": null
    },
    "smartChunking": {
      "markdownConversion": true,
      "llmBasedChunks": true,
      "llmGeneratedQ": true,
      "llmContentSummarization": true,
      "llmPrependContext": true,
      "singleChunk": true
    },
    "folderID": "<string>"
  }
}
```

### Request examples

#### cURL

```bash
curl --request POST \
  --url 'https://realtime-api.voiceflow.com/v1/stable/document/table?projectID=<projectID>&environmentAlias=<environmentAlias>&maxChunkSize=<maxChunkSize>&overwrite=<overwrite>&markdownConversion=<markdownConversion>&llmBasedChunks=<llmBasedChunks>&llmGeneratedQ=<llmGeneratedQ>&llmContentSummarization=<llmContentSummarization>&llmPrependContext=<llmPrependContext>&singleChunk=<singleChunk>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "<string>",
  "name": "<string>",
  "items": [
    {}
  ],
  "schema": {
    "metadataFields": [],
    "searchableFields": [
      "<string>"
    ]
  },
  "metadata": [],
  "folderID": "<string>"
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/document/table?projectID=<projectID>&environmentAlias=<environmentAlias>&maxChunkSize=<maxChunkSize>&overwrite=<overwrite>&markdownConversion=<markdownConversion>&llmBasedChunks=<llmBasedChunks>&llmGeneratedQ=<llmGeneratedQ>&llmContentSummarization=<llmContentSummarization>&llmPrependContext=<llmPrependContext>&singleChunk=<singleChunk>', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "url": "<string>",
    "name": "<string>",
    "items": [
      {}
    ],
    "schema": {
      "metadataFields": [],
      "searchableFields": [
        "<string>"
      ]
    },
    "metadata": [],
    "folderID": "<string>"
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v1/stable/document/table?projectID=<projectID>&environmentAlias=<environmentAlias>&maxChunkSize=<maxChunkSize>&overwrite=<overwrite>&markdownConversion=<markdownConversion>&llmBasedChunks=<llmBasedChunks>&llmGeneratedQ=<llmGeneratedQ>&llmContentSummarization=<llmContentSummarization>&llmPrependContext=<llmPrependContext>&singleChunk=<singleChunk>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "url": "<string>",
      "name": "<string>",
      "items": [
        {}
      ],
      "schema": {
        "metadataFields": [],
        "searchableFields": [
          "<string>"
        ]
      },
      "metadata": [],
      "folderID": "<string>"
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf document create-table --project-id <projectID> --environment-alias <environmentAlias> --max-chunk-size <maxChunkSize> --overwrite <overwrite> --markdown-conversion <markdownConversion> --llm-based-chunks <llmBasedChunks> --llm-generated-q <llmGeneratedQ> --llm-content-summarization <llmContentSummarization> --llm-prepend-context <llmPrependContext> --single-chunk <singleChunk> <<'JSON'
{
  "url": "<string>",
  "name": "<string>",
  "items": [
    {}
  ],
  "schema": {
    "metadataFields": [],
    "searchableFields": [
      "<string>"
    ]
  },
  "metadata": [],
  "folderID": "<string>"
}
JSON
```


## Preview sitemap URLs

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.

### Endpoint

```http
POST /v1/stable/document/sitemap/preview
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/StableDocumentSitemapRequest"
      }
    }
  }
}
```

### Responses

#### 200

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.

Schema:

```json
{
  "$ref": "#/components/schemas/StableDocumentSitemapPreviewResponse"
}
```

Example:

```json
{
  "urls": [
    "<string>"
  ],
  "total": 0,
  "limit": 0,
  "truncated": true,
  "excluded": 0,
  "dropped": 0
}
```

### Request examples

#### cURL

```bash
curl --request POST \
  --url 'https://realtime-api.voiceflow.com/v1/stable/document/sitemap/preview?projectID=<projectID>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "sitemapURL": "<string>",
  "exclude": [
    "<string>"
  ]
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/document/sitemap/preview?projectID=<projectID>', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "sitemapURL": "<string>",
    "exclude": [
      "<string>"
    ]
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v1/stable/document/sitemap/preview?projectID=<projectID>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "sitemapURL": "<string>",
      "exclude": [
        "<string>"
      ]
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf document preview-sitemap --project-id <projectID> <<'JSON'
{
  "sitemapURL": "<string>",
  "exclude": [
    "<string>"
  ]
}
JSON
```


## Create documents from 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.

### Endpoint

```http
POST /v1/stable/document/sitemap
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

#### `markdownConversion`

Optional · object

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

```json
{
  "description": "When enabled, HTML is automatically converted to markdown to generate better chunks.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `llmBasedChunks`

Optional · 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.

```json
{
  "description": "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.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `llmGeneratedQ`

Optional · 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.

```json
{
  "description": "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.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `llmContentSummarization`

Optional · 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.

```json
{
  "description": "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.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `llmPrependContext`

Optional · 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.

```json
{
  "description": "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.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `singleChunk`

Optional · 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.

```json
{
  "description": "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.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/StableDocumentCreateSitemapRequest"
      }
    }
  }
}
```

### Responses

#### 201

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

Schema:

```json
{
  "$ref": "#/components/schemas/StableDocumentSitemapCreateResponse"
}
```

Example:

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

### Request examples

#### cURL

```bash
curl --request POST \
  --url 'https://realtime-api.voiceflow.com/v1/stable/document/sitemap?projectID=<projectID>&environmentAlias=<environmentAlias>&markdownConversion=<markdownConversion>&llmBasedChunks=<llmBasedChunks>&llmGeneratedQ=<llmGeneratedQ>&llmContentSummarization=<llmContentSummarization>&llmPrependContext=<llmPrependContext>&singleChunk=<singleChunk>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "sitemapURL": "<string>",
  "exclude": [
    "<string>"
  ],
  "metadata": [],
  "refreshRate": "never",
  "folderID": "<string>"
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/document/sitemap?projectID=<projectID>&environmentAlias=<environmentAlias>&markdownConversion=<markdownConversion>&llmBasedChunks=<llmBasedChunks>&llmGeneratedQ=<llmGeneratedQ>&llmContentSummarization=<llmContentSummarization>&llmPrependContext=<llmPrependContext>&singleChunk=<singleChunk>', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "sitemapURL": "<string>",
    "exclude": [
      "<string>"
    ],
    "metadata": [],
    "refreshRate": "never",
    "folderID": "<string>"
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v1/stable/document/sitemap?projectID=<projectID>&environmentAlias=<environmentAlias>&markdownConversion=<markdownConversion>&llmBasedChunks=<llmBasedChunks>&llmGeneratedQ=<llmGeneratedQ>&llmContentSummarization=<llmContentSummarization>&llmPrependContext=<llmPrependContext>&singleChunk=<singleChunk>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "sitemapURL": "<string>",
      "exclude": [
        "<string>"
      ],
      "metadata": [],
      "refreshRate": "never",
      "folderID": "<string>"
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf document create-sitemap --project-id <projectID> --environment-alias <environmentAlias> --markdown-conversion <markdownConversion> --llm-based-chunks <llmBasedChunks> --llm-generated-q <llmGeneratedQ> --llm-content-summarization <llmContentSummarization> --llm-prepend-context <llmPrependContext> --single-chunk <singleChunk> <<'JSON'
{
  "sitemapURL": "<string>",
  "exclude": [
    "<string>"
  ],
  "metadata": [],
  "refreshRate": "never",
  "folderID": "<string>"
}
JSON
```


## Create 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`.

### Endpoint

```http
POST /v1/stable/document/managed-sitemap
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

#### `markdownConversion`

Optional · object

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

```json
{
  "description": "When enabled, HTML is automatically converted to markdown to generate better chunks.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `llmBasedChunks`

Optional · 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.

```json
{
  "description": "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.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `llmGeneratedQ`

Optional · 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.

```json
{
  "description": "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.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `llmContentSummarization`

Optional · 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.

```json
{
  "description": "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.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `llmPrependContext`

Optional · 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.

```json
{
  "description": "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.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

#### `singleChunk`

Optional · 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.

```json
{
  "description": "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.",
  "anyOf": [
    {
      "type": "boolean"
    },
    {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "x-enumNames": [
        "TRUE",
        "FALSE"
      ]
    }
  ]
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/StableDocumentCreateManagedSitemapRequest"
      }
    }
  }
}
```

### Responses

#### 202

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.

Schema:

```json
{
  "$ref": "#/components/schemas/StableDocumentResponse"
}
```

Example:

```json
{
  "document": {
    "id": "<string>",
    "data": "<KBDocumentUrlData>",
    "status": {
      "type": "ERROR",
      "data": null
    },
    "smartChunking": {
      "markdownConversion": true,
      "llmBasedChunks": true,
      "llmGeneratedQ": true,
      "llmContentSummarization": true,
      "llmPrependContext": true,
      "singleChunk": true
    },
    "folderID": "<string>"
  }
}
```

### Request examples

#### cURL

```bash
curl --request POST \
  --url 'https://realtime-api.voiceflow.com/v1/stable/document/managed-sitemap?projectID=<projectID>&environmentAlias=<environmentAlias>&markdownConversion=<markdownConversion>&llmBasedChunks=<llmBasedChunks>&llmGeneratedQ=<llmGeneratedQ>&llmContentSummarization=<llmContentSummarization>&llmPrependContext=<llmPrependContext>&singleChunk=<singleChunk>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "sitemapURL": "<string>",
  "patterns": {
    "include": [],
    "exclude": []
  },
  "refreshRate": "never",
  "metadata": [],
  "folderID": "<string>"
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/document/managed-sitemap?projectID=<projectID>&environmentAlias=<environmentAlias>&markdownConversion=<markdownConversion>&llmBasedChunks=<llmBasedChunks>&llmGeneratedQ=<llmGeneratedQ>&llmContentSummarization=<llmContentSummarization>&llmPrependContext=<llmPrependContext>&singleChunk=<singleChunk>', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "sitemapURL": "<string>",
    "patterns": {
      "include": [],
      "exclude": []
    },
    "refreshRate": "never",
    "metadata": [],
    "folderID": "<string>"
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v1/stable/document/managed-sitemap?projectID=<projectID>&environmentAlias=<environmentAlias>&markdownConversion=<markdownConversion>&llmBasedChunks=<llmBasedChunks>&llmGeneratedQ=<llmGeneratedQ>&llmContentSummarization=<llmContentSummarization>&llmPrependContext=<llmPrependContext>&singleChunk=<singleChunk>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "sitemapURL": "<string>",
      "patterns": {
        "include": [],
        "exclude": []
      },
      "refreshRate": "never",
      "metadata": [],
      "folderID": "<string>"
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf document create-managed-sitemap --project-id <projectID> --environment-alias <environmentAlias> --markdown-conversion <markdownConversion> --llm-based-chunks <llmBasedChunks> --llm-generated-q <llmGeneratedQ> --llm-content-summarization <llmContentSummarization> --llm-prepend-context <llmPrependContext> --single-chunk <singleChunk> <<'JSON'
{
  "sitemapURL": "<string>",
  "patterns": {
    "include": [],
    "exclude": []
  },
  "refreshRate": "never",
  "metadata": [],
  "folderID": "<string>"
}
JSON
```


## Update managed sitemap

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.

### Endpoint

```http
PATCH /v1/stable/document/managed-sitemap/{documentID}
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `documentID`

Required · string

The ID of the managed sitemap document to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "allOf": [
          {
            "$ref": "#/components/schemas/StableDocumentUpdateManagedSitemapRequest"
          }
        ]
      }
    }
  }
}
```

### Responses

#### 200

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

Schema:

```json
{
  "$ref": "#/components/schemas/StableDocumentResponse"
}
```

Example:

```json
{
  "document": {
    "id": "<string>",
    "data": "<KBDocumentUrlData>",
    "status": {
      "type": "ERROR",
      "data": null
    },
    "smartChunking": {
      "markdownConversion": true,
      "llmBasedChunks": true,
      "llmGeneratedQ": true,
      "llmContentSummarization": true,
      "llmPrependContext": true,
      "singleChunk": true
    },
    "folderID": "<string>"
  }
}
```

### Request examples

#### cURL

```bash
curl --request PATCH \
  --url 'https://realtime-api.voiceflow.com/v1/stable/document/managed-sitemap/<documentID>?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "patterns": {
    "include": [
      "<string>"
    ],
    "exclude": [
      "<string>"
    ]
  },
  "refreshRate": "daily",
  "markdownConversion": true,
  "llmBasedChunks": true,
  "llmGeneratedQ": true,
  "llmContentSummarization": true,
  "llmPrependContext": true,
  "singleChunk": true
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/document/managed-sitemap/<documentID>?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "patterns": {
      "include": [
        "<string>"
      ],
      "exclude": [
        "<string>"
      ]
    },
    "refreshRate": "daily",
    "markdownConversion": true,
    "llmBasedChunks": true,
    "llmGeneratedQ": true,
    "llmContentSummarization": true,
    "llmPrependContext": true,
    "singleChunk": true
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.patch(
    'https://realtime-api.voiceflow.com/v1/stable/document/managed-sitemap/<documentID>?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "patterns": {
        "include": [
          "<string>"
        ],
        "exclude": [
          "<string>"
        ]
      },
      "refreshRate": "daily",
      "markdownConversion": True,
      "llmBasedChunks": True,
      "llmGeneratedQ": True,
      "llmContentSummarization": True,
      "llmPrependContext": True,
      "singleChunk": True
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf document update-managed-sitemap --document-id <documentID> --project-id <projectID> --environment-alias <environmentAlias> <<'JSON'
{
  "patterns": {
    "include": [
      "<string>"
    ],
    "exclude": [
      "<string>"
    ]
  },
  "refreshRate": "daily",
  "markdownConversion": true,
  "llmBasedChunks": true,
  "llmGeneratedQ": true,
  "llmContentSummarization": true,
  "llmPrependContext": true,
  "singleChunk": true
}
JSON
```


## Get document

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

### Endpoint

```http
GET /v1/stable/document/{documentID}
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `documentID`

Required · string

The ID of the knowledge base document to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Responses

#### 200

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

Schema:

```json
{
  "$ref": "#/components/schemas/StableDocumentDetailsResponse"
}
```

Example:

```json
{
  "document": {
    "id": "<string>",
    "data": "<KBDocumentUrlData>",
    "status": {
      "type": "ERROR",
      "data": null
    },
    "smartChunking": {
      "markdownConversion": true,
      "llmBasedChunks": true,
      "llmGeneratedQ": true,
      "llmContentSummarization": true,
      "llmPrependContext": true,
      "singleChunk": true
    },
    "folderID": "<string>",
    "chunks": [
      {
        "chunkID": "<string>",
        "content": "<string>",
        "metadata": {}
      }
    ],
    "metadata": [
      {
        "key": "<string>",
        "values": [
          "<string>"
        ]
      }
    ]
  }
}
```

### Request examples

#### cURL

```bash
curl --request GET \
  --url 'https://realtime-api.voiceflow.com/v1/stable/document/<documentID>?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/document/<documentID>?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.get(
    'https://realtime-api.voiceflow.com/v1/stable/document/<documentID>?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf document get --document-id <documentID> --project-id <projectID> --environment-alias <environmentAlias>
```


## Delete document

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.

### Endpoint

```http
DELETE /v1/stable/document/{documentID}
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `documentID`

Required · string

The ID of the knowledge base document to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Responses

#### 200

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

Schema:

```json
{
  "$ref": "#/components/schemas/StableDeleteResponse"
}
```

Example:

```json
{
  "message": "<string>"
}
```

### Request examples

#### cURL

```bash
curl --request DELETE \
  --url 'https://realtime-api.voiceflow.com/v1/stable/document/<documentID>?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/document/<documentID>?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.delete(
    'https://realtime-api.voiceflow.com/v1/stable/document/<documentID>?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf document delete --document-id <documentID> --project-id <projectID> --environment-alias <environmentAlias>
```


## Update document

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.

### Endpoint

```http
PATCH /v2/stable/document/{documentID}
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `documentID`

Required · string

The ID of the knowledge base document to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

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

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "allOf": [
          {
            "$ref": "#/components/schemas/StableDocumentUpdateRequestV2"
          }
        ]
      }
    }
  }
}
```

### Responses

#### 200

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.

Schema:

```json
{
  "$ref": "#/components/schemas/StableUpdateResponse"
}
```

Example:

```json
{
  "message": "<string>"
}
```

### Request examples

#### cURL

```bash
curl --request PATCH \
  --url 'https://realtime-api.voiceflow.com/v2/stable/document/<documentID>?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "metadata": [
    {
      "key": "<string>",
      "values": [
        "<string>"
      ]
    }
  ],
  "folderID": "<string>",
  "content": "<string>"
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v2/stable/document/<documentID>?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "metadata": [
      {
        "key": "<string>",
        "values": [
          "<string>"
        ]
      }
    ],
    "folderID": "<string>",
    "content": "<string>"
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.patch(
    'https://realtime-api.voiceflow.com/v2/stable/document/<documentID>?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "metadata": [
        {
          "key": "<string>",
          "values": [
            "<string>"
          ]
        }
      ],
      "folderID": "<string>",
      "content": "<string>"
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf document update --document-id <documentID> --project-id <projectID> --environment-alias <environmentAlias> <<'JSON'
{
  "metadata": [
    {
      "key": "<string>",
      "values": [
        "<string>"
      ]
    }
  ],
  "folderID": "<string>",
  "content": "<string>"
}
JSON
```


## Schema definitions

### KBDocumentCSVData

```json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "csv"
      ],
      "x-enumNames": [
        "CSV"
      ]
    },
    "name": {
      "type": "string"
    },
    "rowsCount": {
      "type": "number"
    },
    "url": {
      "nullable": true,
      "type": "string"
    }
  },
  "required": [
    "type",
    "name"
  ]
}
```

### KBDocumentChunk

```json
{
  "type": "object",
  "properties": {
    "chunkID": {
      "type": "string"
    },
    "content": {
      "type": "string"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {}
    }
  },
  "required": [
    "chunkID",
    "content"
  ]
}
```

### KBDocumentData

```json
{
  "oneOf": [
    {
      "$ref": "#/components/schemas/KBDocumentUrlData"
    },
    {
      "$ref": "#/components/schemas/KBDocumentDocxData"
    },
    {
      "$ref": "#/components/schemas/KBDocumentPDFData"
    },
    {
      "$ref": "#/components/schemas/KBDocumentTextData"
    },
    {
      "$ref": "#/components/schemas/KBDocumentMarkdownData"
    },
    {
      "$ref": "#/components/schemas/KBDocumentCSVData"
    },
    {
      "$ref": "#/components/schemas/KBDocumentXLSXData"
    },
    {
      "$ref": "#/components/schemas/KBDocumentTableData"
    },
    {
      "$ref": "#/components/schemas/KBDocumentSitemapData"
    },
    {
      "$ref": "#/components/schemas/KBDocumentIntegrationData"
    }
  ]
}
```

### KBDocumentDocxData

```json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "docx"
      ],
      "x-enumNames": [
        "DOCX"
      ]
    },
    "name": {
      "type": "string"
    },
    "url": {
      "nullable": true,
      "type": "string"
    }
  },
  "required": [
    "type",
    "name"
  ]
}
```

### KBDocumentIntegrationConfig

```json
{
  "type": "object",
  "properties": {
    "filters": {
      "type": "object",
      "additionalProperties": {}
    },
    "preserveStructure": {
      "type": "boolean"
    },
    "importMetadata": {
      "type": "boolean"
    },
    "connection": {
      "type": "object",
      "properties": {
        "fingerprint": {
          "type": "string"
        }
      },
      "required": [
        "fingerprint"
      ]
    },
    "exclude": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "key",
          "name"
        ]
      }
    }
  },
  "required": [
    "filters",
    "preserveStructure",
    "importMetadata",
    "connection",
    "exclude"
  ]
}
```

### KBDocumentIntegrationData

```json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "integration"
      ],
      "x-enumNames": [
        "INTEGRATION"
      ]
    },
    "name": {
      "type": "string"
    },
    "source": {
      "$ref": "#/components/schemas/KnowledgeBaseDocumentIntegrationType"
    },
    "config": {
      "$ref": "#/components/schemas/KBDocumentIntegrationConfig"
    },
    "refreshRate": {
      "allOf": [
        {
          "$ref": "#/components/schemas/KnowledgeBaseDocumentRefreshRate"
        }
      ]
    },
    "lastSuccessUpdate": {
      "type": "string"
    },
    "sync": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/KBDocumentSitemapSync"
        }
      ]
    }
  },
  "required": [
    "type",
    "name",
    "source",
    "config"
  ]
}
```

### KBDocumentMarkdownData

```json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "md"
      ],
      "x-enumNames": [
        "MD"
      ]
    },
    "name": {
      "type": "string"
    },
    "url": {
      "nullable": true,
      "type": "string"
    }
  },
  "required": [
    "type",
    "name"
  ]
}
```

### KBDocumentPDFData

```json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "pdf"
      ],
      "x-enumNames": [
        "PDF"
      ]
    },
    "name": {
      "type": "string"
    },
    "url": {
      "nullable": true,
      "type": "string"
    }
  },
  "required": [
    "type",
    "name"
  ]
}
```

### KBDocumentSitemapData

```json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "sitemap"
      ],
      "x-enumNames": [
        "SITEMAP"
      ]
    },
    "name": {
      "type": "string"
    },
    "url": {
      "type": "string"
    },
    "refreshRate": {
      "allOf": [
        {
          "$ref": "#/components/schemas/KnowledgeBaseDocumentRefreshRate"
        }
      ]
    },
    "refreshTime": {
      "nullable": true,
      "type": "string",
      "pattern": "^([01]\\d|2[0-3]):(00|30)$"
    },
    "refreshTimezone": {
      "nullable": true,
      "type": "string"
    },
    "lastSuccessUpdate": {
      "type": "string"
    },
    "lastRefreshScheduledFor": {
      "nullable": true,
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "patterns": {
      "allOf": [
        {
          "$ref": "#/components/schemas/KBDocumentSitemapPatterns"
        }
      ]
    },
    "sync": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/KBDocumentSitemapSync"
        }
      ]
    }
  },
  "required": [
    "type",
    "name",
    "url"
  ]
}
```

### KBDocumentSitemapPatterns

```json
{
  "type": "object",
  "properties": {
    "include": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "exclude": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "include",
    "exclude"
  ]
}
```

### KBDocumentSitemapSync

```json
{
  "type": "object",
  "properties": {
    "syncedAt": {
      "type": "string"
    },
    "startedAt": {
      "nullable": true,
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "addedCount": {
      "type": "number"
    },
    "removedCount": {
      "type": "number"
    },
    "failure": {
      "nullable": true,
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        },
        "at": {
          "type": "string"
        },
        "code": {
          "allOf": [
            {
              "$ref": "#/components/schemas/KBDocumentSitemapSyncFailureCode"
            }
          ]
        }
      },
      "required": [
        "message",
        "at"
      ]
    }
  },
  "required": [
    "syncedAt",
    "addedCount",
    "removedCount"
  ]
}
```

### KBDocumentSitemapSyncFailureCode

```json
{
  "type": "string",
  "enum": [
    "documentLimit",
    "integrationDisconnected",
    "integrationUnauthorized",
    "integrationAccountChanged",
    "rateLimited"
  ],
  "x-enumNames": [
    "DOCUMENT_LIMIT",
    "INTEGRATION_DISCONNECTED",
    "INTEGRATION_UNAUTHORIZED",
    "INTEGRATION_ACCOUNT_CHANGED",
    "RATE_LIMITED"
  ]
}
```

### KBDocumentStatus

```json
{
  "type": "object",
  "properties": {
    "type": {
      "$ref": "#/components/schemas/KnowledgeBaseDocumentStatus"
    },
    "data": {}
  },
  "required": [
    "type"
  ]
}
```

### KBDocumentTableData

```json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "table"
      ],
      "x-enumNames": [
        "TABLE"
      ]
    },
    "name": {
      "type": "string"
    },
    "rowsCount": {
      "type": "number"
    },
    "url": {
      "nullable": true,
      "type": "string"
    }
  },
  "required": [
    "type",
    "name",
    "rowsCount"
  ]
}
```

### KBDocumentTextData

```json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "text"
      ],
      "x-enumNames": [
        "TEXT"
      ]
    },
    "name": {
      "type": "string"
    },
    "canEdit": {
      "type": "boolean"
    },
    "url": {
      "nullable": true,
      "type": "string"
    }
  },
  "required": [
    "type",
    "name"
  ]
}
```

### KBDocumentUrlData

```json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "url"
      ],
      "x-enumNames": [
        "URL"
      ]
    },
    "name": {
      "type": "string"
    },
    "url": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "refreshRate": {
      "allOf": [
        {
          "$ref": "#/components/schemas/KnowledgeBaseDocumentRefreshRate"
        }
      ]
    },
    "refreshTime": {
      "nullable": true,
      "type": "string",
      "pattern": "^([01]\\d|2[0-3]):(00|30)$"
    },
    "refreshTimezone": {
      "nullable": true,
      "type": "string"
    },
    "lastSuccessUpdate": {
      "type": "string"
    },
    "lastRefreshScheduledFor": {
      "nullable": true,
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "contentChangedAt": {
      "type": "string"
    },
    "accessTokenID": {
      "type": "number"
    },
    "integrationExternalID": {
      "type": "string"
    },
    "source": {
      "allOf": [
        {
          "$ref": "#/components/schemas/KnowledgeBaseDocumentIntegrationType"
        }
      ]
    },
    "sitemapDocumentID": {
      "nullable": true,
      "type": "string"
    },
    "integrationDocumentID": {
      "nullable": true,
      "type": "string"
    },
    "integrationPath": {
      "nullable": true,
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "type",
    "name",
    "url"
  ]
}
```

### KBDocumentXLSXData

```json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "xlsx"
      ],
      "x-enumNames": [
        "XLSX"
      ]
    },
    "name": {
      "type": "string"
    },
    "rowsCount": {
      "type": "number"
    },
    "url": {
      "nullable": true,
      "type": "string"
    }
  },
  "required": [
    "type",
    "name"
  ]
}
```

### KnowledgeBaseDocumentChangeType

```json
{
  "type": "string",
  "enum": [
    "added",
    "updated",
    "removed"
  ],
  "x-enumNames": [
    "ADDED",
    "UPDATED",
    "REMOVED"
  ]
}
```

### KnowledgeBaseDocumentIntegrationType

```json
{
  "type": "string",
  "enum": [
    "zendesk",
    "shopify",
    "kustomer"
  ],
  "x-enumNames": [
    "ZENDESK",
    "SHOPIFY",
    "KUSTOMER"
  ]
}
```

### KnowledgeBaseDocumentRefreshRate

```json
{
  "type": "string",
  "enum": [
    "daily",
    "weekly",
    "monthly",
    "never"
  ],
  "x-enumNames": [
    "DAILY",
    "WEEKLY",
    "MONTHLY",
    "NEVER"
  ]
}
```

### KnowledgeBaseDocumentStatus

```json
{
  "type": "string",
  "enum": [
    "ERROR",
    "PENDING",
    "SUCCESS",
    "INITIALIZED"
  ],
  "x-enumNames": [
    "ERROR",
    "PENDING",
    "SUCCESS",
    "INITIALIZED"
  ]
}
```

### SmartChunking

```json
{
  "type": "object",
  "properties": {
    "markdownConversion": {
      "description": "When enabled, HTML is automatically converted to markdown to generate better chunks.",
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "enum": [
            "true",
            "false"
          ],
          "x-enumNames": [
            "TRUE",
            "FALSE"
          ]
        }
      ]
    },
    "llmBasedChunks": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "enum": [
            "true",
            "false"
          ],
          "x-enumNames": [
            "TRUE",
            "FALSE"
          ]
        }
      ]
    },
    "llmGeneratedQ": {
      "description": "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.",
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "enum": [
            "true",
            "false"
          ],
          "x-enumNames": [
            "TRUE",
            "FALSE"
          ]
        }
      ]
    },
    "llmContentSummarization": {
      "description": "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.",
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "enum": [
            "true",
            "false"
          ],
          "x-enumNames": [
            "TRUE",
            "FALSE"
          ]
        }
      ]
    },
    "llmPrependContext": {
      "description": "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.",
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "enum": [
            "true",
            "false"
          ],
          "x-enumNames": [
            "TRUE",
            "FALSE"
          ]
        }
      ]
    },
    "singleChunk": {
      "description": "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.",
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "enum": [
            "true",
            "false"
          ],
          "x-enumNames": [
            "TRUE",
            "FALSE"
          ]
        }
      ]
    }
  }
}
```

### StableDeleteResponse

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "A human-readable message confirming the deletion."
    }
  },
  "required": [
    "message"
  ]
}
```

### StableDocument

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "data": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/KBDocumentData"
        }
      ]
    },
    "status": {
      "$ref": "#/components/schemas/KBDocumentStatus"
    },
    "smartChunking": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/SmartChunking"
        }
      ]
    },
    "folderID": {
      "nullable": true,
      "description": "The ID of the Knowledge Base folder the document is filed under, or null when it sits at the top level.",
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "id",
    "data",
    "status",
    "smartChunking",
    "folderID"
  ]
}
```

### StableDocumentChange

```json
{
  "type": "object",
  "properties": {
    "date": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the change was recorded."
    },
    "type": {
      "description": "`added` and `removed`: a sitemap sync added the page or dropped it. `updated`: a refresh found the page text changed.",
      "allOf": [
        {
          "$ref": "#/components/schemas/KnowledgeBaseDocumentChangeType"
        }
      ],
      "enum": [
        "added",
        "updated",
        "removed"
      ],
      "x-enumNames": [
        "ADDED",
        "UPDATED",
        "REMOVED"
      ]
    },
    "documentID": {
      "nullable": true,
      "description": "The changed document. A removed document no longer exists.",
      "type": "string"
    },
    "url": {
      "nullable": true,
      "description": "The page URL at the time of the change.",
      "type": "string"
    },
    "sitemapDocumentID": {
      "nullable": true,
      "description": "The sitemap document the page belongs to, or null for a URL document added on its own.",
      "type": "string"
    }
  },
  "required": [
    "date",
    "type",
    "documentID",
    "url",
    "sitemapDocumentID"
  ]
}
```

### StableDocumentChangeListResponse

```json
{
  "type": "object",
  "properties": {
    "changes": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableDocumentChange"
      },
      "description": "Newest first."
    },
    "nextCursor": {
      "description": "Present when more changes follow. Send it as cursor.",
      "type": "string"
    }
  },
  "required": [
    "changes"
  ]
}
```

### StableDocumentCreateManagedSitemapRequest

```json
{
  "type": "object",
  "properties": {
    "sitemapURL": {
      "type": "string",
      "format": "uri",
      "description": "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": {
      "description": "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`).",
      "allOf": [
        {
          "$ref": "#/components/schemas/StableDocumentSitemapPatterns"
        }
      ]
    },
    "refreshRate": {
      "default": "never",
      "description": "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.",
      "type": "string",
      "enum": [
        "daily",
        "weekly",
        "monthly",
        "never"
      ],
      "x-enumNames": [
        "DAILY",
        "WEEKLY",
        "MONTHLY",
        "NEVER"
      ]
    },
    "metadata": {
      "default": [],
      "description": "Metadata tags attached to the sitemap and to every page it imports, used to filter knowledge base retrieval at runtime.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "The name of the metadata field."
          },
          "values": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The values assigned to this metadata field."
          }
        },
        "required": [
          "key",
          "values"
        ]
      }
    },
    "folderID": {
      "description": "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.",
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "sitemapURL"
  ],
  "additionalProperties": false
}
```

### StableDocumentCreateSitemapRequest

```json
{
  "type": "object",
  "properties": {
    "sitemapURL": {
      "type": "string",
      "format": "uri",
      "description": "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": {
      "description": "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`).",
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      }
    },
    "metadata": {
      "default": [],
      "description": "Metadata tags attached to the document, used to filter knowledge base retrieval at runtime.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "The name of the metadata field."
          },
          "values": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The values assigned to this metadata field."
          }
        },
        "required": [
          "key",
          "values"
        ]
      }
    },
    "refreshRate": {
      "default": "never",
      "description": "How often the URL is automatically re-crawled to refresh the document content.",
      "type": "string",
      "enum": [
        "daily",
        "weekly",
        "monthly",
        "never"
      ],
      "x-enumNames": [
        "DAILY",
        "WEEKLY",
        "MONTHLY",
        "NEVER"
      ]
    },
    "folderID": {
      "description": "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.",
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "sitemapURL"
  ],
  "additionalProperties": false
}
```

### StableDocumentCreateTableRequest

```json
{
  "type": "object",
  "properties": {
    "url": {
      "description": "An optional source URL to associate with the table document.",
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": {}
      },
      "description": "The table rows to ingest; each row is a flat object and becomes its own chunk."
    },
    "schema": {
      "type": "object",
      "properties": {
        "metadataFields": {
          "default": [],
          "description": "Per-row metadata, returned with results.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "searchableFields": {
          "minItems": 1,
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Full-text indexed; what semantic search matches against."
        }
      },
      "required": [
        "searchableFields"
      ],
      "description": "Declares which top-level keys of each row are full-text searchable versus row-level metadata."
    },
    "metadata": {
      "default": [],
      "description": "Metadata tags attached to the document, used to filter knowledge base retrieval at runtime.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "The name of the metadata field."
          },
          "values": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The values assigned to this metadata field."
          }
        },
        "required": [
          "key",
          "values"
        ]
      }
    },
    "folderID": {
      "description": "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.",
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "name",
    "items",
    "schema"
  ],
  "additionalProperties": false
}
```

### StableDocumentCreateURLRequest

```json
{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "description": "The URL of the web page to crawl and ingest into the knowledge base."
    },
    "metadata": {
      "default": [],
      "description": "Metadata tags attached to the document, used to filter knowledge base retrieval at runtime.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "The name of the metadata field."
          },
          "values": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The values assigned to this metadata field."
          }
        },
        "required": [
          "key",
          "values"
        ]
      }
    },
    "refreshRate": {
      "description": "How often the URL is automatically re-crawled to refresh the document content.",
      "type": "string",
      "enum": [
        "daily",
        "weekly",
        "monthly",
        "never"
      ],
      "x-enumNames": [
        "DAILY",
        "WEEKLY",
        "MONTHLY",
        "NEVER"
      ]
    },
    "folderID": {
      "description": "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.",
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}
```

### StableDocumentDetails

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "data": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/KBDocumentData"
        }
      ]
    },
    "status": {
      "$ref": "#/components/schemas/KBDocumentStatus"
    },
    "smartChunking": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/SmartChunking"
        }
      ]
    },
    "folderID": {
      "nullable": true,
      "description": "The ID of the Knowledge Base folder the document is filed under, or null when it sits at the top level.",
      "type": "string",
      "minLength": 1
    },
    "chunks": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/KBDocumentChunk"
      }
    },
    "metadata": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "The name of the metadata field."
          },
          "values": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The values assigned to this metadata field."
          }
        },
        "required": [
          "key",
          "values"
        ]
      },
      "description": "Metadata tags attached to the document, used to filter knowledge base retrieval at runtime."
    }
  },
  "required": [
    "id",
    "data",
    "status",
    "smartChunking",
    "folderID",
    "chunks",
    "metadata"
  ]
}
```

### StableDocumentDetailsResponse

```json
{
  "type": "object",
  "properties": {
    "document": {
      "$ref": "#/components/schemas/StableDocumentDetails"
    }
  },
  "required": [
    "document"
  ]
}
```

### StableDocumentListResponse

```json
{
  "type": "object",
  "properties": {
    "documents": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableDocument"
      }
    }
  },
  "required": [
    "documents"
  ]
}
```

### StableDocumentResponse

```json
{
  "type": "object",
  "properties": {
    "document": {
      "$ref": "#/components/schemas/StableDocument"
    }
  },
  "required": [
    "document"
  ]
}
```

### StableDocumentSitemapCreateResponse

```json
{
  "type": "object",
  "properties": {
    "documents": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableDocument"
      }
    },
    "total": {
      "type": "number",
      "description": "How many documents the import produced, counting reused ones."
    },
    "excluded": {
      "type": "number",
      "description": "How many valid URLs the `exclude` patterns removed. Zero when no patterns were given."
    },
    "dropped": {
      "type": "number",
      "description": "How many entries the sitemap listed that are not usable URLs and were skipped."
    }
  },
  "required": [
    "documents",
    "total",
    "excluded",
    "dropped"
  ]
}
```

### StableDocumentSitemapPatterns

```json
{
  "type": "object",
  "properties": {
    "include": {
      "default": [],
      "description": "Patterns a page must match at least one of to be kept. Empty keeps every page the sitemap lists.",
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      }
    },
    "exclude": {
      "default": [],
      "description": "Patterns that drop a page when any one of them matches, even one an `include` pattern kept.",
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      }
    }
  },
  "additionalProperties": false
}
```

### StableDocumentSitemapPreviewResponse

```json
{
  "type": "object",
  "properties": {
    "urls": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The URLs that would be imported, in sitemap order, capped at `limit` entries."
    },
    "total": {
      "type": "number",
      "description": "How many URLs the sitemap yields once `exclude` is applied, before the cap."
    },
    "limit": {
      "type": "number",
      "description": "The most URL documents this plan allows in a single import."
    },
    "truncated": {
      "type": "boolean",
      "description": "True when `total` is above `limit`, meaning `urls` is only part of what the sitemap holds."
    },
    "excluded": {
      "type": "number",
      "description": "How many valid URLs the `exclude` patterns removed. Zero when no patterns were given."
    },
    "dropped": {
      "type": "number",
      "description": "How many entries the sitemap listed that are not usable URLs and were skipped."
    }
  },
  "required": [
    "urls",
    "total",
    "limit",
    "truncated",
    "excluded",
    "dropped"
  ]
}
```

### StableDocumentSitemapRequest

```json
{
  "type": "object",
  "properties": {
    "sitemapURL": {
      "type": "string",
      "format": "uri",
      "description": "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": {
      "description": "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`).",
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      }
    }
  },
  "required": [
    "sitemapURL"
  ],
  "additionalProperties": false
}
```

### StableDocumentUpdateManagedSitemapRequest

```json
{
  "type": "object",
  "properties": {
    "patterns": {
      "description": "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`).",
      "type": "object",
      "properties": {
        "include": {
          "maxItems": 100,
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "description": "Patterns a page must match at least one of to be kept. Empty keeps every page the sitemap lists."
        },
        "exclude": {
          "maxItems": 100,
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "description": "Patterns that drop a page when any one of them matches, even one an `include` pattern kept."
        }
      },
      "required": [
        "include",
        "exclude"
      ],
      "additionalProperties": false
    },
    "refreshRate": {
      "description": "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.",
      "type": "string",
      "enum": [
        "daily",
        "weekly",
        "monthly",
        "never"
      ],
      "x-enumNames": [
        "DAILY",
        "WEEKLY",
        "MONTHLY",
        "NEVER"
      ]
    },
    "markdownConversion": {
      "description": "When enabled, HTML is automatically converted to markdown to generate better chunks.",
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "enum": [
            "true",
            "false"
          ],
          "x-enumNames": [
            "TRUE",
            "FALSE"
          ]
        }
      ]
    },
    "llmBasedChunks": {
      "description": "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.",
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "enum": [
            "true",
            "false"
          ],
          "x-enumNames": [
            "TRUE",
            "FALSE"
          ]
        }
      ]
    },
    "llmGeneratedQ": {
      "description": "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.",
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "enum": [
            "true",
            "false"
          ],
          "x-enumNames": [
            "TRUE",
            "FALSE"
          ]
        }
      ]
    },
    "llmContentSummarization": {
      "description": "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.",
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "enum": [
            "true",
            "false"
          ],
          "x-enumNames": [
            "TRUE",
            "FALSE"
          ]
        }
      ]
    },
    "llmPrependContext": {
      "description": "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.",
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "enum": [
            "true",
            "false"
          ],
          "x-enumNames": [
            "TRUE",
            "FALSE"
          ]
        }
      ]
    },
    "singleChunk": {
      "description": "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.",
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "enum": [
            "true",
            "false"
          ],
          "x-enumNames": [
            "TRUE",
            "FALSE"
          ]
        }
      ]
    }
  },
  "additionalProperties": false
}
```

### StableDocumentUpdateRequestV2

```json
{
  "type": "object",
  "properties": {
    "metadata": {
      "description": "Replaces the document's metadata tags. Leave it out to keep them.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "The name of the metadata field."
          },
          "values": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The values assigned to this metadata field."
          }
        },
        "required": [
          "key",
          "values"
        ]
      }
    },
    "folderID": {
      "description": "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.",
      "nullable": true,
      "type": "string",
      "minLength": 1
    },
    "content": {
      "description": "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.",
      "type": "string",
      "minLength": 1
    }
  },
  "additionalProperties": false
}
```

### StableUpdateResponse

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "A human-readable message confirming the update."
    }
  },
  "required": [
    "message"
  ]
}
```
