{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/ada/main/json-schema/ada-knowledge-article-upsert-request-schema.json",
  "title": "KnowledgeArticleUpsertRequest",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/ada-knowledge-articles-api-openapi.yml#/components/schemas/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": "#/$defs/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": "#/$defs/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"
  ],
  "$defs": {
    "AvailabilityRule": {
      "type": "object",
      "properties": {
        "match": {
          "$ref": "#/$defs/AvailabilityRuleMatch",
          "description": "Whether all conditions must pass (`all`) or any one condition must pass (`any`)."
        },
        "conditions": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/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"
    },
    "AvailabilityRuleCondition": {
      "type": "object",
      "properties": {
        "variable": {
          "$ref": "#/$defs/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": "#/$defs/AvailabilityRuleConditionOperator",
          "description": "The comparison operator. Unary operators (`is_set`, `is_not_set`) must not include a `value` field."
        },
        "value": {
          "$ref": "#/$defs/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"
    },
    "AvailabilityRuleConditionGroup": {
      "type": "object",
      "properties": {
        "match": {
          "$ref": "#/$defs/AvailabilityRuleConditionGroupMatch",
          "description": "Whether all conditions must pass (`all`) or any one condition must pass (`any`)."
        },
        "conditions": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/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"
    },
    "AvailabilityRuleConditionGroupMatch": {
      "type": "string",
      "enum": [
        "all",
        "any"
      ],
      "description": "Whether all conditions must pass (`all`) or any one condition must pass (`any`).",
      "title": "AvailabilityRuleConditionGroupMatch"
    },
    "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"
    },
    "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"
    },
    "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": "#/$defs/AvailabilityRuleCondition"
        },
        {
          "$ref": "#/$defs/AvailabilityRuleConditionGroup"
        }
      ],
      "title": "AvailabilityRuleConditionsItems"
    },
    "AvailabilityRuleMatch": {
      "type": "string",
      "enum": [
        "all",
        "any"
      ],
      "description": "Whether all conditions must pass (`all`) or any one condition must pass (`any`).",
      "title": "AvailabilityRuleMatch"
    },
    "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"
    }
  }
}