bithuman-ai Knowledge API
Ingest sources and build knowledge bases, with an organization API secret: [https://docs.bithuman.ai/api/knowledge](https://docs.bithuman.ai/api/knowledge).
Ingest sources and build knowledge bases, with an organization API secret: [https://docs.bithuman.ai/api/knowledge](https://docs.bithuman.ai/api/knowledge).
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/bithuman-ai:bithuman-ai-knowledge-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Bithuman Ai Knowledge API
version: '1.0'
contact:
name: bitHuman Support
url: https://www.bithuman.ai/discord
x-logo:
url: https://docs.bithuman.ai/bithuman-mark.png
description: 'Operations tagged Knowledge across 2 of this provider''s published API definitions: openapi.yaml, bithuman-ai-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.bithuman.ai
description: Production
security:
- apiSecret: []
tags:
- name: Knowledge
description: 'Ingest sources and build knowledge bases, with an organization API secret: https://docs.bithuman.ai/api/knowledge.'
paths:
/v1/knowledge/files:
post:
operationId: ingestKnowledgeFile
x-codeSamples:
- lang: shell
label: cURL
source: "curl -X POST https://api.bithuman.ai/v1/knowledge/files \\\n -H \"api-secret: $ORG_API_SECRET\" -H \"content-type: application/json\" \\\n -d '{\"url\":\"https://example.com/help\",\"name\":\"Help Center\",\"sync_freq\":\"weekly\"}'\n"
summary: Ingest a file or URL
description: 'Adds one source to your organization: an uploaded file
(`multipart/form-data`, fields `file` up to 100 MB and `name`) or a URL
to fetch (JSON). Returns the file row at status `uploaded`; conversion
runs in the background. Needs an organization API secret; a personal
secret returns `403`.'
tags:
- Knowledge
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- url
properties:
url:
type: string
description: A public `http(s)` URL to fetch and convert.
name:
type: string
description: Display name; defaults to the URL host.
sync_freq:
type: string
enum:
- never
- daily
- weekly
- monthly
default: never
description: Re-sync cadence.
multipart/form-data:
schema:
type: object
required:
- file
properties:
file:
type: string
format: binary
description: The document bytes. Max 100 MB.
name:
type: string
description: Display name; defaults to the uploaded filename.
responses:
'201':
description: The file row.
content:
application/json:
example:
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'
'403':
description: A personal API secret; use an organization API secret.
'413':
description: File over 100 MB.
'422':
description: Empty file, missing `file`/`url`, non-public URL, or bad `sync_freq`.
servers:
- url: https://api.bithuman.ai
description: Production
/v1/knowledge/kbs:
post:
operationId: createKnowledgeBase
x-codeSamples:
- lang: shell
label: cURL
source: "curl -X POST https://api.bithuman.ai/v1/knowledge/kbs \\\n -H \"api-secret: $ORG_API_SECRET\" -H \"content-type: application/json\" \\\n -d '{\"name\":\"Support KB\",\"file_ids\":[\"3f2b9c14-8a7e-4d21-9f10-2c5b6e0a11dd\"]}'\n"
summary: Create a knowledge base
description: 'Creates a knowledge base and, by default, starts its first build.
`build_dispatched` is `true` only when `build` was `true`, files were
attached and the build queued.'
tags:
- Knowledge
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
description: KB name (1–120 chars).
description:
type: string
description: Up to 2000 chars.
file_ids:
type: array
items:
type: string
description: File `id`s to attach (your organization's own files).
build:
type: boolean
default: true
description: Build immediately after create.
responses:
'201':
description: The KB row, plus `file_ids` and `build_dispatched`.
content:
application/json:
example:
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
'403':
description: A `file_id` isn't yours, or a personal API secret.
'404':
description: A `file_id` doesn't exist.
get:
operationId: listKnowledgeBases
x-codeSamples:
- lang: shell
label: cURL
source: 'curl https://api.bithuman.ai/v1/knowledge/kbs -H "api-secret: $ORG_API_SECRET"
'
summary: List knowledge bases
description: The organization's knowledge bases, newest first, each with `agent_count` and `source_count`.
tags:
- Knowledge
responses:
'200':
description: The list.
content:
application/json:
example:
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
servers:
- url: https://api.bithuman.ai
description: Production
/v1/knowledge/kbs/{kb_id}/rebuild:
parameters:
- name: kb_id
in: path
required: true
schema:
type: string
description: The knowledge base id.
post:
operationId: rebuildKnowledgeBase
x-codeSamples:
- lang: shell
label: cURL
source: "curl -X POST https://api.bithuman.ai/v1/knowledge/kbs/b71e0a92-…/rebuild \\\n -H \"api-secret: $ORG_API_SECRET\"\n"
summary: Rebuild a knowledge base
description: 'Re-indexes a knowledge base after its sources change. Returns the
queued build row; indexing runs in the background. Builds run one at a
time per account, up to 20 per day.'
tags:
- Knowledge
responses:
'200':
description: The queued build.
content:
application/json:
example:
id: e5c9a1f7-0b44-4a6e-9c22-77d0b3e18a55
kb_id: b71e0a92-4c3d-4f88-8a01-9e2f4c6d7b10
status: queued
started_at: '2026-07-15T12:10:00Z'
'404':
description: Unknown knowledge base.
'409':
description: '`BUILD_IN_PROGRESS`, `BUILD_CONCURRENCY` or `BUILD_DAILY_CAP`.'
'422':
description: '`KB_EMPTY` — no source files.'
servers:
- url: https://api.bithuman.ai
description: Production
components:
securitySchemes:
apiSecret:
type: apiKey
name: api-secret
in: header
description: 'Your bitHuman API secret. Get one at
[www.bithuman.ai/developer/api-keys](https://www.bithuman.ai/developer/api-keys).
'
bearerApiSecret:
type: http
scheme: bearer
description: 'The same API secret, sent as `Authorization: Bearer <api-secret>`. Self-
hosted runtimes send it this way; the classic `api-secret` header works
on the same routes.
'
x-refined-from:
- openapi.yaml
- bithuman-ai-openapi.yaml
x-tagGroups:
- name: Get started
tags:
- overview
- quickstart
- auth-guide
- models
- pricing
- name: Core concepts
tags:
- avatars-imx
- audio-streaming
- agent-lifecycle
- name: SDKs
tags:
- sdk-python
- sdk-swift
- cli
- name: Guides
tags:
- local-mode
- building-avatars
- name: Deployment
tags:
- deploy-livekit
- deploy-self-hosted
- deploy-embed
- name: API reference
tags:
- Authentication
- Agent Generation
- Agent Management
- Agent Context
- Files
- Dynamics
- Embedding
- Video
- Billing
- Account
- Self-hosting
- API secrets
- Providers
- Runtime sessions
- Knowledge
- Realtime
- Status
- Webhooks
- name: Resources
tags:
- community
- changelog
- support