Ada knowledge > articles API

openapi: 3.2.0
info:
  title: knowledge > articles API
  version: 1.0.0
servers:
- url: https://example.ada.support/api
  description: Production
tags:
- name: knowledge > articles
paths:
  /v2/knowledge/articles/:
    get:
      operationId: list
      summary: Get knowledge articles
      tags:
      - knowledge > articles
      parameters:
      - name: cursor
        in: query
        description: The article cursor that marks the start or beginning of the returned article records
        required: false
        schema:
          type: string
          format: id
      - name: limit
        in: query
        description: The number of article records to return
        required: false
        schema:
          type: integer
      - name: id
        in: query
        description: Filter by article id
        required: false
        schema:
          type: array
          items:
            type: string
            format: id
      - name: enabled
        in: query
        description: Filter by enabled status
        required: false
        schema:
          type: array
          items:
            type: boolean
      - name: language
        in: query
        description: Filter by language
        required: false
        schema:
          type: array
          items:
            type: string
      - name: knowledge_source_id
        in: query
        description: Filter by knowledge source
        required: false
        schema:
          type: array
          items:
            type: string
            format: id
      - name: tag_ids
        in: query
        description: Filter by tag ids
        required: false
        schema:
          type: array
          items:
            type: string
            format: id
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Matching knowledge articles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/knowledge_articles_list_Response_200'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    delete:
      operationId: delete
      summary: Delete multiple articles
      description: 'Delete multiple articles


        Deletion is asynchronous: a `204` response means the deletion request was accepted and the matching articles are deleted in the background. To confirm completion, re-query `GET /v2/knowledge/articles/` with the same filters until no articles match. A `404` is still returned when no articles match the provided filters.'
      tags:
      - knowledge > articles
      parameters:
      - name: id
        in: query
        description: Filter by article id
        required: false
        schema:
          type: array
          items:
            type: string
            format: id
      - name: enabled
        in: query
        description: Filter by enabled status
        required: false
        schema:
          type: array
          items:
            type: boolean
      - name: language
        in: query
        description: Filter by language
        required: false
        schema:
          type: array
          items:
            type: string
      - name: knowledge_source_id
        in: query
        description: Filter by knowledge source
        required: false
        schema:
          type: array
          items:
            type: string
            format: id
      - name: tag_ids
        in: query
        description: Filter by tag ids
        required: false
        schema:
          type: array
          items:
            type: string
            format: id
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Article deletion accepted; matching articles are deleted in the background
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/knowledge_articles_delete_Response_204'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /v2/knowledge/articles/{id}:
    get:
      operationId: get
      summary: Get a single knowledge article
      description: Get knowledge article by id
      tags:
      - knowledge > articles
      parameters:
      - name: id
        in: path
        description: The id of the article to retrieve
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Knowledge article
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeArticleResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    delete:
      operationId: delete-by-id
      summary: Delete a single article
      description: Delete an article
      tags:
      - knowledge > articles
      parameters:
      - name: id
        in: path
        description: The id of the article to delete
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Articles successfully deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/knowledge_articles_deleteById_Response_204'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /v2/knowledge/bulk/articles/:
    post:
      operationId: bulk-upsert
      summary: Upsert multiple articles
      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 50,000 by default. Higher limits are available for eligible plans — contact your Ada team.


        **Behavior at the article limit:**

        Requests that only update existing articles (every `id` in the request already exists) continue to succeed even when your knowledge base is at its article limit. A request that introduces any new article `id` while at the limit is rejected as a whole with a `400` response. The error message is `Maximum article limit of {N} exceeded`, where `{N}` is your article limit, and the error details include a `code` of `knowledge.articles.total_exceeded`, the list of `new_article_ids` that triggered the rejection (capped at the first 100), and the total `new_article_count`. Use these fields to separate new articles from update-only batches, which can still be submitted.'
      tags:
      - knowledge > articles
      parameters:
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Articles upserted
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KnowledgeArticleUpsertResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/KnowledgeArticleUpsertRequest'
components:
  schemas:
    AvailabilityRuleConditionGroupMatch:
      type: string
      enum:
      - all
      - any
      description: Whether all conditions must pass (`all`) or any one condition must pass (`any`).
      title: AvailabilityRuleConditionGroupMatch
    ArticleLanguage:
      type: string
      enum:
      - ar
      - zh
      - zh-tw
      - da
      - nl
      - en
      - fi
      - fr
      - de
      - he
      - hi
      - id
      - in
      - it
      - ja
      - ko
      - ms
      - 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`
      title: ArticleLanguage
    KnowledgeArticleUpsertRequestMetadata:
      type: object
      properties: {}
      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.
      title: KnowledgeArticleUpsertRequestMetadata
    knowledge_articles_delete_Response_204:
      type: object
      properties: {}
      description: Empty response body
      title: knowledge_articles_delete_Response_204
    KnowledgeArticleUpsertRequest:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier for the article
        name:
          type: string
          description: The name or title of the article
        content:
          type: string
          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
          items:
            type: string
          description: A list of ids for the tags associated with the article
        language:
          type: string
          description: The IETF BCP 47 language code for 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:
          oneOf:
          - $ref: '#/components/schemas/KnowledgeArticleUpsertRequestMetadata'
          - type: '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.
        availability_rules:
          oneOf:
          - $ref: '#/components/schemas/AvailabilityRule'
          - type: 'null'
          description: Availability rule controlling which articles the AI Agent can access during a conversation. Send a rule object to attach or replace a rule, `null` to detach an existing rule, or omit the field to leave any existing rule unchanged. A rule may contain at most 1000 conditions in total. See [Availability rules](/reference/introduction/availability-rules) for the full schema and examples.
      required:
      - id
      - name
      - content
      - knowledge_source_id
      title: KnowledgeArticleUpsertRequest
    PaginationMetadata:
      type: object
      properties:
        next_page_url:
          type:
          - string
          - 'null'
          description: The URL to the next page of results
      title: PaginationMetadata
    knowledge_articles_list_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/KnowledgeArticleResponse'
        meta:
          $ref: '#/components/schemas/PaginationMetadata'
      title: knowledge_articles_list_Response_200
    KnowledgeArticleResponseMetadata:
      type: object
      properties: {}
      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.
      title: KnowledgeArticleResponseMetadata
    AvailabilityRuleConditionVariable:
      type: object
      properties:
        id:
          type: string
          description: The id of the variable.
      required:
      - id
      description: The variable to test, referenced by `id`. Look up the ids for your Agent through the variables endpoint. Not every variable can be used in a rule; referencing one that can't returns a `400`.
      title: AvailabilityRuleConditionVariable
    AvailabilityRuleConditionsItems:
      oneOf:
      - $ref: '#/components/schemas/AvailabilityRuleCondition'
      - $ref: '#/components/schemas/AvailabilityRuleConditionGroup'
      title: AvailabilityRuleConditionsItems
    AvailabilityRule:
      type: object
      properties:
        match:
          $ref: '#/components/schemas/AvailabilityRuleMatch'
          description: Whether all conditions must pass (`all`) or any one condition must pass (`any`).
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/AvailabilityRuleConditionsItems'
          description: List of conditions or condition groups. Must contain at least one entry. Each entry is either a `Condition` object (with `variable`, `operator`, and optional `value`) or a `ConditionGroup` object (with its own `match` and nested `conditions` list).
      required:
      - match
      - conditions
      description: A two-level tree of conditions that determines availability based on variable values during a conversation. The root group has a `match` combinator and a list of conditions or condition groups. A rule may contain at most 1000 conditions in total, counting every condition across the root and all nested condition groups.
      title: AvailabilityRule
    AvailabilityRuleConditionGroup:
      type: object
      properties:
        match:
          $ref: '#/components/schemas/AvailabilityRuleConditionGroupMatch'
          description: Whether all conditions must pass (`all`) or any one condition must pass (`any`).
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/AvailabilityRuleCondition'
          description: List of conditions inside this condition group. Must contain at least one entry.
      required:
      - match
      - conditions
      description: A nested group of conditions inside a rule's top-level `conditions` list. Condition groups may contain only `Condition` objects — further nesting is not supported.
      title: AvailabilityRuleConditionGroup
    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorsErrorsItems'
          description: A list of errors
      required:
      - errors
      title: Errors
    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
          description: A unique identifier for the article
      required:
      - id
      title: KnowledgeArticleUpsertResponse
    knowledge_articles_deleteById_Response_204:
      type: object
      properties: {}
      description: Empty response body
      title: knowledge_articles_deleteById_Response_204
    AvailabilityRuleCondition:
      type: object
      properties:
        variable:
          $ref: '#/components/schemas/AvailabilityRuleConditionVariable'
          description: The variable to test, referenced by `id`. Look up the ids for your Agent through the variables endpoint. Not every variable can be used in a rule; referencing one that can't returns a `400`.
        operator:
          $ref: '#/components/schemas/AvailabilityRuleConditionOperator'
          description: The comparison operator. Unary operators (`is_set`, `is_not_set`) must not include a `value` field.
        value:
          $ref: '#/components/schemas/AvailabilityRuleConditionValue'
          description: The value to compare against. Omit for unary operators (`is_set`, `is_not_set`).
        case_sensitive:
          type: boolean
          description: Whether the comparison is case-sensitive. Defaults to `false`. Only meaningful for the equality (`equals`, `does_not_equal`) and string (`starts_with`, `ends_with`, `contains`, `does_not_contain`) operators. Omitted from responses when `false`.
      required:
      - variable
      - operator
      description: A single condition comparing a variable to a value.
      title: AvailabilityRuleCondition
    ErrorsErrorsItems:
      type: object
      properties:
        type:
          type: string
          description: The error type
        message:
          type: string
          description: The error message
        details:
          type:
          - string
          - 'null'
          description: Extra information about the error
      required:
      - type
      - message
      title: ErrorsErrorsItems
    KnowledgeArticleResponse:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier for the article
        name:
          type: string
          description: The name or title of the article
        content:
          type: string
          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
        language:
          $ref: '#/components/schemas/ArticleLanguage'
        tag_ids:
          type: array
          items:
            type: string
          description: A list of ids for the tags associated with the article
        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:
          oneOf:
          - $ref: '#/components/schemas/KnowledgeArticleResponseMetadata'
          - type: '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.
        availability_rules:
          oneOf:
          - $ref: '#/components/schemas/AvailabilityRule'
          - type: 'null'
          description: Availability rule controlling which articles the AI Agent can access during a conversation. `null` when no rule is set.
      required:
      - id
      - name
      - content
      title: KnowledgeArticleResponse
    AvailabilityRuleConditionValue:
      oneOf:
      - type: string
      - type: number
        format: double
      - type: boolean
      description: The value to compare against. Omit for unary operators (`is_set`, `is_not_set`).
      title: AvailabilityRuleConditionValue
    AvailabilityRuleConditionOperator:
      type: string
      enum:
      - equals
      - does_not_equal
      - greater_than
      - less_than
      - starts_with
      - ends_with
      - contains
      - does_not_contain
      - is_set
      - is_not_set
      description: The comparison operator. Unary operators (`is_set`, `is_not_set`) must not include a `value` field.
      title: AvailabilityRuleConditionOperator
    AvailabilityRuleMatch:
      type: string
      enum:
      - all
      - any
      description: Whether all conditions must pass (`all`) or any one condition must pass (`any`).
      title: AvailabilityRuleMatch
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer