Skip to main content

​
How it works

You don’t need to create a knowledge base manually. Adding content (a URL, file, or text) automatically creates one for you and returns its ID.
Uploaded content is indexed and retrieved automatically during calls — no configuration needed. Supported file types: PDF, Excel, and Word documents. Maximum file size: 20 MB.

​
Quick start — add content in one call

You can skip creating a knowledge base ID manually. POST /v1/knowledge-bases/sources (without a kb_id in the path) auto-creates a new knowledge base named after your source and starts ingestion immediately. The response gives you the knowledge_base_id — save it for attaching to your agent.

​
Add a URL

Provide any public URL — a docs page, FAQ, blog post, or product page. OneInbox fetches the page and indexes its content automatically. 
curl -X POST https://api.oneinbox.ai/v1/knowledge-bases/sources \
  -H "Authorization: Bearer <api_key>" \
  -F "type=url" \
  -F "source=https://docs.yourproduct.com/faq"

​
Upload a file

Upload a document directly. Supported formats: PDF, Excel, and Word documents. Use the file field only — do not include a type field when uploading a file. 
curl -X POST https://api.oneinbox.ai/v1/knowledge-bases/sources \
  -H "Authorization: Bearer <api_key>" \
  -F "file=@/path/to/your-document.pdf"

​
Add inline text

Paste content directly as plain text — useful for policies, scripts, FAQs, or any text you already have on hand. 
curl -X POST https://api.oneinbox.ai/v1/knowledge-bases/sources \
  -H "Authorization: Bearer <api_key>" \
  -F "type=text" \
  -F "source=Our refund policy is 30 days. Customers must provide proof of purchase to receive a refund."
All three endpoints return the same response structure: 
{
  "knowledge_base_id": "kb_abc123",
  "source": { "id": "kbs_xyz", "status": "processing" },
  "job": { "id": "kbj_xyz", "status": "queued" }
}
  • knowledge_base_id — the ID of the auto-created knowledge base. Save this — you’ll use it in Step 3 to attach the KB to your agent.
  • source.id — the individual content source that was added.
  • job.id — the processing job. Poll this to track indexing progress.
The KB is named after the URL domain or file name.

​
Step 2 — Check processing status

Content is indexed asynchronously. Wait for the job to complete before attaching the KB to your agent — the agent can only use content that has finished processing. 
# List all jobs for this KB
curl https://api.oneinbox.ai/v1/knowledge-bases/<kb_id>/jobs \
  -H "Authorization: Bearer <api_key>"

# Get a specific job
curl https://api.oneinbox.ai/v1/knowledge-bases/<kb_id>/jobs/<job_id> \
  -H "Authorization: Bearer <api_key>"
Jobs follow this sequence: queued → running → completed or failed Wait for "status": "completed" before moving to Step 3.

​
Step 3 — Attach to your LLM model

This is the step that makes the knowledge base available to your agent. Attach it to the LLM model (not the agent directly). llm_id is returned when you create an agent — if you don’t have it, fetch it with GET /v1/agents/<agent_id>. 
curl -X PATCH https://api.oneinbox.ai/v1/models/<llm_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "knowledge_base_ids": ["<kb_id>"]
  }'
Every agent using this LLM model now has access to the knowledge base. To attach multiple knowledge bases at once: 
{ "knowledge_base_ids": ["kb_abc123", "kb_def456"] }

​
Manage knowledge bases

​
List all knowledge bases

Retrieve all knowledge bases in your account. Useful for finding kb_id values or auditing what content your agents have access to. 
curl https://api.oneinbox.ai/v1/knowledge-bases \
  -H "Authorization: Bearer <api_key>"

​
List sources in a knowledge base

See all the individual content sources (URLs, files, inline text) that have been added to a specific KB. 
curl https://api.oneinbox.ai/v1/knowledge-bases/<kb_id>/sources \
  -H "Authorization: Bearer <api_key>"

​
Delete a source

Remove a single source from the KB along with its vector chunks and stored file. Get the source_id from the list sources endpoint above. 
curl -X DELETE "https://api.oneinbox.ai/v1/knowledge-bases/<kb_id>/sources/<source_id>" \
  -H "Authorization: Bearer <api_key>"

​
Update a knowledge base

Rename a KB, change its chunk size, or toggle multilingual mode. Chunk size changes take effect on the next source processed — existing content is not re-indexed automatically. 
curl -X PATCH https://api.oneinbox.ai/v1/knowledge-bases/<kb_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Product Docs v2", "chunk_size": 1024, "multilingual": true }'
FieldWhat it does
nameRename the KB
chunk_sizeToken size per chunk — smaller = more precise retrieval, larger = more context per result
multilingualtrue enables cross-language retrieval (content in one language, query in another)

​
Delete a knowledge base

Permanently removes the KB and all its indexed content. If the KB is attached to an LLM model, it will no longer be available to those agents after deletion. 
curl -X DELETE https://api.oneinbox.ai/v1/knowledge-bases/<kb_id> \
  -H "Authorization: Bearer <api_key>"

​
API reference

Add source (auto-create KB) · Add source · List jobs