openapi: 3.1.0
info:
  title: Knowledge API
  description: API for managing knowledge in Ada
  version: 1.0.0
tags:
- name: Articles
  description: Articles represent the individual pieces of knowledge content used
    by your bot
- name: Sources
  description: Knowledge sources represent the different sources of your knowledge
    content - for example, knowledge base, marketing website, product manuals, etc.
- name: Tags
  description: Tags are used to categorize articles
paths:
  /knowledge/v1/sources:
    get:
      description: Get knowledge sources
      operationId: getManyKnowledgeSources
      security:
      - BearerAuth: []
      tags:
      - Sources
      responses:
        '200':
          description: Knowledge sources
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/KnowledgeSourceResponse'
        '400':
          description: Invalid request
    post:
      description: Create a knowledge source
      operationId: createSingleKnowledgeSource
      security:
      - BearerAuth: []
      tags:
      - Sources
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KnowledgeSourceCreateRequest'
      responses:
        '201':
          description: Knowledge source created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/KnowledgeSourceResponse'
        '400':
          description: Invalid request
        '409':
          description: "Knowledge source with that name already exists. A source with\
            \ status \"deleting\" or \"delete_failed\" still reserves its name and\
            \ id until its asynchronous deletion completes \u2014 poll the sources\
            \ list until the source disappears before recreating it. The conflicting\
            \ source, including its status, is returned in the error body."
  /knowledge/v1/sources/{id}:
    patch:
      description: Update a knowledge source
      operationId: updateSingleKnowledgeSource
      security:
      - BearerAuth: []
      tags:
      - Sources
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
        description: id of the knowledge source to update
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KnowledgeSourceUpdateRequest'
      responses:
        '200':
          description: Knowledge source updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/KnowledgeSourceResponse'
        '400':
          description: Invalid request
        '409':
          description: Knowledge source with that name already exists. A source with
            status "deleting" or "delete_failed" still reserves its name and id until
            its asynchronous deletion completes; the conflicting source, including
            its status, is returned in the error body.
    delete:
      description: "Request deletion of a knowledge source and its related articles.\
        \ Deletion is asynchronous \u2014 the source reports status \"deleting\" in\
        \ the sources list until it disappears on completion, or \"delete_failed\"\
        \ if the deletion failed (re-issue the request to retry)."
      operationId: deleteSingleKnowledgeSource
      security:
      - BearerAuth: []
      tags:
      - Sources
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
        description: id of the knowledge source to delete
      responses:
        '202':
          description: Knowledge source deletion accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/DeletionAccepted'
        '404':
          description: Knowledge source not found
  /knowledge/v1/articles:
    get:
      description: Get knowledge articles
      operationId: getManyArticles
      security:
      - BearerAuth: []
      tags:
      - Articles
      parameters:
      - in: query
        name: page
        schema:
          type: integer
          minimum: 1
        required: false
        description: page number
      - in: query
        name: per_page
        schema:
          type: integer
          minimum: 1
        required: false
        description: number of articles to return
      - in: query
        name: id
        schema:
          type: array
          items:
            type: string
        description: Filter by article id
      - in: query
        name: enabled
        schema:
          type: array
          items:
            type: boolean
        description: Filter by enabled status
      - in: query
        name: language
        schema:
          type: array
          items:
            type: string
        description: Filter by language
      - in: query
        name: knowledge_source_id
        schema:
          type: array
          items:
            type: string
        description: Filter by knowledge source
      - in: query
        name: tag_ids
        schema:
          type: array
          items:
            type: string
        description: Filter by tag ids
      responses:
        '200':
          description: Matching knowledge articles
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/KnowledgeArticleResponse'
                  meta:
                    $ref: '#/components/schemas/PaginationMetadata'
        '400':
          description: Invalid request
    post:
      description: "Upsert an array of knowledge articles\n\nThis endpoint will create\
        \ or update articles based on the unique `id` field of each article. If an\
        \ article with the same `id` already exists, it will be updated. Otherwise,\
        \ a new article will be created.\n\n**Limits:**\n- The maximum size of a request\
        \ payload is 10MB\n- The maximum size of an article is 100KB\n- The maximum\
        \ number of articles is 50,000 by default. Higher limits are available for\
        \ eligible plans \u2014 contact your Ada team.\n\n**Behavior at the article\
        \ limit:**\nRequests that only update existing articles succeed even when\
        \ the article limit has been reached. If a request contains any new article\
        \ `id`s that would exceed the limit, the whole request is rejected with a\
        \ 400 error whose `errors` array names the new article ids.\n"
      operationId: upsertManyArticles
      security:
      - BearerAuth: []
      tags:
      - Articles
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                articles:
                  type: array
                  items:
                    $ref: '#/components/schemas/KnowledgeArticleUpsertRequest'
      responses:
        '201':
          description: Articles upserted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/KnowledgeArticleUpsertResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleUpsertError'
    delete:
      description: "Request deletion of multiple articles. Deletion is asynchronous\
        \ \u2014 confirm the drain by re-querying the articles list with the same\
        \ filter."
      operationId: deleteManyArticles
      security:
      - BearerAuth: []
      tags:
      - Articles
      parameters:
      - in: query
        name: id
        schema:
          type: array
          items:
            type: string
        description: Filter by article id
      - in: query
        name: enabled
        schema:
          type: array
          items:
            type: boolean
        description: Filter by enabled status
      - in: query
        name: language
        schema:
          type: array
          items:
            type: string
        description: Filter by language
      - in: query
        name: knowledge_source_id
        schema:
          type: array
          items:
            type: string
        description: Filter by knowledge source
      - in: query
        name: tag_ids
        schema:
          type: array
          items:
            type: string
        description: Filter by tag ids
      responses:
        '202':
          description: Article deletion accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/DeletionAccepted'
        '404':
          description: Articles not found
  /knowledge/v1/articles/{id}:
    get:
      description: Get knowledge article by id
      operationId: getSingleArticle
      security:
      - BearerAuth: []
      tags:
      - Articles
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
        description: id of the article to retrieve
      responses:
        '200':
          description: Knowledge article
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/KnowledgeArticleResponse'
        '404':
          description: Article not found
    delete:
      description: Delete an article
      operationId: deleteSingleArticle
      security:
      - BearerAuth: []
      tags:
      - Articles
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
        description: id of the article to delete
      responses:
        '204':
          description: Article successfully deleted
        '404':
          description: Article not found
  /knowledge/v1/tags:
    get:
      description: Get article tags
      operationId: getManyTags
      security:
      - BearerAuth: []
      tags:
      - Tags
      responses:
        '200':
          description: Article tags
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ArticleTagV1'
        '400':
          description: Invalid request
    post:
      description: 'Upsert an array of tags for articles


        This endpoint will create or update tags based on the unique `id` field of
        each tag. If a tag with the same `id` already exists, it will be updated.
        Otherwise, a new tag will be created.

        '
      operationId: upsertManyTags
      security:
      - BearerAuth: []
      tags:
      - Tags
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArticleTagUpsertRequest'
      responses:
        '201':
          description: Tags upserted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ArticleTagUpsertResponse'
        '400':
          description: Invalid request
  /knowledge/v1/tags/{id}:
    delete:
      description: Delete an article tag
      operationId: deleteSingleTag
      security:
      - BearerAuth: []
      tags:
      - Tags
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
        description: id of the article tag to delete
      responses:
        '200':
          description: Article tag deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ArticleTagDeleteResponse'
        '404':
          description: Article tag not found
  /knowledge/v1/spec: {}
  /knowledge/v1/docs: {}
