> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ada.cx/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server. # Availability rules An availability rule controls which content the AI Agent can access during a conversation, based on the values of variables. A rule is set through the `availability_rules` field on a supported resource, such as a [knowledge article](/reference/knowledge/articles). When a rule is set, the AI Agent can only use the resource on conversations where the variables' values match the rule. ## Rule schema A rule is a two-level tree of conditions (a root group plus one level of nested groups): ```json { "match": "all" | "any", "conditions": [ | , ... ] } ``` > **Info** > > `conditions` must contain at least one entry. A rule may contain at most 1000 conditions in total, counting every condition across the root and all nested condition groups. > > See [Performance recommendations](/reference/knowledge/articles#performance-recommendations) when setting rules on articles in bulk. ### Condition ```json { "variable": { "id": "" }, "operator": "", "value": "", "case_sensitive": false } ``` * `variable` — required. An object `{ "id": "" }` identifying the variable to test. See [Variable references](#variable-references). * `operator` — required. The comparison to apply (see [Operators](#operators) below). * `value` — required for non-unary operators; omit for unary operators (`is_set`, `is_not_set`). * `case_sensitive` — optional, 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`. ### ConditionGroup A condition group applies a nested combinator to a list of conditions. Condition groups may contain only `Condition` objects — further nesting is not supported. ```json { "match": "all" | "any", "conditions": [ , ... ] } ``` --- ## Variable references A condition references a variable by its `id`: ```json { "id": "5df263b7db5a7e6ea03fae9b" } ``` The `id` is the stable identifier for a variable configured on your Agent. Look up the ids for your Agent through the [Variables API](/reference/variables/overview). Not every variable can be used in an availability rule. Variables whose value is set dynamically during a conversation aren't available when a rule is evaluated, so referencing one returns a `400` with the `Variable not usable in a rule` error. --- ## Operators | Operator | Unary | Applies to | Description | | ------------------ | ----- | ----------------------- | ------------------------------------------------------ | | `equals` | No | string, number, boolean | Variable value equals `value`. | | `does_not_equal` | No | string, number, boolean | Variable value does not equal `value`. | | `greater_than` | No | number | Variable value is greater than `value`. | | `less_than` | No | number | Variable value is less than `value`. | | `starts_with` | No | string | Variable value starts with `value`. | | `ends_with` | No | string | Variable value ends with `value`. | | `contains` | No | string | Variable value contains the substring `value`. | | `does_not_contain` | No | string | Variable value does not contain the substring `value`. | | `is_set` | Yes | any | Variable has a non-null, non-empty value. | | `is_not_set` | Yes | any | Variable has no value or is empty. | Unary operators (`is_set`, `is_not_set`) must not include a `value` field. Sending `value` with a unary operator returns a `400` error. --- ## Validation errors The API returns `400` for the following rule errors: | Error | Cause | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | Unknown variable | A variable `id` in the rule does not match a variable on your Agent. | | Variable not usable in a rule | The variable can't be used in an availability rule. | | Unknown operator | The `operator` string is not one of the supported values listed above. | | Operator and variable type mismatch | `Operator '' cannot be used with a variable of type ''` — for example, `starts_with` on a numeric variable. | | Empty `conditions` | A `conditions` array contains zero entries. | | Too many conditions | A rule contains more than 1000 conditions in total, counting every condition across the root and all nested groups. | | Value on unary operator | `value` was provided for `is_set` or `is_not_set`. | | Missing required field | `variable` (with its `id`), `operator`, or `match` is absent from a condition or group. | A validation failure returns a `400` with the error in the standard envelope: ```json { "errors": [ { "type": "bad_request", "message": "Invalid request", "details": "{'availability_rules': {'conditions': {0: {'variable': {'id': ['Unknown variable.']}}}}}" } ] } ``` --- ## Examples Each example references variables by `id`. The ids below are illustrative — use the ids of the variables configured on your own Agent. ### Language targeting Match only when the conversation language (variable `5df263b7db5a7e6ea03fae9b`) is English: ```json { "match": "all", "conditions": [ { "variable": { "id": "5df263b7db5a7e6ea03fae9b" }, "operator": "equals", "value": "en" } ] } ``` ### Presence targeting Match only when a variable has a value. Here `664c0a1e9f3b2d4a8e7c1a02` is the `loyalty_id` variable, and the unary `is_set` operator takes no `value`: ```json { "match": "all", "conditions": [ { "variable": { "id": "664c0a1e9f3b2d4a8e7c1a02" }, "operator": "is_set" } ] } ``` ### Numeric comparison Match only when a numeric variable exceeds a threshold. Here `664c0a1e9f3b2d4a8e7c1a07` is the `loyalty_points` variable: ```json { "match": "all", "conditions": [ { "variable": { "id": "664c0a1e9f3b2d4a8e7c1a07" }, "operator": "greater_than", "value": 1000 } ] } ``` ### Compound rule — any of several markets Match on conversations from either Canada or the United States, where `664c0a1e9f3b2d4a8e7c1a04` is the `region` variable: ```json { "match": "any", "conditions": [ { "variable": { "id": "664c0a1e9f3b2d4a8e7c1a04" }, "operator": "equals", "value": "CA" }, { "variable": { "id": "664c0a1e9f3b2d4a8e7c1a04" }, "operator": "equals", "value": "US" } ] } ``` ### Compound rule — subscription plan with a nested group Match paying users who are also on a higher loyalty tier, using a nested condition group. Here `664c0a1e9f3b2d4a8e7c1a05` is the `subscription_plan` variable and `664c0a1e9f3b2d4a8e7c1a06` is the `loyalty_tier` variable: ```json { "match": "all", "conditions": [ { "variable": { "id": "664c0a1e9f3b2d4a8e7c1a05" }, "operator": "does_not_equal", "value": "free" }, { "match": "any", "conditions": [ { "variable": { "id": "664c0a1e9f3b2d4a8e7c1a06" }, "operator": "equals", "value": "gold" }, { "variable": { "id": "664c0a1e9f3b2d4a8e7c1a06" }, "operator": "equals", "value": "platinum" } ] } ] } ```