swagger.yaml

openapi: 3.0.3
info:
  title: Check-Host.cc API
  version: 2.1.0
  description: |
    The Check-Host.cc API runs distributed network diagnostics from 65+ global nodes — Ping, MTR, DNS, HTTP, TCP and UDP — and exposes IP/host metadata, WHOIS, and historic check reports.

    ## How a check works

    Submitting a check is asynchronous:

    1. `POST /ping`, `/tcp`, `/udp`, `/http`, `/dns`, `/mtr` (or the equivalent GET shortcuts) — returns a UUID and a `reportURL`.
    2. Poll `GET /report/{uuid}` until each requested node has reported a result. Most checks complete in 1–10 seconds.

    ## Network Intelligence

    Beyond live checks, the API exposes our passive intelligence dataset as JSON. `GET /ip`, `/as`, `/prefix`, `/domain`, `/cert`, `/port`, `/software` and `/scan` return the same data that powers the entity pages — BGP/ASN attribution, GeoIP, TLS certificates, open ports, tech-stack, origin-leak candidates and honeypot activity. `POST /fullscan` dispatches a deep, on-demand multi-stage scan and `GET /fullscan/{uuid}/results` returns its aggregated findings. All of it is free: anonymous with per-IP limits, an API key lifts them.

    ## Authentication

    Anonymous use is permitted with conservative per-IP and per-target rate limits. To raise those limits and gain a per-key monthly quota, send your API key (UUID) as an `Authorization: Bearer <key>` header — the default, working for GET and POST alike. `X-API-Key` and a POST-body `apikey` field are also accepted (never the query string). All auth is optional; anonymous requests may omit the key entirely.

    ## Rate limits

    Limits are applied per-IP, per-API-key, and per-target globally to prevent abuse. Exceeding any bucket returns `429`. Live-mode checks (`repeatchecks > 9`) consume a smaller, separate budget.

    ## Official SDKs

    | Language | Repository |
    |---|---|
    | Node.js  | <https://github.com/Check-Host/nodejs-lib>  |
    | Python   | <https://github.com/Check-Host/python-lib>  |
    | PHP 8.1+ | <https://github.com/Check-Host/php-lib>     |
    | Go       | <https://github.com/Check-Host/go-lib>      |
    | Java     | <https://github.com/Check-Host/CheckHost4J> |

    All SDKs and tooling: <https://github.com/Check-Host>

    ## Quick example — polling pattern

    ```bash
    # 1. Dispatch a check, capture the UUID
    UUID=$(curl -s -X POST https://api.check-host.cc/ping \
      -H 'Content-Type: application/json' \
      -d '{"target":"check-host.cc","region":["DE"]}' | jq -r .uuid)

    # 2. Poll the report until every node has reported
    until curl -s "https://api.check-host.cc/report/$UUID" \
      | jq -e '.data | length >= 1' > /dev/null; do sleep 1; done
    curl -s "https://api.check-host.cc/report/$UUID" | jq .
    ```
  contact:
    name: Check-Host API Support
    url: https://check-host.cc
    email: dev@check-host.cc
  license:
    name: Proprietary — free public use
    url: https://check-host.cc/about
  x-logo:
    url: https://check-host.cc/images/Check-Host-Logo-LightMode.png
    altText: Check-Host.cc

externalDocs:
  description: Official SDKs (Node.js, Python, PHP, Go, Java) on GitHub
  url: https://github.com/Check-Host

# ReDoc-only: groups the sidebar tags into top-level sections.
# Ignored by Swagger UI and other tools.
x-tagGroups:
  - name: Submit a check
    tags: [Monitoring]
  - name: Read results
    tags: [Reporting]
  - name: Network Intelligence
    tags: [Intelligence, Fullscan]
  - name: Lookups
    tags: [Utilities]

servers:
  - url: https://api.check-host.cc
    description: Production
  - url: https://check-host.cc/api
    description: Mirror (same backend, useful if api.* is blocked by the network)

tags:
  - name: Utilities
    description: IP geolocation, WHOIS, the requesting client's IP, and the live monitoring node list.
  - name: Monitoring
    description: Dispatch a Ping / TCP / UDP / HTTP / DNS / MTR check to global nodes. Returns a UUID — poll `/report/{uuid}` for results.
    externalDocs:
      description: "Example: dispatching a Ping check via the official SDKs"
      url: https://github.com/Check-Host
  - name: Reporting
    description: Fetch the JSON report, the dynamic OG image, or the country-coloured world map for a previously dispatched check.
  - name: Intelligence
    description: >-
      Machine-readable network-intelligence lookups — the JSON twin of the /ip, /as,
      /domain, /cert … entity pages. Aggregated from our CT-log mirror, world scans,
      BGP/RIR/PeeringDB/RPKI mirrors and honeypot sensors. Open to guests with a
      per-IP rate limit; an API key lifts the limits.
  - name: Fullscan
    description: >-
      Dispatch a deep, multi-stage scan (ports + banners + TLS + DNS + threat-intel)
      of an IP, CIDR, domain or ASN, and read the aggregated results. Asynchronous:
      submit, then poll the status and results endpoints.

# Auth is optional everywhere: `Authorization: Bearer <key>` (the default) lifts
# rate limits, and the empty requirement `{}` permits anonymous use.
security:
  - BearerAuth: []
  - {}

