---
title: "Create Knowledge Source"
method: POST
path: "/v2/KnowledgeBases/{kbId}/Knowledge"
tags: ["Knowledge"]
---

# Create Knowledge Source

`POST /v2/KnowledgeBases/{kbId}/Knowledge`

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.

## Best practices

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.

## Request body

- KnowledgeCore — Core properties for knowledge source that can be set at creation time. Regularly update and organize your Knowledge sources to ensure it contains the most accurate and relevant information. This includes adding new entries, updating existing ones, and removing outdated content.
  - `name` string, required — The name of the knowledge source.
  - `description` string — A detailed description of the knowledge source and when to use it. This helps provide context about the content and its intended purpose.
  - `source` union — Details specific to the knowledge source type. Each knowledge source type has its own set of configuration parameters and source specific properties.
    - object — Configuration details for raw text knowledge sources
      - `type` 'Text', required — Raw text knowledge sources
      - `content` string, required — The raw text content to be processed
    - object — Configuration details for web based knowledge sources
      - `type` 'Web', required — Web based knowledge sources
      - `url` string, uri, required — The URL to crawl for web content
      - `crawlDepth` integer — The maximum depth to crawl from the source URL
      - `crawlPeriod` 'WEEKLY' | 'BIWEEKLY' | 'MONTHLY' | 'NEVER' — Frequency of re-crawling the website for updated content
      - `errors` KnowledgeErrorGroup[] — Processing errors encountered during web crawling, grouped by title. Array of error groups, where each group has a title and list of error instances. Only present when crawl errors occurred.
        - `title` string, required — The error type or reason (e.g., "404 Not Found", "500 Internal Server Error").
        - `instances` KnowledgeErrorInstance[], required — Array of error instances for this error title. Required when an error group is present.
          - `type` string, required — A URI reference identifying the problem type, resolving to human-readable documentation (e.g., https://www.twilio.com/docs/api/errors/420018).
          - `code` integer, required — Twilio-specific numeric error code for programmatic handling.
          - `instance` string, required — The specific URL or resource that caused the error.
          - `detail` string — Detailed explanation of the error.
    - object — Configuration details for file based knowledge sources. Supported file formats (extension → MIME type): .csv → text/csv .md → text/markdown .pdf → application/pdf .tsv → text/tab-separated-values .txt → text/plain Maximum file size: 16MB (16 * 1024 * 1024 bytes).
      - `type` 'File', required — File based knowledge sources
      - `fileName` string, required — Name of the file to be uploaded
      - `fileSize` integer, required — Expected size of the file in bytes
      - `mimeType` 'text/csv' | 'text/markdown' | 'application/pdf' | 'text/tab-separated-values' | 'text/plain', required — Supported MIME types for knowledge file imports. Maximum file size for any file is 16MB (16 * 1024 * 1024 bytes). Extensions → MIME: .csv → text/csv .md → text/markdown .pdf → application/pdf .tsv → text/tab-separated-values .txt → text/plain
      - `importUrl` string, uri — Presigned S3 URL for file upload (when status is SCHEDULED). Use PUT method to upload the file to this URL when status is SCHEDULED.
      - `uploadExpiration` string, date-time — Expiration time of the presigned upload URL in ISO 8601 format (only present when status is SCHEDULED)

## Response `201`

Created

- Knowledge
  - `name` string, required — The name of the knowledge source.
  - `description` string — A detailed description of the knowledge source and when to use it. This helps provide context about the content and its intended purpose.
  - `source` union — Details specific to the knowledge source type. Each knowledge source type has its own set of configuration parameters and source specific properties.
    - object — Configuration details for raw text knowledge sources
      - `type` 'Text', required — Raw text knowledge sources
      - `content` string, required — The raw text content to be processed
    - object — Configuration details for web based knowledge sources
      - `type` 'Web', required — Web based knowledge sources
      - `url` string, uri, required — The URL to crawl for web content
      - `crawlDepth` integer — The maximum depth to crawl from the source URL
      - `crawlPeriod` 'WEEKLY' | 'BIWEEKLY' | 'MONTHLY' | 'NEVER' — Frequency of re-crawling the website for updated content
      - `errors` KnowledgeErrorGroup[] — Processing errors encountered during web crawling, grouped by title. Array of error groups, where each group has a title and list of error instances. Only present when crawl errors occurred.
        - `title` string, required — The error type or reason (e.g., "404 Not Found", "500 Internal Server Error").
        - `instances` KnowledgeErrorInstance[], required — Array of error instances for this error title. Required when an error group is present.
          - `type` string, required — A URI reference identifying the problem type, resolving to human-readable documentation (e.g., https://www.twilio.com/docs/api/errors/420018).
          - `code` integer, required — Twilio-specific numeric error code for programmatic handling.
          - `instance` string, required — The specific URL or resource that caused the error.
          - `detail` string — Detailed explanation of the error.
    - object — Configuration details for file based knowledge sources. Supported file formats (extension → MIME type): .csv → text/csv .md → text/markdown .pdf → application/pdf .tsv → text/tab-separated-values .txt → text/plain Maximum file size: 16MB (16 * 1024 * 1024 bytes).
      - `type` 'File', required — File based knowledge sources
      - `fileName` string, required — Name of the file to be uploaded
      - `fileSize` integer, required — Expected size of the file in bytes
      - `mimeType` 'text/csv' | 'text/markdown' | 'application/pdf' | 'text/tab-separated-values' | 'text/plain', required — Supported MIME types for knowledge file imports. Maximum file size for any file is 16MB (16 * 1024 * 1024 bytes). Extensions → MIME: .csv → text/csv .md → text/markdown .pdf → application/pdf .tsv → text/tab-separated-values .txt → text/plain
      - `importUrl` string, uri — Presigned S3 URL for file upload (when status is SCHEDULED). Use PUT method to upload the file to this URL when status is SCHEDULED.
      - `uploadExpiration` string, date-time — Expiration time of the presigned upload URL in ISO 8601 format (only present when status is SCHEDULED)
  - `id` string, required — The unique identifier of knowledge source.
  - `status` 'SCHEDULED' | 'QUEUED' | 'PROCESSING' | 'COMPLETED' | 'FAILED', required — The status of processing the knowledge source ('SCHEDULED', 'QUEUED', 'PROCESSING', 'COMPLETED', 'FAILED').
  - `createdAt` string, date-time, required — The date and time in GMT when the Knowledge was created specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
  - `updatedAt` string, date-time, required — The date and time in GMT when the Knowledge was last updated specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.

## Other responses

- `400` — Bad Request
- `404` — Not Found
- `429` — This error indicates that you have sent too many requests to the API. You should retry according to the `Retry-After` response header.
- `500` — Internal Server Error
- `503` — Service Unavailable

## Changes

- **2026-08-13** (v2) `9c54c7dd61a0` — 2 info
  - added the new optional request property `source/oneOf[#/components/schemas/WebSourceDetails]/errors`
  - added the optional property `source/oneOf[#/components/schemas/WebSourceDetails]/errors` to the response with the `201` status
- **2026-08-11** (v2) `59909e2b8833` — 6 breaking, 1 info
  - removed the enum value `text/mdx` of the request property `source/oneOf[#/components/schemas/FileSourceDetails]/mimeType`
  - the `code` response property's max was increased from `99999.00` to `999999.00` for the response status `400`
  - the `code` response property's max was increased from `99999.00` to `999999.00` for the response status `404`
  - the `code` response property's max was increased from `99999.00` to `999999.00` for the response status `429`
  - …3 more

[Change history](https://skmtc.dev/twilio/apis/knowledge-v2/changes/v2/KnowledgeBases/:kbId/Knowledge/post.md)

---

[API](https://skmtc.dev/twilio/apis/knowledge-v2.md) · [All operations](https://skmtc.dev/twilio/apis/knowledge-v2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/twilio/knowledge-v2/revisions/36dc1dbda0b4/schema)