Censys Search API

Name: Censys Search API
Brand: Censys Search API
Availability: InStock

★ Only Publicly Available OpenAPI DocumentSecurityThreat Detectionbasic10 EndpointsREST

For Agents

Search internet-wide host and certificate data, look up specific IPs and TLS fingerprints, and aggregate exposure metrics for security and reconnaissance workflows.

Use for: I need to look up which services are exposed on a specific IP address, Search for hosts running a particular software version across the internet, Find all certificates issued to a given organization name, Check whether a host has gained any new open ports in the last week

Not supported: Does not perform active port scanning, vulnerability exploitation, or malware analysis - use for querying Censys's pre-collected host and certificate index only.

Jentic publishes the only available OpenAPI specification for Censys Search API, keeping it validated and agent-ready. Censys Search API provides programmatic access to a continuously updated index of internet-facing hosts, services, and X.509 certificates. Agents can query hosts by IP, search across the global host dataset with structured queries, aggregate results, diff host state over time, and look up TLS certificates by SHA-256 fingerprint. The API is designed for attack-surface discovery, threat research, and infrastructure auditing rather than active scanning.

Jentic One on Github

Install Jentic One Beta

Connect the Censys Search API to your agent

Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Censys Search API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.

Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.

Step 1: Jentic One Host machine

# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fcensys.io%2Fcensys" | sh

Step 2: Agent machine

# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fcensys.io%2Fcensys" | sh
jentic register       # connects your agent to your Jentic One instance

Jentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.

Capabilities

What an agent can do with Censys Search API.

Search Censys host index by structured query and paginate through matching IPs

Retrieve full service banners and metadata for a specific host by IP address

Diff a host's exposed services between two timestamps to detect new ports or software changes

Look up X.509 certificates by SHA-256 fingerprint and inspect chain and validity data

GET STARTED

Start building with Censys Search API

Explore with Jentic One

View OpenAPI Document

Use Cases

Patterns agents use Censys Search API for, with concrete tasks.

★ Attack Surface Discovery

Map the externally exposed assets belonging to an organization by querying Censys for hosts that present the company's certificates, autonomous systems, or domain names. The /v2/hosts/search endpoint returns matching IPs with full service banners, and /v2/hosts/aggregate breaks the result down by port, software, or geography. Useful for security teams who need a continuously updated inventory of internet-facing infrastructure without running their own scanners.

Search /v2/hosts/search for hosts whose certificate names match acme.com, then aggregate results by service.service_name to produce a port distribution

Certificate Transparency Lookup

Investigate a TLS certificate by its SHA-256 fingerprint to retrieve issuer, validity period, subject names, and the chain of trust. The /v2/certificates/{fingerprint} endpoint returns parsed certificate fields, and /v2/certificates/search lets analysts find every certificate matching a given SAN or issuer. Used during phishing investigations, supply-chain incident response, and CT log triage.

Call GET /v2/certificates/{fingerprint} for a suspicious certificate hash and extract the parsed.subject.common_name and parsed.validity fields

Host Change Monitoring

Detect when an internet-facing host has changed by comparing two snapshots of its services. The /v2/hosts/{ip}/diff endpoint returns the exact services, ports, and banners that were added, removed, or modified between observations. Security operations teams use this to flag rogue listeners, unexpected software upgrades, or signs of compromise on monitored infrastructure.

Call GET /v2/hosts/{ip}/diff with at_time set to seven days ago and report any services added since

AI Agent Threat Triage via Jentic

An incident response agent receives an alert containing an IP address or certificate hash and needs structured context fast. Through Jentic, the agent searches for an operation by intent, loads the Censys input schema, and calls /v2/hosts/{ip} or /v2/certificates/{fingerprint} with credentials drawn from your Jentic One instance. The agent returns parsed service and certificate data without the developer hand-coding HTTP basic auth or response parsing.

Use Jentic to search 'look up host details for an IP', load the censys host operation, and call it for IP 8.8.8.8 returning the services list

Key Endpoints

