# /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=online&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=online&version=nsec:8.0&version=ns8:1.2.3&organization_id=org_abc123xyz
```

This retrieves systems that are:
- Type: nsec OR ns8
- Status: online
- 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 (port 8080): https://api.your-domain.com/api (Backend API server (port 8080))
- Collect API server (port 8081): https://collect.your-domain.com/api (Collect API server (port 8081))


## Authentication methods
- Bearer auth


## Parameters


### Query parameters
- **page** (integer)
  Page number
- **page_size** (integer)
  Items per page
- **search** (string)
  Search term
- **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** (string)
  Filter systems by system key (exact match). Useful for exporting a single system.
- **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.
- **status** (array[string])
  Filter systems by status (exact match). Supports multiple values for checkbox filtering.

  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.


## 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)