// developer reference

API DOCS

Every endpoint requires a Bearer token — generate one on /api-keys. Tokens have a lifetime quota (default 1,000 calls). Each successful (2xx/3xx) call decrements it; auth/validation failures don't burn quota.

Getting started

Sign up on /api-keys (email + password).
Click create token and copy the plaintext token — shown only once.
Store it in an env var, e.g. export ECHO_TOKEN=echo_....
Call any endpoint with Authorization: Bearer $ECHO_TOKEN.

Auth quick reference

200 OKSuccessful call. quota_used += 1.

401 UnauthorizedMissing or invalid Bearer. Quota not touched.

402 Payment RequiredQuota exhausted. Contact admin to raise.

429 Too Many RequestsNot currently enforced. Reserved for future rate limiting.

Endpoints

GET/api/v1/echo/tags

Global tag popularity — every behavior/event tag currently attached to an actor, with actor counts.

curl -H "Authorization: Bearer $ECHO_TOKEN" \
  https://echo.ironcatlabs.com/api/v1/echo/tags

GET/api/v1/echo/tags/{tag}/related

For a given tag, the top co-occurring tags on the same actors.

curl -H "Authorization: Bearer $ECHO_TOKEN" \
  https://echo.ironcatlabs.com/api/v1/echo/tags/ssh.bruteforce/related

GET/api/v1/echo/feed/{tag}.json

IP list for one behavior tag. `.txt` and `.csv` also supported.

// Cache TTL is 15 minutes; safe to poll hourly.

curl -H "Authorization: Bearer $ECHO_TOKEN" \
  https://echo.ironcatlabs.com/api/v1/echo/feed/ssh.bruteforce.json

GET/api/v1/echo/ip/{ip}

Full profile for one IP — geo, ASN, tags, stats, recent events.

// Cache TTL is 60 seconds — the freshest of any Echo endpoint.

curl -H "Authorization: Bearer $ECHO_TOKEN" \
  https://echo.ironcatlabs.com/api/v1/echo/ip/1.2.3.4

GET/api/v1/echo/world

Per-country attack volume rollup. Good for choropleth-style views.

curl -H "Authorization: Bearer $ECHO_TOKEN" \
  https://echo.ironcatlabs.com/api/v1/echo/world

GET/api/v1/echo/scan-targets

Top 100 probed URIs. What paths are attackers looking for right now.

curl -H "Authorization: Bearer $ECHO_TOKEN" \
  https://echo.ironcatlabs.com/api/v1/echo/scan-targets

GET/api/v1/echo/top-uas

Top non-browser user-agents seen. Handy for spotting new scanner defaults.

curl -H "Authorization: Bearer $ECHO_TOKEN" \
  https://echo.ironcatlabs.com/api/v1/echo/top-uas

GET/api/v1/echo/asns

Top 50 hosting/ISP networks by attacker count.

curl -H "Authorization: Bearer $ECHO_TOKEN" \
  https://echo.ironcatlabs.com/api/v1/echo/asns

GET/api/v1/echo/wordlists/{file}

SSH username wordlists — what usernames attackers are trying most.

// `{file}` is `ssh-usernames.txt` today.

curl -H "Authorization: Bearer $ECHO_TOKEN" \
  https://echo.ironcatlabs.com/api/v1/echo/wordlists/ssh-usernames.txt