Skip to content

Query Support Matrix

This matrix documents the shared DB-backed query interface used by Hubuum list endpoints.

Notes:

  • limit, sort, and cursor apply to every endpoint listed here.
  • response bodies remain JSON arrays; the next page cursor is returned in X-Next-Cursor
  • contextual endpoints may inject exact filters from path parameters
  • some endpoints also apply permission scoping before query filters are evaluated
  • every authoritative resource row and temporal-history row additionally supports revision filtering and sorting, unless the endpoint is explicitly described as an aggregate or non-paginated representation

POST /api/v1/search accepts a versioned JSON DSL with nested and, or, and not. The field matrix is target-specific; an object target may also contain bounded existential related expressions. See search_api.md for the complete grammar, operator matrix, examples, limits, response union, and authorization behavior.

Target Filter fields Sort fields Default sort
collection id, name, description, created_at, updated_at, revision Same as filters id.asc
class id, name, description, collection_id, created_at, updated_at, revision, validate_schema, json_schema All except validate_schema and json_schema id.asc
object id, name, description, collection_id, created_at, updated_at, revision, json_data; related predicates accept the same fields All direct fields except json_data id.asc
audit_event id, occurred_at, entity_type, entity_id, entity_name, collection_id, action, actor_kind, actor_user_id, initiator_user_id, summary, metadata id, occurred_at occurred_at.desc, id.desc
user id, name, identity_scope, proper_name, email, created_at, updated_at, revision Same as filters id.asc
group id, name, description, identity_scope, managed_by, external_key, last_sync_attempted_at, last_sync_success_at, created_at, updated_at, revision id, name, description, created_at, updated_at, revision id.asc
service_account id, name, description, identity_scope, owner_group_id, created_by, disabled_at, created_at, updated_at, revision id, name, identity_scope, created_at, updated_at, revision id.asc

IAM

Endpoints Filter fields Sort fields Default sort Notes
/api/v1/iam/users id, name, username, proper_name, email, created_at, updated_at id, name, username, proper_name, email, created_at, updated_at id.asc name and username sort/filter the same underlying field; proper_name targets the users table display-name column
/api/v1/iam/groups id, name, groupname, description, created_at, updated_at id, name, groupname, description, created_at, updated_at id.asc name and groupname sort/filter the same underlying field
/api/v1/iam/principals/{principal_id}/groups id, name, groupname, description, created_at, updated_at id, name, groupname, description, created_at, updated_at id.asc path constrains the result to one principal's memberships (human or service account)
/api/v1/iam/groups/{group_id}/members id, name, created_at, updated_at id, name, created_at, updated_at id.asc members are principals; each row carries principal_id, kind (human/service_account), and name (username is accepted as an alias for name)
/api/v1/iam/principals/{principal_id}/tokens id, name, issued_at, expires_at, last_used_at id, name, issued_at, expires_at, last_used_at issued_at.desc, id.asc name is the token's label, never the secret; id is the stable tie-breaker

Collections and permissions

Endpoints Filter fields Sort fields Default sort Notes
/api/v1/collections id, name, description, created_at, updated_at, permissions id, name, description, created_at, updated_at id.asc permissions narrows the collections to those where the caller has the named effective permission
/api/v1/collections/{collection_id}/children, /api/v1/collections/{collection_id}/ancestors n/a n/a n/a hierarchy helpers; results are not query-parameter paginated
/api/v1/collections/{collection_id}/permissions n/a n/a n/a revisioned point representation of the complete SQL-owned permission set; not query-parameter paginated
/api/v1/collections/{collection_id}/permissions/principal/{principal_id} id, name, groupname, created_at, updated_at, permissions id, name, groupname, created_at, updated_at id.asc direct rows constrained to one collection and one principal's memberships (human or service account)
/api/v1/collections/{collection_id}/permissions/effective/group/{group_id}, /api/v1/collections/{collection_id}/permissions/effective/principal/{principal_id} n/a n/a n/a returns direct and inherited rows with source collection and depth; results are not query-parameter paginated
/api/v1/collections/{collection_id}/has_permissions/{permission} id, name, groupname, description, created_at, updated_at id, name, groupname, description, created_at, updated_at id.asc path permission already narrows the result set
/api/v1/remote-targets id, name, description, collection_id, collections, kind, created_at, updated_at id, name, description, collection_id, created_at, updated_at id.asc kind filters the target HTTP method; results are scoped to collections where the caller has ReadRemoteTarget

Classes and objects

