Bulk Update Asset Labels - ProjectDiscovery Documentation

Update Asset Labels

curl --request PATCH \
  --url https://api.projectdiscovery.io/v1/asset/labels \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "filters": {
    "is_tech": true,
    "is_favicon": true,
    "is_new": true,
    "labels": "<string>",
    "host": "<string>",
    "port": "<string>",
    "status_code": "<string>",
    "content_length": "<string>",
    "title": "<string>",
    "domain": [
      "<string>"
    ],
    "cname": "<string>",
    "technologies": "<string>",
    "ip": "<string>",
    "is_screenshot": true,
    "start_date": "2023-12-25",
    "end_date": "2023-12-25",
    "custom_filter": "<string>",
    "search": "<string>",
    "enumeration_ids": [
      "<string>"
    ],
    "only_dns": true,
    "only_ip": true,
    "not_seen_for_days": 2
  },
  "labels": [
    "<string>"
  ]
}
'

import requests

url = "https://api.projectdiscovery.io/v1/asset/labels"

payload = {
    "filters": {
        "is_tech": True,
        "is_favicon": True,
        "is_new": True,
        "labels": "<string>",
        "host": "<string>",
        "port": "<string>",
        "status_code": "<string>",
        "content_length": "<string>",
        "title": "<string>",
        "domain": ["<string>"],
        "cname": "<string>",
        "technologies": "<string>",
        "ip": "<string>",
        "is_screenshot": True,
        "start_date": "2023-12-25",
        "end_date": "2023-12-25",
        "custom_filter": "<string>",
        "search": "<string>",
        "enumeration_ids": ["<string>"],
        "only_dns": True,
        "only_ip": True,
        "not_seen_for_days": 2
    },
    "labels": ["<string>"]
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    filters: {
      is_tech: true,
      is_favicon: true,
      is_new: true,
      labels: '<string>',
      host: '<string>',
      port: '<string>',
      status_code: '<string>',
      content_length: '<string>',
      title: '<string>',
      domain: ['<string>'],
      cname: '<string>',
      technologies: '<string>',
      ip: '<string>',
      is_screenshot: true,
      start_date: '2023-12-25',
      end_date: '2023-12-25',
      custom_filter: '<string>',
      search: '<string>',
      enumeration_ids: ['<string>'],
      only_dns: true,
      only_ip: true,
      not_seen_for_days: 2
    },
    labels: ['<string>']
  })
};

