Create Knowledge Base

import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: 'YOUR_RETELL_API_KEY',
});

async function main() {
  const knowledgeBaseResponse = await client.knowledgeBase.create({
    knowledge_base_name: "Sample KB",
    knowledge_base_texts: [
      {
        text: "Hello, how are you?",
        title: "Sample Question",
      },
    ],
    knowledge_base_urls: [
      "https://www.retellai.com",
      "https://docs.retellai.com",
    ],
    knowledge_base_files: [
      fs.createReadStream("../sample.txt"),
    ],
  });

  console.log(knowledgeBaseResponse.knowledge_base_id);
}

main();

from retell import Retell

client = Retell(
    api_key="YOUR_RETELL_API_KEY",
)

file = open("./test_data.txt", "rb")
knowledge_base_response = client.knowledge_base.create(
    knowledge_base_name="Sample KB",
    knowledge_base_texts=[
        {
            "text": "Hello, how are you?",
            "title": "Sample Question",
        },
    ],
    knowledge_base_urls=[
      "https://www.retellai.com",
      "https://docs.retellai.com",
    ],
    knowledge_base_files=[file],
)
print(knowledge_base_response.knowledge_base_id)
file.close()

curl --request POST \
  --url https://api.retellai.com/create-knowledge-base \
  --header 'Authorization: Bearer <token>' \
  --form 'knowledge_base_name=Sample KB' \
  --form 'knowledge_base_texts=[{"title": "Sample Question", "text": "Hello, how are you?"}]' \
  --form 'knowledge_base_urls=["https://www.retellai.com", "https://docs.retellai.com"]' \
  --form 'knowledge_base_files=@./test_data.txt'

{
  "knowledge_base_id": "knowledge_base_a456426614174000",
  "knowledge_base_name": "Sample KB",
  "status": "in_progress",
  "max_chunk_size": 2000,
  "min_chunk_size": 400,
  "knowledge_base_sources": [
    {
      "type": "document",
      "source_id": "<string>",
      "filename": "<string>",
      "file_url": "<string>",
      "file_size": 123
    }
  ],
  "enable_auto_refresh": true,
  "last_refreshed_timestamp": 1703413636133
}

{
  "status": "error",
  "message": "Invalid request format, please check API reference."
}

{
  "status": "error",
  "message": "API key is missing or invalid."
}

{
  "status": "error",
  "message": "Trial has ended, please add payment method."
}

{
  "status": "error",
  "message": "Account rate limited, please throttle your requests."
}

{
  "status": "error",
  "message": "An unexpected server error occurred."
}

POST

create-knowledge-base

import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: 'YOUR_RETELL_API_KEY',
});

async function main() {
  const knowledgeBaseResponse = await client.knowledgeBase.create({
    knowledge_base_name: "Sample KB",
    knowledge_base_texts: [
      {
        text: "Hello, how are you?",
        title: "Sample Question",
      },
    ],
    knowledge_base_urls: [
      "https://www.retellai.com",
      "https://docs.retellai.com",
    ],
    knowledge_base_files: [
      fs.createReadStream("../sample.txt"),
    ],
  });

  console.log(knowledgeBaseResponse.knowledge_base_id);
}

main();

from retell import Retell

client = Retell(
    api_key="YOUR_RETELL_API_KEY",
)

file = open("./test_data.txt", "rb")
knowledge_base_response = client.knowledge_base.create(
    knowledge_base_name="Sample KB",
    knowledge_base_texts=[
        {
            "text": "Hello, how are you?",
            "title": "Sample Question",
        },
    ],
    knowledge_base_urls=[
      "https://www.retellai.com",
      "https://docs.retellai.com",
    ],
    knowledge_base_files=[file],
)
print(knowledge_base_response.knowledge_base_id)
file.close()

curl --request POST \
  --url https://api.retellai.com/create-knowledge-base \
  --header 'Authorization: Bearer <token>' \
  --form 'knowledge_base_name=Sample KB' \
  --form 'knowledge_base_texts=[{"title": "Sample Question", "text": "Hello, how are you?"}]' \
  --form 'knowledge_base_urls=["https://www.retellai.com", "https://docs.retellai.com"]' \
  --form 'knowledge_base_files=@./test_data.txt'

{
  "knowledge_base_id": "knowledge_base_a456426614174000",
  "knowledge_base_name": "Sample KB",
  "status": "in_progress",
  "max_chunk_size": 2000,
  "min_chunk_size": 400,
  "knowledge_base_sources": [
    {
      "type": "document",
      "source_id": "<string>",
      "filename": "<string>",
      "file_url": "<string>",
      "file_size": 123
    }
  ],
  "enable_auto_refresh": true,
  "last_refreshed_timestamp": 1703413636133
}

{
  "status": "error",
  "message": "Invalid request format, please check API reference."
}

{
  "status": "error",
  "message": "API key is missing or invalid."
}

{
  "status": "error",
  "message": "Trial has ended, please add payment method."
}

{
  "status": "error",
  "message": "Account rate limited, please throttle your requests."
}

