Add Knowledge Base Sources

POST

add-knowledge-base-sources

{knowledge_base_id}

import Retell from 'retell-sdk';
import fs from 'fs';

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

async function main() {
  const knowledgeBaseResponse = await client.knowledgeBase.addSources(
    "knowledge_base_xxxxxxxxxxxx",
    {
      knowledge_base_texts: [
        {
          title: "Sample Question",
          text: "Hello, how are you?",
        },
      ],
      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("./sample.txt", "rb")
knowledge_base_response = client.knowledge_base.add_sources(
    knowledge_base_id="knowledge_base_xxxxxxxxxxxx",
    knowledge_base_texts=[
        {
            "title": "Sample Question",
            "text": "Hello, how are you?",
        },
    ],
    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/add-knowledge-base-sources/knowledge_base_xxxxxxxxxxxx \
  --header 'Authorization: Bearer YOUR_RETELL_API_KEY' \
  --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=@./sample.txt'

{
  "knowledge_base_id": "knowledge_base_a456426614174000",
  "knowledge_base_name": "Sample KB",
  "remaining_ingestion_quota": {
    "files": 25,
    "texts": 50,
    "urls": 200
  },
  "ingestion_limits": {
    "files": 25,
    "texts": 50,
    "urls": 200
  },
  "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": "File source addition limit reached for this knowledge base (25 per 30 days). Please contact support."
}

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

import Retell from 'retell-sdk';
import fs from 'fs';

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

async function main() {
  const knowledgeBaseResponse = await client.knowledgeBase.addSources(
    "knowledge_base_xxxxxxxxxxxx",
    {
      knowledge_base_texts: [
        {
          title: "Sample Question",
          text: "Hello, how are you?",
        },
      ],
      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("./sample.txt", "rb")
knowledge_base_response = client.knowledge_base.add_sources(
    knowledge_base_id="knowledge_base_xxxxxxxxxxxx",
    knowledge_base_texts=[
        {
            "title": "Sample Question",
            "text": "Hello, how are you?",
        },
    ],
    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/add-knowledge-base-sources/knowledge_base_xxxxxxxxxxxx \
  --header 'Authorization: Bearer YOUR_RETELL_API_KEY' \
  --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=@./sample.txt'

Authorizations

Authorization

string

header

required

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

Path Parameters

knowledge_base_id

string

required

The knowledge base id to delete source from.

Example:

"kb_1234567890"

Body

multipart/form-data

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"
]

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"

remaining_ingestion_quota

object | null

required

Ingestion quota available to this knowledge base at response time. Includes unused lifetime fill allowance plus remaining rolling 30-day per-KB capacity. Pending reservations already consume capacity. Default per-KB rolling limits are 25 files, 50 texts, and 200 URLs; organization-specific increases are reflected in these counts. Legacy knowledge bases without fill allowance receive rolling capacity only. Deleting sources does not restore ingestion quota. These counts do not include the separate limits on how many sources a KB can hold, and do not guarantee a concurrent request will succeed. Create and add-source responses include reservations for accepted sources; background discovery and processing may change the counts. Returns null if current usage cannot be read. Null means unavailable, not zero remaining capacity. Configured ingestion_limits are still returned. Quota enforcement remains required for ingestion requests.

Show child attributes

Example:

{ "files": 25, "texts": 50, "urls": 200 }

ingestion_limits

object

required

Effective rolling 30-day ingestion limits. Each KB has an independent budget. Lifetime fill allowance and structural source-count caps are separate.

Show child attributes

Example:

{ "files": 25, "texts": 50, "urls": 200 }

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, Microsoft OneDrive 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 eligible URL and connected-file sources refresh automatically on a daily cadence.

Example:

true

last_refreshed_timestamp

integer

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

Example:

1703413636133

⌘I

import Retell from 'retell-sdk';
import fs from 'fs';

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

async function main() {
  const knowledgeBaseResponse = await client.knowledgeBase.addSources(
    "knowledge_base_xxxxxxxxxxxx",
    {
      knowledge_base_texts: [
        {
          title: "Sample Question",
          text: "Hello, how are you?",
        },
      ],
      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("./sample.txt", "rb")
knowledge_base_response = client.knowledge_base.add_sources(
    knowledge_base_id="knowledge_base_xxxxxxxxxxxx",
    knowledge_base_texts=[
        {
            "title": "Sample Question",
            "text": "Hello, how are you?",
        },
    ],
    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/add-knowledge-base-sources/knowledge_base_xxxxxxxxxxxx \
  --header 'Authorization: Bearer YOUR_RETELL_API_KEY' \
  --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=@./sample.txt'

{
  "knowledge_base_id": "knowledge_base_a456426614174000",
  "knowledge_base_name": "Sample KB",
  "remaining_ingestion_quota": {
    "files": 25,
    "texts": 50,
    "urls": 200
  },
  "ingestion_limits": {
    "files": 25,
    "texts": 50,
    "urls": 200
  },
  "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": "File source addition limit reached for this knowledge base (25 per 30 days). Please contact support."
}

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

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

Add Knowledge Base Sources

Authorizations

Path Parameters

Body

Response