API & query reference

The tttx API is free — unlike Shodan. Sign up for a key (1,000 requests/day). The same query language powers the site search box and the API.

Authentication

Send your key in the X-API-Key header (recommended) or as ?key=. Only the /api/v1/* endpoints require a key.

curl -H "X-API-Key: YOUR_KEY" "https://tttx.net/api/v1/host?ip=154.59.103.7"
curl "https://tttx.net/api/v1/search?q=product:nginx&key=YOUR_KEY"

Endpoints

Endpoints tagged Pro require a Pro key — "AI testing & mitigation". They call our local models, so a response can take a few seconds to a minute.

URL-encode spaces in q as + or %20 (e.g. q=product:nginx+port:443).

Query filters

A query is space-separated tokens. key:value tokens filter; bare words are full-text (matched against banners, page titles, product and AS names). An IP/CIDR bare token filters by address.

Tags & page-type labels

Every service carries a tags array (fast, keyword-exact — use with tag:) and, if a screenshot was captured, a page-type label from the vision/OCR classifier (use with label:"…", quoting multi-word values). Hunt for interesting surfaces like this:

The short page-type tag:s are set from the OCR text during an OCR pass, so they cover image/JS-rendered pages the DOM classifier misses. tag:login and label:"login page" overlap; the tag is quicker to type, the label is exact.

Combining filters & gotchas

Tokens combine with AND at the service level. Because each open port is its own record, filters that describe a single service combine naturally:

product:nginx port:443 country:US has_vuln:true

But two port: filters describe two different services, so port:22 port:443 matches nothing (no single record is both). To require a host to have several ports open, use ports_all::

# WRONG — matches nothing:
port:22 port:443
# RIGHT — hosts with BOTH 22 and 443 open:
ports_all:22,443

Vector search (visual & semantic)

The keyword filters above match exact values. Vector search matches by similarity instead — "show me pages that look like this" and "find pages that mean this", even when they share no keywords. It's backed by two embeddings we compute per host from its screenshot:

Both are indexed as OpenSearch knn_vector fields (HNSW, cosine). Nearest-neighbour lookups are ranked by cosine similarity, returned per result as similarity (1.0 = identical).

Visual similarity — /api/similar

Give it a seed ip; it returns the hosts whose screenshots are closest to that host's. No text needed — this finds the same login portal, appliance UI, or phishing-kit template deployed across many IPs, including ones with no shared banner or certificate. In the web UI, open any host and click “Similar pages”.

# Every host whose page looks like this one
curl "https://tttx.net/api/similar?ip=203.0.113.10"
# …but only German hosts on 443
curl "https://tttx.net/api/similar?ip=203.0.113.10&q=country:DE+port:443"

Semantic search — /api/semantic

Give it a natural-language q; we embed your phrase with the same model that produced text_vec, then return the hosts whose page text is closest in meaning. So database admin control panel surfaces phpMyAdmin, Adminer and Odoo logins even when the page never uses those words. In the web UI, prefix the search box with ~:

~wordpress login page
~industrial control system HMI
~parked domain for sale

# Pages that mean "remote desktop gateway", German only
curl "https://tttx.net/api/semantic?q=remote+desktop+gateway&and=country:DE"

Coverage. A host is only returned once its screenshot has been vectorised (an ongoing backfill over ~42k thumbnails). Hosts without a screenshot — or not yet processed — won't appear. Visual results need screenshot_vec; semantic results need text_vec, which exists only when the page had a title/OCR text/banner to embed.

Similarity vs. filters. kNN returns a fixed top-k ranked by closeness, not a filtered set — so there are no facets or deep pagination, and a low-scoring tail is expected. Combine with structured filters (q/and) to keep the neighbour pool tight.

Worked examples

# One host, everything we know about it
curl -H "X-API-Key: KEY" "https://tttx.net/api/v1/host?ip=154.59.103.7"

# nginx on 443 in the United States
curl -H "X-API-Key: KEY" "https://tttx.net/api/v1/search?q=product:nginx+port:443+country:US"

# Hosts exposing SSH and RDP (jump boxes)
curl -H "X-API-Key: KEY" "https://tttx.net/api/v1/search?q=ports_all:22,3389"

# Anything on the common web ports OR a high range
curl -H "X-API-Key: KEY" "https://tttx.net/api/v1/search?q=port:80,443,8080,8000-8100"

# Critical vulnerabilities (CVSS >= 9)
curl -H "X-API-Key: KEY" "https://tttx.net/api/v1/search?q=has_vuln:true+cvss:>=9"

# Exposed control-panel / admin login pages (no auth in front of them)
curl -H "X-API-Key: KEY" "https://tttx.net/api/v1/search?q=tag:control-panel"
curl -H "X-API-Key: KEY" "https://tttx.net/api/v1/search?q=label:%22login+page%22"

# Internet-facing cameras / IoT device UIs
curl -H "X-API-Key: KEY" "https://tttx.net/api/v1/search?q=tag:iot-camera"

# Open directory listings on TLS in the US
curl -H "X-API-Key: KEY" "https://tttx.net/api/v1/search?q=tag:dir-listing+has_ssl:true+country:US"

# Unauthenticated databases exposed to the internet
curl -H "X-API-Key: KEY" "https://tttx.net/api/v1/search?q=no_auth:true"

# Expired certs on one operator's network
curl -H "X-API-Key: KEY" "https://tttx.net/api/v1/search?q=asn:7018+expired:true"

# Page 2 of a result set
curl -H "X-API-Key: KEY" "https://tttx.net/api/v1/search?q=product:apache&page=1"

Limits & errors

• Quota: 1,000 requests/day per key (resets at UTC midnight).
• 401 — missing/invalid/revoked key.
• 429 — daily quota exceeded (response includes daily_quota).
• 400 — bad parameter (e.g. malformed ip).
• ports_all: is resolved via an aggregation and capped at 10,000 matching hosts.
• Opted-out ranges are excluded from all public results.

Machine-readable spec

An OpenAPI 3.0 document describes every endpoint, parameter, and response schema. It's served with CORS, so you can point Swagger UI, Redoc, Postman, or a client generator straight at it. The query filters are also enumerated under the q parameter's x-tttx-filters extension.

# Fetch the spec
curl "https://tttx.net/api/openapi.json"

# Generate a typed client (example)
openapi-generator-cli generate -i https://tttx.net/api/openapi.json -g python -o ./tttx-client

View openapi.json

Questions or abuse reports: abuse@tttx.net.