Add labels to an asset

POST /v1/asset/{asset_id}/labels

Try it

Add labels to an asset

cURL

curl --request POST \
  --url https://api.projectdiscovery.io/v1/asset/{asset_id}/labels \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "labels": [
    "<string>"
  ]
}
'

200

{
  "message": "<string>"
}

Overview

Add labels to a specific asset by its ID. This endpoint enables programmatic labeling of individual assets based on custom logic, security findings, or business rules.

Unlike the bulk endpoint (PATCH /v1/asset/labels), this endpoint targets a single asset, making it ideal for:

• Programmatic labeling based on scan results or vulnerability findings
• Building custom asset classification pipelines
• Event-driven labeling (e.g., label assets when specific conditions are met)

Quick Example

curl -X POST "https://api.projectdiscovery.io/v1/asset/123456/labels" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "labels": ["reviewed", "production", "critical"]
  }'

Request Body

{
  "labels": ["label1", "label2", "label3"]
}

The labels array contains all labels you want to add to the asset. Existing labels are preserved - this endpoint always appends.

Response

Success Response

{
  "message": "Labels added successfully"
}

Error Responses

Asset Not Found:

{
  "message": "Asset not found",
  "code": "NOT_FOUND"
}

Invalid Asset ID:

{
  "message": "Invalid asset ID format",
  "code": "INVALID_ID"
}

Use Cases

1. Manual Asset Review

After reviewing an asset, mark it as reviewed:

curl -X POST "https://api.projectdiscovery.io/v1/asset/789012/labels" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "labels": ["reviewed", "approved"]
  }'

2. Security Assessment

Label assets after vulnerability assessment:

curl -X POST "https://api.projectdiscovery.io/v1/asset/345678/labels" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "labels": ["security-tested", "no-vulnerabilities"]
  }'

3. Incident Response

Quickly label compromised or suspicious assets:

curl -X POST "https://api.projectdiscovery.io/v1/asset/901234/labels" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "labels": ["incident", "investigate", "high-priority"]
  }'

4. Asset Ownership

Assign ownership or team responsibility:

curl -X POST "https://api.projectdiscovery.io/v1/asset/567890/labels" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "labels": ["team-backend", "owner-john"]
  }'

Behavior & Important Notes

Label Appending

This endpoint always appends labels. It never removes existing labels:

• Existing labels: ["prod", "api"]
• Adding labels: ["critical"]
• Result: ["prod", "api", "critical"]

Duplicate Prevention

Adding labels that already exist is safe - they won’t be duplicated:

• Existing labels: ["prod", "api"]
• Adding labels: ["api", "critical"]
• Result: ["prod", "api", "critical"] (not ["prod", "api", "api", "critical"])

Empty Labels Array

Sending an empty labels array has no effect:

{
  "labels": []
}
// Result: Asset labels remain unchanged

Getting the Asset ID

You can retrieve asset IDs from:

From Enumeration Contents

GET /v1/asset/enumerate/{enumerate_id}/contents

Response includes id field:

{
  "data": [
    {
      "id": 123456,
      "name": "https://example.com",
      "enumeration_id": "enum_abc",
      "labels": ["existing-label"]
    }
  ]
}

From Asset Details

GET /v1/asset/{asset_id}

Authorizations

X-API-Key · string · header · required

Headers

X-Team-Id · string

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

Path Parameters

asset_id · integer<int64> · required

Body

application/json

labels · string[] · required

Response

200

application/json

Example response

message · string · required