Docs index: /llms.txt · every page as Markdown: add .md

Docs
Pricing Console Discord Get API secret
‹ API reference

Knowledge

Ingest documents and URLs into knowledge bases, with an organization API secret.

View as Markdown Open in ChatGPT Open in Claude

Overview

The Knowledge API lets you ingest sources and build knowledge bases (KBs) from code; attach a knowledge base to an agent in the Console. It covers the ingest → create → build → resync loop: upload a file or URL, create a KB from those files, and rebuild it when the sources change.

Note These endpoints need an organization API secret; a personal secret returns 403. What you create belongs to the organization.

Ingestion and builds run asynchronously: each call returns immediately with the created row, and conversion/indexing continues in the background. There is no per-call credit charge and no file or knowledge-base quota. Builds run one at a time per account, up to 20 per day.

Base URL https://api.bithuman.ai. Authenticate with the api-secret header:

export ORG_API_SECRET="<organization API secret>"

Ingest a file or URL

POST /v1/knowledge/files ingestKnowledgeFile

POST /v1/knowledge/files — add one source. Accepts either an uploaded file (multipart) or a URL to fetch (JSON). Returns the created file row at status uploaded; conversion runs in the background.

Upload a file (multipart/form-data):

FieldTypeRequiredDescription
filefileyesThe document bytes. Max 100 MB.
namestringnoDisplay name; defaults to the uploaded filename.

Fetch a URL (application/json):

FieldTypeRequiredDescription
urlstringyesA public http(s) URL to fetch and convert.
namestringnoDisplay name; defaults to the URL host.
sync_freqstringnoRe-sync cadence: never (default), daily, weekly, monthly.

Upload a file:

Or ingest a URL:

201 Created — the file row:

Use the returned id when creating a KB. Errors: 413 file over 100 MB · 422 empty file, missing file/url, non-public URL, or bad sync_freq.

curl -X POST https://api.bithuman.ai/v1/knowledge/files \
  -H "api-secret: $ORG_API_SECRET" \
  -F "file=@handbook.pdf" -F "name=Employee Handbook"

curl

curl -X POST https://api.bithuman.ai/v1/knowledge/files \
  -H "api-secret: $ORG_API_SECRET" -H "content-type: application/json" \
  -d '{"url":"https://example.com/help","name":"Help Center","sync_freq":"weekly"}'

Python

import os, requests

resp = requests.post(
    "https://api.bithuman.ai/v1/knowledge/files",
    headers={"api-secret": os.environ["ORG_API_SECRET"]},
    json={
        "url": "https://example.com/help",
        "name": "Help Center",
        "sync_freq": "weekly",
    },
)
print(resp.json())

Node

const resp = await fetch("https://api.bithuman.ai/v1/knowledge/files", {
  method: "POST",
  headers: {
    "api-secret": process.env.ORG_API_SECRET,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/help",
    name: "Help Center",
    sync_freq: "weekly",
  }),
});
console.log(await resp.json());
{
  "id": "3f2b9c14-8a7e-4d21-9f10-2c5b6e0a11dd",
  "org_id": "org_9d1f",
  "file_name": "handbook.pdf",
  "ext": "pdf",
  "size_bytes": 428193,
  "status": "uploaded",
  "source_kind": "upload",
  "created_at": "2026-07-15T12:00:00Z"
}

Create a knowledge base

POST /v1/knowledge/kbs createKnowledgeBase

POST /v1/knowledge/kbs — create a KB and (by default) kick off its first build.

FieldTypeRequiredDescription
namestringyesKB name (1–120 chars).
descriptionstringnoUp to 2000 chars.
file_idsstring[]noFile ids to attach (must be your org’s own files).
buildbooleannoBuild immediately after create. Default true.

201 Created — the KB row, plus file_ids and build_dispatched:

build_dispatched is true only when build was true, files were attached, and the build queued successfully. The KB is still created (201) otherwise — build it later with the rebuild call. Errors: 404 a file_id doesn’t exist · 403 a file_id isn’t yours.

curl

curl -X POST https://api.bithuman.ai/v1/knowledge/kbs \
  -H "api-secret: $ORG_API_SECRET" -H "content-type: application/json" \
  -d '{"name":"Support KB","file_ids":["3f2b9c14-8a7e-4d21-9f10-2c5b6e0a11dd"]}'

Python

import os, requests

resp = requests.post(
    "https://api.bithuman.ai/v1/knowledge/kbs",
    headers={"api-secret": os.environ["ORG_API_SECRET"]},
    json={
        "name": "Support KB",
        "file_ids": ["3f2b9c14-8a7e-4d21-9f10-2c5b6e0a11dd"],
    },
)
print(resp.json())

Node

