openapi: 3.1.0
info:
  title: Shodan REST API
  description: >-
    The Shodan REST API exposes search methods, host lookups, on-demand
    scanning, network alerts, notifiers, the saved-query directory, DNS
    lookups, utility methods, account/profile information, bulk data, and
    organization management for the Shodan search engine for Internet-
    connected devices.
  version: '1.0'
  contact:
    name: Shodan Support
    email: support@shodan.io
    url: https://developer.shodan.io/
  license:
    name: Shodan API Terms of Service
    url: https://www.shodan.io/legal/tos
servers:
  - url: https://api.shodan.io
    description: Production
security:
  - apiKey: []
tags:
  - name: Search Methods
    description: Search and lookup endpoints for indexed devices.
  - name: On-Demand Scanning
    description: Request crawls of specific IPs, netblocks, or the entire Internet.
  - name: Network Alerts
    description: Create and manage alerts on monitored IP ranges.
  - name: Notifiers
    description: Manage notification providers used by alerts.
  - name: Directory
    description: Browse and search saved Shodan queries.
  - name: Bulk Data
    description: Enterprise bulk data exports.
  - name: DNS
    description: Forward, reverse, and domain DNS lookups.
  - name: Utility
    description: Helper endpoints for HTTP headers and IP detection.
  - name: Account
    description: Account, profile, and API plan information.
  - name: Organization
    description: Enterprise organization management.
