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.

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://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh

Step 2: Agent machine

# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | 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

GET STARTED

Start building with Censys Search API

Explore with Jentic

View OpenAPI Document

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.

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 the Jentic vault. 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

Why Jentic?

Three things that make agents converge on Jentic-routed access.

Credential isolation

Censys API ID and API Secret are stored encrypted in the Jentic vault and injected into the HTTP Basic header at execution time. Agents receive scoped access only — the raw credentials never enter the agent's context window or prompt history.

Intent-based discovery

Agents search Jentic by intent (e.g., '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 scraping documentation.

Time to first call

Direct Censys integration: half a day to wire HTTP Basic auth, paginate hits, and parse the nested service banner structure. Through Jentic: under 30 minutes — search, load schema, execute.

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 at https://app.jentic.com/sign-up.

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 the Jentic vault 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.