API Asset Discovery¶

Asset Discovery regularly searches for hosts and web applications under your domains that are not yet in your scan scope. These endpoints do everything the Asset Discovery pages do.

Discovered assets are grouped by the apex domain they were found under. Each asset has a discovered asset status: new assets are pending, and can be added to scope or suppressed.

A typical workflow:

GET /api/v1/(api_key)/discovery/groups to see which domains have pending assets.
GET /api/v1/(api_key)/discovery/group/(group_id) to review a group’s assets.
POST /api/v1/(api_key)/discovery/add to add the ones you want to scan, and POST /api/v1/(api_key)/discovery/suppress for the ones you don’t.

Asset Discovery must be enabled for your organisation. Adding, suppressing and restoring assets also require the API user to be allowed to manage the organisation’s scope; trial organisations can view discovered assets but not change them.

GET /api/v1/(api_key)/discovery/groups¶

New in version 1.7.0.

List the apex domains that discovered assets are grouped under, with how many assets each has that match the filters. Only groups with at least one matching asset are listed.

Example request:

GET /api/v1/44df57d3f5a479e334e622f314787dcc/discovery/groups?scope_type=Application HTTP/1.1
Host: api.appcheck-ng.com
Accept-Encoding: identity

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 15 Oct 2026 11:23:50 GMT

{
  "data": [
    {
      "apex_domain": "example.com",
      "count": 12,
      "favicon": "https://example.com/favicon.ico",
      "group_id": "6a1f0c2e9b3d4e57"
    }
  ],
  "message": "Groups found: 1",
  "success": true
}

Query Parameters:
Parameters:	api_key (string) – Your API key
	status (string) – discovered asset status to list: `pending` (default) or `added_to_scope` suppressed_only (boolean) – `1` to list `suppressed` assets instead; overrides `status` search (string) – only assets whose discovered target contains this text (case-insensitive) port (int) – only assets on this port scope_type (string) – only `Application` or only `Infrastructure` assets
Response Headers:
	Content-Type – application/json
Response JSON Object:
	success (boolean) – operation was successful message (string) – human readable response data (objects) – list of groups
Response JSON Array of Objects:
	group_id (string) – ID of the group, for `GET /api/v1/(api_key)/discovery/group/(group_id)` and the bulk actions apex_domain (string) – the apex domain the group’s assets were discovered under favicon (string) – URL of the domain’s favicon, if one was found count (int) – number of assets in the group that match the filters
Status Codes:	400 Bad Request – access denied

See also:

GET /api/v1/(api_key)/discovery/group/(group_id)

GET /api/v1/(api_key)/discovery/group/(group_id)¶

New in version 1.7.0.

List the discovered assets in one group, most recently discovered first.

Example request:

GET /api/v1/44df57d3f5a479e334e622f314787dcc/discovery/group/6a1f0c2e9b3d4e57?limit=50&page=1 HTTP/1.1
Host: api.appcheck-ng.com
Accept-Encoding: identity

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 15 Oct 2026 11:23:50 GMT

{
  "count": 12,
  "data": [
    {
      "added_to_scope_date": null,
      "apex_domain": "example.com",
      "asset_id": "7c2d91a04f6b3e18",
      "cname": null,
      "discovered_target": "shop.example.com",
      "discovery_source": "shodan",
      "favicon": null,
      "first_discovered": 1760083200,
      "geo_location": "GB",
      "ip_address": "203.0.113.10",
      "is_ssl": true,
      "last_discovered": 1760515200,
      "page_title": "Example Shop",
      "parent_cname": "-",
      "ports": [443],
      "queried_target": "example.com",
      "redirect_url": null,
      "scope_type": "Application",
      "screenshot": null,
      "status": "pending",
      "status_code": 200,
      "web_server": "nginx"
    }
  ],
  "message": "Assets found: 12",
  "success": true
}

Query Parameters:
Parameters:	api_key (string) – Your API key group_id (string) – ID of the group, from `GET /api/v1/(api_key)/discovery/groups`
	status (string) – discovered asset status to list: `pending` (default) or `added_to_scope` suppressed_only (boolean) – `1` to list `suppressed` assets instead; overrides `status` search (string) – only assets whose discovered target contains this text (case-insensitive) port (int) – only assets on this port scope_type (string) – only `Application` or only `Infrastructure` assets limit (int) – assets per page, 1 to 250 (default 250) page (int) – page number, starting at 1 (default 1)
Response Headers:
	Content-Type – application/json
Response JSON Object:
	success (boolean) – operation was successful message (string) – human readable response count (int) – total number of matching assets in the group, across all pages data (objects) – the assets on this page
