openapi: 3.2.0
info:
  title: Twilio Knowledge Knowledge Bases API
  description: APIs for managing knowledge bases and knowledge content for AI-powered applications.
  version: '1.0'
  termsOfService: https://www.twilio.com/legal/tos
  contact:
    name: Twilio Support
    url: https://support.twilio.com
    email: support@twilio.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  x-twilio:
    apiStandards: v1.0
servers:
- url: https://knowledge.twilio.com
security:
- accountSid_authToken: []
tags:
- name: KnowledgeBases
paths:
  /v2/ControlPlane/KnowledgeBases:
    servers:
    - url: https://knowledge.twilio.com
    x-twilio:
      pathType: list
    get:
      operationId: ListKnowledgeBases
      tags:
      - KnowledgeBases
      summary: List Knowledge Bases
      description: Get a list of knowledge bases for the Twilio account.
      parameters:
      - $ref: '#/components/parameters/ControlPlanePageSize'
      - $ref: '#/components/parameters/PageToken'
      - $ref: '#/components/parameters/OrderBy'
      responses:
        '200':
          description: Knowledge Bases retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeBaseList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: CreateKnowledgeBase
      tags:
      - KnowledgeBases
      summary: Create a Knowledge Base
      description: Create a new Knowledge Base for the Twilio account. Accounts can have multiple knowledge bases. Each knowledge base can contain multiple knowledge resources such as documents, websites, or text content that can be used for context and information retrieval.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KnowledgeBaseCore'
      responses:
        '202':
          description: Knowledge Base creation request accepted.
          headers:
            Operation-Id:
              $ref: '#/components/headers/OperationId'
            Location:
              $ref: '#/components/headers/OperationLocation'
            Retry-After:
              $ref: '#/components/headers/OperationRetryAfter'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  message:
                    type: string
                    maxLength: 512
                    example: Knowledge Base creation request accepted for processing.
                  statusUrl:
                    type: string
                    description: URI to check operation status.
                    maxLength: 512
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v2/ControlPlane/KnowledgeBases/{kbId}:
    servers:
    - url: https://knowledge.twilio.com
    parameters:
    - $ref: '#/components/parameters/KbId'
    x-twilio:
      pathType: instance
    get:
      operationId: FetchKnowledgeBase
      tags:
      - KnowledgeBases
      summary: Retrieve a Knowledge Base
      description: Retrieve the details of a specific Knowledge Base by its unique ID.
      responses:
        '200':
          description: Knowledge Base details retrieved successfully
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeBase'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    patch:
      operationId: UpdateKnowledgeBase
      parameters:
      - $ref: '#/components/parameters/IfMatchHeader'
      tags:
      - KnowledgeBases
      summary: Update a Knowledge Base
      description: Partially update a Knowledge Base. Only the fields provided in the request body will be updated.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                displayName:
                  type: string
                  description: Provides a unique and addressable name to be assigned to this Knowledge Base. This name is assigned by the developer and can be used in addition to the ID. It is intended to be human-readable and unique within the account.
                  pattern: ^[a-zA-Z0-9-]+$
                  maxLength: 64
                  example: product-docs
                description:
                  type: string
                  description: A human readable description of this resource, up to 128 characters.
                  minLength: 1
                  maxLength: 128
                  example: Product documentation knowledge base for customer support
      responses:
        '202':
          description: Knowledge Base update request accepted.
          headers:
            Operation-Id:
              $ref: '#/components/headers/OperationId'
            Location:
              $ref: '#/components/headers/OperationLocation'
            Retry-After:
              $ref: '#/components/headers/OperationRetryAfter'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  message:
                    type: string
                    maxLength: 512
                    example: Knowledge Base update request accepted for processing.
                  statusUrl:
                    type: string
                    description: URI to check operation status.
                    maxLength: 512
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      operationId: DeleteKnowledgeBase
      tags:
      - KnowledgeBases
      summary: Delete a Knowledge Base
      description: Delete a Knowledge Base and all associated knowledge resources. This action cannot be undone.
      responses:
        '202':
          description: Knowledge Base deletion request accepted.
          headers:
            Operation-Id:
              $ref: '#/components/headers/OperationId'
            Location:
              $ref: '#/components/headers/OperationLocation'
            Retry-After:
              $ref: '#/components/headers/OperationRetryAfter'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  message:
                    type: string
                    maxLength: 512
                    example: Knowledge Base deletion request accepted for processing.
                  statusUrl:
                    type: string
                    description: URI to check operation status.
                    maxLength: 512
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  headers:
    OperationId:
      description: The operation identifier.
      schema:
        type: string
        maxLength: 512
    OperationLocation:
      description: URI to check operation status.
      schema:
        type: string
        maxLength: 512
    OperationRetryAfter:
      description: Suggested number of seconds to wait before checking status again.
      schema:
        type: integer
    ETag:
      description: 'Entity tag that acts as a unique identifier for a specific version of the resource.

        Send updates with If-Match conditional headers for optimistic concurrency control.'
      schema:
        type: string
        maxLength: 512
      example: eyJpZCI6ImFuX2lkIiwidiI6MX0
  schemas:
    TwilioError:
      type: object
      additionalProperties: false
      maxProperties: 10
      description: A generic error object communicating client and server side API errors.
      properties:
        code:
          type: integer
          minimum: 100
          maximum: 999999
          description: The Twilio error code.
          format: int32
        message:
          type: string
          maxLength: 1024
          description: A human readable message describing the error.
        more_info:
          type: string
          description: A URL to a [Twilio error directory](https://www.twilio.com/docs/api/errors) page with more information about the error code.
        status:
          type: integer
          minimum: 100
          maximum: 599
          description: The HTTP status code for the error.
          format: int32
      example:
        code: 21614
        message: The address specified in the request is not a valid phone number.
        more_info: https://www.twilio.com/docs/api/errors/21614
        status: 400
    KnowledgeBase:
      type: object
      properties:
        displayName:
          type: string
          description: 'Provides a unique and addressable name to be assigned to this Knowledge Base. This name is assigned

            by the developer and can be used in addition to the ID. It is intended to be human-readable and unique within

            the account.'
          pattern: ^[a-zA-Z0-9-]+$
          maxLength: 64
          example: product-docs
        description:
          type: string
          description: A human readable description of this resource, up to 128 characters.
          minLength: 1
          maxLength: 128
          example: Product documentation knowledge base for customer support
        id:
          type: string
          description: The unique identifier for the Knowledge Base
          pattern: ^know_knowledgebase_[0-7][0-9a-z]{25}$
          example: know_knowledgebase_00000000000000000000000000
        status:
          type: string
          description: The provisioning status of the Knowledge Base
          enum:
          - QUEUED
          - PROVISIONING
          - ACTIVE
          - FAILED
          - DELETING
          example: ACTIVE
        createdAt:
          type: string
          format: date-time
          description: The ISO 8601 timestamp when the Knowledge Base was created.
          example: '2024-01-15T10:30:00Z'
        updatedAt:
          type: string
          format: date-time
          description: The ISO 8601 timestamp when the Knowledge Base was last updated.
          example: '2024-01-15T11:45:00Z'
        version:
          type: integer
          minimum: 1
          description: The current version number of the Knowledge Base. Incremented on each successful mutable update.
          example: 3
      required:
      - displayName
      - status
      - id
      - updatedAt
      - version
      - createdAt
    KnowledgeBaseCore:
      type: object
      properties:
        displayName:
          type: string
          description: 'Provides a unique and addressable name to be assigned to this Knowledge Base. This name is assigned

            by the developer and can be used in addition to the ID. It is intended to be human-readable and unique within

            the account.'
          pattern: ^[a-zA-Z0-9-]+$
          maxLength: 64
          example: product-docs
        description:
          type: string
          description: A human readable description of this resource, up to 128 characters.
          minLength: 1
          maxLength: 128
          example: Product documentation knowledge base for customer support
      required:
      - displayName
    KnowledgeBaseList:
      type: object
      additionalProperties: false
      properties:
        knowledgeBases:
          type: array
          maxItems: 1000
          items:
            $ref: '#/components/schemas/KnowledgeBase'
          description: List of Knowledge Bases associated with the Twilio account.
        meta:
          $ref: '#/components/schemas/Meta'
    Meta:
      type: object
      additionalProperties: false
      properties:
        key:
          type: string
          maxLength: 64
          description: 'The key of the list property contains the actual data items.

            This enables programmatic iteration over paginated results.

            '
        pageSize:
          type: integer
          description: The number of items returned in this page of results.
        nextToken:
          type: string
          maxLength: 4096
          example: eyJlYXN0ZXIiOiJlZ2cifQ
        previousToken:
          type: string
          maxLength: 4096
          example: eyJlYXN0ZXIiOiJlZ2cifQ
  responses:
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 20500
            message: Internal Server Error
            more_info: https://www.twilio.com/docs/api/errors/20500
            status: 500
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 20404
            message: Not Found
            more_info: https://www.twilio.com/docs/api/errors/20404
            status: 404
    ServiceUnavailable:
      description: Service Unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 20503
            message: Service Unavailable
            more_info: https://www.twilio.com/docs/api/errors/20503
            status: 503
    TooManyRequests:
      description: This error indicates that you have sent too many requests to the API. You should retry according to the `Retry-After` response header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 20429
            message: Too many requests. Please retry according to the Retry-After response header.
            more_info: https://www.twilio.com/docs/api/errors/20429
            status: 429
      headers:
        Retry-After:
          description: The amount of time in seconds that the customer should wait before issuing a new request towards the API.
          schema:
            type: string
            pattern: ^[0-9]+$
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 400
            message: Failed to complete request due to a bad request
            more_info: https://www.twilio.com/docs/api/errors/400
            status: 400
  parameters:
    IfMatchHeader:
      in: header
      name: If-Match
      description: 'Allows for optimistic concurrency control by making the request conditional.

        Server will only act if the resource''s current Entity Tag (ETag) matches

        the one provided, preventing accidental overwrites.'
      schema:
        type: string
        maxLength: 100
        example: '"eyJpZCI6ImFuX2lkIiwidiI6MX0"'
    PageToken:
      name: pageToken
      in: query
      required: false
      description: The token for the page of results to retrieve.
      schema:
        type: string
        maxLength: 4096
    OrderBy:
      name: orderBy
      in: query
      required: false
      description: Either 'ASC' or 'DESC' to sort results ascending or descending respectively.
      schema:
        type: string
        enum:
        - ASC
        - DESC
        default: DESC
    ControlPlanePageSize:
      name: pageSize
      in: query
      required: false
      description: The maximum number of items to return per page, maximum of 100.
      schema:
        type: integer
        default: 50
        minimum: 1
        maximum: 100
    KbId:
      name: kbId
      in: path
      required: true
      description: A unique Knowledge Base ID using Twilio Type ID (TTID) format
      schema:
        type: string
        pattern: ^know_knowledgebase_[0-7][0-9a-z]{25}$
        example: know_knowledgebase_00000000000000000000000000
  securitySchemes:
    accountSid_authToken:
      scheme: basic
      type: http