paths:
  # ─────────────────────────────  Utilities  ─────────────────────────────

  /myip:
    get:
      tags: [Utilities]
      operationId: getMyIp
      summary: Get caller's public IP
      description: Returns the requesting client's public IPv4 or IPv6 address. Useful for client-side identification before dispatching authenticated requests.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MyIpResponse'
              example:
                status: 200
                message: "Your current IP is: 34.36.183.77"
                ip: "34.36.183.77"
                success: true
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  /myinfo:
    get:
      tags: [Utilities]
      operationId: getMyInfo
      summary: Geolocation + ASN for the caller's IP
      description: Same response shape as `/info/{target}` but resolved against the requesting client's IP. Subject to bot detection — repeated cache misses on this endpoint can result in a `429` with a captcha verification URL.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InfoResponse'
        '429':
          description: Rate-limited or flagged by bot detection. Response body includes a captcha URL when bot-flagged.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:     { type: boolean, example: false }
                  error:       { type: string }
                  captcha_url: { type: string, format: uri, nullable: true }
        '500': { $ref: '#/components/responses/ServerError' }

  /usage:
    get:
      tags: [Utilities]
      operationId: getUsage
      summary: Your rate-limit usage vs. limits
      description: >
        Your current rate-limit usage against your limits, per window. With an API key
        (`Authorization: Bearer`) it reports the key's 10s / minute / hour / day / month limits,
        used and remaining, plus `last_used_at`. With no key it reports the anonymous per-IP
        limits (10s / minute / hour). Read-only — checking never counts against your quota — and
        it sits outside the main rate limiter so it works even while you are throttled.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:      { type: boolean }
                  mode:         { type: string, enum: [apikey, ip] }
                  ip:           { type: string, description: "Present in ip mode." }
                  limits:       { type: object, additionalProperties: { type: integer } }
                  used:         { type: object, additionalProperties: { type: integer } }
                  remaining:    { type: object, additionalProperties: { type: integer } }
                  last_used_at: { type: string, nullable: true, description: "apikey mode only." }
                  note:         { type: string, description: "ip mode only." }
              examples:
                apikey:
                  summary: With API key
                  value:
                    success: true
                    mode: apikey
                    limits:    { "10s": 10, min: 120, hour: 2000, day: 20000, month: 200000 }
                    used:      { "10s": 1, min: 14, hour: 230, day: 1120, month: 8400 }
                    remaining: { "10s": 9, min: 106, hour: 1770, day: 18880, month: 191600 }
                    last_used_at: "2026-07-28 21:58:18"
                ip:
                  summary: Anonymous (per-IP)
                  value:
                    success: true
                    mode: ip
                    ip: "203.0.113.55"
                    limits:    { "10s": 6, min: 30, hour: 250 }
                    used:      { "10s": 0, min: 4, hour: 18 }
                    remaining: { "10s": 6, min: 26, hour: 232 }
                    note: "Anonymous per-IP limits. Live-mode checks use lower caps; global per-target limits also apply. Send an API key for higher limits."
        '401': { $ref: '#/components/responses/InvalidApiKey' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  /locations:
    get:
      tags: [Utilities]
      operationId: listLocations
      summary: List all active monitoring nodes
      description: |
        Returns every node currently online. Use the `locationname` value (e.g. `DE-NBG-Hetzner`) in the `region` array of any monitoring request to target a specific node, or the `countryCode` (e.g. `DE`) to fan out across all nodes in a country, or a continent code (`EU`, `NA`, `AS`, `SA`, `AF`, `OC`).

        Continental targeting cannot be mixed with specific node names in the same request.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationsResponse'
              example:
                status: 200
                CountryCodes: "Only supported where Locations are! Take from locationlist"
                Continents: ["EU"]
                locationlist:
                  - { continent: "EU", country: "Germany", countryCode: "DE", city: "Nuernberg", asn: "AS24940", isp: "Hetzner Online GmbH", datacenter: "Hetzner", monitoring_allowed: 1, hostname: "de-nbg-het.check-host.eu", locationname: "DE-NBG-Hetzner", sponsor: null, sponsor_url: null, latitude: null, longitude: null }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  /info:
    post:
      tags: [Utilities]
      operationId: infoLookup
      summary: Geolocation + ASN (POST)
      description: Recommended over GET when the target may need URL-encoding.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TargetRequest' }
            example: { apikey: null, target: "check-host.cc" }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InfoResponse' }
              examples:
                checkHost:
                  $ref: '#/components/examples/InfoCheckHost'
        '400':
          description: Missing or invalid target.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
              example: { status: 400, error: "No target provided", success: false }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  /info/{target}:
    get:
      tags: [Utilities]
      operationId: infoLookupByPath
      summary: Geolocation + ASN (GET)
      description: GET shortcut. Use POST `/info` for targets that contain reserved URL characters.
      parameters:
        - { name: target, in: path, required: true, schema: { type: string }, example: "check-host.cc" }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InfoResponse' }
              examples:
                checkHost:
                  $ref: '#/components/examples/InfoCheckHost'
        '400':
          description: Invalid target.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  /whois:
    post:
      tags: [Utilities]
      operationId: whoisLookup
      summary: WHOIS / RDAP lookup (POST)
      description: Returns the upstream RDAP record for a domain or IP block (registrant, registrar, dates, nameservers, abuse contact).
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TargetRequest' }
            example: { apikey: null, target: "check-host.cc" }
      responses:
        '200':
          description: OK — RDAP record. Shape varies by registry; the example below is from Verisign for a `.cc` domain.
          content:
            application/json:
              example:
                objectClassName: "domain"
                handle: "167044666_DOMAIN_CC-VRSN"
                ldhName: "CHECK-HOST.CC"
                status: ["client delete prohibited", "client transfer prohibited"]
                events:
                  - { eventAction: "registration",  eventDate: "2021-11-20T20:21:05Z" }
                  - { eventAction: "expiration",    eventDate: "2030-11-20T20:21:05Z" }
                  - { eventAction: "last changed",  eventDate: "2026-01-13T13:54:30Z" }
                nameservers:
                  - { objectClassName: "nameserver", ldhName: "PEYTON.NS.CLOUDFLARE.COM" }
                secureDNS: { delegationSigned: false }
        '400': { $ref: '#/components/responses/BadInput' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  /whois/{target}:
    get:
      tags: [Utilities]
      operationId: whoisLookupByPath
      summary: WHOIS / RDAP lookup (GET)
      parameters:
        - { name: target, in: path, required: true, schema: { type: string }, example: "check-host.cc" }
      responses:
        '200':
          description: OK — RDAP record (shape varies by registry).
        '400': { $ref: '#/components/responses/BadInput' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  # ─────────────────────────────  Monitoring  ─────────────────────────────

  /ping:
    post:
      tags: [Monitoring]
      operationId: checkPing
      summary: ICMP Ping
      description: Dispatches ICMP echo requests from each selected node to measure latency and packet loss. Set `repeatchecks` ≥ 10 for live mode (continuous probing for ~`repeatchecks` seconds).
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/MonitoringRequest' }
            example: { apikey: null, target: "check-host.cc", region: ["DE"], repeatchecks: 0 }
      responses:
        '200':
          description: Check dispatched.
          headers:
            X-Ratelimit-Limit:     { $ref: '#/components/headers/X-Ratelimit-Limit' }
            X-Ratelimit-Remaining: { $ref: '#/components/headers/X-Ratelimit-Remaining' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CheckCreated' }
              example:
                status: 200
                success: true
                target: "check-host.cc"
                method: "ping"
                repeatchecks: 0
                region: ["DE"]
                uuid: "0710831d-1589-47d4-9fc1-885fe33a25e4"
                reportURL: "https://check-host.cc/report/0710831d-1589-47d4-9fc1-885fe33a25e4"
                apiURL: "https://api.check-host.cc/report/0710831d-1589-47d4-9fc1-885fe33a25e4"
                og-imageURL: "https://api.check-host.cc/report/0710831d-1589-47d4-9fc1-885fe33a25e4/og-image"
                autodelete: "12-05-2036"
                message: "Broadcasted task to all slaves."
                port: null
                query: null
                payload: null
        '401': { $ref: '#/components/responses/InvalidApiKey' }
        '422': { $ref: '#/components/responses/ValidationError' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  /ping/{target}:
    get:
      tags: [Monitoring]
      operationId: checkPingByPath
      summary: ICMP Ping (GET)
      parameters:
        - { name: target, in: path, required: true, schema: { type: string }, example: "check-host.cc" }
        - { name: timeout, in: query, required: false, schema: { type: integer, minimum: 100, maximum: 30000, default: 1000 }, description: "Per-check timeout in milliseconds. Applied at whole-second granularity, so values below 1000 behave as 1000. A value below 100 is read as seconds and converted, so clients written against the older libraries keep working." }
      responses:
        '200':
          description: Check dispatched.
          headers:
            X-Ratelimit-Limit:     { $ref: '#/components/headers/X-Ratelimit-Limit' }
            X-Ratelimit-Remaining: { $ref: '#/components/headers/X-Ratelimit-Remaining' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CheckCreated' }
        '401': { $ref: '#/components/responses/InvalidApiKey' }
        '422': { $ref: '#/components/responses/ValidationError' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  /tcp:
    post:
      tags: [Monitoring]
      operationId: checkTcp
      summary: TCP port check
      description: |
        Attempts a TCP 3-way handshake on `target:port`. Good for verifying firewall rules and service availability.

        **Live mode:** set `repeatchecks` ≥ 10 for continuous probing — see the same note on `/ping`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/MonitoringRequest'
                - type: object
                  required: [port]
                  properties:
                    port: { type: integer, minimum: 1, maximum: 65535, example: 443 }
            example: { apikey: null, target: "check-host.cc", port: 443, region: ["DE"] }
      responses:
        '200':
          description: Check dispatched.
          headers:
            X-Ratelimit-Limit:     { $ref: '#/components/headers/X-Ratelimit-Limit' }
            X-Ratelimit-Remaining: { $ref: '#/components/headers/X-Ratelimit-Remaining' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CheckCreated' }
              example:
                status: 200
                success: true
                target: "check-host.cc:443"
                method: "tcp"
                repeatchecks: 0
                region: ["DE"]
                uuid: "98eea6c0-d270-4282-af22-d167ff549dd8"
                reportURL: "https://check-host.cc/report/98eea6c0-d270-4282-af22-d167ff549dd8"
                apiURL: "https://api.check-host.cc/report/98eea6c0-d270-4282-af22-d167ff549dd8"
                og-imageURL: "https://api.check-host.cc/report/98eea6c0-d270-4282-af22-d167ff549dd8/og-image"
                autodelete: "12-05-2036"
                message: "Broadcasted task to all slaves."
                port: 443
                query: null
                payload: null
        '401': { $ref: '#/components/responses/InvalidApiKey' }
        '422': { $ref: '#/components/responses/ValidationError' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  /tcp/{target}/{port}:
    get:
      tags: [Monitoring]
      operationId: checkTcpByPath
      summary: TCP port check (GET)
      parameters:
        - { name: target, in: path, required: true, schema: { type: string }, example: "check-host.cc" }
        - { name: port,   in: path, required: true, schema: { type: integer, minimum: 0, maximum: 65535 }, example: 443 }
        - { name: timeout, in: query, required: false, schema: { type: integer, minimum: 100, maximum: 30000, default: 1000 }, description: "Per-check timeout in milliseconds. A value below 100 is read as seconds and converted, so clients written against the older libraries keep working." }
      responses:
        '200':
          description: Check dispatched.
          headers:
            X-Ratelimit-Limit:     { $ref: '#/components/headers/X-Ratelimit-Limit' }
            X-Ratelimit-Remaining: { $ref: '#/components/headers/X-Ratelimit-Remaining' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CheckCreated' }
        '401': { $ref: '#/components/responses/InvalidApiKey' }
        '422': { $ref: '#/components/responses/ValidationError' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  /udp:
    post:
      tags: [Monitoring]
      operationId: checkUdp
      summary: UDP port check
      description: |
        UDP is connectionless, so meaningful availability often requires sending a protocol-specific payload. If `payload` is omitted, the server injects a sensible default for well-known ports (DNS, NTP, SNMP, RIP, OpenVPN, WireGuard, Quake, Minecraft, …) — see [`UdpPayloads.php`](https://github.com/Check-Host) in the project. For unknown ports, a generic probe is used.

        `payload` accepts either a hex string (`0x…`) or printable ASCII (max 2048 bytes). It is sent verbatim by every selected node.

        **Live mode:** set `repeatchecks` ≥ 10 for continuous probing — see the same note on `/ping`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/MonitoringRequest'
                - type: object
                  required: [port]
                  properties:
                    port:    { type: integer, minimum: 1, maximum: 65535, example: 53 }
                    payload: { type: string, nullable: true, maxLength: 2048, example: "0x241a010000010000000000000377777706676f6f676c6503636f6d0000010001" }
            example: { apikey: null, target: "1.1.1.1", port: 53, region: ["DE"] }
      responses:
        '200':
          description: Check dispatched.
          headers:
            X-Ratelimit-Limit:     { $ref: '#/components/headers/X-Ratelimit-Limit' }
            X-Ratelimit-Remaining: { $ref: '#/components/headers/X-Ratelimit-Remaining' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CheckCreated' }
              example:
                status: 200
                success: true
                target: "1.1.1.1:53"
                method: "udp"
                repeatchecks: 0
                region: ["DE"]
                uuid: "b6c616c9-239d-45dd-8120-ccef70ea7927"
                reportURL: "https://check-host.cc/report/b6c616c9-239d-45dd-8120-ccef70ea7927"
                apiURL: "https://api.check-host.cc/report/b6c616c9-239d-45dd-8120-ccef70ea7927"
                og-imageURL: "https://api.check-host.cc/report/b6c616c9-239d-45dd-8120-ccef70ea7927/og-image"
                autodelete: "12-05-2036"
                message: "Broadcasted task to all slaves."
                port: 53
                query: null
                payload: "0x241a010000010000000000000377777706676f6f676c6503636f6d0000010001"
        '401': { $ref: '#/components/responses/InvalidApiKey' }
        '422': { $ref: '#/components/responses/ValidationError' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }
    get:
      tags: [Monitoring]
      operationId: checkUdpByQuery
      summary: UDP port check (GET, query string)
      description: GET variant accepting `target` and `port` as query parameters. Equivalent to POST `/udp`.
      parameters:
        - { name: target,  in: query, required: true,  schema: { type: string }, example: "1.1.1.1" }
        - { name: port,    in: query, required: true,  schema: { type: integer, minimum: 1, maximum: 65535 }, example: 53 }
        - { name: region,  in: query, required: false, schema: { type: array, items: { type: string } } }
        - { name: payload, in: query, required: false, schema: { type: string }, description: "Hex (0x…) or printable ASCII, max 2048 bytes." }
        - { name: timeout, in: query, required: false, schema: { type: integer, minimum: 100, maximum: 30000, default: 2000 }, description: "Per-check timeout in milliseconds. A value below 100 is read as seconds and converted, so clients written against the older libraries keep working." }
      responses:
        '200':
          description: Check dispatched.
          headers:
            X-Ratelimit-Limit:     { $ref: '#/components/headers/X-Ratelimit-Limit' }
            X-Ratelimit-Remaining: { $ref: '#/components/headers/X-Ratelimit-Remaining' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CheckCreated' }
        '401': { $ref: '#/components/responses/InvalidApiKey' }
        '422': { $ref: '#/components/responses/ValidationError' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  /http:
    post:
      tags: [Monitoring]
      operationId: checkHttp
      summary: HTTP/HTTPS check
      description: |
        Issues an HTTP(S) GET to the target and records status code, status text, target IP, and connection time. Accepts a full URL (including scheme, port, path, query) or a bare host — when the scheme is omitted, `https` is assumed.

        **Live mode:** set `repeatchecks` ≥ 10 to have each node issue `repeatchecks + 1` consecutive requests over ~`repeatchecks` seconds. The `checks` array in the report then contains one entry per probe (with `repeat: 0..N`).
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/MonitoringRequest' }
            example: { apikey: null, target: "https://check-host.cc", region: ["DE"] }
      responses:
        '200':
          description: Check dispatched.
          headers:
            X-Ratelimit-Limit:     { $ref: '#/components/headers/X-Ratelimit-Limit' }
            X-Ratelimit-Remaining: { $ref: '#/components/headers/X-Ratelimit-Remaining' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CheckCreated' }
              example:
                status: 200
                success: true
                target: "https://check-host.cc"
                method: "http"
                repeatchecks: 0
                region: ["DE"]
                uuid: "2afce05a-a6d8-460c-83fc-0da441c376bc"
                reportURL: "https://check-host.cc/report/2afce05a-a6d8-460c-83fc-0da441c376bc"
                apiURL: "https://api.check-host.cc/report/2afce05a-a6d8-460c-83fc-0da441c376bc"
                og-imageURL: "https://api.check-host.cc/report/2afce05a-a6d8-460c-83fc-0da441c376bc/og-image"
                autodelete: "12-05-2036"
                message: "Broadcasted task to all slaves."
                port: null
                query: null
                payload: null
        '401': { $ref: '#/components/responses/InvalidApiKey' }
        '422': { $ref: '#/components/responses/ValidationError' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  /http/{target}:
    get:
      tags: [Monitoring]
      operationId: checkHttpByPath
      summary: HTTP/HTTPS check (GET)
      description: GET shortcut for a bare host or scheme-prefixed origin (`https` assumed when no scheme is given). Use POST `/http` for a full URL with a path, a custom port, or region targeting.
      parameters:
        - { name: target, in: path, required: true, schema: { type: string }, example: "check-host.cc" }
        - { name: timeout, in: query, required: false, schema: { type: integer, minimum: 100, maximum: 30000, default: 15000 }, description: "Per-check timeout in milliseconds. A value below 100 is read as seconds and converted, so clients written against the older libraries keep working." }
      responses:
        '200':
          description: Check dispatched.
          headers:
            X-Ratelimit-Limit:     { $ref: '#/components/headers/X-Ratelimit-Limit' }
            X-Ratelimit-Remaining: { $ref: '#/components/headers/X-Ratelimit-Remaining' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CheckCreated' }
        '401': { $ref: '#/components/responses/InvalidApiKey' }
        '422': { $ref: '#/components/responses/ValidationError' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  /dns:
    post:
      tags: [Monitoring]
      operationId: checkDns
      summary: DNS record lookup / propagation check
      description: Queries the named DNS record type from each selected node's local resolver. When `querymethod` is `PTR`, an IP address is allowed as the `target`; for any other method the `target` must be a domain.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/DNSTargetRequest' }
            example: { apikey: null, target: "check-host.cc", querymethod: "A", region: ["DE"] }
      responses:
        '200':
          description: Check dispatched.
          headers:
            X-Ratelimit-Limit:     { $ref: '#/components/headers/X-Ratelimit-Limit' }
            X-Ratelimit-Remaining: { $ref: '#/components/headers/X-Ratelimit-Remaining' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CheckCreated' }
              example:
                status: 200
                success: true
                target: "check-host.cc"
                method: "dns"
                repeatchecks: 0
                region: ["DE"]
                uuid: "da7e9b71-8cd0-4818-9ba3-7e0e34e370b1"
                reportURL: "https://check-host.cc/report/da7e9b71-8cd0-4818-9ba3-7e0e34e370b1"
                apiURL: "https://api.check-host.cc/report/da7e9b71-8cd0-4818-9ba3-7e0e34e370b1"
                og-imageURL: "https://api.check-host.cc/report/da7e9b71-8cd0-4818-9ba3-7e0e34e370b1/og-image"
                autodelete: "12-05-2036"
                message: "Broadcasted task to all slaves."
                port: null
                query: "A"
                payload: null
        '422':
          description: Validation error (e.g. IP supplied with non-PTR method).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
              example: { status: 422, error: "Only domain names are allowed for DNS checks, or use PTR for IPs.", success: false }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  /dns/{target}/{method}:
    get:
      tags: [Monitoring]
      operationId: checkDnsByPath
      summary: DNS record lookup (GET)
      parameters:
        - { name: target, in: path, required: true, schema: { type: string }, example: "check-host.cc" }
        - { name: method, in: path, required: true, schema: { type: string, default: "A", enum: [A/AAAA, A, AAAA, NS, MD, MF, CNAME, SOA, MB, MG, MR, "NULL", WKS, PTR, HINFO, MINFO, MX, TXT, SRV, EDNS, SPF, AXFR, MAILB, MAILA, ANY, CAA, DNSKEY] }, example: "A" }
        - { name: timeout, in: query, required: false, schema: { type: integer, minimum: 100, maximum: 30000, default: 5000 }, description: "Per-check timeout in milliseconds. A value below 100 is read as seconds and converted, so clients written against the older libraries keep working." }
      responses:
        '200':
          description: Check dispatched.
          headers:
            X-Ratelimit-Limit:     { $ref: '#/components/headers/X-Ratelimit-Limit' }
            X-Ratelimit-Remaining: { $ref: '#/components/headers/X-Ratelimit-Remaining' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CheckCreated' }
        '401': { $ref: '#/components/responses/InvalidApiKey' }
        '422': { $ref: '#/components/responses/ValidationError' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  /mtr:
    post:
      tags: [Monitoring]
      operationId: checkMtr
      summary: MTR (My Traceroute)
      description: |
        Combines traceroute and ping for hop-by-hop network path analysis. Default protocol is ICMP — use `forceProtocol: udp` or `tcp` to bypass ICMP-blocking firewalls. Default 5 packets per hop; raise `repeatchecks` (3–30) for higher-confidence stats at the cost of longer completion time.

        MTR results are larger than other check types — expect ~1–3 KB per hop per node.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/MTRMonitoringRequest' }
            example: { apikey: null, target: "check-host.cc", repeatchecks: 5, region: ["DE"] }
      responses:
        '200':
          description: Check dispatched.
          headers:
            X-Ratelimit-Limit:     { $ref: '#/components/headers/X-Ratelimit-Limit' }
            X-Ratelimit-Remaining: { $ref: '#/components/headers/X-Ratelimit-Remaining' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CheckCreated' }
              example:
                status: 200
                success: true
                target: "check-host.cc"
                method: "mtr"
                repeatchecks: 5
                region: ["DE"]
                uuid: "bc7b2683-2bc5-4604-8130-ad70df7b1e64"
                reportURL: "https://check-host.cc/report/bc7b2683-2bc5-4604-8130-ad70df7b1e64"
                apiURL: "https://api.check-host.cc/report/bc7b2683-2bc5-4604-8130-ad70df7b1e64"
                og-imageURL: "https://api.check-host.cc/report/bc7b2683-2bc5-4604-8130-ad70df7b1e64/og-image"
                autodelete: "12-05-2036"
                message: "Broadcasted task to all slaves."
                port: null
                query: null
                payload: null
        '401': { $ref: '#/components/responses/InvalidApiKey' }
        '422': { $ref: '#/components/responses/ValidationError' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  /mtr/{target}:
    get:
      tags: [Monitoring]
      operationId: checkMtrByPath
      summary: MTR (GET)
      parameters:
        - { name: target, in: path, required: true, schema: { type: string }, example: "check-host.cc" }
        - { name: timeout, in: query, required: false, schema: { type: integer, minimum: 100, maximum: 30000, default: 1000 }, description: "Per-check timeout in milliseconds. Runtime budget; nodes apply it in whole seconds. A value below 100 is read as seconds and converted, so clients written against the older libraries keep working." }
      responses:
        '200':
          description: Check dispatched.
          headers:
            X-Ratelimit-Limit:     { $ref: '#/components/headers/X-Ratelimit-Limit' }
            X-Ratelimit-Remaining: { $ref: '#/components/headers/X-Ratelimit-Remaining' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CheckCreated' }
        '401': { $ref: '#/components/responses/InvalidApiKey' }
        '422': { $ref: '#/components/responses/ValidationError' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  # ─────────────────────────────  Reporting  ─────────────────────────────

  /report/{uuid}:
    get:
      tags: [Reporting]
      operationId: getReport
      summary: Fetch check results
      description: |
        Returns the JSON report for a previously dispatched check. The `data` map is keyed by `locationname` (e.g. `DE-NBG-Hetzner`); each entry includes the node metadata and a `checks` field whose **shape depends on the check method**:

        - `ping`, `tcp`, `udp`, `http` — `checks` is an **array** of probe results.
        - `dns`, `mtr` — `checks` is a **single object** (DNS holds a record list, MTR holds a hop graph).

        Nodes that haven't reported yet are omitted from `data`. Poll until every requested node appears.

        ### Caching

        Reports are immutable once every selected node has reported. The response sets `Cache-Control: no-store` for the first ~200 seconds (settling window for slow nodes), then flips to `public, max-age=31536000, s-maxage=31536000, immutable` — safe to cache aggressively at edge/CDN.
      parameters:
        - { name: uuid, in: path, required: true, schema: { type: string, format: uuid }, example: "0710831d-1589-47d4-9fc1-885fe33a25e4" }
      responses:
        '200':
          description: Report (full or partial — poll until complete).
          headers:
            Cache-Control:
              schema: { type: string }
              description: "`no-store` while collecting results, `public, max-age=31536000, immutable` once final."
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CheckReport' }
              examples:
                ping:     { $ref: '#/components/examples/ReportPing' }
                http:     { $ref: '#/components/examples/ReportHttp' }
                httpLive: { $ref: '#/components/examples/ReportHttpLive' }
                dns:      { $ref: '#/components/examples/ReportDns'  }
                mtr:      { $ref: '#/components/examples/ReportMtr'  }
        '404':
          description: UUID not found or wrong format.
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  /report/{uuid}/og-image:
    get:
      tags: [Reporting]
      operationId: getReportOgImage
      summary: Continental status map (PNG, 1200×630)
      description: |
        Renders an Open Graph card showing per-continent up/down status (green / amber / red / inactive). 1200×630 PNG, suitable for `<meta property="og:image">` and social previews.

        Cached with the same age-based policy as `/report/{uuid}`: `no-store` until the test settles, then `public, max-age=31536000, immutable`.
      parameters:
        - { name: uuid, in: path, required: true, schema: { type: string, format: uuid }, example: "0710831d-1589-47d4-9fc1-885fe33a25e4" }
      responses:
        '200':
          description: PNG image.
          content:
            image/png:
              schema: { type: string, format: binary }
        '404': { description: UUID not found. }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  /report/{uuid}/country-map:
    get:
      tags: [Reporting]
      operationId: getReportCountryMap
      summary: Per-country world map (SVG or PNG)
      description: |
        Renders a country-coloured world map for the report. Each country with a participating node is filled green / amber / red based on its up/down ratio. Default response is SVG; pass `?format=png` for a rasterised PNG at one of three resolutions.

        Cached identically to `/og-image`.
      parameters:
        - { name: uuid,   in: path,  required: true,  schema: { type: string, format: uuid }, example: "0710831d-1589-47d4-9fc1-885fe33a25e4" }
        - { name: format, in: query, required: false, schema: { type: string, enum: [svg, png], default: svg } }
        - { name: res,    in: query, required: false, schema: { type: string, enum: [low, med, high], default: med }, description: "PNG resolution: low=800px, med=1200px, high=2000px wide." }
      responses:
        '200':
          description: SVG (default) or PNG image.
          content:
            image/svg+xml:
              schema: { type: string }
            image/png:
              schema: { type: string, format: binary }
        '404': { description: UUID not found. }
        '500': { $ref: '#/components/responses/ServerError' }

  # ────────────────────────  Network Intelligence  ────────────────────────

  /ip/{ip}:
    get:
      tags: [Intelligence]
      operationId: intelIp
      summary: IP intelligence profile
      description: |
        Everything we know about a single IPv4/IPv6 address — reverse DNS, open ports + banners, TLS certificates, BGP/ASN attribution, GeoIP, tech-stack, co-hosted domains, origin-leak candidates, threat-intel matches and honeypot activity. The JSON twin of the `/ip/{ip}` page. Sections with no data come back as empty arrays / `null`.

        Honeypot passwords are never returned in cleartext — each honeypot entry exposes only `password_captured` (bool) and `password_len`.
      parameters:
        - { name: ip, in: path, required: true, schema: { type: string }, example: "1.1.1.1" }
      responses:
        '200':
          description: OK
          headers:
            X-Ratelimit-Limit:     { $ref: '#/components/headers/X-Ratelimit-Limit' }
            X-Ratelimit-Remaining: { $ref: '#/components/headers/X-Ratelimit-Remaining' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/IpIntel' }
              example:
                success: true
                ip: "1.1.1.1"
                family: "IPv4"
                data:
                  ptr: { ptr: "one.one.one.one", observed_at: "2026-07-14 09:12:44" }
                  open_ports:
                    - { port: 443, proto: "tcp", last_seen: "2026-07-14 03:20:12", service: "https" }
                  tls_certs:
                    - { port: 443, sha256: "3a1b8f0c…9f90", subject: "CN=cloudflare-dns.com", sans_str: "cloudflare-dns.com, one.one.one.one", not_before: "2025-01-02 00:00:00", not_after: "2026-01-15 23:59:59", observed_at: "2026-07-14 03:20:12" }
                  bgp: { asn: 13335, as_name: "Cloudflare, Inc.", prefix: "1.1.1.0/24", rpki_status: "valid", country_code: "US", registry: "ARIN" }
                  geo: { country_code: "US", country_name: "United States", continent_code: "NA" }
                  techs:
                    - { technology: "Cloudflare", category: "CDN", confidence: 100 }
                  threat_count: 0
                  honeypot: null
                  honeypot_recent: []
        '422': { $ref: '#/components/responses/ValidationError' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  /as/{asn}:
    get:
      tags: [Intelligence]
      operationId: intelAsn
      summary: ASN intelligence profile
      description: Full autonomous-system intel aggregated from our BGP mirrors (CAIDA pfx2as + AS-relationships, RIR delegated stats, PeeringDB, RPKI) — profile, prefix counts, announced-IP totals, peers / providers / customers, IXP memberships, RPKI coverage, GeoIP footprint, top ports, hosted-domains and pingable-IP summaries. Accepts `13335` or `AS13335`.
      parameters:
        - { name: asn, in: path, required: true, schema: { type: string }, example: "AS13335" }
      responses:
        '200':
          description: OK
          headers:
            X-Ratelimit-Limit:     { $ref: '#/components/headers/X-Ratelimit-Limit' }
            X-Ratelimit-Remaining: { $ref: '#/components/headers/X-Ratelimit-Remaining' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AsnIntel' }
              example:
                success: true
                asn: 13335
                as_name: "Cloudflare, Inc."
                data:
                  as_name: "Cloudflare, Inc."
                  as_type: "Content"
                  country: "US"
                  registry: "arin"
                  prefix_count: 1542
                  prefix_count_v4: 1180
                  prefix_count_v6: 362
                  announced_ips_v4: 1520640
                  peers_count: 9821
                  providers_count: 18
                  customers_count: 420
                  rpki_valid: 1500
                  rpki_coverage_pct: 97.3
                  ixp_count: 285
                  hosted_domains: 8412339
                  pingable_count: 94021
        '422': { $ref: '#/components/responses/ValidationError' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  /prefix/{net}/{mask}:
    get:
      tags: [Intelligence]
      operationId: intelPrefix
      summary: CIDR prefix intelligence
      description: BGP origin (ASN), RPKI validity, GeoIP distribution, open-IP count, top ports, sample scanned hosts and cert subjects observed inside a CIDR block.
      parameters:
        - { name: net,  in: path, required: true, schema: { type: string }, example: "1.1.1.0" }
        - { name: mask, in: path, required: true, schema: { type: integer, minimum: 0, maximum: 128 }, example: 24 }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PrefixIntel' }
              example:
                success: true
                cidr: "1.1.1.0/24"
                net: "1.1.1.0"
                mask: 24
                family: "IPv4"
                anycast_label: "Anycast (Cloudflare)"
                data:
                  announced_by:
                    - { asn: 13335, source: "caida-pfx2as", last_seen: "2026-07-13 22:00:00" }
                  asn_name: "Cloudflare, Inc."
                  open_ips: 42
                  top_ports:
                    - { port: 443, ips: "40" }
                  geo: { country_code: "US", country_name: "United States", continent: "NA" }
                  rpki:
                    - { asn: 13335, max_length: 24, validity: "valid", trust_anchor: "arin" }
        '422': { $ref: '#/components/responses/ValidationError' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  /domain/{domain}:
    get:
      tags: [Intelligence]
      operationId: intelDomain
      summary: Domain intelligence
      description: Current DNS records + full passive-DNS history, TLS certificates, CT-log evidence, discovered subdomains and their resolutions, Wappalyzer tech-stack, IPs citing the domain in their HTML, and origin-leak (Cloudflare-bypass) candidates.
      parameters:
        - { name: domain, in: path, required: true, schema: { type: string }, example: "check-host.cc" }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/DomainIntel' }
              example:
                success: true
                domain: "check-host.cc"
                data:
                  dns_records:
                    - { record_type: "A", value: "104.21.32.100", last_seen: "2026-07-14 08:00:00" }
                  subdomains:
                    - { subdomain: "docs.check-host.cc", source: "ct", observed_at: "2026-07-01 00:00:00" }
                  tech_stack:
                    - { technology: "Cloudflare", category: "CDN", confidence: 100 }
                  apex_stats: { sub_count: "7", hosting_ips: "3", record_types: "6", certs: "14" }
                  leak_candidates: []
        '422': { $ref: '#/components/responses/ValidationError' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  /cert/{sha256}:
    get:
      tags: [Intelligence]
      operationId: intelCert
      summary: TLS certificate intelligence
      description: Certificate subject, issuer, SANs and validity window, plus every `(ip, port)` we have observed serving it and the matching CT-log entries. Falls back to CT-log data when the cert has not been observed live yet.
      parameters:
        - { name: sha256, in: path, required: true, schema: { type: string, pattern: '^[a-f0-9]{64}$' }, example: "3a1b8f0c9d2e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f90" }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CertIntel' }
              example:
                success: true
                sha256: "3a1b8f0c9d2e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f90"
                data:
                  cert: { subject: "CN=cloudflare-dns.com", issuer: "DigiCert Global G2", sans_str: "cloudflare-dns.com, one.one.one.one", not_before: "2025-01-02 00:00:00", not_after: "2026-01-15 23:59:59", deployments: "4" }
                  served_by:
                    - { ip: "1.1.1.1", port: 443, last_seen: "2026-07-14 03:20:12" }
                  ct_logs:
                    - { operator: "Google", log_id: "argon2025", seen_at: "2025-01-02 04:00:00" }
        '422': { $ref: '#/components/responses/ValidationError' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  /port/{port}:
    get:
      tags: [Intelligence]
      operationId: intelPort
      summary: Port exposure intelligence
      description: How widespread a port is across the scanned Internet — open-IP count, most common server banners, top countries + ASNs, Wappalyzer tech-stack and a sample of recent hosts. Includes a well-known service hint.
      parameters:
        - { name: port, in: path, required: true, schema: { type: integer, minimum: 1, maximum: 65535 }, example: 443 }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PortIntel' }
              example:
                success: true
                port: 443
                well_known: "HTTPS"
                data:
                  open_ips: 48213904
                  top_servers:
                    - { server: "cloudflare", c: "5120334" }
                  top_countries:
                    - { cc: "US", ips: "12043221" }
                  top_asns:
                    - { asn: 13335, ips: "2201004", name: "Cloudflare, Inc." }
        '422': { $ref: '#/components/responses/ValidationError' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  /software/{name}:
    get:
      tags: [Intelligence]
      operationId: intelSoftware
      summary: Software / tech-stack intelligence
      description: Host counts for a detected technology, version breakdown, categories and a sample of hosts running it. Append `/{version}` to pin the stats to one version.
      parameters:
        - { name: name, in: path, required: true, schema: { type: string }, example: "nginx" }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SoftwareIntel' }
              example:
                success: true
                name: "nginx"
                version: null
                data:
                  host_count: 8412339
                  top_versions:
                    - { version: "1.24.0", c: "1204338" }
                  categories:
                    - { category: "Web servers", c: "8412339" }
        '422': { $ref: '#/components/responses/ValidationError' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  /software/{name}/{version}:
    get:
      tags: [Intelligence]
      operationId: intelSoftwareVersion
      summary: Software intelligence (version-pinned)
      description: Same as `/software/{name}`, restricted to a single version.
      parameters:
        - { name: name,    in: path, required: true, schema: { type: string }, example: "nginx" }
        - { name: version, in: path, required: true, schema: { type: string }, example: "1.24.0" }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SoftwareIntel' }
        '422': { $ref: '#/components/responses/ValidationError' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  /scan/{target}:
    get:
      tags: [Intelligence]
      operationId: intelScan
      summary: Recent fullscan jobs for a target
      description: Lists the most-recent fullscan jobs submitted for a target (IP, CIDR, domain or ASN), so clients can deep-link to a fresh report via `GET /fullscan/{uuid}/results` instead of triggering a redundant scan.
      parameters:
        - { name: target, in: path, required: true, schema: { type: string }, example: "check-host.cc" }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ScanRecent' }
              example:
                success: true
                target: "check-host.cc"
                recent_scans:
                  - { uuid: "9f2c8a14-3b6d-4e21-9a55-71b0c2d8e4f0", scope: "deep", status: "complete", subjobs_done: 5, subjobs_total: 5, created_at: "2026-07-14T09:12:44+00:00", completed_at: "2026-07-14T09:14:02+00:00" }
        '422': { $ref: '#/components/responses/ValidationError' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '500': { $ref: '#/components/responses/ServerError' }

  # ─────────────────────────────  Fullscan  ─────────────────────────────

  /fullscan:
    post:
      tags: [Fullscan]
      operationId: fullscanSubmit
      summary: Submit a fullscan job
      description: |
        Dispatches a deep, multi-stage scan of a target (IP, CIDR, domain or ASN). The manager classifies the target, fans out typed sub-jobs to dedicated workers (resolve / portscan / banner / body-fetch / threat-intel) and aggregates the results. Returns immediately with `status=pending` — poll `GET /fullscan/{uuid}` for progress and `GET /fullscan/{uuid}/results` for data.

        Anonymous CIDR submissions are capped at `/24` (v4) / `/120` (v6); an API key raises that to `/20` / `/112`.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/FullscanSubmitRequest' }
            example: { apikey: null, target: "check-host.cc", scope: "deep" }
      responses:
        '202':
          description: Accepted — job queued.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/FullscanJob' }
              example:
                success: true
                uuid: "9f2c8a14-3b6d-4e21-9a55-71b0c2d8e4f0"
                target: "check-host.cc"
                target_type: "domain"
                scope: "deep"
                status: "pending"
                subjobs_total: 0
                subjobs_done: 0
                subjobs_failed: 0
                error: null
                report_url: "https://check-host.cc/fullscan/9f2c8a14-3b6d-4e21-9a55-71b0c2d8e4f0"
                api_url: "https://check-host.cc/api/fullscan/9f2c8a14-3b6d-4e21-9a55-71b0c2d8e4f0"
        '422': { $ref: '#/components/responses/ValidationError' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '502':
          description: Scan queue unreachable — retry.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '503':
          description: Fullscan is not enabled on this deployment.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }

  /fullscan/{uuid}:
    get:
      tags: [Fullscan]
      operationId: fullscanStatus
      summary: Poll fullscan progress
      description: Returns the current job counters. Workers bump `subjobs_done`; the job moves to `status=complete` (all sub-jobs done) or `partial` (some failed). For the findings themselves, use `GET /fullscan/{uuid}/results`.
      parameters:
        - { name: uuid, in: path, required: true, schema: { type: string, format: uuid }, example: "9f2c8a14-3b6d-4e21-9a55-71b0c2d8e4f0" }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean, example: true }
                  job:     { $ref: '#/components/schemas/FullscanJob' }
        '400': { $ref: '#/components/responses/BadInput' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /fullscan/{uuid}/results:
    get:
      tags: [Fullscan]
      operationId: fullscanResults
      summary: Fetch aggregated fullscan results
      description: Returns the actual findings a fullscan produced — open ports, banners, DNS records, BGP context and TLS certificates — aggregated from ClickHouse. Partial results are available while `status=running`.
      parameters:
        - { name: uuid, in: path, required: true, schema: { type: string, format: uuid }, example: "9f2c8a14-3b6d-4e21-9a55-71b0c2d8e4f0" }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/FullscanResults' }
              example:
                success: true
                data:
                  uuid: "9f2c8a14-3b6d-4e21-9a55-71b0c2d8e4f0"
                  target: "1.1.1.1"
                  target_type: "ip"
                  scope: "deep"
                  status: "complete"
                  subjobs_total: 5
                  subjobs_done: 5
                  open_ports:
                    - { port: 443, proto: "tcp", service: "https", last_seen: "2026-07-14 09:13:11" }
                  banners:
                    - { port: 443, server_str: "cloudflare", observed_at: "2026-07-14 09:13:11" }
                  bgp: { asn: 13335, as_name: "Cloudflare, Inc.", prefix: "1.1.1.0/24", rpki_status: "valid" }
        '400': { $ref: '#/components/responses/BadInput' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }

# ──────────────────────────────────────────────────────────────────────────
components:

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: UUID
      description: >
        Pass your API key (UUID) as `Authorization: Bearer <key>`. This is the
        default and works for every endpoint, GET and POST alike, without ever
        putting the key in the URL. `X-API-Key: <key>` is also accepted, and for
        backward compatibility the key may be sent as an `apikey` field in a POST
        body — but never in the query string. All auth is optional: anonymous use
        is allowed under conservative rate limits, and a key simply lifts them.

  headers:
    X-Ratelimit-Limit:
      description: Maximum requests permitted in the current bucket window.
      schema: { type: integer, example: 60 }
    X-Ratelimit-Remaining:
      description: Requests remaining in the current bucket window. Reaches `0` immediately before the next request returns `429`.
      schema: { type: integer, example: 52 }

  responses:
    InvalidApiKey:
      description: The supplied `apikey` is not a valid UUID, is unknown, or is disabled. Anonymous use does not return this — `apikey` may simply be `null`.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
          example: { success: false, error: "Invalid or inactive API key." }
    BadInput:
      description: Bad request (missing/invalid input).
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
          example: { status: 400, error: "No target provided", success: false }
    ValidationError:
      description: Request validation failed.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
          example: { status: 422, error: "The target field is required.", success: false }
    RateLimited:
      description: Rate limit reached. Wait or supply a higher-tier API key.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
          example: { success: false, error: "Rate limit exceeded. Please slow down." }
    ServerError:
      description: Internal error.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
          example: { status: 500, error: "Internal server error.", success: false }
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
          example: { success: false, error: "Job not found." }

  schemas:

    # ─── Requests ───────────────────────────────────────────────────────

    TargetRequest:
      type: object
      required: [target]
      properties:
        apikey: { type: string, format: uuid, nullable: true, description: "Your API key (UUID). Leave null for anonymous use." }
        target: { type: string, example: "check-host.cc", description: "Hostname or IP address." }

    DNSTargetRequest:
      type: object
      required: [target]
      properties:
        apikey:      { type: string, format: uuid, nullable: true }
        target:      { type: string, example: "check-host.cc" }
        querymethod: { type: string, default: "A/AAAA", enum: [A/AAAA, A, AAAA, NS, MD, MF, CNAME, SOA, MB, MG, MR, "NULL", WKS, PTR, HINFO, MINFO, MX, TXT, SRV, EDNS, SPF, AXFR, MAILB, MAILA, ANY, CAA, DNSKEY] }
        region:      { type: array, items: { type: string }, example: ["DE"] }

    MonitoringRequest:
      type: object
      required: [target]
      properties:
        apikey:       { type: string, format: uuid, nullable: true }
        target:       { type: string, example: "check-host.cc" }
        repeatchecks: { type: integer, minimum: 0, maximum: 120, default: 0, description: "0 = single shot. ≥10 enables Live Mode (continuous probing for ~repeatchecks seconds)." }
        timeout:      { type: integer, minimum: 100, maximum: 30000, description: "Per-check timeout in milliseconds. Optional — omit to use the per-method default: ping 1000, tcp 1000, udp 2000, dns 5000, http 15000 (1000 in Live Mode). Values outside 100–30000 are rejected with 422. Note: ICMP ping applies the value at whole-second granularity, so anything below 1000 behaves as 1000." }
        region:
          type: array
          items: { type: string, example: "DE" }
          example: ["DE"]
          description: |
            Mix of:

            - Specific node names from `/locations` — e.g. `DE-NBG-Hetzner`
            - ISO country codes — e.g. `DE`, `US`, `BR`
            - Continent codes — `EU`, `NA`, `AS`, `SA`, `AF`, `OC`

            Continent codes cannot be mixed with specific node names in the same request.

            **If `region` is omitted entirely, the check fans out to every active node worldwide.** That is normally what you want for an availability check; specify a `region` to keep latency low or to test from a particular vantage point.

    MTRMonitoringRequest:
      type: object
      required: [target]
      properties:
        apikey:         { type: string, format: uuid, nullable: true }
        target:         { type: string, example: "check-host.cc" }
        repeatchecks:   { type: integer, minimum: 3, maximum: 30, default: 5, description: "Packets per hop." }
        forceIPversion: { type: integer, enum: [4, 6], nullable: true, description: "Force IPv4 or IPv6. Not all nodes support IPv6." }
        forceProtocol:  { type: string, enum: [udp, tcp], nullable: true, description: "Force UDP or TCP. Default is ICMP. Useful when ICMP is filtered." }
        timeout:        { type: integer, minimum: 100, maximum: 30000, default: 1000, description: "Runtime budget for the trace, in milliseconds for consistency with the other checks. Nodes apply it in whole seconds, so values below 1000 behave as 1000." }
        region:         { type: array, items: { type: string }, example: ["DE"] }

    # ─── Responses ──────────────────────────────────────────────────────

    MyIpResponse:
      type: object
      properties:
        status:  { type: integer, example: 200 }
        message: { type: string, example: "Your current IP is: 34.36.183.77" }
        ip:      { type: string, example: "34.36.183.77" }
        success: { type: boolean, example: true }

    InfoResponse:
      type: object
      description: Geolocation, ASN, privacy and abuse data for a host or IP.
      properties:
        ip:             { type: string, example: "34.36.183.77" }
        reverse:        { type: string, nullable: true, example: "77.183.36.34.bc.googleusercontent.com" }
        country:        { type: string, example: "United States" }
        countryCode:    { type: string, example: "US" }
        isEu:           { type: boolean, example: false }
        city:           { type: string, example: "Kansas City" }
        continent:      { type: string, example: "North America" }
        latitude:       { type: number, example: 39.09973 }
        longitude:      { type: number, example: -94.57857 }
        timeZone:       { type: string, example: "America/Chicago" }
        postalCode:     { type: string, nullable: true, example: "64101" }
        subdivision:    { type: string, nullable: true, example: "Missouri" }
        currencyCode:   { type: string, nullable: true, example: "USD" }
        callingCode:    { type: string, nullable: true, example: "1" }
        privacy:
          type: object
          properties:
            isAbuser:      { type: boolean }
            isAnonymous:   { type: boolean }
            isBogon:       { type: boolean }
            isHosting:     { type: boolean }
            isIcloudRelay: { type: boolean }
            isProxy:       { type: boolean }
            isTor:         { type: boolean }
            isVpn:         { type: boolean }
        asn:
          type: object
          nullable: true
          properties:
            asn:         { type: string, example: "AS396982" }
            route:       { type: string, example: "34.32.0.0/11" }
            netname:     { type: string, example: "GOOGLE-CLOUD-PLATFORM" }
            name:        { type: string, example: "Google LLC" }
            countryCode: { type: string, example: "US" }
            domain:      { type: string, example: "google.com" }
            type:        { type: string, example: "hosting" }
            rir:         { type: string, example: "ARIN" }
        company:
          type: object
          nullable: true
          properties:
            name:        { type: string }
            domain:      { type: string }
            countryCode: { type: string }
            type:        { type: string }
        abuse:
          type: object
          nullable: true
          properties:
            address:     { type: string }
            countryCode: { type: string }
            email:       { type: string, format: email }
            name:        { type: string }
            network:     { type: string }
            phone:       { type: string }
        success: { type: boolean, example: true }

    LocationsResponse:
      type: object
      properties:
        status:        { type: integer, example: 200 }
        CountryCodes:  { type: string, description: "Hint string — country codes are derived from `locationlist[].countryCode`." }
        Continents:    { type: array, items: { type: string }, example: ["EU"] }
        locationlist:
          type: array
          items: { $ref: '#/components/schemas/LocationItem' }

    LocationItem:
      type: object
      properties:
        continent:          { type: string, example: "EU" }
        country:            { type: string, example: "Germany" }
        countryCode:        { type: string, example: "DE" }
        city:               { type: string, example: "Nuernberg" }
        asn:                { type: string, example: "AS24940" }
        isp:                { type: string, example: "Hetzner Online GmbH" }
        datacenter:         { type: string, example: "Hetzner" }
        monitoring_allowed: { type: integer, example: 1 }
        hostname:           { type: string, nullable: true, example: "de-nbg-het.check-host.eu" }
        locationname:       { type: string, example: "DE-NBG-Hetzner", description: "Use this in `region` to target this exact node." }
        sponsor:            { type: string, nullable: true }
        sponsor_url:        { type: string, nullable: true, format: uri }
        latitude:           { type: number, nullable: true }
        longitude:          { type: number, nullable: true }

    CheckCreated:
      type: object
      properties:
        status:       { type: integer, example: 200 }
        success:      { type: boolean, example: true }
        target:       { type: string, example: "check-host.cc" }
        method:       { type: string, example: "ping" }
        repeatchecks: { type: integer, example: 0 }
        region:       { type: array, items: { type: string }, example: ["DE"] }
        uuid:         { type: string, format: uuid }
        reportURL:    { type: string, format: uri, example: "https://check-host.cc/report/0710831d-1589-47d4-9fc1-885fe33a25e4" }
        apiURL:       { type: string, format: uri, example: "https://api.check-host.cc/report/0710831d-1589-47d4-9fc1-885fe33a25e4" }
        og-imageURL:  { type: string, format: uri }
        autodelete:   { type: string, example: "12-05-2036", description: "DD-MM-YYYY. Reports are kept ~10 years." }
        message:      { type: string, example: "Broadcasted task to all slaves." }
        port:         { type: integer, nullable: true }
        query:        { type: string, nullable: true, description: "DNS record type when method is `dns`." }
        payload:      { type: string, nullable: true, description: "UDP payload echoed back (hex string)." }

    CheckReport:
      type: object
      properties:
        status:       { type: integer, example: 200 }
        success:      { type: boolean, example: true }
        target:       { type: string }
        method:       { type: string, enum: [ping, tcp, udp, http, dns, mtr] }
        query:        { type: string, nullable: true }
        repeatchecks: { type: integer }
        created_at:   { type: string, format: date-time }
        delete_at:    { type: string }
        payload:      { type: string, nullable: true }
        data:
          type: object
          additionalProperties: { $ref: '#/components/schemas/ReportLocation' }
          description: "Map keyed by `locationname`. Empty until at least one node has reported."

    ReportLocation:
      type: object
      properties:
        id:                 { type: integer }
        continent:          { type: string }
        country:            { type: string }
        countryCode:        { type: string }
        city:               { type: string }
        isp:                { type: string }
        asn:                { type: string }
        datacenter:         { type: string }
        monitoring_allowed: { type: integer }
        rabbitmq_queue:     { type: string }
        locationname:       { type: string }
        hostname:           { type: string, nullable: true }
        sponsor:            { type: string, nullable: true }
        sponsor_url:        { type: string, nullable: true }
        latitude:           { type: number, nullable: true }
        longitude:          { type: number, nullable: true }
        checks:
          oneOf:
            - { type: array, items: { $ref: '#/components/schemas/PingCheck' }, description: "ping/tcp/udp" }
            - { $ref: '#/components/schemas/HttpCheck' }
            - { $ref: '#/components/schemas/DnsCheck' }
            - { $ref: '#/components/schemas/MtrCheck' }

    PingCheck:
      type: object
      description: Single probe result for ping, tcp, or udp.
      properties:
        location_id:    { type: integer }
        slave_id:       { type: integer }
        repeat:         { type: integer }
        connectiontime: { type: number, description: "Milliseconds. 0 = sub-millisecond." }
        target_ip:      { type: string }
        errortext:      { type: string }
        status:         { type: integer, enum: [0, 1], description: "1 = success, 0 = fail." }

    HttpCheck:
      type: array
      items:
        type: object
        properties:
          location_id:     { type: integer }
          slave_id:        { type: integer }
          repeat:          { type: integer }
          connectiontime:  { type: number }
          http_status:     { type: integer, example: 200 }
          http_statustext: { type: string,  example: "OK" }
          target_ip:       { type: string }
          status:          { type: integer, enum: [0, 1] }

    DnsCheck:
      type: object
      description: DNS lookup result (single object, not an array).
      properties:
        location_id: { type: integer }
        slave_id:    { type: integer }
        data:
          type: array
          items:
            type: object
            properties:
              ttl:      { type: integer, example: 300 }
              address:  { type: string,  example: "34.36.183.77", description: "For A/AAAA records." }
              data:     { type: string,  description: "For TXT/MX/CNAME records." }
              exchange: { type: string,  description: "For MX records." }
              ns:       { type: string,  description: "For NS records." }
        errortext: { type: string }
        status:    { type: integer, enum: [0, 1] }

    MtrCheck:
      type: object
      description: MTR result (single object). `data.hubs` is the per-hop list.
      properties:
        location_id: { type: integer }
        slave_id:    { type: integer }
        data:
          type: object
          properties:
            mtr:
              type: object
              properties:
                src:        { type: string }
                dst:        { type: string }
                tos:        { type: integer }
                tests:      { type: integer }
                psize:      { type: string }
                bitpattern: { type: string }
            hubs:
              type: array
              items:
                type: object
                properties:
                  count:   { type: integer, description: "Hop number (1-indexed)." }
                  host:    { type: string,  description: "Hop IP, or `-` for an unresponsive hop." }
                  Loss%:   { type: number }
                  Snt:     { type: integer }
                  Last:    { type: number }
                  Avg:     { type: number }
                  Best:    { type: number }
                  Wrst:    { type: number }
                  StDev:   { type: number }
                  ASN:     { type: string }
                  PTR:     { type: string }
        errortext: { type: string }
        status:    { type: integer, enum: [0, 1] }

    ErrorResponse:
      type: object
      properties:
        status:  { type: integer, example: 400 }
        success: { type: boolean, example: false }
        error:   { type: string,  example: "No target provided" }

    # ─── Intelligence / Fullscan ────────────────────────────────────────

    IntelData:
      type: object
      additionalProperties: true
      description: "Section map. Arrays are empty and scalars `null` where we hold no data yet — see each endpoint's example for the populated shape."

    IpIntel:
      type: object
      properties:
        success: { type: boolean, example: true }
        ip:      { type: string, example: "1.1.1.1" }
        family:  { type: string, enum: [IPv4, IPv6] }
        data:
          allOf: [ { $ref: '#/components/schemas/IntelData' } ]
          description: >-
            Sections: `ptr`, `open_ports`, `banners`, `tls_certs`,
            `co_hosted_domains`, `external_refs`, `leak_candidates`, `titles`,
            `techs`, `bgp`, `geo`, `probe_findings`, `threat_matches`,
            `threat_count`, `honeypot`, `honeypot_recent` (passwords masked as
            `password_captured` + `password_len`), `honeypot_actor`,
            `honeypot_ja`, `honeypot_classes`.

    AsnIntel:
      type: object
      properties:
        success: { type: boolean, example: true }
        asn:     { type: integer, example: 13335 }
        as_name: { type: string, nullable: true, example: "Cloudflare, Inc." }
        data:    { $ref: '#/components/schemas/IntelData' }

    PrefixIntel:
      type: object
      properties:
        success:       { type: boolean, example: true }
        cidr:          { type: string, example: "1.1.1.0/24" }
        net:           { type: string, example: "1.1.1.0" }
        mask:          { type: integer, example: 24 }
        family:        { type: string, enum: [IPv4, IPv6] }
        anycast_label: { type: string, nullable: true, example: "Anycast (Cloudflare)" }
        data:          { $ref: '#/components/schemas/IntelData' }

    DomainIntel:
      type: object
      properties:
        success: { type: boolean, example: true }
        domain:  { type: string, example: "check-host.cc" }
        data:    { $ref: '#/components/schemas/IntelData' }

    CertIntel:
      type: object
      properties:
        success: { type: boolean, example: true }
        sha256:  { type: string, example: "3a1b8f0c9d2e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f90" }
        data:    { $ref: '#/components/schemas/IntelData' }

    PortIntel:
      type: object
      properties:
        success:    { type: boolean, example: true }
        port:       { type: integer, example: 443 }
        well_known: { type: string, nullable: true, example: "HTTPS" }
        data:       { $ref: '#/components/schemas/IntelData' }

    SoftwareIntel:
      type: object
      properties:
        success: { type: boolean, example: true }
        name:    { type: string, example: "nginx" }
        version: { type: string, nullable: true }
        data:    { $ref: '#/components/schemas/IntelData' }

    ScanRecent:
      type: object
      properties:
        success: { type: boolean, example: true }
        target:  { type: string, example: "check-host.cc" }
        recent_scans:
          type: array
          items: { $ref: '#/components/schemas/FullscanJob' }

    FullscanSubmitRequest:
      type: object
      required: [target]
      properties:
        apikey: { type: string, format: uuid, nullable: true, description: "Optional API key (UUID). Required for custom probe recipes and larger CIDR ranges." }
        target: { type: string, example: "check-host.cc", description: "IPv4/IPv6 address, CIDR block, domain or AS number." }
        scope:  { type: string, enum: [basic, deep, full], default: deep, description: "`basic` = top-100 ports + banner; `deep` = full port range + TLS + body + threat-intel; `full` = deep + subdomain enumeration (domains only)." }

    FullscanJob:
      type: object
      description: Master job row (the shape returned by submit, status, and each entry in `/scan`).
      properties:
        success:        { type: boolean, example: true }
        uuid:           { type: string, format: uuid }
        target:         { type: string, example: "check-host.cc" }
        target_type:    { type: string, enum: [ip, cidr, domain, asn] }
        scope:          { type: string, enum: [basic, deep, full] }
        status:         { type: string, enum: [pending, running, complete, partial, failed] }
        subjobs_total:  { type: integer, example: 5 }
        subjobs_done:   { type: integer, example: 5 }
        subjobs_failed: { type: integer, example: 0 }
        error:          { type: string, nullable: true }
        created_at:     { type: string, format: date-time, nullable: true }
        completed_at:   { type: string, format: date-time, nullable: true }
        report_url:     { type: string, format: uri }
        api_url:        { type: string, format: uri }

    FullscanResults:
      type: object
      properties:
        success: { type: boolean, example: true }
        data:
          allOf:
            - $ref: '#/components/schemas/FullscanJob'
            - type: object
              properties:
                open_ports:  { type: array, items: { type: object } }
                banners:     { type: array, items: { type: object } }
                dns_records: { type: array, items: { type: object } }
                bgp:         { type: object, nullable: true }
                tls_certs:   { type: array, items: { type: object } }

  examples:

    InfoCheckHost:
      summary: /info for check-host.cc
      value:
        ip: "34.36.183.77"
        reverse: "77.183.36.34.bc.googleusercontent.com"
        country: "United States"
        countryCode: "US"
        isEu: false
        city: "Kansas City"
        continent: "North America"
        latitude: 39.09973
        longitude: -94.57857
        timeZone: "America/Chicago"
        postalCode: "64101"
        subdivision: "Missouri"
        currencyCode: "USD"
        callingCode: "1"
        privacy: { isAbuser: false, isAnonymous: false, isBogon: false, isHosting: true, isIcloudRelay: false, isProxy: false, isTor: false, isVpn: false }
        asn: { asn: "AS396982", route: "34.32.0.0/11", netname: "GOOGLE-CLOUD-PLATFORM", name: "Google LLC", countryCode: "US", domain: "google.com", type: "hosting", rir: "ARIN" }
        company: { name: "Google LLC", domain: "google.com", countryCode: "US", type: "hosting" }
        abuse: { address: "1600 Amphitheatre Parkway, Mountain View, CA, 94043, US", countryCode: "US", email: "google-cloud-compliance@google.com", name: "Google LLC", network: "34.4.5.0 - 34.63.255.255", phone: "+1-650-253-0000" }
        success: true

    ReportPing:
      summary: Completed Ping report (1 node, DE region)
      value:
        status: 200
        success: true
        target: "check-host.cc"
        method: "ping"
        query: null
        repeatchecks: 0
        created_at: "2026-05-12T00:30:43.000000Z"
        delete_at: "2036-05-12 02:30:43"
        payload: null
        data:
          DE-NBG-Hetzner:
            id: 8
            continent: "EU"
            country: "Germany"
            countryCode: "DE"
            city: "Nuernberg"
            isp: "Hetzner Online GmbH"
            asn: "AS24940"
            datacenter: "Hetzner"
            monitoring_allowed: 1
            rabbitmq_queue: "DE-NBG-Hetzner"
            locationname: "DE-NBG-Hetzner"
            hostname: "de-nbg-het.check-host.eu"
            sponsor: null
            sponsor_url: null
            latitude: null
            longitude: null
            checks:
              - { location_id: 8, slave_id: 1, repeat: 0, connectiontime: 4, target_ip: "34.36.183.77", errortext: "", status: 1 }

    ReportHttp:
      summary: Completed HTTP report (single shot)
      value:
        status: 200
        success: true
        target: "https://check-host.cc"
        method: "http"
        query: null
        repeatchecks: 0
        created_at: "2026-05-12T00:31:00.000000Z"
        delete_at: "2036-05-12 02:31:00"
        payload: null
        data:
          DE-NBG-Hetzner:
            id: 8
            continent: "EU"
            country: "Germany"
            countryCode: "DE"
            city: "Nuernberg"
            isp: "Hetzner Online GmbH"
            asn: "AS24940"
            datacenter: "Hetzner"
            monitoring_allowed: 1
            rabbitmq_queue: "DE-NBG-Hetzner"
            locationname: "DE-NBG-Hetzner"
            hostname: "de-nbg-het.check-host.eu"
            sponsor: null
            sponsor_url: null
            latitude: null
            longitude: null
            checks:
              - { location_id: 8, slave_id: 1, repeat: 0, connectiontime: 20, http_status: 200, http_statustext: "OK", target_ip: "34.36.183.77", status: 1 }

    ReportHttpLive:
      summary: Completed HTTP report in Live mode (repeatchecks=15 → 16 entries)
      value:
        status: 200
        success: true
        target: "https://check-host.cc"
        method: "http"
        query: null
        repeatchecks: 15
        created_at: "2026-05-12T00:31:30.000000Z"
        delete_at: "2036-05-12 02:31:30"
        payload: null
        data:
          DE-NBG-Hetzner:
            id: 8
            continent: "EU"
            country: "Germany"
            countryCode: "DE"
            city: "Nuernberg"
            isp: "Hetzner Online GmbH"
            asn: "AS24940"
            datacenter: "Hetzner"
            monitoring_allowed: 1
            rabbitmq_queue: "DE-NBG-Hetzner"
            locationname: "DE-NBG-Hetzner"
            hostname: "de-nbg-het.check-host.eu"
            sponsor: null
            sponsor_url: null
            latitude: null
            longitude: null
            checks:
              - { location_id: 8, slave_id: 1, repeat: 0,  connectiontime: 35, http_status: 200, http_statustext: "OK", target_ip: "34.36.183.77", status: 1 }
              - { location_id: 8, slave_id: 1, repeat: 1,  connectiontime: 12, http_status: 200, http_statustext: "OK", target_ip: "34.36.183.77", status: 1 }
              - { location_id: 8, slave_id: 1, repeat: 2,  connectiontime: 14, http_status: 200, http_statustext: "OK", target_ip: "34.36.183.77", status: 1 }
              # … entries 3–14 elided …
              - { location_id: 8, slave_id: 1, repeat: 15, connectiontime: 13, http_status: 200, http_statustext: "OK", target_ip: "34.36.183.77", status: 1 }

    ReportDns:
      summary: Completed DNS A-record report — note `checks` is an object, not an array
      value:
        status: 200
        success: true
        target: "check-host.cc"
        method: "dns"
        query: "A"
        repeatchecks: 0
        created_at: "2026-05-12T00:31:01.000000Z"
        delete_at: "2036-05-12 02:31:01"
        payload: null
        data:
          DE-NBG-Hetzner:
            id: 8
            continent: "EU"
            country: "Germany"
            countryCode: "DE"
            city: "Nuernberg"
            isp: "Hetzner Online GmbH"
            asn: "AS24940"
            datacenter: "Hetzner"
            monitoring_allowed: 1
            rabbitmq_queue: "DE-NBG-Hetzner"
            locationname: "DE-NBG-Hetzner"
            hostname: "de-nbg-het.check-host.eu"
            sponsor: null
            sponsor_url: null
            latitude: null
            longitude: null
            checks:
              location_id: 8
              slave_id: 1
              data:
                - { ttl: 300, address: "34.36.183.77" }
              errortext: ""
              status: 1

    ReportMtr:
      summary: Completed MTR report (truncated — `hubs` lists every hop)
      value:
        status: 200
        success: true
        target: "check-host.cc"
        method: "mtr"
        query: null
        repeatchecks: 5
        created_at: "2026-05-12T00:31:01.000000Z"
        delete_at: "2036-05-12 02:31:01"
        payload: null
        data:
          DE-NBG-Hetzner:
            id: 8
            continent: "EU"
            country: "Germany"
            countryCode: "DE"
            city: "Nuernberg"
            isp: "Hetzner Online GmbH"
            asn: "AS24940"
            datacenter: "Hetzner"
            monitoring_allowed: 1
            rabbitmq_queue: "DE-NBG-Hetzner"
            locationname: "DE-NBG-Hetzner"
            hostname: "de-nbg-het.check-host.eu"
            sponsor: null
            sponsor_url: null
            latitude: null
            longitude: null
            checks:
              location_id: 8
              slave_id: 1
              data:
                mtr: { src: "e6a6076aff2d", dst: "34.36.183.77", tos: 0, tests: 5, psize: "64", bitpattern: "0x00" }
                hubs:
                  - { count: 1, host: "172.19.0.1",      "Loss%": 0,   Snt: 5, Last: 0.197, Avg: 0.214, Best: 0.168, Wrst: 0.318, StDev: 0.059, ASN: "-",       PTR: "-" }
                  - { count: 2, host: "172.31.1.1",      "Loss%": 0,   Snt: 5, Last: 2.785, Avg: 2.933, Best: 2.196, Wrst: 3.562, StDev: 0.498, ASN: "-",       PTR: "-" }
                  - { count: 3, host: "116.203.161.165", "Loss%": 0,   Snt: 5, Last: 0.396, Avg: 0.549, Best: 0.353, Wrst: 0.908, StDev: 0.218, ASN: "AS24940", PTR: "12936.your-cloud.host" }
                  - { count: 4, host: "-",               "Loss%": 100, Snt: 5, Last: 0,     Avg: 0,     Best: 0,     Wrst: 0,     StDev: 0,     ASN: "-",       PTR: "-" }
              errortext: ""
              status: 1