Endpoints Filter fields Sort fields Default sort Notes
/api/v1/classes id, collections, name, description, validate_schema, json_schema, created_at, updated_at, permissions id, name, description, collections, collection_id, created_at, updated_at id.asc json_schema is only filterable, not sortable
/api/v1/classes/{class_id}/, /api/v1/classes/by-name/{class_name}/objects id, name, description, collections, collection_id, classes, class_id, json_data, created_at, updated_at, permissions, computed.shared.<key>, computed.personal.<key>, named related.<alias> groups id, name, description, collections, collection_id, classes, class_id, created_at, updated_at, computed.shared.<key>, computed.personal.<key> id.asc path constrains the result to a single class; related groups require one target class, support target object fields and a bounded bidirectional depth, and are combined with AND; computed.public.<key> and computed.private.<key> are aliases
/api/v1/classes/{class_id}/object-aggregates, /api/v1/classes/by-name/{class_name}/object-aggregates id, name, description, collections, collection_id, classes, class_id, json_data, created_at, updated_at, permissions, computed.shared.<key>, computed.personal.<key> dimensions, object_count dimensions.asc requires at least one group_by dimension or numeric aggregate measure; supports up to three scalar, nested JSON, shared computed, or owned personal computed dimensions and up to four sum, average, min, or max JSON/computed measures; computed.public.<key> and computed.private.<key> are filter aliases; X-Total-Count reports aggregate cardinality
/api/v1/classes/{class_id}/permissions id, name, groupname, created_at, updated_at, permissions id, name, groupname, created_at, updated_at id.asc collection permission rows for the class's collection

Relations

Endpoints Filter fields Sort fields Default sort Notes
/api/v1/relations/classes id, from_classes, to_classes, from_class_name, to_class_name, created_at, updated_at, permissions id, from_classes, to_classes, created_at, updated_at id.asc from_class_name and to_class_name are filter-only helpers
/api/v1/relations/objects id, class_relation, from_objects, to_objects, created_at, updated_at, permissions id, class_relation, from_objects, to_objects, created_at, updated_at id.asc permission filters narrow the collections used to scope object relations
Endpoints Filter fields Sort fields Default sort Notes
/api/v1/classes/{class_id}/related/classes id, name, description, collection_id, collections, class_id, classes, created_at, updated_at, from_classes, to_classes, from_collections, to_collections, from_name, to_name, from_description, to_description, from_created_at, to_created_at, from_updated_at, to_updated_at, depth, path id, name, description, collection_id, collections, class_id, classes, created_at, updated_at, from_classes, to_classes, from_collections, to_collections, from_name, to_name, from_description, to_description, from_created_at, to_created_at, from_updated_at, to_updated_at, depth, path path.asc, class_id.asc returns connected classes with a path; sorting and cursor pagination are done against class-closure columns in SQL
/api/v1/classes/{class_id}/related/relations id, from_classes, to_classes, created_at, updated_at id, from_classes, to_classes, created_at, updated_at id.asc path constrains the result to direct relations touching the class in the URL
/api/v1/classes/{class_id}/objects/{object_id}/related/objects id, name, description, collection_id, collections, class_id, classes, created_at, updated_at, from_objects, to_objects, from_classes, to_classes, from_collections, to_collections, from_name, to_name, from_description, to_description, from_created_at, to_created_at, from_updated_at, to_updated_at, from_json_data, to_json_data, depth, path id, name, description, collection_id, collections, class_id, classes, created_at, updated_at, from_objects, to_objects, from_classes, to_classes, from_collections, to_collections, from_name, to_name, from_description, to_description, from_created_at, to_created_at, from_updated_at, to_updated_at, depth, path path.asc, id.asc returns connected objects with a path; sorting and cursor pagination are done against closure-table/object-join columns in SQL; JSON fields are filter-only; also accepts endpoint-specific ignore_classes and ignore_self_class result filters
/api/v1/classes/{class_id}/objects/{object_id}/related/relations id, class_relation, from_objects, to_objects, created_at, updated_at, permissions id, class_relation, from_objects, to_objects, created_at, updated_at id.asc path constrains the result to direct relations touching the object in the URL

/api/v1/classes/{class_id}/related/graph and its by-name alias are not paginated list endpoints. They accept connected-class filters such as depth to define the included neighborhood and return a graph object containing classes and relations. limit is a maximum related-class safety bound rather than a page size. include_total has no effect, and graph responses never include X-Total-Count.

/api/v1/classes/{class_id}/objects/{object_id}/related/graph and its by-name alias are not paginated list endpoints. They accept connected-object filters such as depth to define the included neighborhood and return a graph object containing objects and relations. limit is a maximum related-object safety bound rather than a page size. include_total has no effect, and graph responses never include X-Total-Count.

Query aliases

Common aliases accepted by the parser:

  • order_by is an alias for sort
  • name and username both target the user name field on user endpoints
  • name and groupname both target the group name field on group endpoints
  • collections and collection_id can both be used for collection-oriented object and class ordering
  • classes and class_id can both be used for class-oriented object ordering

Source of truth

This file is the human-oriented summary. For exact route definitions and generated parameter docs, see: