The Assets API from CyCognito — 6 operation(s) for assets.
openapi: 3.0.3
info:
version: 0.0.1
title: CyCognito API V1 Reference Assets API
description: 'The CyCognito API V1 is a REST API that allows you to post and get data from our main data entities—assets and issues. You can also manage the scope of your attack surface, attribute assets to organizations, and verify the identity of IP scans on your assets. Our legacy API (V0) documentation is available for download [here](https://platform.cycognito.com/CyCognito-API-V0-Reference.pdf). While V0 is still being supported, please note that this API is undergoing deprecation.
| Code | Name | Description |
|------|------|-------------|
| 200 | OK | Success |
| 400 | Bad Request | The request is malformed—e.g., the body cannot be properly parsed, expected fields are not included in the body, or unsupported request header values. |
| 403 | Access Restricted | There are insufficient permissions or a valid API key was not provided. |
| 404 | Not Found | The provided resource was not found. |
| 405 | Method Not Allowed | The HTTP method is not allowed for the given resource. |
| 415 | Unsupported Media Type | The request content type is not supported. |
| 5XX | | Server failure | |
'
tags:
- name: Assets
paths:
/v1/assets:
post:
description: Query assets across all asset types (IPs, domains, certificates, web applications, IP ranges) simultaneously in a single API call. This unified endpoint simplifies asset management by allowing you to retrieve and filter multiple asset types at once, rather than querying each type separately. Returns results in a consistent format with fields set to `null` when not applicable to a specific asset type.
security:
- apiAuth: []
summary: Retrieve unified assets
tags:
- Assets
parameters:
- name: count
in: query
schema:
type: integer
required: false
description: Defines the number of results to be retrieved. Defaults to 10 with a max limit of 1000.
- name: advanced-search
in: query
schema:
type: string
required: false
description: Allows you to input raw CyQL in order to query assets, issues, or organizations. See our <span name="kb-advanced-search-link">Advanced Search</span> documentation for more details.
- name: offset
in: query
schema:
type: integer
required: false
description: 'Sets the starting index for result retrieval, influenced by the `count` parameter. By default, `offset` is 0. Example: `offset` 3 with `count` 25 fetches results from index 75 to 99.'
- name: q
in: query
schema:
type: string
required: false
description: Specifies a search term for conducting a keyword-based search and retrieving data that matches your query.
- name: fields
in: query
schema:
type: string
required: false
description: A comma-separated list specifying the desired entity properties to appear in the response. For more information, view the response example and schema.
- name: sort-by
in: query
schema:
type: string
required: false
description: Specifies the field by which the results should be sorted.
- name: sort-order
in: query
schema:
type: string
enum:
- asc
- desc
required: false
description: Sorts the specified field in ascending or descending order.
requestBody:
content:
application/json:
schema:
type: array
items:
type: object
properties:
field:
description: Field to apply the filter on. Typically, any field present in the response can be used.
allOf:
- type: string
example: status
op:
description: "Specifies the operation to apply on the desired field.\n \n*Supported values:* \n \n* `is` – Searches for values that match the specified text exactly. \n \n* `not` – Searches for values that **do not** match the specified text exactly. \n \n* `in` – Filters entities for values that include the specified strings. Note that these should be *full strings* and not *substrings*—see `contains`. \n \n* `not-in` – Filters entities for values that do not include the specified strings. Note that these should be *full strings* and not *substrings*—see `contains`. \n \n* `only-in` – Filters **exclusively** so that only entities with the values specified will be searched. This operator is currently available only for the `organizations` and `tags` properties for assets and issues. \n \n* `between` – Searches by dates that are in between two specified values. Each date range should be placed in square brackets `[]`, in the format `<YYYY>-<MM>-<DD>T<HH>:<mm>:<ss>.<SSS>Z`, and separated by a comma—e.g., `[\"2022-01-01T00:00:00.000Z\", \"2022-12-31T23:59:59.999Z\"]`. \n \n* `not-between` – Searches by dates that are **not** in between two specified values. Each date range should be placed in square brackets `[]`, in the format `<YYYY>-<MM>-<DD>T<HH>:<mm>:<ss>.<SSS>Z`, and separated by a comma—e.g., `[\"2022-01-01T00:00:00.000Z\", \"2022-12-31T23:59:59.999Z\"]`. \n \n* `within-range` – Searches by number values that are in between a specified range. Each range should be placed in square brackets `[]` and separated by a comma—e.g., `[60,75]`.\n \n* `not-within-range` – Searches by number values that are **not** in between a specified range. Each range should be placed in square brackets `[]` and separated by a comma—e.g., `[10,59]`.\n \n* `within-last` – Searches for date values that are within the specified time frame in days—e.g., `64` is the value for 64 days.\n \n* `not-within-last` – Searches for date values that are **not** within the specified time frame in days—e.g., `128` is the value for 128 days.\n \n* `contains` – Searches for a specific substring within a string value."
allOf:
- type: string
enum:
- is
- not
- in
- not-in
- only-in
- key-of
- not-key-of
- between
- not-between
- within-range
- not-within-range
- contains
- within-last
- not-within-last
example: in
values:
description: Specifies the value or values for the field.
type: array
items:
$ref: '#/components/schemas/json.any?'
example:
- new
required:
- field
- op
- values
responses:
'200':
content:
application/json:
schema:
type: array
items:
type: object
properties:
active:
description: Indicates whether an IP address, domain, or certificate is currently used by your organization's IT infrastructure.
anyOf:
- type: boolean
- type: 'null'
example: 'true'
additional-properties:
description: Supplementary attributes or characteristics of a web application asset, particularly detailing any unique web resource features or specifications of interest.
anyOf:
- $ref: '#/components/schemas/json.any?'
- type: 'null'
example: "{\n \"hosting.environment\": {\n \"value\": [\n \"IaaS\"\n ],\n \"display_name\": \"Hosting environment\"\n },\n \"hosting.provider\": {\n \"value\": [\n \"Amazon\"\n ],\n \"display_name\": \"Hosting provider\"\n },\n \"hosting.type\": {\n \"value\": [\n \"cloud\"\n ],\n \"display_name\": \"Hosting type\"\n }\n }"
advisories:
description: A list of curated pieces of threat intelligence that highlight vulnerabilities actively exploited by attackers in the wild. This property is available only for customers using Exploit Intelligence.
anyOf:
- type: array
items:
anyOf:
- type: object
properties:
last-verified:
anyOf:
- type: string
format: date-time
- type: 'null'
evidence-id:
anyOf:
- type: string
- type: 'null'
evidence-last-seen:
anyOf:
- type: string
format: date-time
- type: 'null'
vulnerable:
anyOf:
- type: boolean
- type: 'null'
advisory:
anyOf:
- type: string
- type: 'null'
issue-id:
anyOf:
- type: string
- type: 'null'
required:
- last-verified
- evidence-id
- evidence-last-seen
- vulnerable
- advisory
- issue-id
- type: 'null'
- type: 'null'
example: "[\n {\n \"last_verified\": \"2024-08-04T08:21:17.000Z\",\n \"id\": \"ip/1.2.2.2\",\n \"issue_id\": \"CYC-VS-APACHE-HTTP_SERVER-2.2.15\",\n \"advisory\": \"CISA | Known Exploited Vulnerabilities (KEV) catalog\",\n \"type\": \"ip\",\n \"evidence_id\": \"issue/1.2.2.2-cyc-vs-apache-http_server-2.2.15\",\n \"realm_id\": \"acme-corporation\",\n \"security_score\": 16,\n \"evidence_last_seen\": \"2024-08-04T08:21:17.000Z\",\n \"vulnerable\": true\n }\n ]"
alive:
description: Indicates whether an IP Address has at least one open or closed port (i.e., an installed service), or responds to a ping.
anyOf:
- type: boolean
- type: 'null'
example: 'true'
alive-evidence:
description: Refers to any specific evidence gathered from the internet which indicates the reason why an asset is considered alive.
anyOf:
- type: string
- type: 'null'
example: ports
as-list:
description: The list of autonomous systems (AS list) to which an IP range and its IP addresses belong.
anyOf:
- type: array
items:
anyOf:
- type: string
- type: 'null'
- type: 'null'
example: "[\n \"AS1234\",\n \"AS23456\",\n \"AS567890\"\n ]"
asns:
description: The Autonomous System Number (ASN) of an IP address.
anyOf:
- type: array
items:
$ref: '#/components/schemas/json.any?'
- type: 'null'
example: "[\n {\n \"owner\": \"Amazon.com, Inc.\",\n \"asn\": \"AS16509\"\n },\n {\n \"owner\": \"GoDaddy.com, LLC\",\n \"asn\": \"AS26496\"\n }\n ]"
attractiveness:
description: A measurement of how attractive a particular asset may be to a potential attacker. For example, a server with an exposed RDP service is a highly attractive target for attackers, regardless of any issues it has.
anyOf:
- type: number
- type: 'null'
example: extreme
attractiveness-label:
description: A measurement of how attractive a particular asset may be to a potential attacker. For example, a server with an exposed RDP service is a higher-priority target for attackers, regardless of any issues it has.
anyOf:
- type: string
- type: 'null'
example: extreme
attribution-certainty:
description: Refers to the degree of certainty in which an organization can be said to own a particular asset. This value is expressed as one of five levels for ease of prioritization.
anyOf:
- type: string
- type: 'null'
example: highest
business-units:
description: '[DEPRECATED] - The functional areas of the business that use the assets or the platform, or are affected by the issue.'
anyOf:
- type: array
items:
type: string
- type: 'null'
example: "[\n \"Marketing\"\n ]"
certificate-subject-key-id:
description: The certificates subject key.
anyOf:
- type: string
- type: 'null'
certification-authority-key-id:
description: The certificates authority key.
anyOf:
- type: string
- type: 'null'
cidr:
description: The CIDR IP range.
anyOf:
- type: string
- type: 'null'
example: 1.1.*.*
cis-controls:
description: Refers to the compliance control number of the CIS framework.
anyOf:
- type: array
items:
anyOf:
- type: string
- type: 'null'
uniqueItems: true
- type: 'null'
example: "[\n \"7.6\",\n \"3.11\",\n \"7.5\",\n \"16.7\"\n ]"
closed-ports:
description: A collection of objects describing closed ports associated with the asset.
anyOf:
- type: array
items:
type: object
properties:
status:
type: string
port:
type: integer
first-seen:
type: string
protocol:
type: string
enum:
- tcp
- udp
required:
- status
- port
- first-seen
- protocol
additionalProperties: false
- type: 'null'
example: "[\n {\n \"port\": 80,\n \"protocol\": \"udp\",\n \"status\": \"closed\"\n },\n {\n \"port\": 8081,\n \"protocol\": \"tcp\",\n \"first_seen\": \"2024-09-29T18:26:30.650Z\",\n \"status\": \"closed\"\n }\n ]"
cloud-env:
description: The cloud environment in which the asset is located.
anyOf:
- type: array
items:
type: string
- type: 'null'
example: ACME AWS Cloud Environment
cloud-env-metadata:
description: Data that CyCognito fetches directly from your cloud service (e.g., AWS, Azure, GCP) and includes the configuration of your instance.
anyOf:
- type: array
items:
type: object
additionalProperties:
anyOf:
- type: string
- type: object
- type: 'null'
example: "[{\"cloud-env\": \"value\"\n \"cloud-env-id\": \"value\"\n \"metadata\": \"value\"}]"
comment:
description: Custom text that can be added to the details of an asset or issue. Comments are typically used to make notes or personal descriptions regarding the significance of a particular asset or issue.
anyOf:
- type: object
properties:
content:
type: string
last-update:
anyOf:
- type: string
format: date-time
- type: 'null'
required:
- content
- last-update
- type: 'null'
example: Reviewed by Gary
comments:
description: Comments is a collection of custom text entries, providing the ability to record multiple notes or personal descriptions related to an asset or issue. Unlike the single 'comment' field, this allows for a running log or more detailed commentary over time.
anyOf:
- type: array
items:
type: object
properties:
content:
type: string
created-by-name:
anyOf:
- type: string
- type: 'null'
last-update:
anyOf:
- type: string
- type: 'null'
required:
- content
- created-by-name
- last-update
- type: 'null'
example: Reviewed by Gary
compliance-violations:
description: Refers to specific compliance frameworks that have been violated.
anyOf:
- type: array
items:
anyOf:
- type: string
- type: 'null'
uniqueItems: true
- type: 'null'
example: "[\n \"NIST-800-171\",\n \"CIS\",\n \"ISO27001\"\n ]"
continent:
description: The geographical continent in which the asset or issue is located.
anyOf:
- type: array
items:
anyOf:
- type: string
- type: 'null'
- type: 'null'
example: Americas
country-code:
description: The country code in which the asset's underlying IP range is currently hosted.
anyOf:
- type: string
- type: 'null'
example: US
created:
description: The date and time at which the asset was created—e.g., *2019-03-03T22:00:10.000Z*.
anyOf:
- type: string
format: date-time
- type: 'null'
example: '2019-03-03T22:00:10.000Z'
discoverability:
description: Indicates an asset's level of exposure, or how easily an attacker can find an asset affected by a specific issue and identify its relation to your enterprise.
anyOf:
- type: string
- type: 'null'
example: extreme
discovery-path:
description: The sequence of steps involved in discovering a specific asset or organization in your attack surface. It details each step and the connections between them, illustrating how one step leads to the subsequent step in the discovery process.
anyOf:
- type: array
items:
type: object
properties:
src:
type: string
dest:
type: string
movement-type:
$ref: '#/components/schemas/json.any?'
movement-data:
$ref: '#/components/schemas/json.any?'
required:
- src
- dest
- movement-type
- movement-data
- type: 'null'
example: '[{"dest":"org/acme-corporation","movement_data":{"sources":[]},"movement_type":"default","src":"_ENTRY_"},{"dest":"ip/1.1.1.1","movement_data":{"probability":1,"relation_id":"org-relation/acme-corporation-has-subsidiary-acme-jubilee-limited","sources":[]},"movement_type":"relation","src":"org/acme-corporation"}]'
dns-rcode:
description: A string representing one of the common <a href="https://support.umbrella.com/hc/en-us/articles/232254248-Common-DNS-return-codes-for-any-DNS-service-and-Umbrella-">DNS return code messages</a>.
anyOf:
- type: string
- type: 'null'
example: NXDOMAIN
dns-records:
description: A list of the domain's DNS, SPF, and DKIM records.
anyOf:
- $ref: '#/components/schemas/json.any?'
- type: 'null'
example: "{\n \"A\": [\n \"1.1.255.255\"\n ],\n \"MX\": [\n \"10 us2.mx1.foobar.com.\"\n ],\n \"NS\": [\n \"ns0.acmedns.net.\"\n ],\n \"SOA\": [\n \"ns0.acmedns.net. support.acme.com. 1122334455 66778 8990 9090 1212\"\n ],\n \"TXT\": [\n \"\\\"v=spf1 redirect=_spf.foobar.com\\\"\"\n ]\n }"
domain:
description: The domain name associated with the asset.
anyOf:
- type: string
- type: 'null'
example: www.foobar.com
domains:
description: A list of domain names associated with the IP address.
anyOf:
- type: array
items:
type: string
- type: 'null'
example: "[\n \"blog.domain.com\",\n \"blog2.domain.com\",\n \"blog3.domain.com\"\n ]"
dynamic-dns:
description: Indicates whether a domain changes its DNS resolutions frequently or not.
anyOf:
- type: string
- type: 'null'
example: 'no'
dynamically-resolved:
description: Refers to whether an IP address is dynamically resolved or not, or partially dynamically resolved.
anyOf:
- type: array
items:
$ref: '#/components/schemas/json.any?'
- type: string
- type: 'null'
example: 'no'
environments:
description: Refers to IT environments, or the different hardware, software, infrastructure, and networks in which your assets are found.
anyOf:
- type: array
items:
anyOf:
- type: string
- type: 'null'
- type: 'null'
example: "[\n \"Cryptographic Protocols\",\n \"Operating Systems\",\n \"Web Servers\"\n ]"
expiration:
description: The date and time at which the asset expired—e.g., *2019-06-01T22:00:10.000Z*.
anyOf:
- type: string
format: date-time
- type: 'null'
example: '2023-02-07T23:59:59.000Z'
first-detected:
description: The date and time at which CyCognito first discovered and attributed the asset to the organization.
anyOf:
- type: string
format: date-time
- type: 'null'
example: '2022-03-18T09:07:22.977Z'
first-seen:
description: The date and time at which CyCognito first discovered and attributed the asset to the organization.
anyOf:
- type: string
format: date-time
- type: 'null'
example: '2022-03-18T09:07:22.977Z'
formats:
description: 'The specific type or standard of the web application''s structure and markup. It denotes the version or specification of web content being used, enabling users to identify how the application''s content is formatted. *Examples: html-5*, *xhtml-1.0-strict*, *xhtml-1.0-transitional*, etc.'
anyOf:
- type: array
items:
anyOf:
- type: string
- type: 'null'
- type: 'null'
example: "[\n \"html-5\"\n ]"
has-form:
description: Indicates whether a web page belonging to a web application contains a form or not.
anyOf:
- type: boolean
- type: 'null'
example: 'true'
has-login:
description: Refers to whether a web application includes a login mechanism in which a user could input credentials.
anyOf:
- type: boolean
- type: 'null'
example: 'true'
home-page-description:
description: The description of the homepage.
anyOf:
- type: string
- type: 'null'
example: Official homepage of Acme
home-page-status-code:
description: Indicates the HTTP status code returned by the homepage of a web application. This integer value represents the response status of the website, providing insight into its current accessibility or operational state.
anyOf:
- type: number
- type: 'null'
example: '200'
home-page-title:
description: The title of the homepage.
anyOf:
- type: string
- type: 'null'
example: Acme Home
home-page-url:
description: The URL of the homepage.
anyOf:
- type: string
- type: 'null'
example: https://1.1.1.1
hosting-type:
description: Refers to type of hosting platform for the asset or issue.
anyOf:
- type: string
- type: 'null'
example: undetermined
id:
description: "The unique identifier for an asset, formatted by combining its type (ip, domain, cert, webapp, or iprange) with its name: IP addresses as `ip/{ip}`, domains as `domain/{domain}`, certificates as `cert/{cert}`, web applications as `webapp/{webapp}`, and IP ranges as `iprange/{iprange}`. \n *Examples:* `ip/192.168.0.0`, `domain/acme-studios.com`"
anyOf:
- type: string
- type: 'null'
example: ip/192.168.0.0
investigation-status:
description: Indicates whether or not an asset or issue has undergone investigation by you or someone on your team.
anyOf:
- type: string
enum:
- investigating
- investigated
- uninvestigated
- type: 'null'
example: investigating
ip:
description: The IP address—e.g., `1.2.3.4`.
anyOf:
- type: string
- type: 'null'
example: 1.1.1.1
ip-addresses:
description: A list of the IP addresses hosting the asset.
anyOf:
- type: array
items:
type: string
- type: 'null'
example: "[\n \"1.1.1.2\",\n \"1.1.2.1\",\n \"1.2.1.1\"\n ]"
ip-ranges:
description: A list detailing specific IP ranges, with each item indicating the range (`inetnum`) and its associated owner (i.e., the organization registered in the Whois database). For example, a range might be *1.1.1.1-2.2.2.2* owned by *Acme Studios*.
anyOf:
- type: array
items:
anyOf:
- type: object
properties:
inetnu
# --- truncated at 32 KB (188 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cycognito/refs/heads/main/openapi/cycognito-assets-api-openapi.yml