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 description: 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: 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 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 knowledge_articles_deleteById_Response_204: type: object properties: {} description: Empty response body title: knowledge_articles_deleteById_Response_204 AvailabilityRuleConditionsItems: oneOf: - $ref: '#/components/schemas/AvailabilityRuleCondition' - $ref: '#/components/schemas/AvailabilityRuleConditionGroup' title: AvailabilityRuleConditionsItems 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 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 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 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 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 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 knowledge_articles_delete_Response_204: type: object properties: {} description: Empty response body title: knowledge_articles_delete_Response_204 AvailabilityRuleMatch: type: string enum: - all - any description: Whether all conditions must pass (`all`) or any one condition must pass (`any`). title: AvailabilityRuleMatch 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 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 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 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 AvailabilityRuleConditionGroupMatch: type: string enum: - all - any description: Whether all conditions must pass (`all`) or any one condition must pass (`any`). title: AvailabilityRuleConditionGroupMatch 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 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 Errors: type: object properties: errors: type: array items: $ref: '#/components/schemas/ErrorsErrorsItems' description: A list of errors required: - errors title: Errors securitySchemes: BearerAuth: type: http scheme: bearer