{"openapi":"3.1.0","info":{"title":"Shodan (BYOK) API","version":"0.1.0","description":"Shodan (BYOK) lets an AI assistant read your own Shodan data through the Shodan API with a key you supply (Shodan API key). Read-only: 9 tools (get_host, search_hosts, count_hosts, list_ports, list_search_filters, list_search_facets, resolve_hostnames, reverse_dns, get_api_info). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-shodan.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-shodan/docs"},"termsOfService":"https://connectorbay.com/byok-shodan/terms"},"servers":[{"url":"https://byok-shodan.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-shodan/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_host":{"post":{"operationId":"get_host","summary":"Get what Shodan knows about one IP address: organization, ISP, ASN, location, hostnames, domains, open ports and tags. U","description":"Get what Shodan knows about one IP address: organization, ISP, ASN, location, hostnames, domains, open ports and tags. Use for \"What ports are open on 8.8.8.8 according to Shodan\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"ip":{"description":"IP address of the host, for example '8.8.8.8'.","maxLength":45,"title":"Ip","type":"string"},"history":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to also include historical banners (default false).","title":"History"},"minify":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to return only the general host information without the banners (default false).","title":"Minify"}},"required":["ip"],"title":"get_hostArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_hosts":{"post":{"operationId":"search_hosts","summary":"Search Shodan banners with a query such as 'apache country:DE'. Returns up to 100 matches per page with IP, port, produc","description":"Search Shodan banners with a query such as 'apache country:DE'. Returns up to 100 matches per page with IP, port, product, organization and location. A search that uses a filter, or goes past the first page, uses query credits of the plan. Use for \"Which Apache servers does Shodan list in Germany\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Shodan search query with optional filters, for example 'product:nginx country:US'.","maxLength":300,"title":"Query","type":"string"},"page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1; each page has up to 100 matches and pages after the first cost query credits.","title":"Page"},"minify":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"True to return a reduced banner per match (default true).","title":"Minify"}},"required":["query"],"title":"search_hostsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/count_hosts":{"post":{"operationId":"count_hosts","summary":"Count how many hosts match a Shodan search query without returning the results; this call does not use query credits. Us","description":"Count how many hosts match a Shodan search query without returning the results; this call does not use query credits. Use for \"How many hosts does Shodan list with product nginx\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Shodan search query, for example 'product:nginx'.","maxLength":300,"title":"Query","type":"string"},"facets":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Optional facets to summarize, for example 'country,org'. Use list_search_facets for names.","title":"Facets"}},"required":["query"],"title":"count_hostsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_ports":{"post":{"operationId":"list_ports","summary":"List the port numbers that Shodan's crawlers check. Use for \"Which ports does Shodan crawl\".","description":"List the port numbers that Shodan's crawlers check. Use for \"Which ports does Shodan crawl\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_portsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_search_filters":{"post":{"operationId":"list_search_filters","summary":"List the filter names that can be used in a Shodan search query, such as country, org or port. Use for \"Which search fil","description":"List the filter names that can be used in a Shodan search query, such as country, org or port. Use for \"Which search filters does Shodan support\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_search_filtersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_search_facets":{"post":{"operationId":"list_search_facets","summary":"List the facet names usable in Shodan counts and searches, such as country or org. Use for \"Which facets can I use in a ","description":"List the facet names usable in Shodan counts and searches, such as country or org. Use for \"Which facets can I use in a Shodan count\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_search_facetsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/resolve_hostnames":{"post":{"operationId":"resolve_hostnames","summary":"Look up the IP addresses of one or more hostnames using Shodan's DNS resolver. Use for \"What are the IP addresses of goo","description":"Look up the IP addresses of one or more hostnames using Shodan's DNS resolver. Use for \"What are the IP addresses of google.com and bing.com\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"hostnames":{"description":"Comma-separated hostnames, for example 'google.com,bing.com'.","maxLength":500,"title":"Hostnames","type":"string"}},"required":["hostnames"],"title":"resolve_hostnamesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/reverse_dns":{"post":{"operationId":"reverse_dns","summary":"Look up the hostnames that Shodan has for one or more IP addresses. Use for \"What hostnames belong to 8.8.8.8\".","description":"Look up the hostnames that Shodan has for one or more IP addresses. Use for \"What hostnames belong to 8.8.8.8\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"ips":{"description":"Comma-separated IP addresses, for example '8.8.8.8,1.1.1.1'.","maxLength":500,"title":"Ips","type":"string"}},"required":["ips"],"title":"reverse_dnsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_api_info":{"post":{"operationId":"get_api_info","summary":"Show the plan and remaining credits of the Shodan API key. Use for \"How many Shodan query credits do I have left\".","description":"Show the plan and remaining credits of the Shodan API key. Use for \"How many Shodan query credits do I have left\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_api_infoArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}