> For the complete documentation index, see [llms.txt](https://docs.cybaops.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybaops.com/settings/access-tokens/asset-and-vulnerability-api-usage.md).

# Asset and Vulnerability API Usage

The API key secret throughout this document is referred to as {APIKEY}.

The next token returned from api queries includes the filters defined by the original query.

{% hint style="info" %}

#### **Note**

Throughout this document, the API key secret is referred to as `{APIKEY}`. Valid next tokens are referred to as `{nextToken}.` All data referenced is testing data.
{% endhint %}

***

### <mark style="color:$primary;">Table of Contents</mark>

1. [Authentication & Pagination Behaviour](#id-1-authentication-and-pagination-behaviour)
2. [Enumerating Assets](#id-2-enumerating-assets)&#x20;
   1. [Initial Asset Enumeration](#id-2.1-initial-asset-enumeration)&#x20;
   2. [Asset Pagination Using Next](#id-2.2-asset-pagination-using-next)
3. [Enumerating Vulnerabilities for Assets](#id-3-enumerating-a-vulnerability-for-an-asset)&#x20;
   1. [Single Asset](#id-3.1-single-asset)
   2. [Multiple Assets](#id-3.2-multiple-assets)
   3. [Filtering by Status](#id-3.3-filtering-by-status)
4. [Vulnerability Status Reference](#id-4-vulnerability-status-reference)
5. [Retrieving Vulnerability Details](#id-5-retrieving-vulnerability-details)
   1. [Single Vulnerability](#id-5.1-single-vulnerability)&#x20;
   2. [Multiple Vulnerabilities](#id-5.2-multiple-vulnerabilities)
6. [Returning Select Fields](#id-6-returning-select-fields)
7. [Important Behavior Notes](#id-7-important-behaviour-notes)

***

### <mark style="color:$primary;">1) Authentication & Pagination Behaviour</mark>

* All requests require the `secureauth-accesskey` header.
* Some endpoints additionally require `secureauth-tenant`.
* Paginated endpoints return a **`next` token**.
* The `next` token **retains the original filters** and must be passed verbatim to continue enumeration.

***

### <mark style="color:$primary;">2) Enumerating Assets</mark>

#### <mark style="color:$primary;">2.1) Initial asset enumeration</mark>

```
curl --location 'https://cybaverse.cybaops.com/assets/api/1.0/assets' \
--header 'secureauth-accesskey: {APIKEY}' \
--header 'Content-Type: application/json'
```

Expected output:

```json
{
    "total": null,
    "documents": [
        {
            "_id": "69e7e373f0a2c6aec8b60b78",
            "created_by": "build",
            "modified_by": "6846ce1aa40692191e905fb3",
            "created_at": 1776804723.0087607,
            "modified_at": 1777296191.2933884,
            "name": "prxixt.uggdub.edu",
            "type": "domain",
            "entity": "",
            "fields_calculated": true,
            "fields_calculated_at": 0,
            "fields_version": 1,
            "fields": {
                "external": false,
                "last_seen": 1776804723
            },
            "sources": [
                {
                    "external": false,
                    "meta": {
                        "name": "dns",
                        "updated_at": 1776804723,
                        "priority": 856,
                        "source_priority_max_age": 789072
                    }
                },
                {
                    "external": true,
                    "meta": {
                        "name": "ms entra",
                        "updated_at": 1776804723,
                        "priority": 103,
                        "source_priority_max_age": 2136816
                    }
                },
                {
                    "external": false,
                    "meta": {
                        "name": "manual",
                        "updated_at": 1776804723,
                        "priority": 33,
                        "source_priority_max_age": 2146359
                    }
                }
            ]
        },
        {
            "_id": "69e7e373f0a2c6aec8b60b79",
            "created_by": "build",
            "modified_by": "6846ce1aa40692191e905fb3",
            "created_at": 1776804723.010946,
            "modified_at": 1777296191.2935567,
            "name": "server-qhjkxatf",
            "type": "server",
            "entity": "",
            "fields_calculated": true,
            "fields_calculated_at": 0,
            "fields_version": 1,
            "fields": {
                "operating_system": "ubuntu",
                "version": "2019",
                "build_number": "10.0.17763",
                "ip": "10.11.69.177",
                "last_seen": 1776804723
            },
            "sources": [
                {
                    "operating_system": "ubuntu",
                    "version": "2019",
                    "build_number": "10.0.17763",
                    "ip": "10.11.69.177",
                    "meta": {
                        "name": "manual",
                        "updated_at": 1776804723,
                        "priority": 795,
                        "source_priority_max_age": 796004
                    }
                },
                {
                    "operating_system": "ubuntu",
                    "version": "2022",
                    "build_number": "10.0.14393",
                    "ip": "172.16.70.13",
                    "meta": {
                        "name": "azure",
                        "updated_at": 1776804723,
                        "priority": 902,
                        "source_priority_max_age": 1900989
                    }
                },
                {
                    "operating_system": "centos",
                    "version": "7",
                    "build_number": "10.0.19043.5678",
                    "ip": "10.124.232.94",
                    "meta": {
                        "name": "aws",
                        "updated_at": 1776804723,
                        "priority": 817,
                        "source_priority_max_age": 572796
                    }
                }
            ]
        }
    ],
    "next": "eyJmaWx0ZXIiOiB7fSwgImFmdGVyIjogeyIkb3IiOiBbeyJfaWQiOiB7IiRndCI6ICIkb2lkLTY5ZTdlMzczZjBhMmM2YWVjOGI2MGI3OSJ9fV19LCAic29ydCI6IFtbIl9pZCIsIDFdXSwgImZpZWxkcyI6IHsibWV0YSI6IDAsICJhY2wiOiAwfSwgImxpbWl0IjogMn0="
}
```

#### <mark style="color:$primary;">2.2) Asset Pagination Using</mark> <mark style="color:$primary;"></mark><mark style="color:$primary;">`next`</mark>

The next token can be used for enumerating more assets:

```
curl --location 'https://cybaverse.cybaops.com/assets/api/1.0/assets' \
--header 'secureauth-accesskey: {APITOKEN}' \
--header 'Content-Type: application/json' \
--data '{
    "query": {
        "next": "eyJmaWx0ZXIiOiB7fSwgImFmdGVyIjogeyIkb3IiOiBbeyJfaWQiOiB7IiRndCI6ICIkb2lkLTY5ZTdlMzczZjBhMmM2YWVjOGI2MGI3OSJ9fV19LCAic29ydCI6IFtbIl9pZCIsIDFdXSwgImZpZWxkcyI6IHsibWV0YSI6IDAsICJhY2wiOiAwfSwgImxpbWl0IjogMn0="
    }
}'
```

### <mark style="color:$primary;">3) Enumerating a vulnerability for an asset</mark>

#### <mark style="color:$primary;">3.1) Single Asset</mark>

*Single Asset*

```
curl --location 'https://cybaverse.cybaops.com/vulnerabilities/api/1.0/affected/list' \
--header 'secureauth-accesskey: {APITOKEN}' \
--header 'Content-Type: application/json' \
--data '{
    "query": {
        "filter": {
            "asset": "69e7e373f0a2c6aec8b60b7b"
        }
    }
}'
```

#### <mark style="color:$primary;">3.2) Multiple Assets</mark>

Multiple Assets

```
{
    "query": {
        "filter": {
            "asset": {"$in": ["69e7e373f0a2c6aec8b60b7b","69e7e373f0a2c6aec8b60b7a"]}
        }
    }
}
```

#### <mark style="color:$primary;">3.3) Filtering by Status</mark>

Multiple Assets + filter by status

```
curl --location 'https://cybaverse.cybaops.com/vulnerabilities/api/1.0/affected/list' \
--header 'secureauth-accesskey: {APITOKEN}' \
--header 'Content-Type: application/json' \
--data '{
    "query": {
        "filter": {
            "asset": {"$in": ["69e7e373f0a2c6aec8b60b7b","69e7e373f0a2c6aec8b60b7a"]},
            "status": {"$in": [1,2]}
        }
    }
}'
```

Status of 1 means open Status of 2 means closed Status of 3 means pending (marked as closed, awaiting a scan to confirm) Status of 4 means false positive

Expected response:

```json
{
    "total": null,
    "documents": [
        {
            "_id": "69e7e37545e26f8e858ba5c2",
            "created_by": "build",
            "modified_by": "build",
            "created_at": 1776804725.5140097,
            "modified_at": 1776804725.5140097,
            "vulnerability": "637962616f70732d32370000",
            "asset": "69e7e373f0a2c6aec8b60b7b",
            "status": 3,
            "status_at": 1776804725,
            "first_affected_at": 1776804725,
            "last_affected_at": 1776804725,
            "document_type": "asset",
            "source": {
                "name": "External Audit",
                "id": "external-audit-456"
            }
        },
        {
            "_id": "69e7e37645e26f8e858ba71b",
            "created_by": "build",
            "modified_by": "build",
            "created_at": 1776804726.1839502,
            "modified_at": 1776804726.1839502,
            "vulnerability": "637962616f70732d39360000",
            "asset": "69e7e373f0a2c6aec8b60b7a",
            "status": 3,
            "status_at": 1776804726,
            "first_affected_at": 1776804726,
            "last_affected_at": 1776804726,
            "document_type": "asset",
            "source": {
                "name": "External Audit",
                "id": "external-audit-456"
            }
        },
        {
            "_id": "69e7e37745e26f8e858ba8b3",
            "created_by": "build",
            "modified_by": "build",
            "created_at": 1776804727.0415814,
            "modified_at": 1776804727.0415816,
            "vulnerability": "637962616f70732d31373300",
            "asset": "69e7e373f0a2c6aec8b60b7b",
            "status": 1,
            "status_at": 1776804727,
            "first_affected_at": 1776804727,
            "last_affected_at": 1776804727,
            "document_type": "asset",
            "source": {
                "name": "Vulnerability Scanner2",
                "id": "vulnerability-scanner-d31d2e0628"
            }
        },
        {
            "_id": "69e7e37745e26f8e858ba8d7",
            "created_by": "build",
            "modified_by": "build",
            "created_at": 1776804727.1138167,
            "modified_at": 1776804727.1138167,
            "vulnerability": "637962616f70732d31373900",
            "asset": "69e7e373f0a2c6aec8b60b7a",
            "status": 3,
            "status_at": 1776804727,
            "first_affected_at": 1776804727,
            "last_affected_at": 1776804727,
            "document_type": "asset",
            "evidence": "69e7e373f0a2c6aec8b60b7a - SQLMap found injectable parameter.",
            "source": {
                "name": "External Audit",
                "id": "external-audit-456"
            }
        },
        {
            "_id": "69e7e37745e26f8e858ba953",
            "created_by": "build",
            "modified_by": "build",
            "created_at": 1776804727.3249197,
            "modified_at": 1776804727.3249197,
            "vulnerability": "637962616f70732d31393800",
            "asset": "69e7e373f0a2c6aec8b60b7a",
            "status": 3,
            "status_at": 1776804727,
            "first_affected_at": 1776804727,
            "last_affected_at": 1776804727,
            "document_type": "asset",
            "source": {
                "name": "External Audit",
                "id": "external-audit-456"
            }
        }
    ],
    "next": "eyJmaWx0ZXIiOiB7ImFzc2V0IjogeyIkaW4iOiBbIjY5ZTdlMzczZjBhMmM2YWVjOGI2MGI3YiIsICI2OWU3ZTM3M2YwYTJjNmFlYzhiNjBiN2EiXX19LCAiYWZ0ZXIiOiB7IiRvciI6IFt7Il9pZCI6IHsiJGd0IjogIiRvaWQtNjllN2UzNzc0NWUyNmY4ZTg1OGJhOTUzIn19XX0sICJzb3J0IjogW1siX2lkIiwgMV1dLCAiZmllbGRzIjogeyJhY2wiOiAwLCAibWV0YSI6IDB9LCAibGltaXQiOiA1fQ=="
}
```

Similarly to before, the next token can be used for pagination:

```
curl --location 'https://cybaverse.cybaops.com/vulnerabilities/api/1.0/affected/list' \
--header 'secureauth-accesskey: {APITOKEN}' \
--header 'Content-Type: application/json' \
--data '{
    "query": {
        "next": "eyJmaWx0ZXIiOiB7ImFzc2V0IjogeyIkaW4iOiBbIjY5ZTdlMzczZjBhMmM2YWVjOGI2MGI3YiIsICI2OWU3ZTM3M2YwYTJjNmFlYzhiNjBiN2EiXX19LCAiYWZ0ZXIiOiB7IiRvciI6IFt7Il9pZCI6IHsiJGd0IjogIiRvaWQtNjllN2UzNzc0NWUyNmY4ZTg1OGJhOTUzIn19XX0sICJzb3J0IjogW1siX2lkIiwgMV1dLCAiZmllbGRzIjogeyJhY2wiOiAwLCAibWV0YSI6IDB9LCAibGltaXQiOiA1fQ=="
    }
}'
```

***

### <mark style="color:$primary;">4) Vulnerability Status Reference</mark>

| Status | Meaning                                      |
| ------ | -------------------------------------------- |
| `1`    | Open                                         |
| `2`    | Closed                                       |
| `3`    | Pending (closed, awaiting scan confirmation) |
| `4`    | False positive                               |

***

### <mark style="color:$primary;">5) Retrieving Vulnerability details</mark>

Each affected record includes a `vulnerability` ID.\
Use this ID with the vulnerabilities endpoint to retrieve full metadata.

***

#### <mark style="color:$primary;">5.1) Single Vulnerability</mark>

Each object returned, also includes the vulnerability id. The information for this can be retrieved with the following request:

Single vulnerability

```
curl --location 'https://cybaverse.cybaops.com/vulnerabilities/api/1.0/vulnerabilities/list' \
--header 'secureauth-accesskey: {APITOKEN}' \
--header 'Content-Type: application/json' \
--data '{
    "query": {
        "filter": {
            "_id": "$oid-637962616f70732d30000000"
        }
    }
}'
```

#### <mark style="color:$primary;">5.2) Multiple Vulnerabilities</mark>

Multiple vulnerabilities

```
curl --location 'https://cybaverse.cybaops.com/vulnerabilities/api/1.0/vulnerabilities/list' \
--header 'secureauth-accesskey: {APITOKEN}' \
--header 'Content-Type: application/json' \
--data '{
    "query": {
        "filter": {
            "_id": {
                "$in": ["$oid-637962616f70732d30000000","$oid-637962616f70732d34383000"]
            }
        }
    }
}'
```

Expected Response

```json
{
    "total": null,
    "documents": [
        {
            "_id": "637962616f70732d30000000",
            "created_by": "build",
            "modified_by": "build",
            "created_at": 1776804725.1858401,
            "modified_at": 1776804725.1858404,
            "title": "Unpatched software detected 80",
            "description": "Port is open to the internet and may be vulnerable.",
            "impact": "Medium",
            "recommendation": "Add missing security headers.",
            "severity": 3,
            "cvss": 8.2,
            "cvss_vector": "AV:N/AC:H/PR:N/UI:R/S:U/C:N/I:L/A:N",
            "cve": "",
            "base_vulnerability": null,
            "first_seen_at": 1776804725,
            "last_seen_at": 1776804725,
            "document_type": "vulnerability",
            "affected_assets_count": 0,
            "status": 2,
            "status_at": 1776804725,
            "user_status": null,
            "user_status_at": 1776804725,
            "user_status_by": "build",
            "user_status_note": null,
            "user_status_reason": null,
            "sources": [
                {
                    "name": "Manual Review",
                    "id": "manual-review-123"
                }
            ]
        },
        {
            "_id": "637962616f70732d34383000",
            "created_by": "build",
            "modified_by": "build",
            "created_at": 1776804730.2319233,
            "modified_at": 1776804730.2319233,
            "title": "SQL Injection risk 46",
            "description": "Application is vulnerable to XSS attacks.",
            "impact": "Medium",
            "recommendation": "Publish a valid SPF record.",
            "evidence": "Nmap scan found open port.",
            "severity": 1,
            "cvss": 9.1,
            "cvss_vector": "AV:N/AC:H/PR:N/UI:R/S:U/C:N/I:L/A:N",
            "cve": "",
            "base_vulnerability": null,
            "first_seen_at": 1776804730,
            "last_seen_at": 1776804730,
            "document_type": "vulnerability",
            "affected_assets_count": 1,
            "status": 1,
            "status_at": 1776804730,
            "user_status": null,
            "user_status_at": 1776804730,
            "user_status_by": "build",
            "user_status_note": null,
            "user_status_reason": null,
            "sources": [
                {
                    "name": "Vulnerability Scanner2",
                    "id": "vulnerability-scanner-d31d2e0628"
                }
            ]
        }
    ],
    "next": null
}
```

With this approach. The status of the vulnerability for a specific asset should be taken from "/api/1.0/affected/list". The status of "/api/1.0/vulnerabilities/list" relates to all assets combined.

***

### <mark style="color:$primary;">6) Returning select fields</mark>

Queries without the `fields` key inserted will return all data. To return selected fields we can define with the `fields` key as follows (examples taken from `/api/1.0/vulnerabilities/list`):

```curl
curl --location 'https://cybaverse.cybaops.com/vulnerabilities/api/1.0/vulnerabilities/list' \
--header 'secureauth-accesskey: {APIKEY}' \
--header 'Content-Type: application/json' \
--data '{
    "query": {
        "filter": {
            "_id": {
                "$in": ["$oid-637962616f70732d30000000","$oid-637962616f70732d34383000"]
            }
        },
        "fields": {
            "title": 1,
            "description": 1,
            "cvss":1
        }
    }
}'
```

#### <mark style="color:$primary;">Example response</mark>

```json
{
    "total": null,
    "documents": [
        {
            "_id": "637962616f70732d30000000",
            "title": "Unpatched software detected 80",
            "description": "Port is open to the internet and may be vulnerable.",
            "cvss": 8.2
        },
        {
            "_id": "637962616f70732d34383000",
            "title": "SQL Injection risk 46",
            "description": "Application is vulnerable to XSS attacks.",
            "cvss": 9.1
        }
    ],
    "next": null
}
```

***

### <mark style="color:$primary;">7) Important Behaviour Notes</mark>

* **Asset‑specific status** must be taken from:\
  `/api/1.0/affected/list`
* **Vulnerability status** from:\
  `/api/1.0/vulnerabilities/list`\
  represents the **aggregate state across all assets**
* `next` tokens **preserve original filters automatically** and must not be modified


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cybaops.com/settings/access-tokens/asset-and-vulnerability-api-usage.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.