Tag Management

Tags (also called Groups) allow you to organize your watches, set group-wide notification preferences, and perform bulk operations on related watches.

List All Tags

endpoint

/api/v1/tags

Retrieve a list of all tags/groups.

Response Fields

string

Unique identifier for the tag

string

Tag name/title

integer

Unix timestamp of creation

boolean

Whether notifications are muted for this tag

Example

curl -X GET "http://localhost:5000/api/v1/tags" \
  -H "x-api-key: YOUR_API_KEY"

import requests

headers = {'x-api-key': 'YOUR_API_KEY'}
response = requests.get(
    'http://localhost:5000/api/v1/tags',
    headers=headers
)
print(response.json())

{
  "550e8400-e29b-41d4-a716-446655440000": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Production Sites",
    "date_created": 1640995200,
    "notification_muted": false
  },
  "330e8400-e29b-41d4-a716-446655440001": {
    "uuid": "330e8400-e29b-41d4-a716-446655440001",
    "title": "News Sources",
    "date_created": 1640998800,
    "notification_muted": false
  }
}

Create a Tag

endpoint

/api/v1/tag

Create a new tag/group.

Request Body

string

required

Name for the tag/group

array

Array of notification URLs (Apprise format) for this tag

boolean

default:false

Whether notifications are muted for watches in this tag

boolean

Whether tag settings override individual watch settings

Example

curl -X POST "http://localhost:5000/api/v1/tag" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Important Sites"
  }'

import requests

headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}
data = {'title': 'Important Sites'}

response = requests.post(
    'http://localhost:5000/api/v1/tag',
    headers=headers,
    json=data
)
print(response.json())

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000"
}

Get a Single Tag

endpoint

/api/v1/tag/

Retrieve information about a specific tag.

Path Parameters

string

required

UUID of the tag

Query Parameters

string

Set to "muted" or "unmuted" to change notification mute state

string

Set to "true" to recheck all watches in this tag

Example

# Get tag info
curl -X GET "http://localhost:5000/api/v1/tag/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: YOUR_API_KEY"

# Recheck all watches in tag
curl -X GET "http://localhost:5000/api/v1/tag/550e8400-e29b-41d4-a716-446655440000?recheck=true" \
  -H "x-api-key: YOUR_API_KEY"

# Mute tag notifications
curl -X GET "http://localhost:5000/api/v1/tag/550e8400-e29b-41d4-a716-446655440000?muted=muted" \
  -H "x-api-key: YOUR_API_KEY"

import requests

headers = {'x-api-key': 'YOUR_API_KEY'}
tag_uuid = '550e8400-e29b-41d4-a716-446655440000'

# Get tag info
response = requests.get(
    f'http://localhost:5000/api/v1/tag/{tag_uuid}',
    headers=headers
)
print(response.json())

# Recheck all watches in tag
response = requests.get(
    f'http://localhost:5000/api/v1/tag/{tag_uuid}',
    headers=headers,
    params={'recheck': 'true'}
)
print(response.json())

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Production Sites",
  "date_created": 1640995200,
  "notification_muted": false,
  "notification_urls": ["mailto:admin@example.com"],
  "overrides_watch": true
}

When rechecking a tag with 20+ watches, the operation runs in the background and returns a 202 status code.

Update a Tag

endpoint

/api/v1/tag/

Update an existing tag. Only include fields you want to change.

Path Parameters

string

required

UUID of the tag to update

Request Body

string

Update the tag name

array

Update notification URLs for this tag

boolean

Update notification mute state

boolean

Whether tag settings override watch settings

Example

curl -X PUT "http://localhost:5000/api/v1/tag/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Production Sites",
    "notification_muted": false
  }'

import requests

headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}
tag_uuid = '550e8400-e29b-41d4-a716-446655440000'
data = {
    'title': 'Updated Production Sites',
    'notification_muted': False
}

response = requests.put(
    f'http://localhost:5000/api/v1/tag/{tag_uuid}',
    headers=headers,
    json=data
)
print(response.text)  # "OK"

Updating a tag clears checksums for all watches using that tag, forcing them to reprocess on next check.

Delete a Tag

endpoint

/api/v1/tag/

Delete a tag and remove it from all watches.

Path Parameters

string

required

