---
title: "Create new Discovery"
method: POST
path: "/api/v1/discovery"
tags: ["Discoveries"]
---

# Create new Discovery

`POST /api/v1/discovery`

## Request body

- Discovery
  - `daemon_id` string, uuid, required
  - `discovery_type` union, required
    - object
      - `host_id` string, uuid, required
      - `type` 'SelfReport', required
    - object
      - `host_naming_fallback` 'Ip' | 'BestService', required
      - `snmp_credentials` object — SNMP credentials for querying devices during discovery Server builds this mapping before initiating discovery
      - `subnet_ids` string[], nullable, required
      - `type` 'Network', required
    - object
      - `host_id` string, uuid, required
      - `host_naming_fallback` 'Ip' | 'BestService', required
      - `type` 'Docker', required
    - object
      - `host_id` string, uuid, required — ID of the host that the daemon is running on
      - `host_naming_fallback` 'Ip' | 'BestService', required
      - `scan_settings` ScanSettings — Scan performance settings. Lives on the discovery entity. Numeric fields are `Option<T>` — `None` means "use daemon default". The daemon unwraps with defaults at point of use.
        - `arp_rate_pps` integer, nullable — ARP packets per second (default: 50)
        - `arp_retries` integer, nullable — ARP retry rounds for non-responsive targets (default: 2 = 3 total attempts)
        - `arp_scan_cutoff` integer, nullable — ARP scan cutoff prefix. Interfaced subnets larger than this prefix are truncated to this many IPs. Default: 15 (= /15, ~131K IPs). Lower values scan more IPs — increase arp_rate_pps accordingly.
        - `full_scan_interval` integer, nullable — Run a full 65k port scan every N scans. Other scans use a light port set. Default: 3. Value of 0 means never full scan. Value of 1 means every scan is full.
        - `is_full_scan` boolean — Whether this specific scan run should do a full 65k port scan. Set by the server before dispatching to the daemon — not user-configurable.
        - `port_scan_batch_size` integer, nullable — Ports scanned concurrently per host (default: 200, clamped 16-1000)
        - `probe_raw_socket_ports` boolean — Whether to probe raw-socket ports 9100-9107 (default: false). Disabled by default to prevent ghost printing on JetDirect printers.
        - `scan_rate_pps` integer, nullable — Port scan probes per second (default: 500)
        - `use_npcap_arp` boolean — On Windows, use Npcap broadcast ARP instead of SendARP (default: false)
      - `subnet_ids` string[], nullable, required — Subnets to scan. None = scan all interfaced subnets.
      - `type` 'Unified', required
  - `name` string, required
  - `network_id` string, uuid, required
  - `run_type` union, required
    - object
      - `cron_schedule` string, required
      - `enabled` boolean, required
      - `last_run` string, date-time, nullable
      - `timezone` string, nullable — IANA timezone for cron evaluation, e.g. "America/New_York". None = UTC.
      - `type` 'Scheduled', required
    - object — Historical discovery runs are created by the server and cannot be submitted via API
      - `results` DiscoveryUpdatePayload, required — Progress update from daemon to server during discovery
        - `daemon_id` string, uuid, required
        - `discovery_id` string, uuid, nullable — The discovery configuration this session belongs to. Always enriched server-side; daemons do not send this field.
        - `discovery_type` union, required
          - object
            - `host_id` string, uuid, required
            - `type` 'SelfReport', required
          - object
            - `host_naming_fallback` 'Ip' | 'BestService', required
            - `snmp_credentials` object — SNMP credentials for querying devices during discovery Server builds this mapping before initiating discovery
            - `subnet_ids` string[], nullable, required
            - `type` 'Network', required
          - object
            - `host_id` string, uuid, required
            - `host_naming_fallback` 'Ip' | 'BestService', required
            - `type` 'Docker', required
          - object
            - `host_id` string, uuid, required — ID of the host that the daemon is running on
            - `host_naming_fallback` 'Ip' | 'BestService', required
            - `scan_settings` ScanSettings — Scan performance settings. Lives on the discovery entity. Numeric fields are `Option<T>` — `None` means "use daemon default". The daemon unwraps with defaults at point of use.
              - …
            - `subnet_ids` string[], nullable, required — Subnets to scan. None = scan all interfaced subnets.
            - `type` 'Unified', required
        - `error` string, nullable
        - `estimated_remaining_secs` integer, nullable
        - `finished_at` string, date-time, nullable
        - `hosts_discovered` integer, nullable
        - `network_id` string, uuid, required
        - `phase` 'Queued' | 'Pending' | 'Starting' | 'Started' | 'Scanning' | 'Complete' | 'Failed' | 'Cancelled', required
        - `progress` integer, required
        - `session_id` string, uuid, required
        - `started_at` string, date-time, nullable
      - `type` 'Historical', required
    - object
      - `last_run` string, date-time, nullable
      - `type` 'AdHoc', required
  - `tags` string[], required
  - `created_at` string, date-time, required
  - `force_full_scan` boolean — When true, the next scan will be a full port scan regardless of interval
  - `id` string, uuid, required
  - `pending_credential_ids` string[] — Credential IDs to include in the next scan's credential_mappings. Set by the discovery edit modal, cleared after each scan completes.
  - `scan_count` integer — Number of completed scans (incremented by server on session completion)
  - `updated_at` string, date-time, required

## Response `200`

Discovery created successfully