fetch('https://api.projectdiscovery.io/v1/asset/labels', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.projectdiscovery.io/v1/asset/labels",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'filters' => [
        'is_tech' => true,
        'is_favicon' => true,
        'is_new' => true,
        'labels' => '<string>',
        'host' => '<string>',
        'port' => '<string>',
        'status_code' => '<string>',
        'content_length' => '<string>',
        'title' => '<string>',
        'domain' => [
                '<string>'
        ],
        'cname' => '<string>',
        'technologies' => '<string>',
        'ip' => '<string>',
        'is_screenshot' => true,
        'start_date' => '2023-12-25',
        'end_date' => '2023-12-25',
        'custom_filter' => '<string>',
        'search' => '<string>',
        'enumeration_ids' => [
                '<string>'
        ],
        'only_dns' => true,
        'only_ip' => true,
        'not_seen_for_days' => 2
    ],
    'labels' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.projectdiscovery.io/v1/asset/labels"

	payload := strings.NewReader("{\n  \"filters\": {\n    \"is_tech\": true,\n    \"is_favicon\": true,\n    \"is_new\": true,\n    \"labels\": \"<string>\",\n    \"host\": \"<string>\",\n    \"port\": \"<string>\",\n    \"status_code\": \"<string>\",\n    \"content_length\": \"<string>\",\n    \"title\": \"<string>\",\n    \"domain\": [\n      \"<string>\"\n    ],\n    \"cname\": \"<string>\",\n    \"technologies\": \"<string>\",\n    \"ip\": \"<string>\",\n    \"is_screenshot\": true,\n    \"start_date\": \"2023-12-25\",\n    \"end_date\": \"2023-12-25\",\n    \"custom_filter\": \"<string>\",\n    \"search\": \"<string>\",\n    \"enumeration_ids\": [\n      \"<string>\"\n    ],\n    \"only_dns\": true,\n    \"only_ip\": true,\n    \"not_seen_for_days\": 2\n  },\n  \"labels\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.projectdiscovery.io/v1/asset/labels")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filters\": {\n    \"is_tech\": true,\n    \"is_favicon\": true,\n    \"is_new\": true,\n    \"labels\": \"<string>\",\n    \"host\": \"<string>\",\n    \"port\": \"<string>\",\n    \"status_code\": \"<string>\",\n    \"content_length\": \"<string>\",\n    \"title\": \"<string>\",\n    \"domain\": [\n      \"<string>\"\n    ],\n    \"cname\": \"<string>\",\n    \"technologies\": \"<string>\",\n    \"ip\": \"<string>\",\n    \"is_screenshot\": true,\n    \"start_date\": \"2023-12-25\",\n    \"end_date\": \"2023-12-25\",\n    \"custom_filter\": \"<string>\",\n    \"search\": \"<string>\",\n    \"enumeration_ids\": [\n      \"<string>\"\n    ],\n    \"only_dns\": true,\n    \"only_ip\": true,\n    \"not_seen_for_days\": 2\n  },\n  \"labels\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.projectdiscovery.io/v1/asset/labels")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"filters\": {\n    \"is_tech\": true,\n    \"is_favicon\": true,\n    \"is_new\": true,\n    \"labels\": \"<string>\",\n    \"host\": \"<string>\",\n    \"port\": \"<string>\",\n    \"status_code\": \"<string>\",\n    \"content_length\": \"<string>\",\n    \"title\": \"<string>\",\n    \"domain\": [\n      \"<string>\"\n    ],\n    \"cname\": \"<string>\",\n    \"technologies\": \"<string>\",\n    \"ip\": \"<string>\",\n    \"is_screenshot\": true,\n    \"start_date\": \"2023-12-25\",\n    \"end_date\": \"2023-12-25\",\n    \"custom_filter\": \"<string>\",\n    \"search\": \"<string>\",\n    \"enumeration_ids\": [\n      \"<string>\"\n    ],\n    \"only_dns\": true,\n    \"only_ip\": true,\n    \"not_seen_for_days\": 2\n  },\n  \"labels\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "message": "<string>",
  "asset_count": 123,
  "async": true
}

{
  "message": "<string>",
  "kind": "<string>",
  "code": "<string>",
  "error": "<string>",
  "error_id": "<string>",
  "param": "<string>",
  "status": 123
}

{
  "message": "<string>",
  "kind": "<string>",
  "code": "<string>",
  "error": "<string>",
  "error_id": "<string>",
  "param": "<string>",
  "status": 123
}

{
  "message": "<string>",
  "kind": "<string>",
  "code": "<string>",
  "error": "<string>",
  "error_id": "<string>",
  "param": "<string>",
  "status": 123
}

{
  "message": "<string>",
  "kind": "<string>",
  "code": "<string>",
  "error": "<string>",
  "error_id": "<string>",
  "param": "<string>",
  "status": 123
}

{
  "message": "<string>",
  "kind": "<string>",
  "code": "<string>",
  "error": "<string>",
  "error_id": "<string>",
  "param": "<string>",
  "status": 123
}

PATCH

asset

labels

Update Asset Labels

