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 Global Data API
version: 1.0.12
servers:
- description: Asset Graph API
url: https://graph.data.censys.io
tags:
- description: Endpoints related to the Global Data product
name: Global Data
paths:
/v3/global/asset/certificate:
get:
deprecated: true
description: Retrieve information about multiple certificates. A certificate ID is its SHA-256 fingerprint in the Censys dataset.<br><br>The GET method of this endpoint is deprecated, but will continue to be supported for backwards compatibility. Please use the [POST variant](https://docs.censys.com/reference/v3-globaldata-asset-certificate-list-post#/) of this endpoint instead.
operationId: v3-globaldata-asset-certificate-list
parameters:
- description: The ID of a Censys organization to associate the request with. If omitted, the request will be processed using the authenticated user's free wallet where applicable. 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
schema:
description: The ID of a Censys organization to associate the request with. If omitted, the request will be processed using the authenticated user's free wallet where applicable. 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. If omitted, the request will be processed using the authenticated user''s free wallet where applicable. 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. If omitted, the request will be processed using the authenticated user''s free wallet where applicable. 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: A list of SHA-256 certificate fingerprints.
example:
- 3daf2843a77b6f4e6af43cd9b6f6746053b8c928e056e8a724808db8905a94cf
explode: false
in: query
name: certificate_ids
required: true
schema:
description: A list of SHA-256 certificate fingerprints.
examples:
- - 3daf2843a77b6f4e6af43cd9b6f6746053b8c928e056e8a724808db8905a94cf
items:
type: string
maxItems: 1000
minItems: 1
type:
- array
- 'null'
responses:
'200':
content:
application/vnd.censys.api.v3.certificate.v1+json:
schema:
$ref: '#/components/schemas/ResponseEnvelopeListCertificateAsset'
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: No certificates found
'500':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Internal server error
security:
- PersonalAccessToken: []
summary: Censys Retrieve Multiple Certificates
tags:
- Global Data
x-speakeasy-ignore: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
description: Retrieve information about multiple certificates. You can retrieve up to 1,000 certificates per call. A certificate ID is its SHA-256 fingerprint in the Censys dataset.
operationId: v3-globaldata-asset-certificate-list-post
parameters:
- description: The ID of a Censys organization to associate the request with. If omitted, the request will be processed using the authenticated user's free wallet where applicable. 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
schema:
description: The ID of a Censys organization to associate the request with. If omitted, the request will be processed using the authenticated user's free wallet where applicable. 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. If omitted, the request will be processed using the authenticated user''s free wallet where applicable. 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. If omitted, the request will be processed using the authenticated user''s free wallet where applicable. 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/AssetCertificateListInputBody'
required: true
responses:
'200':
content:
application/vnd.censys.api.v3.certificate.v1+json:
schema:
$ref: '#/components/schemas/ResponseEnvelopeListCertificateAsset'
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: No certificates found
'500':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Internal server error
security:
- PersonalAccessToken: []
summary: Censys Retrieve Multiple Certificates
tags:
- Global Data
x-speakeasy-name-override: GetCertificates
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v3/global/asset/certificate/raw:
get:
deprecated: true
description: Retrieve the raw PEM-encoded format for multiple certificates. A certificate ID is its SHA-256 fingerprint in the Censys dataset.<br><br>The GET method of this endpoint is deprecated, but will continue to be supported for backwards compatibility. Please use the [POST variant](https://docs.censys.com/reference/v3-globaldata-asset-certificate-list-raw-post#/) of this endpoint instead.
operationId: v3-globaldata-asset-certificate-list-raw
parameters:
- description: The ID of a Censys organization to associate the request with. If omitted, the request will be processed using the authenticated user's free wallet where applicable. 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
schema:
description: The ID of a Censys organization to associate the request with. If omitted, the request will be processed using the authenticated user's free wallet where applicable. 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. If omitted, the request will be processed using the authenticated user''s free wallet where applicable. 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. If omitted, the request will be processed using the authenticated user''s free wallet where applicable. 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: A list of SHA-256 certificate fingerprints.
example:
- 3daf2843a77b6f4e6af43cd9b6f6746053b8c928e056e8a724808db8905a94cf
explode: false
in: query
name: certificate_ids
required: true
schema:
description: A list of SHA-256 certificate fingerprints.
examples:
- - 3daf2843a77b6f4e6af43cd9b6f6746053b8c928e056e8a724808db8905a94cf
items:
type: string
maxItems: 1000
minItems: 1
type:
- array
- 'null'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseEnvelopeListRawCertificateResponse'
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: No certificates found
'500':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Internal server error
security:
- PersonalAccessToken: []
summary: Censys Retrieve Multiple Certificates in PEM Format
tags:
- Global Data
x-speakeasy-ignore: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
description: Retrieve the raw PEM-encoded format for multiple certificates. You can retrieve up to 1,000 certificates per call. A certificate ID is its SHA-256 fingerprint in the Censys dataset.
operationId: v3-globaldata-asset-certificate-list-raw-post
parameters:
- description: The ID of a Censys organization to associate the request with. If omitted, the request will be processed using the authenticated user's free wallet where applicable. 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
schema:
description: The ID of a Censys organization to associate the request with. If omitted, the request will be processed using the authenticated user's free wallet where applicable. 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. If omitted, the request will be processed using the authenticated user''s free wallet where applicable. 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. If omitted, the request will be processed using the authenticated user''s free wallet where applicable. 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/AssetCertificateListInputBody'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseEnvelopeListRawCertificateResponse'
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: No certificates found
'500':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Internal server error
security:
- PersonalAccessToken: []
summary: Censys Retrieve Multiple Certificates in PEM Format
tags:
- Global Data
x-speakeasy-name-override: GetCertificatesRaw
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v3/global/asset/certificate/{certificate_id}:
get:
description: Retrieve information about a single certificate. A certificate ID is its SHA-256 fingerprint in the Censys dataset.
operationId: v3-globaldata-asset-certificate
parameters:
- description: The ID of a Censys organization to associate the request with. If omitted, the request will be processed using the authenticated user's free wallet where applicable. 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
schema:
description: The ID of a Censys organization to associate the request with. If omitted, the request will be processed using the authenticated user's free wallet where applicable. 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. If omitted, the request will be processed using the authenticated user''s free wallet where applicable. 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. If omitted, the request will be processed using the authenticated user''s free wallet where applicable. 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 SHA-256 certificate fingerprint.
example: 3daf2843a77b6f4e6af43cd9b6f6746053b8c928e056e8a724808db8905a94cf
in: path
name: certificate_id
required: true
schema:
description: The SHA-256 certificate fingerprint.
examples:
- 3daf2843a77b6f4e6af43cd9b6f6746053b8c928e056e8a724808db8905a94cf
type: string
responses:
'200':
content:
application/vnd.censys.api.v3.certificate.v1+json:
schema:
$ref: '#/components/schemas/ResponseEnvelopeCertificateAsset'
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: No certificate found
'500':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Internal server error
security:
- PersonalAccessToken: []
summary: Censys Get a Certificate
tags:
- Global Data
x-speakeasy-name-override: GetCertificate
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v3/global/asset/certificate/{certificate_id}/raw:
get:
description: Retrieve the raw PEM-encoded format of a certificate. A certificate ID is its SHA-256 fingerprint in the Censys dataset.
operationId: v3-globaldata-asset-certificate-raw
parameters:
- description: The ID of a Censys organization to associate the request with. If omitted, the request will be processed using the authenticated user's free wallet where applicable. 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
schema:
description: The ID of a Censys organization to associate the request with. If omitted, the request will be processed using the authenticated user's free wallet where applicable. 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. If omitted, the request will be processed using the authenticated user''s free wallet where applicable. 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. If omitted, the request will be processed using the authenticated user''s free wallet where applicable. 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 SHA-256 certificate fingerprint.
example: 3daf2843a77b6f4e6af43cd9b6f6746053b8c928e056e8a724808db8905a94cf
in: path
name: certificate_id
required: true
schema:
description: The SHA-256 certificate fingerprint.
examples:
- 3daf2843a77b6f4e6af43cd9b6f6746053b8c928e056e8a724808db8905a94cf
type: string
responses:
'200':
content:
application/x-pem-file:
schema:
contentMediaType: application/octet-stream
format: binary
type: string
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: No certificate found
'500':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Internal server error
security:
- PersonalAccessToken: []
summary: Censys Get a Certificate in PEM Format
tags:
- Global Data
x-speakeasy-name-override: GetCertificateRaw
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v3/global/asset/host:
get:
deprecated: true
description: Retrieve information about multiple hosts. A host ID is its IP address.<br><br>The GET method of this endpoint is deprecated, but will continue to be supported for backwards compatibility. Please use the [POST variant](https://docs.censys.com/reference/v3-globaldata-asset-host-list-post#/) of this endpoint instead.
operationId: v3-globaldata-asset-host-list
parameters:
- description: The ID of a Censys organization to associate the request with. If omitted, the request will be processed using the authenticated user's free wallet where applicable. 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
schema:
description: The ID of a Censys organization to associate the request with. If omitted, the request will be processed using the authenticated user's free wallet where applicable. 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. If omitted, the request will be processed using the authenticated user''s free wallet where applicable. 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. If omitted, the request will be processed using the authenticated user''s free wallet where applicable. 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
# --- truncated at 32 KB (443 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/censys/refs/heads/main/openapi/censys-global-data-api-openapi.yml