- ApiResponseDiscovery
  - `data` object
    - `daemon_id` string, uuid, required
    - `discovery_type` union, required
      - object
        - `host_id` string, uuid, required
        - `type` 'SelfReport', required
      - object
        - `host_naming_fallback` 'Ip' | 'BestService', required
        - `snmp_credentials` object — SNMP credentials for querying devices during discovery Server builds this mapping before initiating discovery
        - `subnet_ids` string[], nullable, required
        - `type` 'Network', required
      - object
        - `host_id` string, uuid, required
        - `host_naming_fallback` 'Ip' | 'BestService', required
        - `type` 'Docker', required
      - object
        - `host_id` string, uuid, required — ID of the host that the daemon is running on
        - `host_naming_fallback` 'Ip' | 'BestService', required
        - `scan_settings` ScanSettings — Scan performance settings. Lives on the discovery entity. Numeric fields are `Option<T>` — `None` means "use daemon default". The daemon unwraps with defaults at point of use.
          - `arp_rate_pps` integer, nullable — ARP packets per second (default: 50)
          - `arp_retries` integer, nullable — ARP retry rounds for non-responsive targets (default: 2 = 3 total attempts)
          - `arp_scan_cutoff` integer, nullable — ARP scan cutoff prefix. Interfaced subnets larger than this prefix are truncated to this many IPs. Default: 15 (= /15, ~131K IPs). Lower values scan more IPs — increase arp_rate_pps accordingly.
          - `full_scan_interval` integer, nullable — Run a full 65k port scan every N scans. Other scans use a light port set. Default: 3. Value of 0 means never full scan. Value of 1 means every scan is full.
          - `is_full_scan` boolean — Whether this specific scan run should do a full 65k port scan. Set by the server before dispatching to the daemon — not user-configurable.
          - `port_scan_batch_size` integer, nullable — Ports scanned concurrently per host (default: 200, clamped 16-1000)
          - `probe_raw_socket_ports` boolean — Whether to probe raw-socket ports 9100-9107 (default: false). Disabled by default to prevent ghost printing on JetDirect printers.
          - `scan_rate_pps` integer, nullable — Port scan probes per second (default: 500)
          - `use_npcap_arp` boolean — On Windows, use Npcap broadcast ARP instead of SendARP (default: false)
        - `subnet_ids` string[], nullable, required — Subnets to scan. None = scan all interfaced subnets.
        - `type` 'Unified', required
    - `name` string, required
    - `network_id` string, uuid, required
    - `run_type` union, required
      - object
        - `cron_schedule` string, required
        - `enabled` boolean, required
        - `last_run` string, date-time, nullable
        - `timezone` string, nullable — IANA timezone for cron evaluation, e.g. "America/New_York". None = UTC.
        - `type` 'Scheduled', required
      - object — Historical discovery runs are created by the server and cannot be submitted via API
        - `results` DiscoveryUpdatePayload, required — Progress update from daemon to server during discovery
          - `daemon_id` string, uuid, required
          - `discovery_id` string, uuid, nullable — The discovery configuration this session belongs to. Always enriched server-side; daemons do not send this field.
          - `discovery_type` union, required
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
          - `error` string, nullable
          - `estimated_remaining_secs` integer, nullable
          - `finished_at` string, date-time, nullable
          - `hosts_discovered` integer, nullable
          - `network_id` string, uuid, required
          - `phase` 'Queued' | 'Pending' | 'Starting' | 'Started' | 'Scanning' | 'Complete' | 'Failed' | 'Cancelled', required
          - `progress` integer, required
          - `session_id` string, uuid, required
          - `started_at` string, date-time, nullable
        - `type` 'Historical', required
      - object
        - `last_run` string, date-time, nullable
        - `type` 'AdHoc', required
    - `tags` string[], required
    - `created_at` string, date-time, required
    - `force_full_scan` boolean — When true, the next scan will be a full port scan regardless of interval
    - `id` string, uuid, required
    - `pending_credential_ids` string[] — Credential IDs to include in the next scan's credential_mappings. Set by the discovery edit modal, cleared after each scan completes.
    - `scan_count` integer — Number of completed scans (incremented by server on session completion)
    - `updated_at` string, date-time, required
  - `error` string, nullable
  - `meta` ApiMeta, required — API metadata included in all responses
    - `api_version` integer, required — API version (integer, increments on breaking changes)
    - `server_version` string, required — Server version (semver)
  - `success` boolean, required

## Other responses

- `400` — Can't create historical discovery

## Changes

- **2026-04-20** `f04499e2280f` — 2 breaking, 3 warning, 3 info
  - removed the enum value `AwaitingSnapshot` of the request property `allOf[#/components/schemas/DiscoveryBase]/run_type/oneOf[subschema #2: Historical]/results/phase`
  - removed the required property `data/allOf[subschema #2]/integration_targets` from the response with the `200` status
  - removed the request property `allOf[#/components/schemas/DiscoveryBase]/run_type/oneOf[subschema #2: Historical]/results/scanned`
  - removed the request property `allOf[subschema #2]/integration_targets`
  - …4 more

[Change history](https://skmtc.dev/scanopy/apis/scanopy-api/changes/api/v1/discovery/post.md)

---

[API](https://skmtc.dev/scanopy/apis/scanopy-api.md) · [All operations](https://skmtc.dev/scanopy/apis/scanopy-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/scanopy/scanopy-api/revisions/f04499e2280f/schema)