# Managed knowledge Upload and search an app-owned AI Search knowledge base with the DeepSpace worker helper. DeepSpace can provision one managed Cloudflare AI Search instance per app. Declare it in `wrangler.toml`; the app calls it through the typed `knowledge(env)` worker helper, and usage is charged to the app owner. ## Configure the binding ```toml [[ai_search]] binding = "KNOWLEDGE" instance_name = "auto" ``` `instance_name` must be `"auto"`, and an app may declare only one `ai_search` binding. DeepSpace owns provisioning and app isolation. The `KNOWLEDGE` name is manifest metadata rather than an AI Search object you call directly from application code. ## Use it from the worker ```ts import { knowledge } from 'deepspace/worker' const kb = knowledge(env) const added = await kb.add( new File( ['DeepSpace keeps records in app-owned Durable Objects.'], 'architecture.md', { type: 'text/markdown', }, ), { folder: 'docs' }, ) const results = await kb.search('Where are records stored?', { folder: 'docs', mode: 'hybrid', limit: 5, }) ``` The helper uses the app's signed platform transport. It does not read `env.KNOWLEDGE` as a provider binding. ## API ```ts const kb = knowledge(env) await kb.add(file, { folder: 'docs' }) await kb.list({ folder: 'docs', page: 1, perPage: 20, status: 'completed' }) await kb.remove(itemId) await kb.search(query, { folder: 'docs', mode: 'hybrid', limit: 5 }) const docs = kb.scoped({ folder: 'docs' }) await docs.add(file) await docs.list({ page: 1, perPage: 20 }) await docs.search(query, { mode: 'semantic', limit: 5 }) ``` `scoped` fixes the folder for add, list, and search. Remove remains on the root client because it addresses a provider item ID directly. Items report one of these statuses: `queued`, `running`, `completed`, `error`, `skipped`, or `outdated`. Upload completion means the provider accepted the item; use `list` to observe indexing status before assuming it is searchable. ## Limits and validation * A provider upload part may be at most 4 MiB. The SDK safely splits oversized text files on UTF-8 boundaries; oversized non-text files are rejected so application code can use a format-aware splitter. * A query may contain at most 4,096 characters. * `limit` and `perPage` must be integers from 1 through 50. * Folders are relative forward-slash paths. Empty segments, `.` / `..`, backslashes, control characters, and leading slashes are rejected. Folder plus filename must fit the provider's 128-character item-key limit. * `mode` is `hybrid`, `semantic`, or `fulltext`. ## Pricing The amounts below include the 10% managed-binding markup: | Operation | Price | | ------------------------- | --------------------------------------------------------------: | | Text ingestion | $0.825 per 1 million provider-reported tokens | | Image ingestion | $0.55 per 1 million image tokens, in addition to text ingestion | | Storage | $2.20 per GB-month | | Hybrid or semantic search | $0.825 per 1,000 queries | | Full-text search | $0.11 per 1,000 queries | Charges settle against actual provider usage when it is available. Uploads reserve a conservative amount first, so a rejected or smaller operation does not become an unbounded charge. DeepSpace credits use 100 credits per US dollar, and managed-knowledge usage appears in the account-wide usage surfaces. ## Errors Failures throw `KnowledgeError`, which includes `status` and a machine-readable `code`. A split text upload can partially succeed; in that case `uploadedItems` names the accepted parts so you can avoid uploading them twice. ```ts import { KnowledgeError, knowledge } from 'deepspace/worker' try { await knowledge(env).add(file) } catch (error) { if (error instanceof KnowledgeError) { console.error(error.code, error.uploadedItems) } } ``` ## See also * [Bindings reference](/sdk-reference/worker/bindings) * [Custom bindings](/guides/custom-bindings) * [App usage](/cli-reference/commands#app-usage)