# /systems - List systems **GET /systems** Get list of systems visible to the user based on hierarchical organization permissions. Supports filtering by name, type, creator, version, organization, and status. **Query String Examples:** 1. **Single type filter**: `?type=nsec` 2. **Multiple types filter**: `?type=nsec&type=ns8` 3. **Multiple filters combined**: `?type=nsec&status=active&status=deleted&version=8.0` 4. **With pagination and sorting**: `?page=1&page_size=50&sort_by=name&sort_direction=asc&type=nsec` 5. **Search with filters**: `?search=backup&type=ns8&organization_id=org_abc123xyz` 6. **Creator filter (by user)**: `?created_by=53h5zxpwu4vc` 7. **Creator filter (by organization)**: `?created_by=lbswt1rxdhbz` 8. **Creator filter (multiple)**: `?created_by=53h5zxpwu4vc&created_by=lbswt1rxdhbz` **Complete Example Request:** ``` GET /api/systems?page=1&page_size=20&sort_by=created_at&sort_direction=desc&type=nsec&type=ns8&status=active&version=nsec:8.0&version=ns8:1.2.3&organization_id=org_abc123xyz ``` This retrieves systems that are: - Type: nsec OR ns8 - Status: active - Version: (nsec version 8.0) OR (ns8 version 1.2.3) - Organization: org_abc123xyz - Sorted by creation date (newest first) - Page 1 with 20 items per page ## Servers - Backend API server: https://my.nethesis.it/backend/api (Backend API server) ## Authentication methods - Bearer auth ## Parameters ### Query parameters - **page** (integer) Page number - **page_size** (integer) Items per page - **search** (string) Search term. For organizations (distributors, resellers, customers), searches across name, description, and all custom_data fields (vat, address, city, contact, email, phone, language, notes, etc.). For systems, also searches across ipv4_address and ipv6_address. - **sort_by** (string) Field to sort systems by - **sort_direction** (string) Sort direction - **name** (string) Filter systems by name (case-insensitive, partial match) - **system_key** (array[string]) Filter systems by system key (exact match). Supports multiple values, so it doubles as a batch lookup: `?system_key=KEY1&system_key=KEY2` returns exactly the requested systems (within the caller's RBAC scope). - **type** (array[string]) Filter systems by type/product (exact match). Supports multiple values for checkbox filtering. - **created_by** (array[string]) Filter systems by creator user ID or creator organization ID (exact match). Each provided ID is checked against both the user_id and organization_id fields of the system creator. Supports multiple values for checkbox filtering. Examples: - `?created_by=53h5zxpwu4vc` - matches systems created by user with ID 53h5zxpwu4vc - `?created_by=lbswt1rxdhbz` - matches systems created by users in organization lbswt1rxdhbz - `?created_by=53h5zxpwu4vc&created_by=lbswt1rxdhbz` - matches systems created by the user OR by users in the organization - **version** (array[string]) Filter systems by version using prefixed format `product:version` (e.g., `nsec:8.0`, `ns8:1.2.3`). The prefix prevents ambiguity when the same version number exists for multiple products. Supports multiple values for checkbox filtering. **Example**: `?version=nsec:8.0&version=ns8:1.2.3` matches systems with (nsec version 8.0) OR (ns8 version 1.2.3) **Backward compatibility**: Non-prefixed versions (e.g., `8.0`) are still supported but may match multiple products. - **organization_id** (array[string]) Filter systems by organization ID (exact match). Supports multiple values for checkbox filtering. - **include_hierarchy** (boolean) When true (and organization_id is provided), each organization_id is expanded to the organization plus all its descendants (a distributor's resellers and their customers, a reseller's customers) before filtering - **status** (array[string]) Filter systems by status. Supports multiple values. - unknown, active, inactive, deleted: match the system status column - suspended: virtual status matching systems with suspended_at IS NOT NULL - no_inventory: virtual status matching systems that have been in contact but never delivered an inventory (last_inventory_at IS NULL AND status <> 'unknown') Special value "deleted" shows soft-deleted systems (where deleted_at IS NOT NULL). When "deleted" is combined with other statuses, both deleted and non-deleted systems matching the other statuses are returned. "no_inventory" is additive rather than exclusive: such a system is also active or inactive, so it matches both filters. Selecting it alone yields exactly the systems flagged with the missing-inventory warning in the UI. The status field of the response never carries this value. - **addon** (array[string]) Filter systems by add-on. Supports multiple values: a system matches when it holds at least one of them (OR). Only grants valid at the time of the request count — an expired or revoked add-on is not one the system has. Use GET /api/filters/systems to populate the choices with the add-ons actually present in the caller's hierarchy. - **include_addons** (boolean) Add the `addons` list to every system of the page. It costs one extra indexed query per page, so it is opt-in: ask for it where the add-ons are shown, leave it out for bulk reads. ## Responses ### 200 Systems retrieved successfully #### Body: application/json (object) - **code** (integer) - **message** (string) - **data** (object) ### 401 Unauthorized - invalid or missing token #### Body: application/json (object) - **code** (integer) - **message** (string) - **data** (object | null) ### 403 Forbidden - insufficient permissions #### Body: application/json (object) - **code** (integer) - **message** (string) - **data** (object | null) [Powered by Bump.sh](https://bump.sh)