Knowledge Bases

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-tokyo.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-tokyo.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-tokyo.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:

{
  "source": { "source_id": "kbs_xyz", "kb_id": "kb_abc123", "status": "processing" },
  "job": { "job_id": "kbj_xyz", "kb_id": "kb_abc123", "status": "queued" },
  "message": "Source accepted. Ingestion is running in the background."
}

source.kb_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.source_id — the individual content source that was added.
job.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-tokyo.oneinbox.ai/v1/knowledge-bases/<kb_id>/jobs \
  -H "Authorization: Bearer <api_key>"

# Get a specific job
curl https://api-tokyo.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-tokyo.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"] }

Detach a knowledge base from a model

To remove a KB from an LLM model without replacing the entire list, use remove_knowledge_base_ids:

curl -X PATCH https://api-tokyo.oneinbox.ai/v1/models/<llm_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "remove_knowledge_base_ids": ["<kb_id_to_remove>"]
  }'

You can attach and detach KBs in the same request — knowledge_base_ids adds, remove_knowledge_base_ids detaches.

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-tokyo.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-tokyo.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-tokyo.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-tokyo.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 }'

Field	What it does
`name`	Rename the KB
`chunk_size`	Token size per chunk — smaller = more precise retrieval, larger = more context per result
`multilingual`	`true` 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-tokyo.oneinbox.ai/v1/knowledge-bases/<kb_id> \
  -H "Authorization: Bearer <api_key>"

API reference

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

Get started

Make calls

Configure your agent

Monitor & integrate

Core concepts

How it works

Quick start — add content in one call

Add a URL

Upload a file

Add inline text

Step 2 — Check processing status

Step 3 — Attach to your LLM model

Detach a knowledge base from a model

Manage knowledge bases

List all knowledge bases

List sources in a knowledge base

Delete a source

Update a knowledge base

Delete a knowledge base

API reference

​How it works

​Quick start — add content in one call

​Add a URL

​Upload a file

​Add inline text

​Step 2 — Check processing status

​Step 3 — Attach to your LLM model

​Detach a knowledge base from a model

​Manage knowledge bases

​List all knowledge bases

​List sources in a knowledge base

​Delete a source

​Update a knowledge base

​Delete a knowledge base

​API reference

How it works

Quick start — add content in one call

Add a URL

Upload a file

Add inline text

Step 2 — Check processing status

Step 3 — Attach to your LLM model

Detach a knowledge base from a model

Manage knowledge bases

List all knowledge bases

List sources in a knowledge base

Delete a source

Update a knowledge base

Delete a knowledge base

API reference