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.

Other

data
/api/v1/data
Provides metadata on raw data that can be downloaded from Censys.
account
/api/v1/account
Returns information about your Censys Search account, most notably query quota: usage, allowance, and reset date.