Censys REST API
The Censys REST API provides programmatic access to the same data accessible through the web interface. API access is governed by our Terms of Service and all scripted access should use this API. We list our API endpoints below.
v2 Endpoints
The Censys v2 API currently provides HTTP endpoints to search and view hosts using the latest Censys Search data. Endpoints are hosted at https://search.censys.io/api/v2/ and require
authenticating with HTTP basic auth using the API ID and secret that are shown on the
account page, which also lists the rate limits that apply
to your account.
Hosts
- view
/api/v2/hosts/{ip} - Fetches the most recent host information for the specified IP address.
- search
/api/v2/hosts/search - Allows queries for hosts using the Censys Search Language and returns results of hosts matching the provided search terms.
- aggregate
/api/v2/hosts/aggregate - Generates bucket-based aggregation statistics about a specified data field for hosts matching a provided query.
Response Format
All endpoints return response bodies formatted as application/json with the following top-level
structure:
Success
{
"code": 200, // HTTP Status Code
"status": "OK", // HTTP Status Text
"result": { ... } // API Result
}
Error
{
"code": 422, // HTTP Status Code
"status": "Unprocessable Entity", // HTTP Status Text
"error": "Query is malformed." // Error Details
}
Use This API
- Import the Censys Postman Collection and call the API with Postman.
- Copy & paste this cURL script into your terminal and replace the query with yours:
curl -G 'https://search.censys.io/api/v2/hosts/search' --data-urlencode 'q=service.service_name: HTTP' -u LOGIN_FOR_API_ID:LOGIN_FOR_API_SECRET | jq - Copy & paste this WGET script into your terminal and replace the query with yours:
wget -qO- --auth-no-challenge 'https://search.censys.io/api/v2/hosts/search?q=service.service_name: HTTP' --user=LOGIN_FOR_API_ID --password=LOGIN_FOR_API_SECRET | jq - Call the API from your Python app using our Python library.
- Call the API from your NodeJS app using our NodeJS library.
v1 Endpoints
The Censys legacy v1 API contains API endpoints which are being maintained until replacement v2 endpoints are available. To see the original v1 API docs, please visit the original search site.
Endpoints are hosted at https://search.censys.io/api/v1/ and require authenticating with HTTP basic auth using the API ID and secret that are shown on the account page, which also lists the rate limits that apply to your account.
Certificates
- search
/api/v1/certificates - Allows searches against the Certificates index using the same search language as the original search site and returns a paginated result of the most recent information for the set of user-selected fields.
- view
/api/v1/certificates/{sha256-fp} - Fetches structured certificate data for the specified SHA-256 fingerprint.
- bulk
/api/v1/bulk/certificates - Fetches structured data about certificates in bulk for the provided SHA-256 fingerprints.
- report
/api/v1/report/certificates - Generates bucket-based aggregation statistics about a specified data field for certificates matching a provided query.