HTML docs · raw markdown

Files

Every knowledgebase has its own file tree. Paths are slash-separated and relative to that knowledgebase’s root (for example docs/guide.md). A leading / is stripped (so /docs/a becomes docs/a). Segments . and .. are rejected.

All routes live under /v1/knowledgebases/{kbId}/files…. In the CLI, pass -kb with the knowledgebase id.

Tree

Recursive snapshot of the tree.

kobold-cli files tree -kb kb_qc0rp0gz

GET /v1/knowledgebases/kb_qc0rp0gz/files/tree
Authorization: Bearer <api_key>

Root node: name is home, path is "". Children are directories (type: "dir") or files (type: "file"). Files include size, mime, and modified.

Usage

Aggregate counts for one knowledgebase.

kobold-cli files usage -kb kb_qc0rp0gz

GET /v1/knowledgebases/kb_qc0rp0gz/files/usage
Authorization: Bearer <api_key>

{
  "totalFiles": 3,
  "totalBytes": 12000,
  "byType": [
    { "mime": "text/markdown", "count": 2, "bytes": 8000 },
    { "mime": "text/plain", "count": 1, "bytes": 4000 }
  ]
}

Mkdir

Create a directory (and any missing parents).

kobold-cli files mkdir -kb kb_qc0rp0gz -path docs/notes

POST /v1/knowledgebases/kb_qc0rp0gz/files/mkdir
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "path": "docs/notes"
}

Success: {} / CLI {"ok": true}. Bad paths → 400.

Ingest

Upload raw file bytes into the knowledgebase.

kobold-cli files ingest -kb kb_qc0rp0gz -file ./guide.md
kobold-cli files ingest -kb kb_qc0rp0gz -filename guide.md -dest-dir docs -file ./guide.md
cat guide.md | kobold-cli files ingest -kb kb_qc0rp0gz -filename guide.md -dest-dir docs -file -

POST /v1/knowledgebases/kb_qc0rp0gz/files/ingest?filename=guide.md&destDir=docs
Authorization: Bearer <api_key>
Content-Type: application/octet-stream

<raw bytes>

Param / flag	Required	Notes
`filename` / `-filename`	yes (HTTP); CLI infers from `-file` path	Basename only
`destDir` / `-dest-dir`	no	Relative directory; empty = knowledgebase root. Must already exist — create it with mkdir first. Missing `destDir` → `404`.
body / `-file`	yes	File path, or `-` for stdin

On name collision in the destination directory, a numeric suffix is added (guide-1.md, guide-2.md, …).

Success 201:

{
  "homePath": "docs/guide.md"
}

Behavioral notes:

Request body size must stay within your plan’s per-file upload size (maxApiUploadBytesPerFile from stats get). Oversized bodies → 413.
Successful uploads count toward your plan’s daily upload allowance (maxApiUploadsPerDay). Exhausted → 429.
Exceeding storage for the account → 403.
Ingest does not wait for indexing. Call sync when you want the index to catch up promptly.

Rename / move

kobold-cli files rename -kb kb_qc0rp0gz -from docs/old.md -to docs/new.md
kobold-cli files rename -kb kb_qc0rp0gz -from docs/old.md -to archive/old.md

PATCH /v1/knowledgebases/kb_qc0rp0gz/files
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "from": "docs/old.md",
  "to": "docs/new.md"
}

Both paths are relative to the knowledgebase root. Missing source → 404.

Same directory: to is treated as a new basename in that directory (docs/old.md → docs/new.md).
Cross directory: to is the full destination path; parent directories are created as needed (docs/old.md → archive/old.md).

Delete

kobold-cli files delete -kb kb_qc0rp0gz -path docs/new.md
kobold-cli files delete -kb kb_qc0rp0gz -path docs -recursive

DELETE /v1/knowledgebases/kb_qc0rp0gz/files?path=docs&recursive=true
Authorization: Bearer <api_key>

Query / flag	Required	Notes
`path` / `-path`	yes	Relative path
`recursive` / `-recursive`	no	Required to delete a non-empty directory

Non-empty directory without recursive → 400.

Content (read bytes)

This is the endpoint for reading file payloads. Search never returns a full file.

kobold-cli files content -kb kb_qc0rp0gz -path docs/guide.md
kobold-cli files content -kb kb_qc0rp0gz -path docs/guide.md -offset 0 -length 65536 -out ./part.bin

GET /v1/knowledgebases/kb_qc0rp0gz/files/content?path=docs/guide.md&offset=0&length=65536
Authorization: Bearer <api_key>

Query / flag	Default	Notes
`path` / `-path`	—	Required
`offset` / `-offset`	`0`	Start byte
`length` / `-length`	`65536` (64 KiB)	Max `1048576` (1 MiB) per request
`-out`	(stdout)	CLI only: write bytes to a file

Response body is raw file bytes. Useful response headers:

Header	Meaning
`Content-Type`	MIME type
`X-Content-Offset`	Start offset of this slice
`X-Content-Length`	Bytes in this response
`X-Content-Total`	Full file size when known

To read a large file, issue multiple ranged requests by advancing offset. Each successful content request counts as one download toward your plan’s daily download allowance (maxApiDownloadsPerDay from stats get).

Directories and bad ranges → 400. Missing file → 404.

Index and search — index after ingest
Errors — status codes