const resp = await fetch("https://api.bithuman.ai/v1/knowledge/kbs", {
  method: "POST",
  headers: {
    "api-secret": process.env.ORG_API_SECRET,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    name: "Support KB",
    file_ids: ["3f2b9c14-8a7e-4d21-9f10-2c5b6e0a11dd"],
  }),
});
console.log(await resp.json());
{
  "id": "b71e0a92-4c3d-4f88-8a01-9e2f4c6d7b10",
  "org_id": "org_9d1f",
  "name": "Support KB",
  "status": "stale",
  "content_rev": 1,
  "file_ids": ["3f2b9c14-8a7e-4d21-9f10-2c5b6e0a11dd"],
  "build_dispatched": true
}

List knowledge bases

GET /v1/knowledge/kbs listKnowledgeBases

GET /v1/knowledge/kbs — the organization’s KBs, newest first. Each row includes computed agent_count and source_count.

curl

curl https://api.bithuman.ai/v1/knowledge/kbs -H "api-secret: $ORG_API_SECRET"

Python

import os, requests

resp = requests.get(
    "https://api.bithuman.ai/v1/knowledge/kbs",
    headers={"api-secret": os.environ["ORG_API_SECRET"]},
)
print(resp.json())

Node

const resp = await fetch("https://api.bithuman.ai/v1/knowledge/kbs", {
  headers: { "api-secret": process.env.ORG_API_SECRET },
});
console.log(await resp.json());
{
  "kbs": [
    {
      "id": "b71e0a92-4c3d-4f88-8a01-9e2f4c6d7b10",
      "name": "Support KB",
      "status": "ready",
      "content_rev": 2,
      "built_rev": 2,
      "artifact_url": "https://…/artifact.zip",
      "agent_count": 1,
      "source_count": 3
    }
  ],
  "total": 1
}

Rebuild a knowledge base

POST /v1/knowledge/kbs/{kb_id}/rebuild rebuildKnowledgeBase

POST /v1/knowledge/kbs/{kb_id}/rebuild — re-index a KB after its sources change. Returns the queued build row; indexing runs in the background.

Errors: 404 unknown KB · 422 KB_EMPTY (no source files) · 409 BUILD_IN_PROGRESS (one already running on this KB — the request flags a rebuild-when-done), BUILD_CONCURRENCY (another build is running for the account), or BUILD_DAILY_CAP (20/day reached).

curl

curl -X POST https://api.bithuman.ai/v1/knowledge/kbs/b71e0a92-…/rebuild \
  -H "api-secret: $ORG_API_SECRET"

Python

import os, requests

resp = requests.post(
    "https://api.bithuman.ai/v1/knowledge/kbs/b71e0a92-…/rebuild",
    headers={"api-secret": os.environ["ORG_API_SECRET"]},
)
print(resp.json())

Node

const resp = await fetch("https://api.bithuman.ai/v1/knowledge/kbs/b71e0a92-…/rebuild", {
  method: "POST",
  headers: { "api-secret": process.env.ORG_API_SECRET },
});
console.log(await resp.json());
{
  "id": "e5c9a1f7-0b44-4a6e-9c22-77d0b3e18a55",
  "kb_id": "b71e0a92-4c3d-4f88-8a01-9e2f4c6d7b10",
  "status": "queued",
  "started_at": "2026-07-15T12:10:00Z"
}

Inject knowledge

POST /v1/agent/{code}/add-context addContext

Gives a live agent background knowledge ("type": "add_context", the default) or a message to say ("type": "speak"). room_id targets one session. It needs a live session, like speak.

curl

curl -X POST https://api.bithuman.ai/v1/agent/A80HVD8577/add-context \
  -H "Content-Type: application/json" -H "api-secret: $BITHUMAN_API_SECRET" \
  -d '{"context": "The visitor is a member. Preferred name: Alex."}'

Python

import os, requests

resp = requests.post(
    "https://api.bithuman.ai/v1/agent/A80HVD8577/add-context",
    headers={"api-secret": os.environ["BITHUMAN_API_SECRET"]},
    json={"context": "The visitor is a member. Preferred name: Alex."},
)
print(resp.json())

Node

const resp = await fetch("https://api.bithuman.ai/v1/agent/A80HVD8577/add-context", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "api-secret": process.env.BITHUMAN_API_SECRET,
  },
  body: JSON.stringify({ context: "The visitor is a member. Preferred name: Alex." }),
});
console.log(await resp.json());

Scope & limits

The /v1/knowledge surface covers ingest → create → build → resync. Attaching a knowledge base to an agent, sharing, Q&A curation and build history are in the Console only. To follow a build, list your KBs (GET /v1/knowledge/kbs) and read status and built_rev.