10 endpoints — jentic publishes the only available openapi specification for censys search api, keeping it validated and agent-ready.

METHOD

PATH

DESCRIPTION

GET

/v2/hosts/search

Search the host index by query

GET

/v2/hosts/{ip}

View a single host by IP

GET

/v2/hosts/{ip}/diff

Diff a host between two snapshots

GET

/v2/hosts/aggregate

Aggregate host fields across results

GET

/v2/certificates/{fingerprint}

View a certificate by SHA-256 fingerprint

GET

/v2/certificates/search

Search certificates by query

GET

/v1/account

Read account quota and credits

GET

/v2/hosts/search

Search the host index by query

GET

/v2/hosts/{ip}

View a single host by IP

GET

/v2/hosts/{ip}/diff

Diff a host between two snapshots

GET

/v2/hosts/aggregate

Aggregate host fields across results

GET

/v2/certificates/{fingerprint}

View a certificate by SHA-256 fingerprint

GET

/v2/certificates/search

Search certificates by query

GET

/v1/account

Read account quota and credits

Why Jentic?

What agents get from Jentic-routed access to this vendor.

Setup

Wiring the Censys Search API by hand means handling HTTP basic auth with your API ID as username and secret as password, and building the host and certificate query parameters yourself. Through Jentic you install once, import Censys Search from the API Directory, store the credentials once, and your agent calls it.

Permission scoping

Censys puts the host IP and certificate fingerprint in the URL path for operations like /v2/hosts/{ip} and /v2/certificates/{fingerprint}, so a rule can pin your agent to lookups for one host or certificate. The API is read-only over Censys's pre-collected index, and you choose which search operations it may call.

Credential isolation

Your Censys API ID and secret are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.

Intent-based discovery

Agents search Jentic by intent such as 'look up a host by IP' or 'search certificates by issuer', and Jentic returns the matching Censys operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

FAQs

Specific to using Censys Search API through Jentic.

Why is there no official OpenAPI spec for Censys Search API?

Censys does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Censys Search API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

What authentication does the Censys Search API use?

The API uses HTTP Basic authentication where the username is your Censys API ID and the password is your API Secret, both issued from the Censys account console. Through Jentic, these credentials live in your Jentic One instance and are injected at execution time so the API ID and Secret never enter the agent's prompt or context.

Can I search for all hosts running a specific software version with the Censys Search API?

Yes. Call GET /v2/hosts/search with a structured query such as services.software.product:"nginx" and services.software.version:"1.18.0". The response includes paginated hits with full service banners, and you can pass the same query to /v2/hosts/aggregate to see counts grouped by any field.

What are the rate limits for the Censys Search API?

Censys enforces per-account quotas measured in queries per month rather than fixed requests per second; the exact ceiling depends on the plan attached to your API ID. Call GET /v1/account to read your remaining credits and quota reset date before scheduling large aggregations.

How do I look up a certificate by fingerprint with the Censys Search API through Jentic?

Search Jentic for 'look up a tls certificate by fingerprint', load the operation backed by GET /v2/certificates/{fingerprint}, and execute it with the SHA-256 hash. Jentic returns the parsed certificate including issuer, validity, and subject alternative names without any manual HTTP basic auth setup.

Does the Censys Search API let me detect when a host changes?

Yes. GET /v2/hosts/{ip}/diff compares two snapshots of a host and returns the services, ports, and banners that were added, removed, or modified between them. This is the supported way to monitor internet-facing infrastructure for new listeners or software upgrades without polling the full host record.

Can I limit what my agent is allowed to do with the Censys Search API?

Yes. Because you run Jentic One yourself, your own rules decide which Censys operations the agent may call and which stored credentials it may use. Since Censys puts the host IP and certificate fingerprint in the URL path for operations like /v2/hosts/{ip} and /v2/certificates/{fingerprint}, you can pin the agent to lookups for a single host or certificate, and because the API is read-only over Censys's pre-collected index you can also restrict it to specific search operations such as /v2/hosts/search or /v2/certificates/search. Your API ID and secret stay in your own instance and are injected only at execution time.