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/.
- Global data endpoints use
- 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 endpoint | Platform API method and endpoint | Description and link |
|---|---|---|
GET /v2/hosts/search | POST /v3/global/search/query | Unified search across all record types. |
GET /v2/hosts/aggregate | POST /v3/global/search/aggregate | Aggregate search results. |
GET /v2/hosts/{ip} | GET /v3/global/asset/host/{ip} | Retrieve data for a single host. |
GET /v2/hosts/{ip}/events | GET /v3/global/asset/host/{ip}/timeline | Retrieve events for a host. |
GET /v2/certificates/search | POST /v3/global/search/query | Specify certificate fields in your query. |
GET /v2/certificates/aggregate | POST /v3/global/search/aggregate | Specify 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}/hosts | n/a | Available in Threat Hunting module in a future release. |
GET /v2/hosts/{ip}/certificates | n/a | Available in Threat Hunting module in a future release. |
GET /v2/certificates/{fp}/observations | n/a | Available in Threat Hunting module in a future release. |
| All comment and tag endpoints | n/a | Available 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 endpoint | Description 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}/timeline | Host asset timeline data. |
POST /v3/global/search/query | Unified 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 endpoint | Description and link |
|---|---|
GET /v3/collections | List an organization's collections. |
POST /v3/collections | Create a collection. |
POST /v3/collections/{collection_uid}/search/query | Search within a collection. |
POST /v3/collections/{collection_uid}/search/aggregate | Aggregate results within a collection. |
Updated 15 days ago