The Shodan Network Alerts API lets you name a set of IP ranges and ask Shodan to watch them. The contract for it is small: eight operations on https://api.shodan.io. Two choices in it shape every integration, and you can see both before you write a line of code. Updates go through POST, not PUT or PATCH. The only security scheme is an API key passed as a query parameter named key.
Shodan scores 63.0 on the Kin Score (strong) and 22.8 on Agent Readiness (agent-aware). The API page counts 15 Shodan APIs. The provider header counts 5, because it counts only published contracts.
What the API covers
| Operation | Method | Path |
|---|---|---|
| Create Network Alert | POST | /shodan/alert |
| List Network Alerts | GET | /shodan/alert/info |
| Get Network Alert | GET | /shodan/alert/{id}/info |
| Update Network Alert | POST | /shodan/alert/{id} |
| Delete Network Alert | DELETE | /shodan/alert/{id} |
| List Alert Triggers | GET | /shodan/alert/triggers |
| Enable Alert Trigger | PUT | /shodan/alert/{id}/trigger/{trigger} |
| Disable Alert Trigger | DELETE | /shodan/alert/{id}/trigger/{trigger} |
Creating an alert takes two required fields: name, and filters holding an ip array. An optional expires sets an expiration in seconds. The Alert schema that comes back carries id, created, expires, expiration, filters, size, and a triggers map whose entries hold a single enabled boolean.
The verbs are not where you expect them
The same path does different jobs depending on the verb. /shodan/alert/{id} updates on POST and deletes on DELETE, and reading that alert needs a different path with /info added. Triggers work the other way: PUT turns one on and DELETE turns it off. That makes triggers easy to treat as idempotent, since enabling an enabled trigger is a natural PUT. The alert update is not idempotent in the same way, so a client that retries a POST should re-read the alert first.
List Alert Triggers is the operation an agent needs first. It returns each trigger’s name, description and rule. It is the only place in the contract that lists which trigger names {trigger} accepts, because the path parameter is typed as a plain string.
What the key in the URL costs you
The apiKey scheme is declared in: query, name: key. Every call in this API, including the DELETEs, carries the credential in the URL. A URL ends up in proxy logs, gateway traces and browser history in a way a header does not. If you put a gateway or an agent tool layer in front of this API, strip or redact key from whatever it logs.
What is ours to fix
The page lists 10 JSON Schemas and calls the Network Alerts API “13 JSON Schema definitions.” Only one of those schemas, shodan-rest-alert-schema.json, is about alerts. The others describe hosts, scans, the stream banner, InternetDB and CVEDB, so the artifact list is the provider-wide set attached to this page. The contract also has no operation that connects an alert to a notifier. Alerts and the Notifiers API appear as two separate contracts with no link between them. Do not read that gap as a statement about Shodan’s live API until it is checked against the documentation.
Takeaway
Call List Alert Triggers before you enable anything. Re-read an alert before you retry an update. Keep the query-string key out of your logs. The contract is at apis.io/apis/shodan/shodan-network-alerts-api/.