Bulk Update Asset Labels

PATCH /v1/asset/labels

Try it

Update Asset Labels

cURL

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,
    "time": "last_day",
    "start_date": "2023-12-25",
    "end_date": "2023-12-25",
    "custom_filter": "<string>",
    "search": "<string>",
    "enumeration_id": "<string>",
    "only_dns": true,
    "only_ip": true
  },
  "labels": [
    "<string>"
  ]
}
'

200

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

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

filters. is_tech · boolean

Return records that have technologies

filters. is_favicon · boolean

Return the records that have favicon

filters. is_new · boolean

Filter by new content

filters. labels · string

Filter by comma separated labels, e.g-> labels=p1,p2

filters. host · string

Filter by comma separated hosts, e.g-> host=p1,p2

filters. port · string

Filter by comma separated ports, e.g-> port=p1,p2

filters. status_code · string

Filter by comma separated status codes, e.g-> status_code=p1,p2

filters. content_length · string

Filter by comma separated content lengths, e.g-> content_length=p1,p2

filters. title · string

Filter by comma separated titles, e.g-> title=p1,p2

filters. domain · string[]

Filter by comma separated domain names, e.g-> domain=domain1.com,domain2.com

filters. cname · string

Filter by comma separated cnames, e.g-> cname=p1,p2

filters. technologies · string

Filter by comma separated technologies, e.g-> technologies=p1,p2

filters. ip · string

Filter by comma separated ips, e.g-> ip=p1,p2

filters. is_screenshot · boolean

Return the records with screenshots

filters. time · enum<string>

Filter by time range

Available options: last_day, last_week, last_month, last_3_months, last_6_months, last_12_months, all_time

filters. start_date · string<date>

Filter by start date

filters. end_date · string<date>

Filter by end date

filters. custom_filter · string

Filter by custom filter. Double encode the query string.

filters. search · string

Search on the content name

filters. enumeration_id · string

Filter by enumeration id

filters. only_dns · boolean

Query only dns FQDN records

filters. only_ip · boolean

Query only dns IP records

labels · string[] · required

Response

200

application/json

Example response

message · string · required

asset_count · integer · required

async · boolean · required

Whether the operation is running asynchronously