# Add Labels by Filter (bulk)

`POST https://api.tweetsmash.com/v1/labels/add-by-filter`

Add one label to EVERY bookmark matching a filter, in a single request — no need to list and loop. Returns how many bookmarks matched and were tagged.

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Your secret API key. Should be provided as a Bearer token. |

### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `label_name` | string | No | Label to create/apply. Either label_id or label_name is required. |
| `label_id` | string | No | Existing label id. Either label_id or label_name is required. |
| `search_query` | string | No | Keyword search that scopes which bookmarks are tagged. |
| `filter` | string | No | A filter field (e.g. author). |
| `value` | string | No | The value for the filter field. |

### Response

```json
{
  "status": true,
  "data": {
    "matched": 42,
    "tagged": 42,
    "failed": 0,
    "truncated": false,
    "label": {
      "id": "177...",
      "name": "AI"
    }
  }
}
```

---

Full reference: https://www.tweetsmash.com/api-docs/add-labels-by-filter