Response JSON Array of Objects:
	asset_id (string) – ID of the asset, for the bulk actions discovered_target (string) – the host name or IP address that was discovered queried_target (string) – what was searched for when it was found apex_domain (string) – the apex domain it was found under scope_type (string) – `Application` (a web application) or `Infrastructure` (a host) status (string) – its discovered asset status ports (ints) – the port it was found on ip_address (string) – IP address the target resolved to geo_location (string) – where the IP address is located cname (string) – the target’s CNAME, if any parent_cname (string) – the CNAME of the hosting service, if any is_ssl (boolean) – whether the service uses TLS status_code (int) – HTTP status code returned, for web applications redirect_url (string) – where the page redirected to, if it did page_title (string) – title of the page, for web applications web_server (string) – web server software reported favicon (string) – URL of the favicon, if one was found screenshot (string) – URL of a screenshot, if one was taken discovery_source (string) – where the asset was discovered first_discovered (int) – timestamp when the asset was first discovered last_discovered (int) – timestamp when the asset was last discovered added_to_scope_date (int) – timestamp when it was added to scope (or null)
Status Codes:	400 Bad Request – access denied

See also:

GET /api/v1/(api_key)/discovery/groups
POST /api/v1/(api_key)/discovery/add
POST /api/v1/(api_key)/discovery/suppress

POST /api/v1/(api_key)/discovery/add¶

New in version 1.7.0.

Add pending discovered assets to your scan scope, either a whole group or chosen assets.

Example request:

POST /api/v1/44df57d3f5a479e334e622f314787dcc/discovery/add HTTP/1.1
Host: api.appcheck-ng.com
Accept-Encoding: identity
Content-Type: application/x-www-form-urlencoded

asset_ids=7c2d91a04f6b3e18,7c2d91a04f6b3e19

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 15 Oct 2026 11:23:50 GMT

{
  "data": {
    "count": 2,
    "scope_change": "applied",
    "targets": ["https://shop.example.com", "https://admin.example.com:8443"]
  },
  "message": "Successfully added 2 assets to scope",
  "success": true
}

Form Parameters:
Parameters:	api_key (string) – Your API key
	group_id – add every `pending` asset in this group asset_ids – add these assets: a comma-separated list of IDs, or the field repeated once per ID. Every asset must exist and be `pending`. Send either `group_id` or `asset_ids`, not both
Response Headers:
	Content-Type – application/json
Response JSON Object:
	success (boolean) – operation was successful message (string) – human readable response data.count (int) – number of assets added data.targets (strings) – the scope targets they were added as. Web applications become `https://host` (`http://` on port 80), with the port appended if it is not 80 or 443 data.scope_change (string) – what happened to your scope, see below
Status Codes:	400 Bad Request – access denied

The API user must be allowed to manage the organisation’s scope. Nothing is added if any of the assets cannot be: if one is not pending, if a target is on the AppCheck blacklist, or if adding them would take you over your licensed number of web applications or infrastructure hosts. Use GET /api/v1/(api_key)/discovery/stats to see what is left, and POST /api/v1/(api_key)/discovery/upgrade to ask for more.

data.scope_change is one of:

applied: the targets were added to your scope.
pending_approval: your organisation requires scope changes to be approved, and the change is waiting for approval. The assets are marked added_to_scope now.
unchanged: the targets were already in scope, or another scope change is already waiting for approval.

See also:

GET /api/v1/(api_key)/discovery/group/(group_id)
GET /api/v1/(api_key)/discovery/stats

POST /api/v1/(api_key)/discovery/suppress¶

New in version 1.7.0.

Suppress pending discovered assets, so they are no longer listed as pending or included in the pending asset emails. Suppressed assets can be listed with suppressed_only=1 and restored with POST /api/v1/(api_key)/discovery/unsuppress.

Example request:

POST /api/v1/44df57d3f5a479e334e622f314787dcc/discovery/suppress HTTP/1.1
Host: api.appcheck-ng.com
Accept-Encoding: identity
Content-Type: application/x-www-form-urlencoded

group_id=6a1f0c2e9b3d4e57

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 15 Oct 2026 11:23:50 GMT

{
  "data": {"count": 5},
  "message": "Successfully suppressed 5 assets",
  "success": true
}

Form Parameters:
Parameters:	api_key (string) – Your API key
	group_id – suppress every `pending` asset in this group asset_ids – suppress these assets: a comma-separated list of IDs, or the field repeated once per ID. Every asset must exist and be `pending`. Send either `group_id` or `asset_ids`, not both
Response Headers:
	Content-Type – application/json
Response JSON Object:
	success (boolean) – operation was successful message (string) – human readable response data.count (int) – number of assets suppressed
Status Codes:	400 Bad Request – access denied

The API user must be allowed to manage the organisation’s scope.

POST /api/v1/(api_key)/discovery/unsuppress¶

New in version 1.7.0.

Return suppressed discovered assets to pending.

Example request:

POST /api/v1/44df57d3f5a479e334e622f314787dcc/discovery/unsuppress HTTP/1.1
Host: api.appcheck-ng.com
Accept-Encoding: identity
Content-Type: application/x-www-form-urlencoded

