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

GET

endpoint

/api/v1/tags

Retrieve a list of all tags/groups.

Response Fields

uuid

string

Unique identifier for the tag

title

string

Tag name/title

date_created

integer

Unix timestamp of creation

notification_muted

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"

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

POST

endpoint

/api/v1/tag

Create a new tag/group.

Request Body

title

string

required

Name for the tag/group

notification_urls

array

Array of notification URLs (Apprise format) for this tag

notification_muted

boolean

default:false

Whether notifications are muted for watches in this tag

overrides_watch

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

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

Get a Single Tag

GET

endpoint

/api/v1/tag/

Retrieve information about a specific tag.

Path Parameters

uuid

string

required

UUID of the tag

Query Parameters

muted

string

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

recheck

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"

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

PUT

endpoint

/api/v1/tag/

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

Path Parameters

uuid

string

required

UUID of the tag to update

Request Body

title

string

Update the tag name

notification_urls

array

Update notification URLs for this tag

notification_muted

boolean

Update notification mute state

overrides_watch

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

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

Delete a Tag

DELETE

endpoint

/api/v1/tag/

Delete a tag and remove it from all watches.

Path Parameters

uuid

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"

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

notification_urls

array

Array of Apprise notification URLs

notification_title

string

Custom notification title template

notification_body

string

Custom notification body template

notification_format

string

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

notification_muted

boolean

Mute all notifications for watches in this tag

Check Interval Settings

time_between_check

object

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

time_between_check_use_default

boolean

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

Fetch Settings

fetch_backend

string

Backend: system, html_requests, html_webdriver, extra_browser_*

method

string

HTTP method: GET, POST, PUT, DELETE

headers

object

Custom HTTP headers as key-value pairs

proxy

string

Proxy configuration key

Content Filtering

include_filters

array

CSS/XPath selectors to extract specific content

subtractive_selectors

array

CSS/XPath selectors to remove content

ignore_text

array

Text patterns to ignore in change detection

trigger_text

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"

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.

Documentation Index

​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