RQL Reference

Resource Query Language (RQL) is the syntax accepted by the filter parameter on the Hubbl REST API list endpoints and the MCP list_* tools. A filter is a single expression built from nestable operator(arguments) calls.

and(eq(priority,high),eq(effort,1),in(metadataType,profiles,17),contains(wellArchitectedCategoryLevel3,security))

Syntax rules

A filter is one top-level expression. To combine conditions, wrap them in and() or or().
Arguments are separated by commas. Whitespace around arguments is ignored.
Values are written literally, without quotes. Numeric values are compared as numbers, null is the null literal, and everything else is treated as a string. Values cannot contain commas or parentheses.
Each endpoint and tool accepts a fixed set of filterable fields. The supported fields are listed in the endpoint documentation in the API Reference and in each tool description in the MCP docs. Filtering on any other field returns a validation error.
Some MCP tools substitute numeric IDs for enum-like string values to reduce token usage. Their filters accept either form (for example eq(priority,high) or eq(priority,3)); see the individual tool description.

Logical operators

Operator	Meaning	Example
`and(expr, expr, ...)`	Every expression must match	`and(eq(priority,high),eq(effort,1))`
`or(expr, expr, ...)`	At least one expression must match	`or(eq(category,security),eq(category,limits))`
`not(expr)`	The expression must not match	`not(eq(namespace,null))`

Comparison operators

Operator	Meaning	Example
`eq(field,value)`	Equals. `eq(field,null)` matches records where the field is null.	`eq(status,active)`
`ne(field,value)`	Not equal. `ne(field,null)` matches records where the field is not null.	`ne(namespace,null)`
`gt(field,value)` / `gte(field,value)`	Greater than / greater than or equal. `null` is not allowed.	`gte(percentUsed,80)`
`lt(field,value)` / `lte(field,value)`	Less than / less than or equal. `null` is not allowed.	`lt(effort,5)`
`between(field,lower,upper)`	Within an inclusive range. Bounds may be given in either order; `null` is not allowed.	`between(effort,2,4)`

Set operators

Operator	Meaning	Example
`in(field,v1,v2,...)`	The field matches any of the listed values	`in(metadataType,profiles,flows)`
`out(field,v1,v2,...)`	The field matches none of the listed values	`out(status,deleted,archived)`

Text operators

Operator	Meaning	Example
`like(field,pattern)`	Case-sensitive pattern match. Use `*` as the wildcard.	`like(apiName,Account*)`
`ilike(field,pattern)`	Case-insensitive pattern match. Use `*` as the wildcard.	`ilike(label,login)`
`contains(field,value)`	Case-insensitive substring match. Shorthand for `ilike(field,value)`.	`contains(title,password)`

Null checks

Operator	Meaning	Example
`isNull(field)`	The field is null. Equivalent to `eq(field,null)`.	`isNull(namespace)`
`isNotNull(field)`	The field is not null. Equivalent to `ne(field,null)`.	`isNotNull(lastUsedDate)`

Validation errors

An invalid filter fails the whole request with a validation error describing the problem. Common causes are unbalanced parentheses, more than one top-level expression, an unsupported operator, or a field that is not filterable on that endpoint or tool.

Sorting is not RQL

The sort parameter uses JSON:API sort syntax, not RQL: a comma-separated list of field names, each optionally prefixed with - for descending order (for example -priority,effort). Pagination uses the limit and offset parameters.