Manage Documents

RAG document management — embed, list, and delete. All operations are scoped to the organization of the API key.

Embed a document

Chunks, embeds, and stores a document. Embedding an existing source replaces the previous chunks for that source (idempotent upsert).

Endpoint

POST /api/v1/rag/documents

Request Body

Parameter	Type	Required	Description
`source`	`string`	Yes	Stable identifier for the document (e.g. a file path or URL). Used as the primary key for updates and deletes.
`content`	`string`	Yes	Full document text
`doc_type`	`string`	No	Content type hint (default: `markdown`). Common values: `markdown`, `html`, `yaml`, `json`, `text`
`metadata`	`object`	No	Arbitrary key-value metadata persisted with every chunk

Examples

from cerebe import AsyncCerebe

client = AsyncCerebe(api_key="ck_live_...")

with open("docs/auth.md") as f:
    await client.rag.embed(
        source="docs/auth.md",
        content=f.read(),
        doc_type="markdown",
        metadata={"version": "v2", "team": "platform"},
    )

import Cerebe from '@cerebe/sdk'
import { readFileSync } from 'node:fs'

const client = new Cerebe({ apiKey: 'ck_live_...' })

await client.rag.embed({
  source: 'docs/auth.md',
  content: readFileSync('docs/auth.md', 'utf-8'),
  docType: 'markdown',
  metadata: { version: 'v2', team: 'platform' },
})

curl -X POST https://api.cerebe.ai/api/v1/rag/documents \
  -H "X-API-Key: ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "source": "docs/auth.md",
    "content": "# Auth\n\nThe backend uses API keys...",
    "doc_type": "markdown",
    "metadata": {"version": "v2", "team": "platform"}
  }'

Response

{
  "message": "Document embedded",
  "data": {
    "status": "success",
    "source": "docs/auth.md",
    "chunks_created": 4,
    "doc_type": "markdown"
  }
}

Chunking

Documents are split with a recursive character splitter:

Chunk size: 1000 characters (default)
Overlap: 200 characters (default)
Separators preferred: paragraph breaks → line breaks → whitespace → character

Smaller documents produce one chunk. Large documents produce many chunks that share surrounding context via the overlap.

Batch embed

Embed many documents in a single call. Faster than looping embed() because chunking, embedding, and persistence happen in batches.

Endpoint

POST /api/v1/rag/documents/batch

Request Body

Parameter	Type	Required	Description
`documents`	`array`	Yes	Array of documents. Each item accepts the same fields as the single-embed request body: `source`, `content`, optional `doc_type`, optional `metadata`.

Examples

result = await client.rag.embed_batch([
    {"source": "docs/auth.md", "content": "..."},
    {"source": "docs/storage.md", "content": "...", "doc_type": "markdown"},
    {"source": "api/spec.yaml", "content": "...", "doc_type": "yaml"},
])
print(result.data["total_chunks_created"])

const result = await client.rag.embedBatch({
  documents: [
    { source: 'docs/auth.md', content: '...' },
    { source: 'docs/storage.md', content: '...', docType: 'markdown' },
    { source: 'api/spec.yaml', content: '...', docType: 'yaml' },
  ],
})
console.log(result.data.total_chunks_created)

curl -X POST https://api.cerebe.ai/api/v1/rag/documents/batch \
  -H "X-API-Key: ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {"source": "docs/auth.md", "content": "..."},
      {"source": "docs/storage.md", "content": "...", "doc_type": "markdown"}
    ]
  }'

Response

{
  "message": "Batch embedding completed",
  "data": {
    "status": "success",
    "documents_processed": 3,
    "total_chunks_created": 14,
    "results": [
      { "source": "docs/auth.md", "chunks_created": 4, "status": "success" },
      { "source": "docs/storage.md", "chunks_created": 7, "status": "success" },
      { "source": "api/spec.yaml", "chunks_created": 3, "status": "success" }
    ]
  }
}

List documents

Return every document in your organization's collection with its chunk count and last-updated timestamp.

Endpoint

GET /api/v1/rag/documents

Examples

result = await client.rag.list_documents()
for doc in result.data["documents"]:
    print(f"{doc['source']} ({doc['chunk_count']} chunks)")

const result = await client.rag.listDocuments()
for (const doc of result.data.documents) {
  console.log(`${doc.source} (${doc.chunk_count} chunks)`)
}

curl https://api.cerebe.ai/api/v1/rag/documents \
  -H "X-API-Key: ck_live_..."

Response

{
  "message": "Documents listed",
  "data": {
    "documents": [
      {
        "source": "docs/auth.md",
        "doc_type": "markdown",
        "chunk_count": 4,
        "last_updated": "2026-04-19T20:56:14Z"
      }
    ],
    "total_documents": 1
  }
}

Delete a document

Remove every chunk for a given source. Safe to call on a non-existent source (returns chunks_deleted: 0).

Endpoint

DELETE /api/v1/rag/documents/{source}

The source path segment can contain slashes — FastAPI's path converter captures the full remainder after /documents/.

Examples

await client.rag.delete_document("docs/auth.md")

await client.rag.deleteDocument({ source: 'docs/auth.md' })

curl -X DELETE https://api.cerebe.ai/api/v1/rag/documents/docs/auth.md \
  -H "X-API-Key: ck_live_..."

Response

{
  "message": "Document deleted",
  "data": {
    "status": "success",
    "source": "docs/auth.md",
    "chunks_deleted": 4
  }
}

Manage Documents

On this page