curl --request PATCH \
  --url https://api.projectdiscovery.io/v1/asset/labels \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "filters": {
    "is_tech": true,
    "is_favicon": true,
    "is_new": true,
    "labels": "<string>",
    "host": "<string>",
    "port": "<string>",
    "status_code": "<string>",
    "content_length": "<string>",
    "title": "<string>",
    "domain": [
      "<string>"
    ],
    "cname": "<string>",
    "technologies": "<string>",
    "ip": "<string>",
    "is_screenshot": true,
    "start_date": "2023-12-25",
    "end_date": "2023-12-25",
    "custom_filter": "<string>",
    "search": "<string>",
    "enumeration_ids": [
      "<string>"
    ],
    "only_dns": true,
    "only_ip": true,
    "not_seen_for_days": 2
  },
  "labels": [
    "<string>"
  ]
}
'

import requests

url = "https://api.projectdiscovery.io/v1/asset/labels"

payload = {
    "filters": {
        "is_tech": True,
        "is_favicon": True,
        "is_new": True,
        "labels": "<string>",
        "host": "<string>",
        "port": "<string>",
        "status_code": "<string>",
        "content_length": "<string>",
        "title": "<string>",
        "domain": ["<string>"],
        "cname": "<string>",
        "technologies": "<string>",
        "ip": "<string>",
        "is_screenshot": True,
        "start_date": "2023-12-25",
        "end_date": "2023-12-25",
        "custom_filter": "<string>",
        "search": "<string>",
        "enumeration_ids": ["<string>"],
        "only_dns": True,
        "only_ip": True,
        "not_seen_for_days": 2
    },
    "labels": ["<string>"]
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    filters: {
      is_tech: true,
      is_favicon: true,
      is_new: true,
      labels: '<string>',
      host: '<string>',
      port: '<string>',
      status_code: '<string>',
      content_length: '<string>',
      title: '<string>',
      domain: ['<string>'],
      cname: '<string>',
      technologies: '<string>',
      ip: '<string>',
      is_screenshot: true,
      start_date: '2023-12-25',
      end_date: '2023-12-25',
      custom_filter: '<string>',
      search: '<string>',
      enumeration_ids: ['<string>'],
      only_dns: true,
      only_ip: true,
      not_seen_for_days: 2
    },
    labels: ['<string>']
  })
};

