> ## Documentation Index
> Fetch the complete documentation index at: https://docs.projectdiscovery.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Add labels to an asset

## 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

```bash theme={null}
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

```json theme={null}
{
  "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

```json theme={null}
{
  "message": "Labels added successfully"
}
```

### Error Responses

**Asset Not Found:**

```json theme={null}
{
  "message": "Asset not found",
  "code": "NOT_FOUND"
}
```

**Invalid Asset ID:**

```json theme={null}
{
  "message": "Invalid asset ID format",
  "code": "INVALID_ID"
}
```

## Use Cases

### 1. Manual Asset Review

After reviewing an asset, mark it as reviewed:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```json theme={null}
{
  "labels": []
}
// Result: Asset labels remain unchanged
```

## Getting the Asset ID

You can retrieve asset IDs from enumeration contents:

### From Enumeration Contents

```bash theme={null}
GET /v1/asset/enumerate/{enumerate_id}/contents
```

Response includes `id` field:

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


## OpenAPI

````yaml post /v1/asset/{asset_id}/labels
openapi: 3.1.0
info:
  title: PDCP API
  version: '1.0'
  summary: ProjectDiscovery Cloud Platform
  description: >-
    For more details, checkout
    https://docs.projectdiscovery.io/api-reference/editor/scan
servers:
  - url: https://api.projectdiscovery.io
    description: Production
  - url: https://api.dev.projectdiscovery.io
    description: Development
  - url: http://localhost:8085
    description: Localhost
security:
  - X-API-Key: []
paths:
  /v1/asset/{asset_id}/labels:
    parameters:
      - schema:
          type: integer
          format: int64
        name: asset_id
        in: path
        required: true
    post:
      tags:
        - assets
      summary: Add labels to an asset
      operationId: post-v1-asset-id-labels
      parameters:
        - schema:
            type: string
          in: header
          description: >-
            Retrieve the Team ID from:
            https://cloud.projectdiscovery.io/settings/team
          name: X-Team-Id
      requestBody:
        $ref: '#/components/requestBodies/AssetIdLabelsRequest'
      responses:
        '200':
          $ref: '#/components/responses/MessageResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '401':
          $ref: '#/components/responses/ErrorResponse'
        '404':
          $ref: '#/components/responses/ErrorResponse'
        '500':
          $ref: '#/components/responses/ErrorResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
components:
  requestBodies:
    AssetIdLabelsRequest:
      content:
        application/json:
          schema:
            type: object
            required:
              - labels
            properties:
              labels:
                type: array
                items:
                  type: string
  responses:
    MessageResponse:
      description: Example response
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
            required:
              - message
    ErrorResponse:
      description: Example response
      content:
        application/json:
          schema:
            type: object
            required:
              - message
            properties:
              message:
                type: string
              kind:
                type: string
              code:
                type: string
              error:
                type: string
              error_id:
                type: string
              param:
                type: string
              status:
                type: integer
  securitySchemes:
    X-API-Key:
      name: X-API-Key
      type: apiKey
      in: header

````