Add labels to an asset

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>"
  ]
}
'

import requests

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

payload = { "labels": ["<string>"] }
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({labels: ['<string>']})
};

fetch('https://api.projectdiscovery.io/v1/asset/{asset_id}/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/{asset_id}/labels",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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/{asset_id}/labels"

	payload := strings.NewReader("{\n  \"labels\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", 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.post("https://api.projectdiscovery.io/v1/asset/{asset_id}/labels")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"labels\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"labels\": [\n    \"<string>\"\n  ]\n}"

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

{
  "message": "<string>"
}

{
  "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
}

POST

asset

{asset_id}

labels

Add labels to an asset

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>"
  ]
}
'

import requests

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

payload = { "labels": ["<string>"] }
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({labels: ['<string>']})
};

fetch('https://api.projectdiscovery.io/v1/asset/{asset_id}/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/{asset_id}/labels",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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/{asset_id}/labels"

	payload := strings.NewReader("{\n  \"labels\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", 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.post("https://api.projectdiscovery.io/v1/asset/{asset_id}/labels")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"labels\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"labels\": [\n    \"<string>\"\n  ]\n}"

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

{
  "message": "<string>"
}

{
  "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
}

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 enumeration contents:

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"]
    }
  ]
}

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

Example response

message

string

required

​Overview

​Quick Example

​Request Body

​Response

​Success Response

​Error Responses

​Use Cases

​1. Manual Asset Review

​2. Security Assessment

​3. Incident Response

​4. Asset Ownership

​Behavior & Important Notes

​Label Appending

​Duplicate Prevention

​Empty Labels Array

​Getting the Asset ID

​From Enumeration Contents

Authorizations

Headers

Path Parameters

Body

Response

Overview

Quick Example

Request Body

Response

Success Response

Error Responses

Use Cases

1. Manual Asset Review

2. Security Assessment

3. Incident Response

4. Asset Ownership

Behavior & Important Notes

Label Appending

Duplicate Prevention

Empty Labels Array

Getting the Asset ID

From Enumeration Contents