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

# Bulk Update Asset Labels

<Warning>
  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.
</Warning>

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

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

<Warning>
  This will update **every asset** in your account:
</Warning>

```json theme={null}
{
  "filters": {},
  "labels": ["label-for-all-assets"]
}
```

Example:

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

```json theme={null}
{
  "message": "Labels updated successfully",
  "asset_count": 42,
  "async": false
}
```

### Asynchronous Response

For large operations:

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


## OpenAPI

````yaml patch /v1/asset/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/labels:
    patch:
      tags:
        - assets
      summary: Update Asset Labels
      operationId: patch-v1-asset-labels
      parameters:
        - schema:
            type: string
            enum:
              - append
              - replace
              - delete
            default: append
          in: query
          name: update_type
          description: Append or Replace update_type
        - 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/UpdateAssetLabelsRequest'
      responses:
        '200':
          $ref: '#/components/responses/AssetCountResponse'
        '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:
    UpdateAssetLabelsRequest:
      content:
        application/json:
          schema:
            type: object
            required:
              - filters
              - labels
            properties:
              filters:
                $ref: '#/components/schemas/AssetFilters'
              labels:
                type: array
                items:
                  type: string
  responses:
    AssetCountResponse:
      description: Example response
      content:
        application/json:
          schema:
            type: object
            required:
              - message
              - asset_count
              - async
            properties:
              message:
                type: string
              asset_count:
                type: integer
              async:
                type: boolean
                description: Whether the operation is running asynchronously
    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
  schemas:
    AssetFilters:
      title: AssetFilters
      type: object
      additionalProperties: false
      properties:
        is_tech:
          type: boolean
          description: Return records that have technologies
        is_favicon:
          type: boolean
          description: Return the records that have favicon
        is_new:
          type: boolean
          description: Filter by new content
        labels:
          type: string
          description: Filter by comma separated labels, e.g-> labels=p1,p2
        host:
          type: string
          description: Filter by comma separated hosts, e.g-> host=p1,p2
        port:
          type: string
          description: Filter by comma separated ports, e.g-> port=p1,p2
        status_code:
          type: string
          description: Filter by comma separated status codes, e.g-> status_code=p1,p2
        content_length:
          type: string
          description: >-
            Filter by comma separated content lengths, e.g->
            content_length=p1,p2
        title:
          type: string
          description: Filter by comma separated titles, e.g-> title=p1,p2
        domain:
          type: array
          description: >-
            Filter by comma separated domain names, e.g->
            domain=domain1.com,domain2.com
          items:
            type: string
        cname:
          type: string
          description: Filter by comma separated cnames, e.g-> cname=p1,p2
        technologies:
          type: string
          description: Filter by comma separated technologies, e.g-> technologies=p1,p2
        ip:
          type: string
          description: Filter by comma separated ips, e.g-> ip=p1,p2
        is_screenshot:
          type: boolean
          description: Return the records with screenshots
        time:
          $ref: '#/components/schemas/TimeRangeQueryParameter'
          description: Filter by time range
        start_date:
          type: string
          format: date
          description: Filter by start date
        end_date:
          type: string
          format: date
          description: Filter by end date
        custom_filter:
          type: string
          description: Filter by custom filter. Double encode the query string.
        search:
          type: string
          description: Search on the content name
        enumeration_ids:
          type: array
          items:
            type: string
          description: Filter by enumeration ids
        only_dns:
          type: boolean
          description: Query only dns FQDN records
        only_ip:
          type: boolean
          description: Query only dns IP records
    TimeRangeQueryParameter:
      title: TimeRangeQueryParameter
      type: string
      enum:
        - last_day
        - last_week
        - last_month
        - last_3_months
        - last_6_months
        - last_12_months
        - all_time
  securitySchemes:
    X-API-Key:
      name: X-API-Key
      type: apiKey
      in: header

````