# ZoomEye.ai Full Agent Reference

This file is the expanded machine-readable reference for agents integrating with ZoomEye.ai.

## Discovery

- Primary LLM guide: `https://www.zoomeye.ai/llms.txt`
- OpenAPI JSON: `https://www.zoomeye.ai/openapi.json`
- OpenAPI YAML: `https://www.zoomeye.ai/openapi.yaml`
- API catalog: `https://www.zoomeye.ai/.well-known/api-catalog`
- Agent skills index: `https://www.zoomeye.ai/.well-known/agent-skills/index.json`
- MCP server metadata: `https://www.zoomeye.ai/.well-known/mcp/server.json`
- MCP server card: `https://www.zoomeye.ai/.well-known/mcp/server-card.json`
- WebMCP metadata: `https://www.zoomeye.ai/.well-known/webmcp`

## Authentication

Use a ZoomEye API-KEY in the `API-KEY` HTTP header.

```bash
curl -X POST https://api.zoomeye.ai/v2/userinfo -H "API-KEY: $YOUR_API_KEY"
```

## Endpoints

### POST /v2/userinfo

Returns user profile, subscription, and remaining quota information.

```bash
curl -X POST https://api.zoomeye.ai/v2/userinfo -H "API-KEY: $YOUR_API_KEY"
```

### POST /v2/search

Searches global network assets. The `qbase64` field is the base64-encoded ZoomEye dork query.

```bash
echo 'title="nginx"' | base64
curl -X POST https://api.zoomeye.ai/v2/search \
  -H "API-KEY: $YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"qbase64":"dGl0bGU9Im5naW54Igo=","page":1}'
```

### GET /v2/vuldb/{id}

Returns vulnerability details by CVE or vulnerability id.

```bash
curl -X GET https://api.zoomeye.ai/v2/vuldb/CVE-2023-46747 -H "API-KEY: $YOUR_API_KEY"
```

### GET /v2/search/vuldb

Searches vulnerability records.

```bash
curl -X GET 'https://api.zoomeye.ai/v2/search/vuldb?search=tongda' -H "API-KEY: $YOUR_API_KEY"
```

### POST /v2/bugbounty

Searches bug bounty program assets.

```bash
curl -X POST https://api.zoomeye.ai/v2/bugbounty \
  -H "API-KEY: $YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"qbase64":"YXBwPSJHaXRMYWIi","page":1}'
```

## Search Syntax

- `=` fuzzy match: `title="knownsec"`
- `==` exact match: `title=="knownsec"`
- `||` logical OR: `service="ssh" || service="http"`
- `&&` logical AND: `device="router" && after="2020-01-01"`
- `!=` logical NOT: `country="US" && subdivisions!="new york"`
- `()` priority grouping: `(country="US" && port!=80) || (country="JP" && service="ssh")`
- `*` wildcard: `title="google*"`

## Search Fields

Device and service: `app`, `service`, `device`, `os`, `title`, `industry`, `product`, `protocol`, `is_honeypot`.

Network identity: `ip`, `cidr`, `org`, `isp`, `asn`, `port`, `hostname`, `domain`.

Geography: `country`, `subdivisions`, `city`.

SSL/TLS: `ssl`, `ssl.cert.fingerprint`, `ssl.chain_count`, `ssl.cert.alg`, `ssl.cert.issuer.cn`, `ssl.cert.subject.cn`, `ssl.cert.pubkey.rsa.bits`, `ssl.cert.pubkey.ecdsa.bits`, `ssl.cert.pubkey.type`, `ssl.cert.serial`, `ssl.cipher.bits`, `ssl.cipher.name`, `ssl.cipher.version`, `ssl.version`, `ssl.jarm`, `ssl.ja3s`.

HTTP: `http.header`, `http.header_hash`, `http.header.server`, `http.header.version`, `http.header.status_code`, `http.body`, `http.body_hash`.

Other: `banner`, `iconhash`, `filehash`, `dig`, `after`, `before`, `vul.cve`, `is_bugbounty`, `bugbounty.source`, `is_changed`, `is_new`.

## Agent Usage Examples

Find public SSH in the United States:

```text
country="US" && service="ssh"
```

Find Log4j-affected assets:

```text
vul.cve="CVE-2021-44228"
```

Find bug bounty GitLab assets:

```text
is_bugbounty=true && app="GitLab"
```

Find assets newly discovered in the last 7 days:

```text
is_new=true && service="redis"
```

## Response Pattern

Successful API responses use:

```json
{
  "code": 60000,
  "message": "success",
  "data": {}
}
```

Agents should treat non-`60000` responses as errors, inspect `message`, and retry only on transient failures.