fetch('https://api.projectdiscovery.io/v1/asset/labels', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.projectdiscovery.io/v1/asset/labels",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'filters' => [
        'is_tech' => true,
        'is_favicon' => true,
        'is_new' => true,
        'labels' => '<string>',
        'host' => '<string>',
        'port' => '<string>',
        'status_code' => '<string>',
        'content_length' => '<string>',
        'title' => '<string>',
        'domain' => [
                '<string>'
        ],
        'cname' => '<string>',
        'technologies' => '<string>',
        'ip' => '<string>',
        'is_screenshot' => true,
        'start_date' => '2023-12-25',
        'end_date' => '2023-12-25',
        'custom_filter' => '<string>',
        'search' => '<string>',
        'enumeration_ids' => [
                '<string>'
        ],
        'only_dns' => true,
        'only_ip' => true,
        'not_seen_for_days' => 2
    ],
    'labels' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.projectdiscovery.io/v1/asset/labels"

	payload := strings.NewReader("{\n  \"filters\": {\n    \"is_tech\": true,\n    \"is_favicon\": true,\n    \"is_new\": true,\n    \"labels\": \"<string>\",\n    \"host\": \"<string>\",\n    \"port\": \"<string>\",\n    \"status_code\": \"<string>\",\n    \"content_length\": \"<string>\",\n    \"title\": \"<string>\",\n    \"domain\": [\n      \"<string>\"\n    ],\n    \"cname\": \"<string>\",\n    \"technologies\": \"<string>\",\n    \"ip\": \"<string>\",\n    \"is_screenshot\": true,\n    \"start_date\": \"2023-12-25\",\n    \"end_date\": \"2023-12-25\",\n    \"custom_filter\": \"<string>\",\n    \"search\": \"<string>\",\n    \"enumeration_ids\": [\n      \"<string>\"\n    ],\n    \"only_dns\": true,\n    \"only_ip\": true,\n    \"not_seen_for_days\": 2\n  },\n  \"labels\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.projectdiscovery.io/v1/asset/labels")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filters\": {\n    \"is_tech\": true,\n    \"is_favicon\": true,\n    \"is_new\": true,\n    \"labels\": \"<string>\",\n    \"host\": \"<string>\",\n    \"port\": \"<string>\",\n    \"status_code\": \"<string>\",\n    \"content_length\": \"<string>\",\n    \"title\": \"<string>\",\n    \"domain\": [\n      \"<string>\"\n    ],\n    \"cname\": \"<string>\",\n    \"technologies\": \"<string>\",\n    \"ip\": \"<string>\",\n    \"is_screenshot\": true,\n    \"start_date\": \"2023-12-25\",\n    \"end_date\": \"2023-12-25\",\n    \"custom_filter\": \"<string>\",\n    \"search\": \"<string>\",\n    \"enumeration_ids\": [\n      \"<string>\"\n    ],\n    \"only_dns\": true,\n    \"only_ip\": true,\n    \"not_seen_for_days\": 2\n  },\n  \"labels\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.projectdiscovery.io/v1/asset/labels")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"filters\": {\n    \"is_tech\": true,\n    \"is_favicon\": true,\n    \"is_new\": true,\n    \"labels\": \"<string>\",\n    \"host\": \"<string>\",\n    \"port\": \"<string>\",\n    \"status_code\": \"<string>\",\n    \"content_length\": \"<string>\",\n    \"title\": \"<string>\",\n    \"domain\": [\n      \"<string>\"\n    ],\n    \"cname\": \"<string>\",\n    \"technologies\": \"<string>\",\n    \"ip\": \"<string>\",\n    \"is_screenshot\": true,\n    \"start_date\": \"2023-12-25\",\n    \"end_date\": \"2023-12-25\",\n    \"custom_filter\": \"<string>\",\n    \"search\": \"<string>\",\n    \"enumeration_ids\": [\n      \"<string>\"\n    ],\n    \"only_dns\": true,\n    \"only_ip\": true,\n    \"not_seen_for_days\": 2\n  },\n  \"labels\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "message": "<string>",
  "asset_count": 123,
  "async": true
}

{
  "message": "<string>",
  "kind": "<string>",
  "code": "<string>",
  "error": "<string>",
  "error_id": "<string>",
  "param": "<string>",
  "status": 123
}

{
  "message": "<string>",
  "kind": "<string>",
  "code": "<string>",
  "error": "<string>",
  "error_id": "<string>",
  "param": "<string>",
  "status": 123
}

{
  "message": "<string>",
  "kind": "<string>",
  "code": "<string>",
  "error": "<string>",
  "error_id": "<string>",
  "param": "<string>",
  "status": 123
}

{
  "message": "<string>",
  "kind": "<string>",
  "code": "<string>",
  "error": "<string>",
  "error_id": "<string>",
  "param": "<string>",
  "status": 123
}

{
  "message": "<string>",
  "kind": "<string>",
  "code": "<string>",
  "error": "<string>",
  "error_id": "<string>",
  "param": "<string>",
  "status": 123
}

When filters are empty or not specified, this operation applies to ALL assets in your account. Always specify filters to target specific assets unless you intentionally want to update your entire asset inventory.

Overview

Bulk update labels across multiple assets using powerful filters. This endpoint allows you to add, replace, or delete labels on many assets at once, making it ideal for organizing large asset inventories efficiently.

Key Features

Flexible Update Modes

Append: Add new labels without removing existing ones
Replace: Replace all existing labels with new ones
Delete: Remove specific labels from assets

Filter-Based Selection

Apply labels to assets that match your filter criteria:

Technology stack (e.g., all WordPress sites)
Port numbers (e.g., assets with port 443)
Status codes (e.g., all 200 responses)
Domains, hosts, IP addresses
Custom filters for complex queries