paths:
  /shodan/host/{ip}:
    get:
      tags: [Search Methods]
      summary: Get Host Information
      operationId: getHost
      description: Returns all services that have been found on the given host IP.
      parameters:
        - $ref: '#/components/parameters/IpPath'
        - name: history
          in: query
          schema: { type: boolean, default: false }
          description: Include historical banners.
        - name: minify
          in: query
          schema: { type: boolean, default: false }
          description: Return a truncated banner record.
      responses:
        '200':
          description: Host record with banners.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Host' }
        '404': { $ref: '#/components/responses/NotFound' }
  /shodan/host/count:
    get:
      tags: [Search Methods]
      summary: Get Search Result Count
      operationId: getHostCount
      description: Returns the number of results a search would have, without consuming query credits or returning results.
      parameters:
        - $ref: '#/components/parameters/Query'
        - $ref: '#/components/parameters/Facets'
      responses:
        '200':
          description: Count and facet summary.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SearchCount' }
  /shodan/host/search:
    get:
      tags: [Search Methods]
      summary: Search Shodan
      operationId: searchHosts
      description: Search Shodan using the same query syntax as the website. Uses one query credit per page after the first when filters are used.
      parameters:
        - $ref: '#/components/parameters/Query'
        - $ref: '#/components/parameters/Facets'
        - name: page
          in: query
          schema: { type: integer, default: 1, minimum: 1 }
        - name: minify
          in: query
          schema: { type: boolean, default: true }
      responses:
        '200':
          description: Search results with matches and facets.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SearchResult' }
  /shodan/host/search/facets:
    get:
      tags: [Search Methods]
      summary: List Search Facets
      operationId: listSearchFacets
      description: Returns the list of facets that can be used to summarize search results.
      responses:
        '200':
          description: Array of facet names.
          content:
            application/json:
              schema: { type: array, items: { type: string } }
  /shodan/host/search/filters:
    get:
      tags: [Search Methods]
      summary: List Search Filters
      operationId: listSearchFilters
      description: Returns the list of filters that can be used when searching.
      responses:
        '200':
          description: Array of filter names.
          content:
            application/json:
              schema: { type: array, items: { type: string } }
  /shodan/host/search/tokens:
    get:
      tags: [Search Methods]
      summary: Break Query Into Tokens
      operationId: tokenizeSearchQuery
      description: Determine which filters and tokens make up a search query.
      parameters:
        - $ref: '#/components/parameters/Query'
      responses:
        '200':
          description: Parsed token structure.
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
  /shodan/ports:
    get:
      tags: [On-Demand Scanning]
      summary: List Crawled Ports
      operationId: listPorts
      description: Returns the list of port numbers that Shodan is crawling on the Internet.
      responses:
        '200':
          description: Array of port numbers.
          content:
            application/json:
              schema: { type: array, items: { type: integer } }
  /shodan/protocols:
    get:
      tags: [On-Demand Scanning]
      summary: List Supported Protocols
      operationId: listProtocols
      description: Returns the list of protocols that can be used when launching an on-demand Internet scan.
      responses:
        '200':
          description: Map of protocol slug to human-readable name.
          content:
            application/json:
              schema: { type: object, additionalProperties: { type: string } }
  /shodan/scan:
    post:
      tags: [On-Demand Scanning]
      summary: Submit On-Demand Scan
      operationId: createScan
      description: Request Shodan to crawl an IP or netblock. Each IP consumes one scan credit.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [ips]
              properties:
                ips:
                  type: string
                  description: Comma-separated list of IPs or CIDR ranges.
      responses:
        '200':
          description: Scan submission confirmation.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Scan' }
  /shodan/scan/internet:
    post:
      tags: [On-Demand Scanning]
      summary: Scan Internet For Port
      operationId: createInternetScan
      description: Request Shodan to crawl the Internet for a specific port and protocol. Enterprise only.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [port, protocol]
              properties:
                port:
                  type: integer
                protocol:
                  type: string
      responses:
        '200':
          description: Internet scan submission confirmation.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Scan' }
  /shodan/scans:
    get:
      tags: [On-Demand Scanning]
      summary: List On-Demand Scans
      operationId: listScans
      description: Returns the list of on-demand scans submitted by the account.
      responses:
        '200':
          description: Paginated list of scans.
          content:
            application/json:
              schema:
                type: object
                properties:
                  matches:
                    type: array
                    items: { $ref: '#/components/schemas/Scan' }
                  total: { type: integer }
  /shodan/scan/{id}:
    get:
      tags: [On-Demand Scanning]
      summary: Get Scan Status
      operationId: getScan
      description: Returns the status and progress of an on-demand scan.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Scan status.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Scan' }
        '404': { $ref: '#/components/responses/NotFound' }
  /shodan/alert:
    post:
      tags: [Network Alerts]
      summary: Create Network Alert
      operationId: createAlert
      description: Create a network alert on one or more IP ranges.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, filters]
              properties:
                name: { type: string }
                filters:
                  type: object
                  properties:
                    ip:
                      type: array
                      items: { type: string }
                expires:
                  type: integer
                  description: Optional expiration in seconds.
      responses:
        '200':
          description: Created alert.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Alert' }
  /shodan/alert/info:
    get:
      tags: [Network Alerts]
      summary: List Network Alerts
      operationId: listAlerts
      description: Returns the network alerts that have been created on the account.
      responses:
        '200':
          description: List of alerts.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/Alert' }
  /shodan/alert/{id}/info:
    get:
      tags: [Network Alerts]
      summary: Get Network Alert
      operationId: getAlert
      description: Returns the information about a specific network alert.
      parameters:
        - $ref: '#/components/parameters/AlertId'
      responses:
        '200':
          description: Alert details.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Alert' }
        '404': { $ref: '#/components/responses/NotFound' }
  /shodan/alert/{id}:
    post:
      tags: [Network Alerts]
      summary: Update Network Alert
      operationId: updateAlert
      description: Edit the IP ranges or name of a network alert.
      parameters:
        - $ref: '#/components/parameters/AlertId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
                filters:
                  type: object
                  properties:
                    ip:
                      type: array
                      items: { type: string }
      responses:
        '200':
          description: Updated alert.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Alert' }
    delete:
      tags: [Network Alerts]
      summary: Delete Network Alert
      operationId: deleteAlert
      description: Remove the network alert and its triggers.
      parameters:
        - $ref: '#/components/parameters/AlertId'
      responses:
        '200':
          description: Alert deletion result.
          content:
            application/json:
              schema: { type: object, properties: { success: { type: boolean } } }
  /shodan/alert/triggers:
    get:
      tags: [Network Alerts]
      summary: List Alert Triggers
      operationId: listAlertTriggers
      description: Returns the list of triggers that can be enabled on alerts.
      responses:
        '200':
          description: Trigger metadata.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name: { type: string }
                    description: { type: string }
                    rule: { type: string }
  /shodan/alert/{id}/trigger/{trigger}:
    put:
      tags: [Network Alerts]
      summary: Enable Alert Trigger
      operationId: enableAlertTrigger
      description: Enable a trigger on a network alert.
      parameters:
        - $ref: '#/components/parameters/AlertId'
        - $ref: '#/components/parameters/TriggerName'
      responses:
        '200':
          description: Trigger enable result.
          content:
            application/json:
              schema: { type: object, properties: { success: { type: boolean } } }
    delete:
      tags: [Network Alerts]
      summary: Disable Alert Trigger
      operationId: disableAlertTrigger
      description: Disable a trigger on a network alert.
      parameters:
        - $ref: '#/components/parameters/AlertId'
        - $ref: '#/components/parameters/TriggerName'
      responses:
        '200':
          description: Trigger disable result.
          content:
            application/json:
              schema: { type: object, properties: { success: { type: boolean } } }
  /notifier:
    get:
      tags: [Notifiers]
      summary: List Notifiers
      operationId: listNotifiers
      description: Returns the list of notifiers the user has configured.
      responses:
        '200':
          description: Notifier list.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/Notifier' }
    post:
      tags: [Notifiers]
      summary: Create Notifier
      operationId: createNotifier
      description: Create a new notifier for receiving alerts.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/NotifierCreate' }
      responses:
        '200':
          description: Created notifier.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Notifier' }
  /notifier/provider:
    get:
      tags: [Notifiers]
      summary: List Notifier Providers
      operationId: listNotifierProviders
      description: Returns the list of available notification provider types.
      responses:
        '200':
          description: Provider catalog.
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
  /notifier/{id}:
    get:
      tags: [Notifiers]
      summary: Get Notifier
      operationId: getNotifier
      description: Returns information about a specific notifier.
      parameters:
        - $ref: '#/components/parameters/NotifierId'
      responses:
        '200':
          description: Notifier details.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Notifier' }
    put:
      tags: [Notifiers]
      summary: Update Notifier
      operationId: updateNotifier
      description: Update an existing notifier configuration.
      parameters:
        - $ref: '#/components/parameters/NotifierId'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/NotifierCreate' }
      responses:
        '200':
          description: Updated notifier.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Notifier' }
    delete:
      tags: [Notifiers]
      summary: Delete Notifier
      operationId: deleteNotifier
      description: Delete a notifier.
      parameters:
        - $ref: '#/components/parameters/NotifierId'
      responses:
        '200':
          description: Notifier deletion result.
          content:
            application/json:
              schema: { type: object, properties: { success: { type: boolean } } }
  /shodan/query:
    get:
      tags: [Directory]
      summary: List Saved Queries
      operationId: listSavedQueries
      description: Browse the directory of community-saved Shodan queries.
      parameters:
        - name: page
          in: query
          schema: { type: integer, default: 1 }
        - name: sort
          in: query
          schema: { type: string, enum: [votes, timestamp] }
        - name: order
          in: query
          schema: { type: string, enum: [asc, desc] }
      responses:
        '200':
          description: List of saved queries.
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
  /shodan/query/search:
    get:
      tags: [Directory]
      summary: Search Saved Queries
      operationId: searchSavedQueries
      description: Search the directory of saved Shodan queries.
      parameters:
        - $ref: '#/components/parameters/Query'
        - name: page
          in: query
          schema: { type: integer, default: 1 }
      responses:
        '200':
          description: Search results.
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
  /shodan/query/tags:
    get:
      tags: [Directory]
      summary: List Popular Query Tags
      operationId: listSavedQueryTags
      description: Returns the most popular tags assigned to saved queries.
      parameters:
        - name: size
          in: query
          schema: { type: integer, default: 10 }
      responses:
        '200':
          description: Tag list.
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
  /shodan/data:
    get:
      tags: [Bulk Data]
      summary: List Bulk Data Sets
      operationId: listBulkDatasets
      description: Returns the list of bulk data sets available to the account. Enterprise only.
      responses:
        '200':
          description: Dataset list.
          content:
            application/json:
              schema: { type: array, items: { $ref: '#/components/schemas/Dataset' } }
  /shodan/data/{dataset}:
    get:
      tags: [Bulk Data]
      summary: List Bulk Data Files
      operationId: listBulkDatasetFiles
      description: Returns the list of files available within a bulk dataset. Enterprise only.
      parameters:
        - name: dataset
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: File list.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name: { type: string }
                    size: { type: integer }
                    timestamp: { type: string, format: date-time }
                    url: { type: string, format: uri }
  /dns/domain/{domain}:
    get:
      tags: [DNS]
      summary: Get Domain DNS Information
      operationId: getDomainDns
      description: Returns the subdomains and DNS entries known for the given domain.
      parameters:
        - name: domain
          in: path
          required: true
          schema: { type: string }
        - name: history
          in: query
          schema: { type: boolean, default: false }
        - name: type
          in: query
          schema: { type: string, enum: [A, AAAA, CNAME, NS, SOA, MX, TXT] }
        - name: page
          in: query
          schema: { type: integer, default: 1 }
      responses:
        '200':
          description: Domain DNS information.
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
  /dns/resolve:
    get:
      tags: [DNS]
      summary: Resolve Hostnames
      operationId: resolveHostnames
      description: Look up IP addresses for the given hostnames.
      parameters:
        - name: hostnames
          in: query
          required: true
          schema: { type: string }
          description: Comma-separated list of hostnames.
      responses:
        '200':
          description: Map of hostname to IP.
          content:
            application/json:
              schema: { type: object, additionalProperties: { type: string } }
  /dns/reverse:
    get:
      tags: [DNS]
      summary: Reverse DNS Lookup
      operationId: reverseDnsLookup
      description: Look up hostnames for the given IP addresses.
      parameters:
        - name: ips
          in: query
          required: true
          schema: { type: string }
          description: Comma-separated list of IP addresses.
      responses:
        '200':
          description: Map of IP to hostnames.
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: array
                  items: { type: string }
  /tools/httpheaders:
    get:
      tags: [Utility]
      summary: Get Request HTTP Headers
      operationId: getHttpHeaders
      description: Returns the HTTP headers seen by the Shodan server.
      responses:
        '200':
          description: Request headers as a map.
          content:
            application/json:
              schema: { type: object, additionalProperties: { type: string } }
  /tools/myip:
    get:
      tags: [Utility]
      summary: Get Client IP
      operationId: getMyIp
      description: Returns the IP address that the request was issued from.
      responses:
        '200':
          description: Plain-text IP address.
          content:
            application/json:
              schema: { type: string }
  /account/profile:
    get:
      tags: [Account]
      summary: Get Account Profile
      operationId: getAccountProfile
      description: Returns information about the Shodan account.
      responses:
        '200':
          description: Account profile.
          content:
            application/json:
              schema:
                type: object
                properties:
                  member: { type: boolean }
                  credits: { type: integer }
                  display_name: { type: string }
                  created: { type: string, format: date-time }
  /api-info:
    get:
      tags: [Account]
      summary: Get API Plan Info
      operationId: getApiInfo
      description: Returns information about the API plan including remaining query and scan credits.
      responses:
        '200':
          description: API plan info.
          content:
            application/json:
              schema:
                type: object
                properties:
                  query_credits: { type: integer }
                  scan_credits: { type: integer }
                  telnet: { type: boolean }
                  plan: { type: string }
                  https: { type: boolean }
                  unlocked: { type: boolean }
                  monitored_ips: { type: integer }
                  usage_limits:
                    type: object
                    additionalProperties: { type: integer }
  /org:
    get:
      tags: [Organization]
      summary: Get Organization
      operationId: getOrganization
      description: Returns information about the organization the account is part of.
      responses:
        '200':
          description: Organization info.
          content:
            application/json:
              schema:
                type: object
                properties:
                  name: { type: string }
                  upgrade_type: { type: string }
                  domains:
                    type: array
                    items: { type: string }
                  members:
                    type: array
                    items:
                      type: object
                      properties:
                        username: { type: string }
                        email: { type: string }
  /org/member/{user}:
    put:
      tags: [Organization]
      summary: Add Organization Member
      operationId: addOrganizationMember
      description: Add a user to the organization.
      parameters:
        - name: user
          in: path
          required: true
          schema: { type: string }
        - name: notify
          in: query
          schema: { type: boolean, default: true }
      responses:
        '200':
          description: Add result.
          content:
            application/json:
              schema: { type: object, properties: { success: { type: boolean } } }
    delete:
      tags: [Organization]
      summary: Remove Organization Member
      operationId: removeOrganizationMember
      description: Remove a user from the organization.
      parameters:
        - name: user
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Remove result.
          content:
            application/json:
              schema: { type: object, properties: { success: { type: boolean } } }
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: query
      name: key
      description: Shodan API key.
  parameters:
    IpPath:
      name: ip
      in: path
      required: true
      schema: { type: string }
      description: IPv4 or IPv6 address.
    Query:
      name: query
      in: query
      required: true
      schema: { type: string }
      description: Shodan search query.
    Facets:
      name: facets
      in: query
      schema: { type: string }
      description: Comma-separated facet definitions (e.g. `country:5,port:10`).
    AlertId:
      name: id
      in: path
      required: true
      schema: { type: string }
      description: Alert identifier.
    TriggerName:
      name: trigger
      in: path
      required: true
      schema: { type: string }
      description: Trigger name.
    NotifierId:
      name: id
      in: path
      required: true
      schema: { type: string }
      description: Notifier identifier.
  responses:
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            type: object
            properties:
              error: { type: string }
  schemas:
    Host:
      type: object
      properties:
        ip_str: { type: string }
        ip: { type: integer }
        hostnames:
          type: array
          items: { type: string }
        domains:
          type: array
          items: { type: string }
        country_code: { type: string }
        country_name: { type: string }
        city: { type: string }
        region_code: { type: string }
        postal_code: { type: string }
        latitude: { type: number }
        longitude: { type: number }
        org: { type: string }
        isp: { type: string }
        asn: { type: string }
        os: { type: string }
        last_update: { type: string, format: date-time }
        ports:
          type: array
          items: { type: integer }
        vulns:
          type: array
          items: { type: string }
        tags:
          type: array
          items: { type: string }
        data:
          type: array
          items: { $ref: '#/components/schemas/Banner' }
    Banner:
      type: object
      properties:
        port: { type: integer }
        transport: { type: string, enum: [tcp, udp] }
        product: { type: string }
        version: { type: string }
        data: { type: string }
        timestamp: { type: string, format: date-time }
        hash: { type: integer }
        ip_str: { type: string }
        org: { type: string }
        isp: { type: string }
        asn: { type: string }
        hostnames:
          type: array
          items: { type: string }
        domains:
          type: array
          items: { type: string }
        location:
          type: object
          properties:
            city: { type: string }
            country_code: { type: string }
            country_name: { type: string }
            latitude: { type: number }
            longitude: { type: number }
        ssl:
          type: object
          additionalProperties: true
        http:
          type: object
          additionalProperties: true
        cpe23:
          type: array
          items: { type: string }
        vulns:
          type: object
          additionalProperties: true
    SearchCount:
      type: object
      properties:
        total: { type: integer }
        facets:
          type: object
          additionalProperties:
            type: array
            items:
              type: object
              properties:
                count: { type: integer }
                value: { type: string }
    SearchResult:
      type: object
      properties:
        total: { type: integer }
        matches:
          type: array
          items: { $ref: '#/components/schemas/Banner' }
        facets:
          type: object
          additionalProperties:
            type: array
            items:
              type: object
              properties:
                count: { type: integer }
                value: { type: string }
    Scan:
      type: object
      properties:
        id: { type: string }
        count: { type: integer }
        credits_left: { type: integer }
        status: { type: string, enum: [SUBMITTING, QUEUE, PROCESSING, DONE] }
        created: { type: string, format: date-time }
    Alert:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        created: { type: string, format: date-time }
        expires: { type: integer }
        expiration: { type: string, format: date-time }
        filters:
          type: object
          properties:
            ip:
              type: array
              items: { type: string }
        triggers:
          type: object
          additionalProperties:
            type: object
            properties:
              enabled: { type: boolean }
        size: { type: integer }
    Notifier:
      type: object
      properties:
        id: { type: string }
        provider: { type: string }
        description: { type: string }
        args:
          type: object
          additionalProperties: true
    NotifierCreate:
      type: object
      required: [provider, description, args]
      properties:
        provider: { type: string }
        description: { type: string }
        args:
          type: object
          additionalProperties: true
    Dataset:
      type: object
      properties:
        name: { type: string }
        description: { type: string }