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
  /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
    delete:
      description: Delete a knowledge source and its related articles
      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:
        '200':
          description: Knowledge source deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/KnowledgeSourceDeleteResult'
        '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


        This 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.


        **Limits:**

        - The maximum size of a request payload is 10MB

        - The maximum size of an article is 100KB

        - The maximum number of articles is 100,000

        '
      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: Delete multiple articles
      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:
        '200':
          description: Articles successfully deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer
        '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
      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:
          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`
        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:
          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:
          type: string
          description: The type of error returned
      required:
      - message
      - type
    KnowledgeSourceDeleteResult:
      type: object
      properties:
        deleted_source:
          type: boolean
          description: Whether the knowledge source was deleted
        deleted_article_count:
          type: integer
          description: The number of articles that were deleted
    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