Using Enterprise Knowledge APIs
This page describes how to authenticate and use the Enterprise Knowledge APIs.
Twilio supports HTTP Basic authentication. To authenticate, include the Basic Authentication header where the username:password pair is one of the following:
| Username | Password | Best practice |
|---|---|---|
| API Key | API Key Secret | Authenticate with the Twilio APIs using this key. To prevent unauthorized access, revoke unused or compromised keys . |
| Account SID | Auth Token | Limit your use to local testing. |
To learn more about using Twilio APIs, see Twilio API requests.
A knowledge base organizes knowledge sources into containers that can be semantically indexed and searched. It provides the contextual information for AI and retrieval use cases, such as FAQs, warranty policies, or product information necessary for your business needs. Each Twilio account can contain multiple knowledge bases, and each base can include multiple sources—such as documents, websites, or text content—to provide context for information retrieval.
Knowledge sources represent unstructured or semi-structured data (web pages, files, and raw text) that the system processes into searchable chunks for information retrieval and AI workflows. You can create a knowledge source from various data sources, such as web content, files, or raw text. The system processes and indexes knowledge sources to enable semantic search and retrieval.
Keep the following best practices in mind when working with knowledge bases and sources:
- Access and optimize content: Regularly evaluate your existing knowledge sources for accuracy, relevance, and coverage. Identify any gaps or outdated information that could hinder an AI or human agent's performance.
- Simplify and structure content: Ensure that your content is clear and concise. Use headings, bullet points, and metadata so both agents and end users can find information quickly.
- Prioritize high-impact content: Focus on updating and maintaining content that is frequently accessed or critical to customer interactions. Consider using analytics to determine which knowledge entries are most valuable.
To create a knowledge base, send a POST request to the following endpoint:
POST "https://knowledge.twilio.com/v2/ControlPlane/KnowledgeBases"
| Name | Necessity | Type | Description |
|---|---|---|---|
displayName | Required | string | Provides a human-readable, unique, and addressable name assigned to this knowledge base. The developer assigns this name. You can use this in addition to the ID. |
To learn more, see the knowledge bases API reference.
To add a knowledge source to a knowledge base, send a POST request to the following endpoint:
POST "https://knowledge.twilio.com/v2/KnowledgeBases/{kbId}/Knowledge"
| Name | Necessity | Type | Description |
|---|---|---|---|
kbId | Required | string | A unique knowledge base ID using Twilio Type ID (TTID) format. |
Request body schema for knowledge sources
| Name | Type | Description |
|---|---|---|
| name (Required) | string <= 30 characters | The name of the knowledge source. |
| description | string <= 1024 characters | A detailed description of the knowledge source and when to use it. This helps provide context about the content and its intended purpose. |
| source (Required) | string | Details specific to the knowledge source type. Each knowledge source type has its own set of configuration parameters and source-specific properties. |
| source.type | string | The type of knowledge source, such as text or web. |
| source.content.text Required if source = text | string <= 1024 characters | The raw text content to be processed. |
| source.url.web Required if source = web | string <url> | The URL to crawl for web content. |
| source.url.web.crawlDepth | integer [1-10] | The maximum depth to crawl from the source URL. |
| source.url.web.crawlPeriod | string | Default: NEVER. Valid values: WEEKLY, BIWEEKLY, MONTHLY, or NEVER. Specifies how often to re-crawl the website for updated content. |
To learn more, see the knowledge sources API reference.
To perform semantic search across a knowledge base, use the Search Knowledge Chunks endpoint. The response returns ranked chunks from one or more knowledge sources, so your application can retrieve relevant context for AI workflows, chatbots, and information retrieval systems. Search results include chunk citation metadata that points to the specific source location of each chunk. This lets you show users more precise citations, such as a source page URL for web content or a PDF page number for file content.
To search knowledge chunks, send a POST request to the following endpoint:
POST "https://knowledge.twilio.com/v2/KnowledgeBases/{kbId}/Search"
| Name | Necessity | Type | Description |
|---|---|---|---|
kbId | Required | string | A unique knowledge base ID using Twilio Type ID (TTID) format. |
| Name | Necessity | Type | Description | Range | Maximum |
|---|---|---|---|---|---|
query | Required | string | The natural language query to search for in the knowledge base. | ||
top | Required | integer | The number of top-ranked chunks to return. | 1-20 | 20 |
knowledgeIds | array[string] | The list of knowledge source IDs to search. | 100 |
| Name | Type | Description |
|---|---|---|
chunkIndex | integer | The 0-based position of the chunk within its source document for a single ingestion run. To reconstruct source document order, sort by this value. |
documentTitle | string | The human-readable title given for the source document. Web sources use the HTML page title. |
documentUrl | string | null | The specific page URL from which the chunk was crawled. This value only returns for web sources. File and text sources return null. |
documentNumber | integer | omitted | The 1-based page number returned from the source document. This value only returns for PDF sources. |
To preserve the order of chunks from the original source, include the chunkIndex property. This ensures that generated answers follow a logical document flow instead of stitching together unrelated matches.
To learn more, see the Search Knowledge Chunks API reference.
To inspect the chunks created from a specific knowledge source, use the List Knowledge Chunks endpoint. This endpoint can help you debug source ingestion, review how source content was split, and verify the citation metadata available for each chunk.
To list knowledge chunks for a specific knowledge source, send a GET request to the following endpoint:
GET "https://knowledge.twilio.com/v2/KnowledgeBases/{kbId}/Knowledge/{knowledgeId}/Chunks"
| Name | Necessity | Type | Description |
|---|---|---|---|
kbId | Required | string | A unique knowledge base ID using Twilio Type ID format. |
knowledgeId | Required | string | A unique knowledge source ID using Twilio Type ID format. |
| Name | Type | Description | Default | Maximum |
|---|---|---|---|---|
| pageSize | integer | The number of chunks returned per page. | 50 | 1000 |
| pageToken | string | The page token that the API provides for pagination. |
| Name | Type | Description |
|---|---|---|
id | string | The unique identifier of the chunk. |
content | string | The chunk content. |
knowledgeId | string | The unique identifier of the knowledge source that contains the chunk. |
createdAt | string | The date and time in GMT when the chunk was created, specified in ISO-8601 format. |
chunkIndex | integer | The 0-based position of the chunk within its source document for a single ingestion run. Sort by this value to reconstruct source document order. |
tokenCount | integer | The number of tokens in the chunk content, computed with the same tokenizer used for embedding. |
sectionTitle | string | null | The nearest structural heading above this chunk in the source document. Null for CSV, TSV, and plain text sources. |
documentTitle | string | The human-readable title of the source document. For web sources, this is the HTML page title. |
documentUrl | string | null | The specific page URL that the chunk was crawled from. This value is returned for web sources and is null for file and text sources. |
documentNumber | integer | omitted | The physical page number of the source document. This value is 1-based, returned for PDF sources only, and omitted for all other source types. |
To learn more, see the List Knowledge Chunks API reference.