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.

Connecting

All API endpoints are hosted at https://censys.io/api/v1/ and require authenticating with HTTP basic auth using the API ID and secret that are shown under My Account. This page also lists the rate limits that apply to your account.

API Endpoints

We provide the following API endpoints:

search
The search endpoint allows searches against the IPv4, Alexa Top Million, and Certificates indexes using the same search syntax as the main site. The endpoint returns a paginated result of the most recent information we know for the set of user selected fields. More information about the returned hosts, websites, and certificates can be fetched using the /view endpoint.
view
The view endpoint fetches the structured data we have about a specific host, website, or certificate once you know the host's IP address, website's domain, or certificate's SHA-256 fingerprint.
bulk
The bulk endpoint fetches the structured data we have about certificates in bulk, once you know the certificate's SHA-256 fingerprints.
report
The report endpoint allows you to determine the aggregate breakdown of a value for the results a query, similar to the "Build Report" functionality available in the primary search interface. For example, if you wanted to determine the breakdown of cipher suites selected by all websites in the Top Million.
data
The data endpoint exposes metadata on raw data that can be downloaded from Censys. For example, if you wanted to determine whether a new dataset has been posted in a given series and how to download it.
account
The account endpoint returns information about your Censys account, most notably including your current query quota usage.

Examples

REST Access. Below is a sample cURL script that connects to the REST API and performs a search on Hosts. We also maintain a Postman Collection.

    
CURL
curl 'https://censys.io/api/v2/hosts/search?q=service.service_name:%20HTTP' -u LOGIN_FOR_API_ID:LOGIN_FOR_API_SECRET | jq
# or if you want CURL to urlencode your query
curl -G 'https://censys.io/api/v2/hosts/search' --data-urlencode 'q=service.service_name: HTTP' -u LOGIN_FOR_API_ID:LOGIN_FOR_API_SECRET | jq

WGET
# Automatically encodes query
wget -qO- --auth-no-challenge 'https://censys.io/api/v2/hosts/search?q=service.service_name: HTTP' --user=LOGIN_FOR_API_ID --password=LOGIN_FOR_API_SECRET | jq
    
  

REST Access (Raw Data). Below is a sample Python script that connects to the API and lists raw datasets that are available for download.

    
import requests 

UID = "LOGIN_FOR_API_ID"
SECRET = "LOGIN_FOR_API_SECRET"

res = requests.get("https://censys.io/api/v1/data", auth=(UID, SECRET))
if res.status_code != 200:
    print("error occurred: %s" % res.json()["error"])
    exit()
for name, series in res.json()["raw_series"].items():
    print(series["name"], "was last updated at", series["latest_result"]["timestamp"])
    
  

Censys Python Library. We also maintain a Python library for interacting with the API. The package can be installed with pip pip install censys. For more extensive documentation see our docs. For more examples see our examples. Below is a sample script that iterates over NSS trusted certificates:

    
from censys.search import CensysCertificates

c = CensysCertificates(
  api_id="LOGIN_FOR_API_ID",
  api_secret="LOGIN_FOR_API_SECRET"
)

fields = ["parsed.subject_dn", "parsed.fingerprint_sha256", "parsed.fingerprint_sha1"]

for cert in c.search("validation.nss.valid: true", fields, max_records=5):
    print(cert["parsed.subject_dn"])
    
  

Censys NodeJS Library. We also maintain a NodeJS library for interacting with the API. This package can be installed with npm npm install @censys/node or yarn yarn add @censys/node. For more examples see our examples.

    
const { SearchClient } = require("@censys/node");

const c = new SearchClient({
  apiId: "LOGIN_FOR_API_ID",
  apiSecret: "LOGIN_FOR_API_SECRET",
});

let fields = ["parsed.subject_dn", "parsed.fingerprint_sha256", "parsed.fingerprint_sha1"]

// Single page of search results
let query = c.v1.certificates.search("validation.nss.valid: true", fields)
query.next().then((page) => console.log(page.value));