components:
  schemas:
    KnowledgeSourceResponse:
      type: object
      properties:
        external_id:
          type:
          - string
          - 'null'
          minLength: 1
          maxLength: 160
          description: A unique identifier for the knowledge source
        name:
          type: string
          minLength: 1
          description: The name of the knowledge source
        metadata:
          type:
          - object
          - 'null'
          description: A dictionary of arbitrary key,value pairs.                     This
            data is not used by Ada, but can be used by the client to store additional
            information about                     the knowledge source.
        id:
          type: string
          description: A unique identifier for the knowledge source
        created:
          type: string
          format: date-time
          description: The date the knowledge source was created
        updated:
          type: string
          format: date-time
          description: The date the knowledge source was last updated
        status:
          type:
          - string
          - 'null'
          description: 'Deletion lifecycle status of the knowledge source: "deleting"
            while an asynchronous deletion is in progress, "delete_failed" if it failed;
            null otherwise'
      required:
      - id
      - name
    KnowledgeSourceCreateRequest:
      type: object
      properties:
        external_id:
          type:
          - string
          - 'null'
          minLength: 1
          maxLength: 160
          description: A unique identifier for the knowledge source
        name:
          type: string
          minLength: 1
          description: The name of the knowledge source
        metadata:
          type:
          - object
          - 'null'
          description: A dictionary of arbitrary key,value pairs.                     This
            data is not used by Ada, but can be used by the client to store additional
            information about                     the knowledge source.
      required:
      - name
    KnowledgeSourceUpdateRequest:
      type: object
      properties:
        external_id:
          type:
          - string
          - 'null'
          minLength: 1
          maxLength: 160
          description: A unique identifier for the knowledge source
        name:
          type: string
          minLength: 1
          description: The name of the knowledge source
        metadata:
          type:
          - object
          - 'null'
          description: A dictionary of arbitrary key,value pairs.                     This
            data is not used by Ada, but can be used by the client to store additional
            information about                     the knowledge source.
    KnowledgeArticleUpsertResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the article was successfully created/updated
        created:
          type: boolean
          description: '`True` if a new article was created, `false` if an existing
            article was updated'
        id:
          type: string
          minLength: 1
          maxLength: 160
          description: A unique identifier for the article
      required:
      - id
    KnowledgeArticleResponse:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 160
          description: A unique identifier for the article
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: The name or title of the article
        content:
          type: string
          minLength: 1
          description: The content of the article in markdown format
        url:
          type:
          - string
          - 'null'
          format: url
          description: The url of the article
        knowledge_source_id:
          type:
          - string
          - 'null'
          description: The id of the `knowledge_source` the article belongs to
        locale:
          description: The IETF BCP 47 language code for the article, defaults to
            `en` or to the value of language if provided
          type: string
          examples:
          - en-CA
          - en-GB
          - en
          - fr-CA
          - fr-FR
        language:
          type: string
          enum:
          - ar
          - zh
          - zh-tw
          - da
          - nl
          - en
          - fi
          - fr
          - de
          - he
          - hi
          - id
          - in
          - it
          - ja
          - ko
          - ms
          - 'no'
          - pt
          - pa
          - ru
          - es
          - sv
          - tl
          - ta
          - th
          - tr
          - vi
          - ht
          - my
          - km
          - bg
          - ro
          - el
          - hu
          - pl
          - cs
          - et
          - hr
          - lt
          - lv
          - sl
          - sk
          - is
          - be
          - uk
          - ca
          - sq
          - bs
          - sr
          - kk
          description: The ISO 639-1 language code of the article; defaults to `en`
            or is derived from the value of locale if provided
        tag_ids:
          type: array
          maxItems: 100
          description: A list of ids for the tags associated with the article
          items:
            type: string
            minLength: 1
        created:
          type: string
          format: date-time
          description: The date the article was created in Ada
        updated:
          type: string
          format: date-time
          description: The date the article was last updated in Ada
        external_created:
          type:
          - string
          - 'null'
          format: date-time
          description: The date the article was created in the source system
        external_updated:
          type:
          - string
          - 'null'
          format: date-time
          description: The date the article was last updated in the source system
        enabled:
          type: boolean
          description: Whether the article should be referenced during response generation;
            defaults to `true`
        metadata:
          type:
          - object
          - 'null'
          description: A dictionary of arbitrary key,value pairs.                     This
            data is not used by Ada, but can be used by the client to store additional
            information about                     the article.
      required:
      - content
      - id
      - name
    KnowledgeArticleUpsertRequest:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 160
          description: A unique identifier for the article
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: The name or title of the article
        content:
          type: string
          minLength: 1
          description: The content of the article in markdown format
        url:
          type:
          - string
          - 'null'
          format: url
          description: The url of the article
        knowledge_source_id:
          type: string
          description: The id of the `knowledge_source` the article belongs to
        tag_ids:
          type: array
          maxItems: 100
          description: A list of ids for the tags associated with the article
          items:
            type: string
            minLength: 1
        language:
          description: The IETF BCP 47 language code for the article, defaults to
            `en`
          type: string
          examples:
          - en-CA
          - en-GB
          - en
          - fr-CA
          - fr-FR
        external_created:
          type:
          - string
          - 'null'
          format: date-time
          description: The date the article was created in the source system
        external_updated:
          type:
          - string
          - 'null'
          format: date-time
          description: The date the article was last updated in the source system
        enabled:
          type: boolean
          description: Whether the article should be referenced during response generation;
            defaults to `true`
        metadata:
          type:
          - object
          - 'null'
          description: A dictionary of arbitrary key,value pairs.                     This
            data is not used by Ada, but can be used by the client to store additional
            information about                     the article.
      required:
      - content
      - id
      - knowledge_source_id
      - name
    ArticleTagV1:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 40
          description: A unique identifier for the tag
        name:
          type: string
          minLength: 1
          maxLength: 40
          description: The name of the tag
      required:
      - id
      - name
    ArticleTagUpsertRequest:
      type: object
      properties:
        tags:
          type: array
          description: A list of tags
          items:
            $ref: '#/components/schemas/ArticleTagV1'
      required:
      - tags
    ArticleTagUpsertResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the article tag was successfully created/updated
        created:
          type: boolean
          description: '`True` if a new article tag was created, `false` if an existing
            article tag was updated'
        id:
          type: string
          description: The id of the article tag
      required:
      - created
      - id
      - success
    ArticleTagDeleteResponse:
      type: object
      properties:
        deleted_article_tag:
          type: boolean
          description: Whether the article tag was successfully deleted
        updated_article_count:
          type: integer
          description: The number of articles updated
      required:
      - deleted_article_tag
      - updated_article_count
    ArticleUpsertError:
      type: object
      properties:
        message:
          type: string
          description: Error message
        errors:
          description: Error details. For invalid article data, a dictionary where
            the keys represent the index of the item causing the error and the value
            is a dictionary mapping the field name causing the error to an array of
            error messages. When the article limit is exceeded, an array containing
            a single object that identifies the new article ids rejected by the limit
          oneOf:
          - type: object
            description: Dictionary of error details. The keys represent the index
              of the item causing the error. The value is a dictionary where the keys
              specify the field name causing the error. The value is an array of error
              messages
            additionalProperties:
              type: object
              additionalProperties:
                type: array
                items:
                  type: string
          - type: array
            description: Article limit error details
            items:
              type: object
              properties:
                code:
                  type: string
                  description: Machine-readable error code. `knowledge.articles.total_exceeded`
                    when the article limit is exceeded
                new_article_count:
                  type: integer
                  description: The number of new article ids in the request
                new_article_ids:
                  type: array
                  description: The new article ids that would exceed the limit, truncated
                    to the first 100
                  items:
                    type: string
        type:
          type: string
          description: The type of error returned
      required:
      - message
      - type
    DeletionAccepted:
      type: object
      properties:
        status:
          type: string
          description: "Always \"deleting\" \u2014 the deletion was accepted and runs\
            \ asynchronously"
    PaginationMetadata:
      type: object
      properties:
        total_records:
          type: integer
        page:
          type: integer
        per_page:
          type: integer
        next_page_url:
          type:
          - string
          - 'null'
          default: null
        previous_page_url:
          type:
          - string
          - 'null'
          default: null
      required:
      - page
      - per_page
      - total_records
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
servers:
- url: https://{handle}.ada.support/api/
  variables:
    handle:
      default: example
      description: The subdomain of the client