Skip to main content
POST
/
v1
/
knowledge
/
learn
curl -X POST https://api.bland.ai/v1/knowledge/learn \
  -H "authorization: YOUR_API_KEY" \
  -F "type=file" \
  -F "name=Company FAQs" \
  -F "description=Frequently asked questions and policies" \
  -F "file=@company_faqs.pdf"

{
  "data": {
    "id": "kb_01H8X9QK5R2N7P3M6Z8W4Y1V5T",
    "name": "Company FAQs",
    "description": "Frequently asked questions and policies",
    "status": "PROCESSING",
    "type": "FILE",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z",
    "file": {
      "file_name": "company_faqs.pdf",
      "file_size": 2048576,
      "file_type": "application/pdf"
    }
  },
  "errors": null
}

Documentation Index

Fetch the complete documentation index at: https://blandai-feat-kb-attachment-matrix.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Upload a file to create a knowledge base that can be used to provide contextual information to your AI agents. Supported file formats include PDF, Word documents, text files, and more. This endpoint returns a data.id UUID. See Where can a knowledge base be attached? for the surfaces that consume the UUID (Web Agents, Personas, Pathway nodes, outbound calls).

​
Headers

​
authorization
string
required
Your API key for authentication.
​
content-type
string
required
Must be multipart/form-data for file uploads.

​
Body Parameters (multipart/form-data)

​
type
string
default:"file"
required
Must be "file" for file uploads.
​
name
string
KB name (defaults to filename if not provided).
​
description
string
Optional description of the knowledge base content.
​
file
file
required
The file to upload and process into a knowledge base.

​
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 "FILE" for file-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".
​
data.file
object
File information for the uploaded file.
​
data.file.file_name
string
Original filename.
​
data.file.file_size
number
File size in bytes.
​
data.file.file_type
string
MIME type of the file.
​
errors
null
Will be null on successful creation.
curl -X POST https://api.bland.ai/v1/knowledge/learn \
  -H "authorization: YOUR_API_KEY" \
  -F "type=file" \
  -F "name=Company FAQs" \
  -F "description=Frequently asked questions and policies" \
  -F "file=@company_faqs.pdf"

{
  "data": {
    "id": "kb_01H8X9QK5R2N7P3M6Z8W4Y1V5T",
    "name": "Company FAQs",
    "description": "Frequently asked questions and policies",
    "status": "PROCESSING",
    "type": "FILE",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z",
    "file": {
      "file_name": "company_faqs.pdf",
      "file_size": 2048576,
      "file_type": "application/pdf"
    }
  },
  "errors": null
}
Docs for agents: llms.txt