1. Censys
  2. Censys Search
  3. Upgrading to Censys Search 2.0

Other Articles In This Section

In this article:

Three Changes You Need to Make for Search 2.0 API

  • Updated

I’m a Censys Search API user, and I want to upgrade to Search 2.0.

If this is you, here are the three changes you need to make to your API client in order to begin querying hosts in the all new Censys Search 2.0.

1. Update API Endpoints

Host search and lookup has moved to a new URL with new paths and HTTP methods.

  • Method: GET

  • Base URL: https://search.censys.io.

  • Path: /api/v2/hosts

  • Endpoints:

    • /search — Search for hosts by submitting a query using the new Censys Search Language.

    • /{ip-address} — Look up a host by its IP address.

    • /{ip-address}/names — Retrieve a list of domain-style names that a host responded to during a Censys scan.

    • /aggregate — See a breakdown of hosts (that match a provided search query) according to their values for a field that you select.

Visit the Censys Search 2.0 API documentation for details on each endpoint.

2. Update Search Queries

In order to translate search queries used on Censys' legacy host dataset to work in Search 2.0, you must change field names to reflect the new, improved host schema and adjust syntax to use the more powerful Censys Search Language.

Schema Changes

Host data is now modeled to reflect improvements in Censys scanning technology, so the name of almost every field you formerly queried has changed, although keys still use dot notation to show their nested structure (e.g., services.http.response.body).

For more information, you can read about the host data model or see some example queries translated, or just browse the entire schema.

Query Syntax

Search 2.0 also utilizes a new Censys Search Language. Read this introduction to learn how to:

  • Specify fields

  • Write queries that account for port-independent data

  • Use wildcards

  • Limit results to exact matches

  • Leverage boolean operators like and, or and not

3. Update Behavior to Perform Lookups on Search Hits

Unlike the v1 Search API endpoint, the 2.0 hosts/search API endpoint does not accept a list of host fields to return as part of the response.

Instead, a static preview of each host matching the provided query is returned.

Your client must iterate through the results returned by the hosts/search endpoint with calls to the hosts/{ip-address} endpoint to extract all fields of interest.

Note
 Search 2.0 query quotas and rate limits have been increased to account for this behavior change. You can see the rate limits that apply to your account here.

Questions? Reach out to support@censys.io!

Related articles

Comments

0 comments

Please sign in to leave a comment.