{
"knowledgeId": "w8d3k",
"name": "Help center: billing",
"type": "url",
"status": "processing",
"statusReason": null,
"failureCode": null,
"sizeInBytes": 0,
"pageCount": null,
"sectionCount": null,
"charCount": null,
"folderId": null,
"currentVersion": 1,
"latestVersion": 1,
"createdAt": "2026-10-13T09:30:00.000Z",
"updatedAt": "2026-10-13T09:30:00.000Z"
}{
"message": "Invalid payload",
"errors": {
"formErrors": [],
"fieldErrors": {
"name": [
"String must contain at least 1 character(s)"
]
}
}
}{
"error": "<string>"
}{
"message": "Folder not found"
}{
"message": "A folder named \"Product docs\" already exists, send its folderId instead"
}{
"message": "File exceeds the 30MB limit"
}{
"message": "URL is unreachable"
}Create knowledge base
Creates a knowledge base from files, website pages or text. The source you pick decides how you send the request:
| Source | Content type | What to send |
|---|---|---|
| Files | multipart/form-data | One or more files in files |
| Website pages | application/json | The page URLs in source.config.pages |
| Text | application/json | The text in source.config.content |
Processing runs in the background. Poll Get knowledge base status until it’s ready before an agent can use it.
{
"knowledgeId": "w8d3k",
"name": "Help center: billing",
"type": "url",
"status": "processing",
"statusReason": null,
"failureCode": null,
"sizeInBytes": 0,
"pageCount": null,
"sectionCount": null,
"charCount": null,
"folderId": null,
"currentVersion": 1,
"latestVersion": 1,
"createdAt": "2026-10-13T09:30:00.000Z",
"updatedAt": "2026-10-13T09:30:00.000Z"
}{
"message": "Invalid payload",
"errors": {
"formErrors": [],
"fieldErrors": {
"name": [
"String must contain at least 1 character(s)"
]
}
}
}{
"error": "<string>"
}{
"message": "Folder not found"
}{
"message": "A folder named \"Product docs\" already exists, send its folderId instead"
}{
"message": "File exceeds the 30MB limit"
}{
"message": "URL is unreachable"
}Authorizations
Your API token, sent raw (no Bearer prefix).
Body
- Website pages
- Text
A name for the knowledge base.
1 - 256Show child attributes
Show child attributes
An existing folder to put it in. Send this or folderName, not both.
Creates a top-level folder with this name and puts it there. Send this or folderId, not both.
80Response
Created, with status: "processing". Pages and text return the knowledge base. Files return { data: [ ... ] }, one per file. A file that couldn't be stored comes back with status: "failed", while the rest still go through.
- Option 1
- Option 2
Status and size fields describe the current version.
5 characters
"k7x2m"
"pricing.pdf"
pdf, txt, csv, json, docx, md, url processing: being parsed and indexed. Not available to agents yet.ready: indexed and available to agents.failed: processing stopped.statusReasonsays why.
processing, ready, failed Why processing failed.
For example upload_failed or job_not_scheduled.
0 for website knowledge bases.
null when it's at the top level.
The version agents read from.
The newest version. It may still be processing