Asynchronous Processing

Large operations are processed asynchronously, allowing you to label thousands of assets without waiting for the request to complete.

Update Modes Explained

Append Mode (Default)

Adds new labels while preserving existing ones:

Existing labels: ["prod", "api"]
New labels: ["critical"]
Result: ["prod", "api", "critical"]

Replace Mode

Replaces all existing labels with new ones:

Existing labels: ["prod", "api"]
New labels: ["critical", "review"]
Result: ["critical", "review"]

Delete Mode

Removes specific labels from assets:

Existing labels: ["prod", "api", "critical"]
Labels to delete: ["critical"]
Result: ["prod", "api"]

Request Body Structure

With Filters (Recommended)

Target specific assets using filters:

{
  "filters": {
    "technologies": "wordpress,nginx",
    "domain": ["example.com", "api.example.com"],
    "port": "443,8080",
    "status_code": "200,301",
    "is_new": true,
    "labels": "existing-label",
    "time": "last_week",
    "custom_filter": "encoded_custom_query"
  },
  "labels": ["label1", "label2", "label3"]
}

Without Filters (Applies to ALL Assets)

This will update every asset in your account:

{
  "filters": {},
  "labels": ["label-for-all-assets"]
}

Example:

# This deletes "test1" label from ALL assets in your account
curl -X PATCH "https://api.projectdiscovery.io/v1/asset/labels?update_type=delete" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {},
    "labels": ["test1"]
  }'

Response

Synchronous Response

For small operations:

{
  "message": "Labels updated successfully",
  "asset_count": 42,
  "async": false
}

Asynchronous Response

For large operations:

{
  "message": "Label update queued",
  "asset_count": 5000,
  "async": true
}

Available Filters

Filter	Description	Example
`technologies`	Filter by technology stack	`"wordpress,nginx"`
`domain`	Filter by domain names	`["example.com"]`
`host`	Filter by specific hosts	`"https://api.example.com"`
`port`	Filter by port numbers	`"443,8080"`
`status_code`	Filter by HTTP status codes	`"200,301,404"`
`title`	Filter by page titles	`"Admin Panel"`
`ip`	Filter by IP addresses	`"192.168.1.1"`
`cname`	Filter by CNAME records	`"cdn.example.com"`
`is_new`	Filter only new assets	`true`
`is_tech`	Assets with technology data	`true`
`is_screenshot`	Assets with screenshots	`true`
`labels`	Filter by existing labels	`"prod,api"`
`time`	Time range filter	`"last_week"`
`enumeration_id`	Specific enumeration	`"enum_123"`

Authorizations

X-API-Key

string

header

required

Headers

X-Team-Id

string

Retrieve the Team ID from: https://cloud.projectdiscovery.io/settings/team

Query Parameters

update_type

enum<string>

default:append

Append or Replace update_type

Available options:

append,

replace,

delete

Body

application/json

filters

AssetFilters · object

required

Show child attributes

labels

string[]

required

Response

Example response

message

string

required

asset_count

integer

required

async

boolean

required

Whether the operation is running asynchronously

Get Asset Changelogs for a given asset_id Add labels to an asset

⌘I

​Overview

​Key Features

​Flexible Update Modes

​Filter-Based Selection

​Asynchronous Processing

​Update Modes Explained

​Append Mode (Default)

​Replace Mode

​Delete Mode

​Request Body Structure

​With Filters (Recommended)

​Without Filters (Applies to ALL Assets)

​Response

​Synchronous Response

​Asynchronous Response

​Available Filters

Authorizations

Headers

Query Parameters

Body

Response

Overview

Key Features

Flexible Update Modes

Filter-Based Selection

Asynchronous Processing

Update Modes Explained

Append Mode (Default)

Replace Mode

Delete Mode

Request Body Structure

With Filters (Recommended)

Without Filters (Applies to ALL Assets)

Response

Synchronous Response

Asynchronous Response

Available Filters