Knowledge API (v2) - Knowledge endpoints
Legal information
Enterprise Knowledge, including the APIs, may use artificial intelligence or machine learning technologies and is subject to the terms of the Predictive and Generative AI/ML Features Addendum. For more details on AI usage and data, see the AI Nutrition Facts.
Enterprise Knowledge is not a HIPAA Eligible Service or PCI compliant and should not be enabled in workflows that are subject to HIPAA or PCI.
Conversations products are only available in the new Twilio Console. If your account hasn't been migrated, you'll be redirected to the legacy Console where these products won't appear.
Create Knowledge Source
List Knowledge Sources
Retrieve Knowledge Source
Update Knowledge Source
Delete Knowledge Source
List Knowledge Chunks
Search Knowledge Chunks
POST/v2/KnowledgeBases/{kbId}/Knowledge
Base url: https://knowledge.twilio.com (base url)
Create a new knowledge source from various data sources such as web content, files, or raw text. The knowledge source will be processed and indexed to enable semantic search and retrieval.
To maximize the effectiveness of Knowledge, consider the following best practices:
Assess and optimize content: Regularly evaluate your existing Knowledge sources for accuracy, relevance, and coverage. Identify any gaps or outdated information that could hinder the Assistant's performance.
Simplify and structure content: Ensure that the content is clear and concise. Use headings, bullet points, and metadata to make information straightforward to navigate for both the AI Assistant and your users.
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.
A unique Knowledge Base ID using Twilio Type ID (TTID) format
know_knowledgebase_00000000000000000000000000Pattern: ^know_knowledgebase_[0-7][0-9a-z]{25}$application/jsonThe name of the knowledge source.
Company FAQ Knowledge BaseMax length: 30A detailed description of the knowledge source and when to use it. This helps provide context about the content and its intended purpose.
1024Details specific to the knowledge source type. Each knowledge source type has its own set of configuration parameters and source specific properties.
Created
The name of the knowledge source.
Company FAQ Knowledge BaseMax length: 30A detailed description of the knowledge source and when to use it. This helps provide context about the content and its intended purpose.
1024Details specific to the knowledge source type. Each knowledge source type has its own set of configuration parameters and source specific properties.
The unique identifier of knowledge source.
know_knowledge_00000000000000000000000000Pattern: ^know_knowledge_[0-7][0-9a-z]{25}$The status of processing the knowledge source ('SCHEDULED', 'QUEUED', 'PROCESSING', 'COMPLETED', 'FAILED').
COMPLETEDPossible values: SCHEDULEDQUEUEDPROCESSINGCOMPLETEDFAILEDThe date and time in GMT when the Knowledge was created specified in ISO 8601 format.
2025-01-15T10:30:00Z1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createKnowledge() {11const knowledge = await client.knowledge.v212.knowledge("know_knowledgebase_00000000000000000000000000")13.create({14name: "Miss Christine Morgan",15});1617console.log(knowledge.name);18}1920createKnowledge();
Response
1{2"id": "know_knowledge_00000000000000000000000000",3"name": "Miss Christine Morgan",4"description": "Comprehensive product documentation and user guides",5"status": "QUEUED",6"source": {7"type": "Web",8"url": "https://docs.example.com",9"crawlDepth": 310},11"createdAt": "2026-01-15T12:00:00Z",12"updatedAt": "2026-01-15T12:00:00Z"13}
GET/v2/KnowledgeBases/{kbId}/Knowledge
Base url: https://knowledge.twilio.com (base url)
Retrieve a paginated list of all knowledge sources for a specific knowledge base. Knowledge sources represent unstructured data sources such as documents, websites, or text content that can be used for context and information retrieval.
A unique Knowledge Base ID using Twilio Type ID (TTID) format
know_knowledgebase_00000000000000000000000000Pattern: ^know_knowledgebase_[0-7][0-9a-z]{25}$The maximum number of items to return per page, maximum of 1000.
50Minimum: 1Maximum: 1000The token for the page of results to retrieve.
500OK
Pagination metadata for list operations
{"key":"knowledge","pageSize":50,"nextToken":"eyJlYXN0ZXIiOiJlZ2cifQ","previousToken":""}1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function listKnowledge() {11const knowledge = await client.knowledge.v212.knowledge("know_knowledgebase_00000000000000000000000000")13.list({ limit: 20 });1415knowledge.forEach((k) => console.log(k.name));16}1718listKnowledge();
Response
1{2"knowledge": [3{4"name": "name",5"description": "description",6"source": {},7"id": "know_knowledge_00000000000000000000000000",8"status": "COMPLETED",9"createdAt": "2009-07-06T20:30:00Z",10"updatedAt": "2009-07-06T20:30:00Z"11}12],13"meta": {14"key": "key",15"pageSize": 50,16"nextToken": "nextToken",17"previousToken": "previousToken"18}19}
GET/v2/KnowledgeBases/{kbId}/Knowledge/{knowledgeId}
Base url: https://knowledge.twilio.com (base url)
Fetch detailed information about a specific knowledge source by its ID. This returns the complete knowledge source object including processing status, source details, and configuration information.
A unique Knowledge Base ID using Twilio Type ID (TTID) format
know_knowledgebase_00000000000000000000000000Pattern: ^know_knowledgebase_[0-7][0-9a-z]{25}$A unique Knowledge resource ID using Twilio Type ID (TTID) format
know_knowledge_00000000000000000000000000Pattern: ^know_knowledge_[0-7][0-9a-z]{25}$OK
The name of the knowledge source.
Company FAQ Knowledge BaseMax length: 30A detailed description of the knowledge source and when to use it. This helps provide context about the content and its intended purpose.
1024Details specific to the knowledge source type. Each knowledge source type has its own set of configuration parameters and source specific properties.
The unique identifier of knowledge source.
know_knowledge_00000000000000000000000000Pattern: ^know_knowledge_[0-7][0-9a-z]{25}$The status of processing the knowledge source ('SCHEDULED', 'QUEUED', 'PROCESSING', 'COMPLETED', 'FAILED').
COMPLETEDPossible values: SCHEDULEDQUEUEDPROCESSINGCOMPLETEDFAILEDThe date and time in GMT when the Knowledge was created specified in ISO 8601 format.
2025-01-15T10:30:00Z1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function fetchKnowledge() {11const knowledge = await client.knowledge.v212.knowledge(13"know_knowledgebase_00000000000000000000000000",14"know_knowledge_00000000000000000000000000"15)16.fetch();1718console.log(knowledge.name);19}2021fetchKnowledge();
Response
1{2"createdAt": "2009-07-06T20:30:00Z",3"description": "description",4"id": "know_knowledge_00000000000000000000000000",5"name": "Miss Christine Morgan",6"source": {},7"status": "COMPLETED",8"updatedAt": "2009-07-06T20:30:00Z"9}
PATCH/v2/KnowledgeBases/{kbId}/Knowledge/{knowledgeId}
Base url: https://knowledge.twilio.com (base url)
Partially update mutable fields of an existing knowledge source such as name, description, tags, or source-specific configuration. Only the fields provided in the request body will be updated. Some changes (e.g., KnowledgeSourceTypes) may trigger asynchronous reprocessing of the underlying content. Fields omitted from the request remain unchanged. Immutable fields (id, type, status, url, createdAt, updatedAt) cannot be modified directly.
To request reprocessing without changing fields, pass the query parameter refresh=true. When refresh=true is provided,
the server will re-queue processing for this knowledge resource (transitioning the persisted status to QUEUED) and
return 202 Accepted. This query parameter is idempotent while the resource is already QUEUED or PROCESSING.
A unique Knowledge Base ID using Twilio Type ID (TTID) format
know_knowledgebase_00000000000000000000000000Pattern: ^know_knowledgebase_[0-7][0-9a-z]{25}$A unique Knowledge resource ID using Twilio Type ID (TTID) format
know_knowledge_00000000000000000000000000Pattern: ^know_knowledge_[0-7][0-9a-z]{25}$When true, re-queues processing for this knowledge resource. Idempotent while the resource is already QUEUED or PROCESSING.
falseapplication/jsonThe name of the knowledge source.
Company FAQ Knowledge BaseMax length: 30A detailed description of the knowledge source and when to use it. This helps provide context about the content and its intended purpose.
1024Details specific to the knowledge source type. Each knowledge source type has its own set of configuration parameters and source specific properties.
OK
The name of the knowledge source.
Company FAQ Knowledge BaseMax length: 30A detailed description of the knowledge source and when to use it. This helps provide context about the content and its intended purpose.
1024Details specific to the knowledge source type. Each knowledge source type has its own set of configuration parameters and source specific properties.
The unique identifier of knowledge source.
know_knowledge_00000000000000000000000000Pattern: ^know_knowledge_[0-7][0-9a-z]{25}$The status of processing the knowledge source ('SCHEDULED', 'QUEUED', 'PROCESSING', 'COMPLETED', 'FAILED').
COMPLETEDPossible values: SCHEDULEDQUEUEDPROCESSINGCOMPLETEDFAILEDThe date and time in GMT when the Knowledge was created specified in ISO 8601 format.
2025-01-15T10:30:00Z1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function updateKnowledge() {11const knowledge = await client.knowledge.v212.knowledge(13"know_knowledgebase_00000000000000000000000000",14"know_knowledge_00000000000000000000000000"15)16.update({17name: "Miss Christine Morgan",18});1920console.log(knowledge.name);21}2223updateKnowledge();
Response
1{2"createdAt": "2009-07-06T20:30:00Z",3"description": "description",4"id": "know_knowledge_00000000000000000000000000",5"name": "Miss Christine Morgan",6"source": {},7"status": "COMPLETED",8"updatedAt": "2009-07-06T20:30:00Z"9}
DELETE/v2/KnowledgeBases/{kbId}/Knowledge/{knowledgeId}
Base url: https://knowledge.twilio.com (base url)
Permanently delete knowledge source and all its associated data, including processed chunks and embeddings. This action cannot be undone. The knowledge resource will no longer be available for search or retrieval operations.
A unique Knowledge Base ID using Twilio Type ID (TTID) format
know_knowledgebase_00000000000000000000000000Pattern: ^know_knowledgebase_[0-7][0-9a-z]{25}$A unique Knowledge resource ID using Twilio Type ID (TTID) format
know_knowledge_00000000000000000000000000Pattern: ^know_knowledge_[0-7][0-9a-z]{25}$No Content
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function deleteKnowledge() {11await client.knowledge.v212.knowledge(13"know_knowledgebase_00000000000000000000000000",14"know_knowledge_00000000000000000000000000"15)16.remove();17}1819deleteKnowledge();
GET/v2/KnowledgeBases/{kbId}/Knowledge/{knowledgeId}/Chunks
Base url: https://knowledge.twilio.com (base url)
Retrieve a paginated list of all processed content chunks from a specific knowledge source. Chunks are smaller segments of content that have been extracted and processed from the original knowledge source. Each chunk contains content text and associated metadata that can be used for semantic search and retrieval operations.
A unique Knowledge Base ID using Twilio Type ID (TTID) format
know_knowledgebase_00000000000000000000000000Pattern: ^know_knowledgebase_[0-7][0-9a-z]{25}$A unique Knowledge resource ID using Twilio Type ID (TTID) format
know_knowledge_00000000000000000000000000Pattern: ^know_knowledge_[0-7][0-9a-z]{25}$How many resources to return in each list page. The default is 50, and the maximum is 1000.
1Maximum: 1000The page token. This is provided by the API.
2048OK
Pagination metadata for list operations
{"key":"knowledge","pageSize":50,"nextToken":"eyJlYXN0ZXIiOiJlZ2cifQ","previousToken":""}1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function listKnowledgeChunks() {11const chunks = await client.knowledge.v212.chunks(13"know_knowledgebase_00000000000000000000000000",14"know_knowledge_00000000000000000000000000"15)16.list({ limit: 20 });1718chunks.forEach((c) => console.log(c.content));19}2021listKnowledgeChunks();
Response
1{2"chunks": [3{4"content": "content",5"createdAt": "2009-07-06T20:30:00Z"6}7],8"meta": {9"key": "key",10"pageSize": 50,11"nextToken": "nextToken",12"previousToken": "previousToken"13}14}
POST/v2/KnowledgeBases/{kbId}/Search
Base url: https://knowledge.twilio.com (base url)
Perform semantic search across knowledge sources within a knowledge base to find the most relevant content chunks based on a natural language query. Returns ranked chunks with similarity scores, allowing you to retrieve contextually relevant information for AI applications, chatbots, or information retrieval systems. You can filter results by specific knowledge sources.
A unique Knowledge Base ID using Twilio Type ID (TTID) format
know_knowledgebase_00000000000000000000000000Pattern: ^know_knowledgebase_[0-7][0-9a-z]{25}$application/jsonThe list of knowledge IDs to search.
100OK
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createKnowledgeSearch() {11const search = await client.knowledge.v212.search("know_knowledgebase_00000000000000000000000000")13.create({14query: "How do I reset my password?",15top: 5,16knowledgeIds: ["know_knowledge_00000000000000000000000000"],17});1819console.log(search.chunks);20}2122createKnowledgeSearch();
Response
1{2"chunks": [3{4"content": "content",5"createdAt": "2009-07-06T20:30:00Z",6"score": 42,7"knowledgeId": "know_knowledge_00000000000000000000000000"8}9]10}