Skip to main content

​
How it works

OneInbox automatically picks the best retrieval method based on the size of your content:
Content sizeMethodWhat happens
≤ 10k tokensDirect injectionContent is inserted into the system prompt at call time
> 10k tokensVector searchA search_knowledge_base tool is auto-created; the agent queries it during calls
You don’t configure this — OneInbox handles it automatically based on how much content you add.

​
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, DOCX, XLSX, TXT, MD. 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 4 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. To use a custom name, chunk size, or multilingual settings, use the manual setup below.

​
Manual setup (custom name / settings)

Use this flow when you need a specific KB name, chunk size, or multilingual support.

​
Step 1 — Create a knowledge base

Creates an empty knowledge base with the settings you choose. You’ll add content to it in Step 2. 
curl -X POST https://api.oneinbox.ai/v1/knowledge-bases \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Docs",
    "chunk_size": 512,
    "multilingual": false
  }'

{
  "id": "kb_abc123",
  "name": "Product Docs",
  "chunk_size": 512,
  "multilingual": false,
  "created_at": "2026-06-01T10:00:00Z"
}
FieldWhat it does
nameA label for this KB — visible in your account, not shown to callers
chunk_sizeHow many tokens per chunk for vector indexing. 512 is a good default — lower values give more precise retrieval, higher values give more context per result
multilingualSet true if your content or callers use multiple languages
Save the id (kb_abc123) — you’ll use it in Steps 2, 3, and 4.

​
Step 2 — Add content

Add content to the knowledge base you created. You can add links, files, and plain text — mix and match as needed. All sources are processed asynchronously and the API returns 202 immediately with a job.id to track progress.

​
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/<kb_id>/sources \
  -H "Authorization: Bearer <api_key>" \
  -F "type=url" \
  -F "source=https://docs.yourproduct.com/faq"

​
Upload a file

Upload a document as a file source. Supported formats: PDF, DOCX, XLSX, TXT, MD. Use the file field only — do not include a type field. 
curl -X POST https://api.oneinbox.ai/v1/knowledge-bases/<kb_id>/sources \
  -H "Authorization: Bearer <api_key>" \
  -F "file=@/path/to/your-document.pdf"

​
Add inline text

Paste content directly — useful for policies, scripts, or any text you already have. The source field is the raw text content. 
curl -X POST https://api.oneinbox.ai/v1/knowledge-bases/<kb_id>/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 content types return a job response: 
{ "job": { "id": "kbj_abc123", "status": "queued" } }

​
Step 3 — 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 4.

​
Step 4 — 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>"

​
Update a knowledge base

Rename a KB or change its chunk size. Chunk size changes take effect on the next source that is 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 }'

​
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) · Create knowledge base · Add source · List jobs