Upload Text

Creates a new knowledge base from direct text input.

POST /v1/knowledge/learn

cURL

curl -X POST https://api.bland.ai/v1/knowledge/learn \
  -H "authorization: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "type": "text",
    "name": "Product Information",
    "description": "Product specifications and features",
    "text": "Our flagship product offers advanced AI capabilities with industry-leading accuracy. It supports multiple languages, real-time processing, and seamless integration with existing systems. The product includes comprehensive APIs, detailed documentation, and 24/7 support."
  }'

Success Response

{
  "data": {
    "id": "kb_01H8X9QK5R2N7P3M6Z8W4Y1V6U",
    "name": "Product Information",
    "description": "Product specifications and features",
    "status": "PROCESSING",
    "type": "TEXT",
    "created_at": "2025-01-15T11:00:00Z",
    "updated_at": "2025-01-15T11:00:00Z"
  },
  "errors": null
}

Create a knowledge base by providing text content directly in the request. This is ideal for when you have structured text content that you want to make searchable for your AI agents.

This endpoint returns a data.id UUID. Plug that UUID into any of the surfaces below to make the knowledge base available on a call. The same UUID can be attached to as many places as you want; the relationship is many-to-many.

Where can a knowledge base be attached?

Surface	How to attach	Notes
Web Agent (browser SDK)	POST /v1/agents or POST /v1/agents/{id}, tools: ["<kb_uuid>"]	The tools array accepts knowledge base UUIDs and tool IDs interchangeably.
Inbound phone number	POST /v1/personas or PATCH /v1/personas/{id}, kb_ids: ["<kb_uuid>"], then attach the number	Updates land on the draft; promote before the change is live.
SMS / iMessage	Same as inbound phone: set kb_ids on the persona, then attach the SMS-capable number	Channel capability follows the number’s own configuration.
Pathway node	Configure the knowledge base on the node in the pathway builder	See Pathways. Nodes hold their own KB list.
Outbound call	POST /v1/calls, tools: ["<kb_uuid>"]	Same array as Web Agents. If persona_id is set, the persona’s kb_ids apply and tools adds to them.

Legacy KB- prefixed vector store IDs are no longer issued. Existing KB- IDs still resolve, but new knowledge bases use UUIDs.

Headers

authorization · string · required

Your API key for authentication.

content-type · string · required

Must be application/json for text-based knowledge bases.

Body Parameters

type · string · default: "text" · required

Must be "text" for text-based knowledge bases.

name · string · required

Name for the knowledge base.

description · string

Optional description of the knowledge base content.

text · string · required

Text content to be stored in the knowledge base (maximum 1MB).

Response

data · object

The created knowledge base object.

data.id · string

Unique identifier for the knowledge base.

data.name · string

Name of the knowledge base.

data.description · string

Description of the knowledge base (if provided).

data.status · string

Current status: "PROCESSING", "COMPLETED", "FAILED", or "DELETED".

data.type · string

Will be "TEXT" for text-based knowledge bases.

data.created_at · string

ISO timestamp of creation.

data.updated_at · string

ISO timestamp of last update.

data.error_message · string

Error message if status is "FAILED".

errors · null

Will be null on successful creation.

cURL

curl -X POST https://api.bland.ai/v1/knowledge/learn \
  -H "authorization: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "type": "text",
    "name": "Product Information",
    "description": "Product specifications and features",
    "text": "Our flagship product offers advanced AI capabilities with industry-leading accuracy. It supports multiple languages, real-time processing, and seamless integration with existing systems. The product includes comprehensive APIs, detailed documentation, and 24/7 support."
  }'

Success Response

{
  "data": {
    "id": "kb_01H8X9QK5R2N7P3M6Z8W4Y1V6U",
    "name": "Product Information",
    "description": "Product specifications and features",
    "status": "PROCESSING",
    "type": "TEXT",
    "created_at": "2025-01-15T11:00:00Z",
    "updated_at": "2025-01-15T11:00:00Z"
  },
  "errors": null
}

---

Docs for agents: llms.txt