Platform API Transition Guide

The Censys Platform features an extensive set of API endpoints that enable you to integrate Platform functionality with your tech stack. This document explains which Platform APIs provide parity to Legacy Search APIs and describes some new Platform APIs. You can see complete details about API syntax, parameters, and test the new APIs in the documentation.

To ensure a smooth API transition, note the following:

  • You must use the new base URL: https://api.platform.censys.io/v3/.
    • Global data endpoints use https://api.platform.censys.io/v3/global/.
    • Collections endpoints use https://api.platform.censys.io/v3/collections/.
  • Users must have the API Access role in order to use the API.
  • Your API requests must use a valid Personal Access Token.

Platform APIs offer the following advantages over Legacy Search functionality:

  • Query across all asset types with one API search query instead of running multiple endpoints for each asset type.
  • Access to the expanded and improved Platform datasets.
    • The Platform dataset includes additional context about host and web property software, hardware, operating system, and endpoints previously unavailable in Legacy Search.
  • Deeper context about name-based assets on the internet, including websites, APIs, and web-based applications, via the web property dataset.
  • New Collection API endpoints to programmatically monitor changes to internet infrastructure functionality.

📘

Note

The following Platform SDKs are available.

Legacy Search API endpoints replaced by Platform API endpoints

This table maps Legacy Search API endpoints to their equivalent Platform API endpoints, including HTTP methods and notes on any differences. Links to the endpoint documentation in the API reference guide are also provided.

Legacy Search API method and endpointPlatform API method and endpointDescription and link
GET /v2/hosts/searchPOST /v3/global/search/queryUnified search across all record types.
GET /v2/hosts/aggregatePOST /v3/global/search/aggregateAggregate search results.
GET /v2/hosts/{ip}GET /v3/global/asset/host/{ip}Retrieve data for a single host.
GET /v2/hosts/{ip}/eventsGET /v3/global/asset/host/{ip}/timelineRetrieve events for a host.
GET /v2/certificates/searchPOST /v3/global/search/querySpecify certificate fields in your query.
GET /v2/certificates/aggregatePOST /v3/global/search/aggregateSpecify certificate fields in your query.
GET /v2/certificates/{fp}GET /v3/global/asset/certificate/{fp}Retrieve data for a single certificate.
GET /v2/certificates/{fp}/hostsn/aAvailable in Threat Hunting module in a future release.
GET /v2/hosts/{ip}/certificatesn/aAvailable in Threat Hunting module in a future release.
GET /v2/certificates/{fp}/observationsn/aAvailable in Threat Hunting module in a future release.
All comment and tag endpointsn/aAvailable in a future Platform release.

New Platform API endpoints

This table highlights new API functionalities introduced in the Platform that were unavailable in Legacy Search.

Platform API method and endpointDescription and link
GET /v3/global/asset/webproperty/{webproperty_id}Details on a specific web property.
POST /v3/global/asset/host?host_ids={host_id},{host_id}Bulk host asset retrieval.
POST /v3/global/asset/certificate?certificate_ids={fp},{fp}Bulk certificate asset retrieval.
POST /v3/global/asset/webproperty?webproperty_ids={webproperty_id},{webproperty_id}Bulk web property asset retrieval.
GET /v3/global/asset/host/{host_id}/timelineHost asset timeline data.
POST /v3/global/search/queryUnified search across all asset types.

Platform Collection API endpoints

Collections allow you to track and monitor the results of a Censys query over time. You can save time and resources by creating a collection and configuring alerts to track new assets that match your queries. The following table explores a selection of the collection API endpoints that are available to manage, and monitor your collections. See the full list of collection APIs in the reference guide.

Platform API method and endpointDescription and link
GET /v3/collectionsList an organization's collections.
POST /v3/collectionsCreate a collection.
POST /v3/collections/{collection_uid}/search/querySearch within a collection.
POST /v3/collections/{collection_uid}/search/aggregateAggregate results within a collection.