Upsert multiple articles

import requests
url = "https://example.ada.support/api/v2/knowledge/bulk/articles/"
payload = [
    {
        "id": "5df263b7db5a7e6ea03fae9b",
        "name": "How to reset your password",
        "content": "# How to reset your password\n\n1. Go to the login page\n2. Click on the \"Forgot password\" link\n3. Follow the instructions",
        "knowledge_source_id": "5df263b7db5a7e6ea03fae9b",
        "availability_rules": {
            "match": "all",
            "conditions": [
                {
                    "variable": { "id": "5df263b7db5a7e6ea03fae9b" },
                    "operator": "equals",
                    "value": "en"
                }
            ]
        }
    }
]
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

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.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects a list of objects.

idstringRequired1-160 characters

A unique identifier for the article

namestringRequired1-255 characters

The name or title of the article

contentstringRequired>=1 character

The content of the article in markdown format

knowledge_source_idstringRequired

The id of the knowledge_source the article belongs to

urlstring or nullOptionalformat: "url"

The url of the article

tag_idslist of stringsOptional

A list of ids for the tags associated with the article

languagestringOptional

The IETF BCP 47 language code for the article, defaults to en

external_createdstring or nullOptionalformat: "date-time"

The date the article was created in the source system

external_updatedstring or nullOptionalformat: "date-time"

The date the article was last updated in the source system

enabledbooleanOptional

Whether the article should be referenced during response generation, defaults to true

metadataobject or nullOptional

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_rulesobject or nullOptional

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 for the full schema and examples.

Response

Articles upserted

idstring1-160 characters

A unique identifier for the article

successbooleanOptional

Whether the article was successfully created/updated

createdbooleanOptional

True if a new article was created, false if an existing article was updated

Errors

400

Bad Request Error

401

Unauthorized Error

429

Too Many Requests Error

500

Internal Server Error