canonical: https://jentic.com/apis/censys.io/censys

# Censys Search API

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.

## For AI agents

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

## Scope

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

## Capabilities

- 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
- Aggregate host or certificate fields to count distributions across the dataset
- Resolve all forward and reverse DNS names associated with a host
- Read account quota and credits remaining for the current API ID

## Use cases

### 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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

| 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 |

## Key resources

- **Hosts** — Search, view, diff, aggregate, and resolve names for IPv4 hosts in the Censys index
- **Certificates** — Search certificates by query, retrieve full parsed certificates by SHA-256 fingerprint, and aggregate certificate fields
- **Account** — Read API quota and credit balance for the authenticated API ID
- **Metadata** — Read dataset-level metadata such as the most recent host snapshot timestamp

## Why Jentic

- **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 handling:** 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.
- **Discovery method:** 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.

## Related APIs

- **Shodan API** — Internet-wide host search engine with similar coverage of exposed services and banners
- **MISP API** — Open-source threat intelligence platform for sharing IOCs and event data
- **AbuseIPDB API** — Community-reported abuse and confidence scores for IP addresses

## FAQ

### 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.