servers: - url: https://{handle}.ada.support/api/ variables: handle: default: example description: The subdomain of the client tags: - name: Sources description: 'Knowledge sources represent the different sources of your knowledge content. For Example: knowledgebase, marketing website, product manuals, etc.' - name: Articles description: Articles represent the individual pieces of knowledge content used by your bot paths: /knowledge/v1/sources: get: description: Get knowledge sources 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 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 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 it's related articles 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 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 ' 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 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 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 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 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. ' 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 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: {} info: title: Knowledge API version: 1.0.0 openapi: 3.1.0 components: schemas: KnowledgeSourceResponse: type: object properties: name: type: string minLength: 1 description: The name of 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: name: type: string minLength: 1 description: The name of the knowledge source required: - name KnowledgeSourceUpdateRequest: type: object properties: name: type: string minLength: 1 description: The name of 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 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` 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, and the value is dictionary where the keys specify the field name causing the error, and 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