openapi: 3.1.0
info:
contact:
email: support@censys.io
name: Censys Support
description: '# Asset Graph API
The Asset Graph API provides comprehensive visibility into your Internet-facing assets. Use this API to build and manage attack surfaces by creating asset graphs, configuring seeds and exclusions, running discovery executions, and retrieving discovered assets and risk metadata.
### Authentication
All requests must include a valid Censys personal access token (PAT) in the `Authorization` header:
```
Authorization: Bearer <your-api-token>
```
An `X-Organization-ID` header must also be present on every request. This identifies the Censys organization that owns the resources being accessed.
```
X-Organization-ID: <your-organization-id>
```
### Core Concepts
- **Asset Graph**: The parent resource representing an attack surface. Each asset graph contains seeds, excluded assets, and executions.
- **Seeds**: Persistent starting points used to discover additional assets. Supported types include IP addresses, domains, CIDRs, ASNs, certificates, and web properties.
- **Excluded Assets**: Assets explicitly excluded from the graph. Excluded assets will not appear in execution results and will not be used to discover additional assets.
- **Executions**: A discovery process that uses the graph''s configured seeds and excluded assets to generate a complete snapshot of the attack surface. Censys periodically runs executions in the background, or they can be triggered on-demand.
- **Assets**: Internet-facing resources discovered during an execution, including hosts, domains, certificates, and web properties. Each asset includes discovery paths showing how it was found from your seeds.
- **Risks**: Vulnerabilities, exposures, misconfigurations, and threats identified on discovered assets.
### Getting Started
1. **Create an asset graph** to represent your attack surface.
2. **Add seeds** — the known assets that Censys will use as starting points for discovery.
3. **Optionally add excluded assets** to omit specific assets from results.
4. **Create an execution** to trigger the discovery process, or wait for Censys to run one automatically.
5. **List assets** from a completed execution to view your discovered attack surface.
6. **Look up risk metadata** for any risk IDs found on your assets.
'
title: Asset Graph Account Management Threat Hunting API
version: 1.0.12
servers:
- description: Asset Graph API
url: https://graph.data.censys.io
tags:
- description: Endpoints related to the Adversary Investigation product
name: Threat Hunting
paths:
/v3/threat-hunting/censeye/jobs:
get:
description: List CensEye pivot analysis jobs for the current organization. Results are paginated. Optionally filter by asset (host, web property, or certificate).
operationId: v3-threathunting-censeye-jobs-list
parameters:
- description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
example: 11111111-2222-3333-4444-555555555555
explode: false
in: query
name: organization_id
required: true
schema:
description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
examples:
- 11111111-2222-3333-4444-555555555555
format: uuid
type: string
- description: 'The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.'
example: 11111111-2222-3333-4444-555555555555
in: header
name: X-Organization-ID
schema:
description: 'The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.'
examples:
- 11111111-2222-3333-4444-555555555555
format: uuid
type: string
x-speakeasy-ignore: true
- description: Number of results per page (max 100)
explode: false
in: query
name: page_size
schema:
default: 100
description: Number of results per page (max 100)
format: int32
maximum: 100
minimum: 1
type: integer
- description: Pagination token from previous response
explode: false
in: query
name: page_token
schema:
description: Pagination token from previous response
type: string
- description: Filter by host IP address.
example: 8.8.8.8
explode: false
in: query
name: host_id
schema:
description: Filter by host IP address.
examples:
- 8.8.8.8
type: string
- description: Filter by web property (hostname:port).
example: example.com:443
explode: false
in: query
name: webproperty_id
schema:
description: Filter by web property (hostname:port).
examples:
- example.com:443
type: string
- description: Filter by certificate SHA-256 fingerprint.
example: 3daf2843a77b6f4e6af43cd9b6f6746053b8c928e056e8a724808db8905a94cf
explode: false
in: query
name: certificate_id
schema:
description: Filter by certificate SHA-256 fingerprint.
examples:
- 3daf2843a77b6f4e6af43cd9b6f6746053b8c928e056e8a724808db8905a94cf
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseEnvelopeCenseyeJobsListResponse'
description: OK
headers:
Content-Type:
schema:
type: string
X-Request-ID:
schema:
type: string
'400':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticationError'
description: Request does not contain a valid Authorization token
'403':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: User does not have permission to access this data
'409':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Conflict
'500':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Internal server error
security:
- PersonalAccessToken: []
summary: 'Censys CensEye: List Jobs'
tags:
- Threat Hunting
x-speakeasy-name-override: ListCenseyeJobs
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
description: Create an asynchronous CensEye pivot analysis job for a host, web property, or certificate. The job extracts [default pivot fields](https://docs.censys.com/docs/platform-threat-hunting-use-censeye-to-build-detections#default-pivot-fields) from the target asset and counts matching documents for each field-value pair. Poll the job status endpoint to track progress, then retrieve results when complete.<br><br>To use this endpoint, your organization must have access to the Adversary Investigation module.<br><br>This endpoint costs 44 credits to execute for a host, 28 credits to execute for a web property, and 7 credits to execute for a certificate.
operationId: v3-threathunting-censeye-jobs-create
parameters:
- description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
example: 11111111-2222-3333-4444-555555555555
explode: false
in: query
name: organization_id
required: true
schema:
description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
examples:
- 11111111-2222-3333-4444-555555555555
format: uuid
type: string
- description: 'The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.'
example: 11111111-2222-3333-4444-555555555555
in: header
name: X-Organization-ID
schema:
description: 'The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.'
examples:
- 11111111-2222-3333-4444-555555555555
format: uuid
type: string
x-speakeasy-ignore: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCenseyeJobInputBody'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseEnvelopeCenseyeJob'
description: OK
headers:
Content-Type:
schema:
type: string
X-Request-ID:
schema:
type: string
'400':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticationError'
description: Request does not contain a valid Authorization token
'403':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: User does not have permission to access this data
'422':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Invalid input
'500':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Internal server error
security:
- PersonalAccessToken: []
summary: 'Censys CensEye: Create a Pivot Analysis Job'
tags:
- Threat Hunting
x-speakeasy-name-override: CreateCenseyeJob
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v3/threat-hunting/censeye/jobs/{job_id}:
get:
description: Retrieve the current status of a CensEye pivot analysis job. Use this to poll for completion before fetching results.<br><br>To use this endpoint, your organization must have access to the Adversary Investigation module.
operationId: v3-threathunting-censeye-jobs-get
parameters:
- description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
example: 11111111-2222-3333-4444-555555555555
explode: false
in: query
name: organization_id
required: true
schema:
description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
examples:
- 11111111-2222-3333-4444-555555555555
format: uuid
type: string
- description: 'The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.'
example: 11111111-2222-3333-4444-555555555555
in: header
name: X-Organization-ID
schema:
description: 'The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.'
examples:
- 11111111-2222-3333-4444-555555555555
format: uuid
type: string
x-speakeasy-ignore: true
- description: The unique identifier of the CensEye job.
in: path
name: job_id
required: true
schema:
description: The unique identifier of the CensEye job.
format: uuid
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseEnvelopeCenseyeJob'
description: OK
headers:
Content-Type:
schema:
type: string
X-Request-ID:
schema:
type: string
'400':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticationError'
description: Request does not contain a valid Authorization token
'403':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: User does not have permission to access this data
'404':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Resource not found
'500':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Internal server error
security:
- PersonalAccessToken: []
summary: 'Censys CensEye: Get Job Status'
tags:
- Threat Hunting
x-speakeasy-name-override: GetCenseyeJob
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v3/threat-hunting/censeye/jobs/{job_id}/results:
get:
description: Retrieve the results of a completed CensEye pivot analysis job. Each result contains a count and the field-value pairs that were analyzed. Results may be empty if the job is still running.<br><br>Results are paginated. Use the `next_page_token` from the response to fetch subsequent pages.<br><br>To use this endpoint, your organization must have access to the Adversary Investigation module.
operationId: v3-threathunting-censeye-job-results
parameters:
- description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
example: 11111111-2222-3333-4444-555555555555
explode: false
in: query
name: organization_id
required: true
schema:
description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
examples:
- 11111111-2222-3333-4444-555555555555
format: uuid
type: string
- description: 'The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.'
example: 11111111-2222-3333-4444-555555555555
in: header
name: X-Organization-ID
schema:
description: 'The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.'
examples:
- 11111111-2222-3333-4444-555555555555
format: uuid
type: string
x-speakeasy-ignore: true
- description: The unique identifier of the CensEye job.
in: path
name: job_id
required: true
schema:
description: The unique identifier of the CensEye job.
format: uuid
type: string
- description: Number of results per page (max 100)
explode: false
in: query
name: page_size
schema:
default: 100
description: Number of results per page (max 100)
format: int32
maximum: 100
minimum: 1
type: integer
- description: Pagination token from previous response
explode: false
in: query
name: page_token
schema:
description: Pagination token from previous response
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseEnvelopeCenseyeResultsResponse'
description: OK
headers:
Content-Type:
schema:
type: string
X-Request-ID:
schema:
type: string
'400':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticationError'
description: Request does not contain a valid Authorization token
'403':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: User does not have permission to access this data
'404':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Resource not found
'500':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Internal server error
security:
- PersonalAccessToken: []
summary: 'Censys CensEye: Get Job Results'
tags:
- Threat Hunting
x-speakeasy-name-override: GetCenseyeJobResults
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v3/threat-hunting/certificate/{certificate_id}/observations/hosts:
get:
description: Retrieve the historical observations of hosts associated with a certificate. This is useful for threat hunting, detection engineering, and timeline generation. Certificate history is also visible to Adversary Investigation users in the Platform UI on the [certificate timeline](https://docs.censys.com/docs/platform-threat-hunting-use-cert-history-to-build-better-detections#/).<br><br>You can define a specific time frame of interest. If you do not specify a time frame, this endpoint will search the historical dataset that is available to your account. You may also filter results by port and transport protocol.<br><br>This endpoint is available to organizations that have access to the Adversary Investigation module. It costs 5 credits per page of results.
operationId: v3-threathunting-get-host-observations-with-certificate
parameters:
- description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
example: 11111111-2222-3333-4444-555555555555
explode: false
in: query
name: organization_id
required: true
schema:
description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
examples:
- 11111111-2222-3333-4444-555555555555
format: uuid
type: string
- description: 'The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.'
example: 11111111-2222-3333-4444-555555555555
in: header
name: X-Organization-ID
schema:
description: 'The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.'
examples:
- 11111111-2222-3333-4444-555555555555
format: uuid
type: string
x-speakeasy-ignore: true
- description: SHA-256 hash of the certificate
example: 55af8a301eb51abdaf7c31bec951638fe5a99d5d92117eca2be493026613fa46
in: path
name: certificate_id
required: true
schema:
description: SHA-256 hash of the certificate
examples:
- 55af8a301eb51abdaf7c31bec951638fe5a99d5d92117eca2be493026613fa46
type: string
- description: Only show ranges ending at or after this time (ISO 8601)
example: '2023-01-01T00:00:00Z'
explode: false
in: query
name: start_time
schema:
description: Only show ranges ending at or after this time (ISO 8601)
examples:
- '2023-01-01T00:00:00Z'
type: string
- description: Only show ranges starting at or before this time (ISO 8601)
example: '2023-12-31T23:59:59Z'
explode: false
in: query
name: end_time
schema:
description: Only show ranges starting at or before this time (ISO 8601)
examples:
- '2023-12-31T23:59:59Z'
type: string
- description: The port to filter by
example: 443
explode: false
in: query
name: port
schema:
description: The port to filter by
examples:
- 443
format: int32
type: integer
- description: The transport protocol to filter by
example: TCP
explode: false
in: query
name: protocol
schema:
description: The transport protocol to filter by
examples:
- TCP
type: string
- description: Pagination token from previous response to retrieve next page of results
explode: false
in: query
name: page_token
schema:
description: Pagination token from previous response to retrieve next page of results
type: string
- description: Number of results per page. Maximum 100, defaults to 100 if not specified
example: 50
explode: false
in: query
name: page_size
schema:
description: Number of results per page. Maximum 100, defaults to 100 if not specified
examples:
- 50
format: int32
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseEnvelopeHostObservationResponse'
description: A list of host observations for the certificate
headers:
Content-Type:
schema:
type: string
X-Request-ID:
schema:
type: string
'400':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticationError'
description: Request does not contain a valid Authorization token
'403':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: User does not have permission to access this data
'404':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Resource not found
'500':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Internal server error
security:
- PersonalAccessToken: []
summary: Censys Get Host History for a Certificate
tags:
- Threat Hunting
x-speakeasy-name-override: GetHostObservationsWithCertificate
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v3/threat-hunting/host/{ip}/observations/endpoints:
get:
description: Retrieve historical endpoint-level hash observations for a host. This action returns time frames during which Censys observed host service endpoint body, favicon, and banner hash values. You must provide an `observation_type` and can optionally filter by a specific value using the `observation_value` parameter. You may also filter by port number.<br><br>To use this endpoint, your organization must have access to the Adversary Investigation module.
operationId: v3-threathunting-endpoint-observations-on-host
parameters:
- description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
example: 11111111-2222-3333-4444-555555555555
explode: false
in: query
name: organization_id
required: true
schema:
description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
examples:
- 11111111-2222-3333-4444-555555555555
format: uuid
type: string
- description: 'The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.'
example: 11111111-2222-3333-4444-555555555555
in: header
name: X-Organization-ID
schema:
description: 'The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.'
examples:
- 11111111-2222-3333-4444-555555555555
format: uuid
type: string
x-speakeasy-ignore: true
- description: Start of date range (RFC3339 format, e.g., 2024-01-01T00:00:00Z). If not specified, defaults to the maximum query window back from the end time.
example: '2024-01-01T00:00:00Z'
explode: false
in: query
name: start_time
schema:
description: Start of date range (RFC3339 format, e.g., 2024-01-01T00:00:00Z). If not specified, defaults to the maximum query window back from the end time.
examples:
- '2024-01-01T00:00:00Z'
type: string
- description: End of date range (RFC3339 format, e.g., 2024-01-31T23:59:59Z). If not specified, defaults to now. Cannot be in the future.
example: '2024-01-31T23:59:59Z'
explode: false
in: query
name: end_time
schema:
description: End of date range (RFC3339 format, e.g., 2024-01-31T23:59:59Z). If not specified, defaults to now. Cannot be in the future.
examples:
- '2024-01-31T23:59:59Z'
type: string
- description: Number of results per page (max 100)
example: 50
explode: false
in: query
name: page_size
schema:
default: 100
description: Number of results per page (max 100)
examples:
- 50
format: int32
maximum: 100
minimum: 1
type: integer
- description: Pagination token from previous response
explode: false
in: query
name: page_token
schema:
description: Pagination token from previous response
type: string
- description: Filter by port number
example: 443
explode: false
in: query
name: port
schema:
description: Filter by port number
examples:
- 443
format: int32
type: integer
- description: Filter by observation value for the selected observation_type
explode: false
in: query
name: observation_value
schema:
description: Filter by observation value for the selected observation_type
type: string
- description: The IP address of a host.
example: 8.8.8.8
in: path
name: ip
required: true
schema:
description: The IP address of a host.
examples:
- 8.8.8.8
format: ip
type: string
- description: Endpoint observation type to query.
explode: false
in: query
# --- truncated at 32 KB (96 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/censys/refs/heads/main/openapi/censys-threat-hunting-api-openapi.yml