> ## Documentation Index
> Fetch the complete documentation index at: https://developer.secfix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Working with inventory

> List, filter, read, and govern assets across every category.

The inventory endpoints expose your assets across every category — cloud resources, computers,
custom assets, information assets, and employees. You can read them, filter them, and update their
**governance metadata**. The API never creates or deletes assets.

Reads require **Read** access (`all:read`); writes require **Write** access (`all:write`). See
[Scopes](/scopes).

## Categories

Every asset has a `categoryKey`:

| `categoryKey` | What it is                                            |
| ------------- | ----------------------------------------------------- |
| `CLOUD`       | Cloud resources (adds `accountId`, `region`).         |
| `COMPUTER`    | Managed computers (adds `serialNumber`, `osVersion`). |
| `CUSTOM`      | Custom assets you defined.                            |
| `INFORMATION` | Information assets.                                   |
| `EMPLOYEE`    | Employee records (adds `email`; **read-only**).       |

List the categories with `GET /v1/inventory/categories`.

## List and filter assets

`GET /v1/inventory/assets` returns a [cursor-paginated](/pagination) list. Narrow it with query
parameters:

| Parameter        | Filters by                                       |
| ---------------- | ------------------------------------------------ |
| `categoryKey`    | Asset category (e.g. `CLOUD`).                   |
| `subKey`         | Category sub-type.                               |
| `hasOwner`       | Whether an owner is assigned (`true` / `false`). |
| `hasDescription` | Whether a description is set.                    |
| `classification` | `CONFIDENTIAL`, `INTERNAL`, `PUBLIC`, `UNKNOWN`. |
| `completeStatus` | `COMPLETE` / `INCOMPLETE` (read-only, derived).  |

```bash theme={null}
curl "https://api.secfix.com/v1/inventory/assets?categoryKey=CLOUD&hasOwner=false&pageSize=50" \
  -H "Authorization: Bearer $TOKEN"
```

Read a single asset by its opaque id with `GET /v1/inventory/assets/{id}`.

## Update governance metadata

`PATCH /v1/inventory/assets/{id}` updates governance metadata on one asset — `ownerId`,
`description`, `classification`, and `tags`. Device facts, names, and status are never writable.

```bash theme={null}
curl -X PATCH "https://api.secfix.com/v1/inventory/assets/$ASSET_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Primary production database",
    "classification": "CONFIDENTIAL",
    "ownerId": "b2c3d4e5-...",
    "tags": [{ "key": "environment", "value": "production" }]
  }'
```

* `description` is capped at 500 characters.
* `tags` accepts up to 20 entries and only **existing** tag keys — an unknown key returns
  `400 validation_failed`. Tag values are read-only in v1.
* `ownerId` is an employee's opaque id.

## Bulk updates

`PATCH /v1/inventory/assets` updates governance metadata on many assets at once (1–100 ids):

```bash theme={null}
curl -X PATCH "https://api.secfix.com/v1/inventory/assets" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["3f1c9a2e-...", "7a2b4c6d-..."],
    "patch": { "classification": "INTERNAL" }
  }'
```

```json Response theme={null}
{ "successfulUpdates": 2, "failedUpdates": 0 }
```

<Note>
  Bulk updates **do not support `tags`** — set tags with the single-asset `PATCH`. Employee-category
  ids in a bulk request are rejected with `403 resource_not_writable`.
</Note>