{
  "status": "error",
  "message": "An unexpected server error occurred."
}

import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: 'YOUR_RETELL_API_KEY',
});

async function main() {
  const knowledgeBaseResponse = await client.knowledgeBase.create({
    knowledge_base_name: "Sample KB",
    knowledge_base_texts: [
      {
        text: "Hello, how are you?",
        title: "Sample Question",
      },
    ],
    knowledge_base_urls: [
      "https://www.retellai.com",
      "https://docs.retellai.com",
    ],
    knowledge_base_files: [
      fs.createReadStream("../sample.txt"),
    ],
  });

  console.log(knowledgeBaseResponse.knowledge_base_id);
}

main();

from retell import Retell

client = Retell(
    api_key="YOUR_RETELL_API_KEY",
)

file = open("./test_data.txt", "rb")
knowledge_base_response = client.knowledge_base.create(
    knowledge_base_name="Sample KB",
    knowledge_base_texts=[
        {
            "text": "Hello, how are you?",
            "title": "Sample Question",
        },
    ],
    knowledge_base_urls=[
      "https://www.retellai.com",
      "https://docs.retellai.com",
    ],
    knowledge_base_files=[file],
)
print(knowledge_base_response.knowledge_base_id)
file.close()

curl --request POST \
  --url https://api.retellai.com/create-knowledge-base \
  --header 'Authorization: Bearer <token>' \
  --form 'knowledge_base_name=Sample KB' \
  --form 'knowledge_base_texts=[{"title": "Sample Question", "text": "Hello, how are you?"}]' \
  --form 'knowledge_base_urls=["https://www.retellai.com", "https://docs.retellai.com"]' \
  --form 'knowledge_base_files=@./test_data.txt'

Authorizations

Authorization

string

header

required

Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY"

Body

multipart/form-data

knowledge_base_name

string

required

Name of the knowledge base. Must be less than 40 characters.

Example:

"Sample KB"

knowledge_base_texts

object[]

Texts to add to the knowledge base.

Show child attributes

knowledge_base_files

file[]

Files to add to the knowledge base. Limit to 25 files, where each file is limited to 50MB.

knowledge_base_urls

string[]

URLs to be scraped and added to the knowledge base. Must be valid urls.

Example:

[
  "https://www.example.com",
  "https://www.retellai.com"
]

enable_auto_refresh

boolean

Whether to enable auto refresh for the knowledge base urls. If set to true, will retrieve the data from the specified url every 12 hours.

Example:

true

max_chunk_size

integer

Maximum number of characters per chunk when splitting knowledge base. Default is 2000. content. Immutable after creation.

Required range: 600 <= x <= 6000

Example:

2000

min_chunk_size

integer

Minimum number of characters per chunk. Chunks smaller than this will be merged with adjacent chunks. Must be less than max_chunk_size. Immutable after creation. Default is 400.

Required range: 200 <= x <= 2000

Example:

400

Response

Successfully created a new knowledge base.

knowledge_base_id

string

required

Unique id of the knowledge base.

Example:

"knowledge_base_a456426614174000"

knowledge_base_name

string

required

Name of the knowledge base. Must be less than 40 characters.

Example:

"Sample KB"

status

enum<string>

required

Current processing state of the knowledge base:

in_progress: Initial indexing is running. Source metadata may be incomplete until indexing finishes.
complete: Initial indexing or the latest update or refresh finished. Individual source failures may still be reported in error_messages.
error: Initial indexing failed. Source metadata may be incomplete.
refreshing_in_progress: An existing knowledge base is being updated. This includes indexing newly added sources or running a manual or automatic refresh that re-indexes URLs, Google Drive files, and pages from auto-crawling paths. Previously indexed sources remain available during the update, and the source list may change when it finishes.

Available options:

in_progress,

complete,

error,

refreshing_in_progress

Example:

"in_progress"

max_chunk_size

integer

Maximum number of characters per chunk when splitting knowledge base content.

Example:

2000

min_chunk_size

integer

Minimum number of characters per chunk. Chunks smaller than this are merged with adjacent chunks.

Example:

400

knowledge_base_sources

object[]

Sources of the knowledge base. Will be populated after the processing is done (when status is "complete").

Option 1
Option 2
Option 3

Show child attributes

enable_auto_refresh

boolean

Whether to enable auto refresh for the knowledge base urls. If set to true, will retrieve the data from the specified url every 12 hours.

Example:

true

last_refreshed_timestamp

integer

Last refreshed timestamp (milliseconds since epoch). Only applicable when enable_auto_refresh is true.

Example:

1703413636133

⌘I

Call

Chat

Playground

Phone Number

Voice Agent

Chat Agent

Retell LLM Response Engine (for single / multi prompt agent)

Conversation Flow Response Engine (for conversation flow agent)

Conversation Flow Subflows

MCP Tool

Knowledge Base

Voice

Batch call

Contact

App

CRM

Test Case Definitions

Batch Tests

Test Runs

Account

Custom Telephony

Custom LLM

Create Knowledge Base

Authorizations

Body

Response