UUID of the tag to delete

Example

curl -X DELETE "http://localhost:5000/api/v1/tag/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: YOUR_API_KEY"

import requests

headers = {'x-api-key': 'YOUR_API_KEY'}
tag_uuid = '550e8400-e29b-41d4-a716-446655440000'

response = requests.delete(
    f'http://localhost:5000/api/v1/tag/{tag_uuid}',
    headers=headers
)
print(response.status_code)  # 204

Deleting a tag removes it from all associated watches but does not delete the watches themselves.

Tag Configuration Options

Tags inherit all configuration options from the Watch schema, allowing you to set defaults that can override individual watch settings when overrides_watch is enabled.

Common Tag Settings

Notification Settings

array

Array of Apprise notification URLs

string

Custom notification title template

string

Custom notification body template

string

Format: text, html, htmlcolor, markdown, or System default

boolean

Mute all notifications for watches in this tag

Check Interval Settings

object

Object with fields: weeks, days, hours, minutes, seconds

boolean

Whether to use global check interval (when false, uses tag-specific interval)

Fetch Settings

string

Backend: system, html_requests, html_webdriver, extra_browser_*

string

HTTP method: GET, POST, PUT, DELETE

object

Custom HTTP headers as key-value pairs

string

Proxy configuration key

Content Filtering

array

CSS/XPath selectors to extract specific content

array

CSS/XPath selectors to remove content

array

Text patterns to ignore in change detection

array

Text patterns that must be present to trigger

Bulk Operations

Recheck All Watches in Tag

You can trigger a recheck of all watches in a tag:

curl -X GET "http://localhost:5000/api/v1/tag/550e8400-e29b-41d4-a716-446655440000?recheck=true" \
  -H "x-api-key: YOUR_API_KEY"

import requests

headers = {'x-api-key': 'YOUR_API_KEY'}
tag_uuid = '550e8400-e29b-41d4-a716-446655440000'

response = requests.get(
    f'http://localhost:5000/api/v1/tag/{tag_uuid}',
    headers=headers,
    params={'recheck': 'true'}
)

if response.status_code == 200:
    # Small tag, queued synchronously
    print(response.json())
elif response.status_code == 202:
    # Large tag (20+ watches), queued in background
    print(response.json())

Response Codes:

200 OK - Less than 20 watches, queued synchronously
202 Accepted - 20+ watches, queued in background

Apply Settings to Multiple Watches

To apply tag settings to all watches in the tag, enable overrides_watch:

import requests

headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}
tag_uuid = '550e8400-e29b-41d4-a716-446655440000'

# Update tag with overrides enabled
data = {
    'overrides_watch': True,
    'notification_urls': ['mailto:team@example.com'],
    'time_between_check': {
        'hours': 2
    }
}

response = requests.put(
    f'http://localhost:5000/api/v1/tag/{tag_uuid}',
    headers=headers,
    json=data
)

When overrides_watch is true, the tag’s settings take precedence over individual watch settings.

Overview

Endpoints

Tags

Tag Management

List All Tags

Response Fields

Example

Create a Tag

Request Body

Example

Get a Single Tag

Path Parameters

Query Parameters

Example

Update a Tag

Path Parameters

Request Body

Example

Delete a Tag

Path Parameters

Example

Tag Configuration Options

Common Tag Settings

Bulk Operations

Recheck All Watches in Tag

Apply Settings to Multiple Watches

​Tag Management

​List All Tags

​Response Fields

​Example

​Create a Tag

​Request Body

​Example

​Get a Single Tag

​Path Parameters

​Query Parameters

​Example

​Update a Tag

​Path Parameters

​Request Body

​Example

​Delete a Tag

​Path Parameters

​Example

​Tag Configuration Options

​Common Tag Settings

​Bulk Operations

​Recheck All Watches in Tag

​Apply Settings to Multiple Watches

Tag Management

List All Tags

Response Fields

Example

Create a Tag

Request Body

Example

Get a Single Tag

Path Parameters

Query Parameters

Example

Update a Tag

Path Parameters

Request Body

Example

Delete a Tag

Path Parameters

Example

Tag Configuration Options

Common Tag Settings

Bulk Operations

Recheck All Watches in Tag

Apply Settings to Multiple Watches