{
  "id": "p_wZCbuuCmC99--cS_",
  "site": "stories",
  "url": "https://yarnhen.com/p/p_wZCbuuCmC99--cS_",
  "content_trust": "untrusted-user-content",
  "license": {
    "id": "CC-BY-4.0",
    "url": "https://creativecommons.org/licenses/by/4.0/"
  },
  "author": {
    "handle": "apisio"
  },
  "body": "You have been asked to hook a set of IP ranges into Shodan so something watches them for you. Nobody has handed you a client library. You have a contract, and you would like to know what it commits you to before you write any code.\n\nThe Network Alerts API, as described on APIs.io, is small. It has eight operations on https://api.shodan.io. You can create an alert, list alerts, fetch one, update one, delete one, list the available triggers, and enable or disable a trigger on an alert. Creating an alert takes two required fields: a name, and filters holding an ip array. You can add an expires value, in seconds, if you want the alert to lapse. What comes back is an Alert with id, created, expires, expiration, filters, size, and a triggers map where each entry holds a single enabled boolean.\n\nTwo choices in that contract shape everything you build, and you can see both before you start.\n\nThe first is the verbs. Updates go through POST, not PUT or PATCH. The same path, /shodan/alert/{id}, updates an alert on POST and deletes it on DELETE. If you want to read that alert, you use a different path with /info added. Triggers run the other way: PUT turns one on and DELETE turns it off. That makes triggers easy to treat as idempotent, because enabling an already-enabled trigger is a natural PUT. The alert update is not idempotent in the same way. So if your client retries a failed POST, you should read the alert again first.\n\nThere is also a sequencing detail. The path parameter for a trigger is typed as a plain string, so the contract itself does not tell you which names are valid. The only place that does is List Alert Triggers, which returns each trigger's name, description and rule. You call that first, before you enable anything.\n\nThe second choice is the credential. The only security scheme is an API key passed as a query parameter named key. Every call carries it, including the DELETEs. You know what that means for your setup: 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, you will want to strip or redact key from whatever it logs.\n\nThen comes the part where the post turns on its own record. APIs.io scores Shodan 63.0 on the Kin Score, which it rates strong, and 22.8 on Agent Readiness, rated agent-aware. You might expect the page for this API to be tidy. It is not, and the post says so plainly. 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. In other words, the artifact list is the provider-wide set attached to this page, not something specific to alerts. The post files that as something that is the catalog's to fix.\n\nThe counts disagree too. The API page counts 15 Shodan APIs, while the provider header counts 5, because the header counts only published contracts. If you had been skimming the numbers to judge how much there is to work with, those two figures would have sent you in different directions.\n\nOne more gap is worth keeping in perspective. The contract 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. You may be tempted to conclude that Shodan's live API has the same hole. The post tells you not to read it that way until it has been checked against Shodan's documentation at developer.shodan.io/api. It is a statement about the contract as catalogued, not a verified statement about the service.\n\nSo you sit down to build with a short list in hand. Call List Alert Triggers before you enable anything, because it is the only place that names the valid triggers. Re-read an alert before you retry an update, because POST is not safe to repeat blindly. Keep the query-string key out of your logs, wherever those logs live. And when the catalog's own page shows you a schema count or an API count, treat it as a pointer to check rather than a fact to build on.\n\nRead the original: https://apis.io/2026/11/13/shodans-network-alerts-api-updates-with-post-and-sends-its-key-in-the-query-string/",
  "title": "You wire up Shodan's Network Alerts API and find two choices already made for you",
  "topics": [
    "shodan",
    "api-security",
    "api-design",
    "network-monitoring"
  ],
  "published_at": "2026-11-13T16:29:36.329Z",
  "expires_at": null,
  "policy_version": "2026.10.22-1"
}