Ada Knowledge API
Import and sync knowledge articles into Ada so the AI agent can generate accurate responses from your existing content.
OpenAPI Specification
openapi: 3.1.0
info:
title: Knowledge
version: 1.0.0
paths:
/v2/knowledge/sources/:
get:
operationId: list
summary: Get knowledge sources
description: Get knowledge sources
tags:
- subpackage_knowledge.subpackage_knowledge/sources
parameters:
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Knowledge sources
content:
application/json:
schema:
$ref: '#/components/schemas/knowledge_sources_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'
'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'
post:
operationId: create
summary: Create a knowledge source
description: Create a knowledge source
tags:
- subpackage_knowledge.subpackage_knowledge/sources
parameters:
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Knowledge source created
content:
application/json:
schema:
$ref: '#/components/schemas/KnowledgeSourceResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'409':
description: Duplicate Resource
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:
$ref: '#/components/schemas/KnowledgeSourceCreateRequest'
/v2/knowledge/sources/{id}:
delete:
operationId: delete
summary: Delete a knowledge source
description: Delete a knowledge source, and its related articles
tags:
- subpackage_knowledge.subpackage_knowledge/sources
parameters:
- name: id
in: path
description: id of the knowledge source to delete
required: true
schema:
type: string
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'204':
description: Knowledge source deleted
content:
application/json:
schema:
$ref: '#/components/schemas/knowledge_sources_delete_Response_204'
'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'
patch:
operationId: update
summary: Update a knowledge source
description: Update a knowledge source
tags:
- subpackage_knowledge.subpackage_knowledge/sources
parameters:
- name: id
in: path
description: id of the knowledge source to update
required: true
schema:
type: string
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Knowledge source updated
content:
application/json:
schema:
$ref: '#/components/schemas/KnowledgeSourceResponse'
'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'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/KnowledgeSourceUpdateRequest'
/v2/knowledge/articles/:
get:
operationId: list
summary: Get knowledge articles
description: Get knowledge articles
tags:
- subpackage_knowledge.subpackage_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
tags:
- subpackage_knowledge.subpackage_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: Articles successfully deleted
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:
- subpackage_knowledge.subpackage_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:
- subpackage_knowledge.subpackage_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
tags:
- subpackage_knowledge.subpackage_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'
/v2/knowledge/tags/:
get:
operationId: list
summary: Get article tags
description: Get article tags
tags:
- subpackage_knowledge.subpackage_knowledge/tags
parameters:
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Article tags
content:
application/json:
schema:
$ref: '#/components/schemas/knowledge_tags_list_Response_200'
'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/tags/{id}:
delete:
operationId: delete
summary: Delete a single article tag
description: Delete an article tag
tags:
- subpackage_knowledge.subpackage_knowledge/tags
parameters:
- name: id
in: path
description: The id of the article tag to delete
required: true
schema:
type: string
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'204':
description: Article tag deleted
content:
application/json:
schema:
$ref: '#/components/schemas/knowledge_tags_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/bulk/tags/:
post:
operationId: upsert-multiple
summary: Upsert multiple tags
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.
tags:
- subpackage_knowledge.subpackage_knowledge/tags
parameters:
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Tags upserted
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ArticleTagUpsertResponse'
'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/ArticleTag'
/v2/end-users/{end_user_id}:
get:
operationId: get-end-user-by-id
summary: Get an end user
description: Get a specific end user by id
tags:
- subpackage_endUsers
parameters:
- name: end_user_id
in: path
description: The Ada end_user_id
required: true
schema:
type: string
format: id
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EndUser'
'400':
description: Invalid 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'
patch:
operationId: patch-end-user-by-id
summary: Update an end user
description: Update a specific end user by id
tags:
- subpackage_endUsers
parameters:
- name: end_user_id
in: path
description: The Ada end_user_id
required: true
schema:
type: string
format: id
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EndUser'
'400':
description: Invalid 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'
'409':
description: Conflict — the requested external_id is already assigned to a different end user on this AI Agent.
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:
$ref: '#/components/schemas/EndUserRequest'
/v2/end-users/:
get:
operationId: get-end-users
summary: Get multiple end users
description: >-
Get multiple end users. You can specify how many users appear per page, and which user id to start from.
Alternatively, supply an `external_id` query parameter to look up a single end user by their caller-supplied
identifier. When `external_id` is supplied, the 200 response is a single end user object (same shape as `GET
/v2/end-users/{end_user_id}`) and is mutually exclusive with cursor/limit pagination. The `external_id` query
parameter is available for custom channel integrations only (V1).
tags:
- subpackage_endUsers
parameters:
- name: external_id
in: query
description: >-
Look up a single end user by the external identifier set at creation or via PATCH. Returns the matching end
user with the same shape as GET /v2/end-users/{end_user_id}, or 404 if no mapping exists. Mutually exclusive
with cursor/limit pagination. Available for custom channel integrations only (V1).
required: false
schema:
type: string
- name: cursor
in: query
description: The ID that marks the start or beginning of the returned records
required: false
schema:
type: string
format: id
- name: limit
in: query
description: The number of records to return
required: false
schema:
type: integer
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: >-
OK. When `external_id` is supplied, returns a single end user object. Otherwise returns a paginated list of
end users.
content:
application/json:
schema:
$ref: '#/components/schemas/End Users_getEndUsers_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 — no end user is mapped to the requested external_id
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'
post:
operationId: create-end-user
summary: Create an end user
description: >-
Create a new end user with optional profile data and sensitive metadata. Use this endpoint to establish an end
user with context (language, metadata, sensitive metadata) before starting a conversation via POST
/v2/conversations/. This ensures the AI Agent has full user context from the first turn. Available for custom
channel (Conversations API) integrations. End users created through this endpoint that are not associated with a
conversation within 24 hours of creation are automatically deleted.
tags:
- subpackage_endUsers
parameters:
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: >-
Existing end user returned. Issued when the request includes an external_id that is already mapped to an end
user on the same AI Agent (idempotent upsert).
content:
application/json:
schema:
$ref: '#/components/schemas/EndUser'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'413':
description: Content Too Large
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:
$ref: '#/components/schemas/CreateEndUserRequest'
/v2/platform-integrations/:
get:
operationId: get-platform-integrations
summary: List integrations
description: Get a list of platform integrations owned by your account (e.g. a developer sandbox)
tags:
- subpackage_platformIntegrations
parameters:
- name: cursor
in: query
description: The ID that marks the start or beginning of the returned records
required: false
schema:
type: string
format: id
- name: limit
in: query
description: The number of records to return
required: false
schema:
type: integer
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Platform integrations
content:
application/json:
schema:
$ref: '#/components/schemas/Platform Integrations_getPlatformIntegrations_Response_200'
'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'
post:
operationId: create-platform-integration
summary: Create
# --- truncated at 32 KB (151 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ada/refs/heads/main/openapi/ada-knowledge-openapi.yml