asset_ids=7c2d91a04f6b3e20

Form Parameters:
Parameters:	api_key (string) – Your API key
	group_id – restore every `suppressed` asset in this group asset_ids – restore these assets: a comma-separated list of IDs, or the field repeated once per ID. Every asset must exist and be `suppressed`. Send either `group_id` or `asset_ids`, not both
Response Headers:
	Content-Type – application/json
Response JSON Object:
	success (boolean) – operation was successful message (string) – human readable response data.count (int) – number of assets restored
Status Codes:	400 Bad Request – access denied

The API user must be allowed to manage the organisation’s scope.

GET /api/v1/(api_key)/discovery/stats¶

New in version 1.7.0.

How much of your licensed scope is used, when discovery last ran and will next run, and whether a licence upgrade can be requested.

Example request:

GET /api/v1/44df57d3f5a479e334e622f314787dcc/discovery/stats HTTP/1.1
Host: api.appcheck-ng.com
Accept-Encoding: identity

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 15 Oct 2026 11:23:50 GMT

{
  "data": {
    "application": {"available": 3, "limit": 25, "limit_reached": false, "used": 22},
    "infrastructure": {"available": 0, "limit": 64, "limit_reached": true, "used": 64},
    "last_discovery_run": 1760140800,
    "last_license_upgrade_request": null,
    "next_discovery_run": 1760745600,
    "unlimited_scope": false,
    "upgrade_request_allowed": true
  },
  "message": "OK",
  "success": true
}

Response Headers:
Parameters:	api_key (string) – Your API key
	Content-Type – application/json
Response JSON Object:
	success (boolean) – operation was successful data.application (object) – web applications in scope: `used`, `limit` and `available` (`limit` and `available` are null when unlimited), and `limit_reached` data.infrastructure (object) – infrastructure hosts in scope, in the same form data.unlimited_scope (boolean) – the organisation has no scope limit data.last_discovery_run (int) – timestamp of the last discovery run (or null) data.next_discovery_run (int) – timestamp of the next scheduled discovery run. Discovery runs weekly data.upgrade_request_allowed (boolean) – `POST /api/v1/(api_key)/discovery/upgrade` can be used now: a limit has been reached and no request was made in the last 7 days data.last_license_upgrade_request (int) – timestamp of the last upgrade request (or null)
Status Codes:	400 Bad Request – access denied

GET /api/v1/(api_key)/discovery/export¶

New in version 1.7.0.

Download every discovered asset matching the filters, across all groups, as a CSV file. This is the same export as the Asset Discovery page’s CSV download.

Example request:

GET /api/v1/44df57d3f5a479e334e622f314787dcc/discovery/export?status=pending HTTP/1.1
Host: api.appcheck-ng.com
Accept-Encoding: identity

Query Parameters:
Parameters:	api_key (string) – Your API key
	status (string) – discovered asset status to export: `pending` (default) or `added_to_scope` suppressed_only (boolean) – `1` to export `suppressed` assets instead; overrides `status` search (string) – only assets whose discovered target contains this text (case-insensitive) port (int) – only assets on this port scope_type (string) – only `Application` or only `Infrastructure` assets
Response Headers:
	Content-Type – text/csv (UTF-8), or application/json with `success: false` if the request is refused Content-Disposition – `attachment; filename="discovered-assets.csv"`
Status Codes:	200 OK – the CSV file, with the columns Discovered Target, Apex Domain, Scope Type, CNAME, Parent CNAME, Geolocation, IP Address, Port, SSL, Web Server, Page Title, Status Code, Redirect Url, First Discovered, Last Discovered 400 Bad Request – access denied

POST /api/v1/(api_key)/discovery/upgrade¶

New in version 1.7.0.

Ask your AppCheck account manager for a larger licence, when you have reached your limit and want to add more discovered assets to scope. This is the same request as the “Upgrade” button on the Asset Discovery page.

Example request:

POST /api/v1/44df57d3f5a479e334e622f314787dcc/discovery/upgrade HTTP/1.1
Host: api.appcheck-ng.com
Accept-Encoding: identity
Content-Type: application/x-www-form-urlencoded

asset_ids=7c2d91a04f6b3e18

Form Parameters:
Parameters:	api_key (string) – Your API key
	asset_ids – (optional) the discovered assets you want to add, so your account manager can see what the upgrade is for: a comma-separated list of IDs, or the field repeated once per ID
Response Headers:
	Content-Type – application/json
Response JSON Object:
	success (boolean) – operation was successful message (string) – human readable response
Status Codes:	400 Bad Request – access denied

The request is refused if your licence limit would not be exceeded by the assets, or if a request was already made in the last 7 days. data.upgrade_request_allowed from GET /api/v1/(api_key)/discovery/stats says whether a request can be made now.