Watchlists

Moderation Dashboard is an add-on designed to complement our existing APIs, such as Visual Moderation, by providing a powerful UI for reviewing flagged content, managing high-stakes workflows, and defining custom automation rules. If you haven’t already upgraded to this feature, contact our team to request access and enhance your moderation capabilities.

The Watchlists tab on the Dashboard allows you to create and manage keyword lists, which you can use inside your custom moderation rule definitions. Use these lists to match against the post's content or metadata and trigger actions based on specific terms.

Creating a Watchlist

To create a watchlist, click the plus button next to All Lists. A new Create Watch List window should pop up. Choose a name for your new watchlist. An API value will be auto-generated according to your chosen name. You can use this API value to add, update, and remove terms from your watchlist via a cURL request.

Uploading Terms

There are three possible ways to upload new terms to a watchlist:

1. Manual (add words to a watchlist manually)
2. CSV (upload CSV with words to add)
3. cURL Request

The first two methods are accessible through the user interface. To upload new terms, click on the watchlist you wish to modify. A new tab should open, displaying the watchlist and its current words. In the tab's top-right corner, click the blue plus button (circled in red in the screenshot below). A new pop-up should open, allowing you to select between uploading new terms manually or through a CSV.

For each new word you add, you can include an optional note field. You can use this note to explain why the word is in the watchlist. It will not be displayed anywhere outside of the watchlist interface.

Manual

Below is a screenshot of the interface for adding words manually. It includes two columns: one for the word, and one for the optional note.

CSV (via UI)

After you select a CSV file to upload, the pop-up shown in the image below will appear. In this window, you can adjust the following fields:

1. Name: Allows you to give your current CSV upload a name, which will be shown in the Upload History tab.
2. Has Header Row: Checkbox that allows you to designate if the top row of your CSV is a header row.
3. Mapping: Allows you to map the appropriate columns as either the term or notes columns. If there are additional columns that are not relevant, leave it as the default -Not Mapped-.

cURL Request

You can use a cURL request to add, update, or remove terms from a watchlist. In your request, make sure to include your API Value, which was auto-generated upon the watchlist's creation. This value can be found in the respective watchlist's tab, underneath its name.

Below are sample requests and responses for each possible action.

Add

Add a new term to the watchlist.

If the term already exists in the watchlist, it will be included in pre_existing_termsin the response and the associated note will be updated accordingly. If there is at least one pre-existing term,"Some terms may already exist in list." will be added to message in the response.

{
  "watchlist": "test_field",  // This is your auto-generated API value.
  "terms": [
    { "term": "term1", "notes": "note1" }, 
    { "term": "term2" }, 
    { "term": "term3", "notes": "note3" }
  ] // Terms to add to watchlist.
}

{
  "message": "Successfully added to list.", // If there is at least one pre-existing term, the following message will be added: "Some terms may already exist in list".
  "watchlist": "test_field",
  "added_terms": [
    { "term": "term2" }, 
    { "term": "term3", "notes": "note3" }
  ],
  "pre_existing_terms": [{ "term": "term1", "notes": "note1" }],
  "failed_terms": []
}

{
  "message": "Unable to add to list. Watchlist does not exist.",
  "watchlist": "test_field"
}

{
  "message": "Successfully added to list.",
  "watchlist": "test_field",
  "terms": [
    { "term": "term2" }, 
    { "term": "term3", "notes": "note3" }
  ]
}

Update

Update an existing term's associated note. NOTE: You can only edit the note; you cannot edit the term itself.

If you attempt to update a term that doesn't exist in the watchlist, it will be included innon_existent_terms in the response. If there is at least one non-existent term,"Some terms may not exist in list." will be added to message in the response.

{
  "watchlist": "test_field",  // This is your auto-generated API value.
  "terms": [
    { "term": "term2", "notes": "updated second note" },
    { "term": "nonexistant_term", "notes": "this term doesn't exist"}
  ] // Watchlist terms to update.
}

{
  "message": "Successfully updated list.", // If there is at least one non-existent term, the following message will be added: "Some terms may not exist in list".
  "watchlist": "test_field",
  "updated_terms": [
    { "term": "term2", "notes": "updated second note" }
  ],
  "non_existent_terms": [ { "term": "nonexistant_term", "notes": "this term doesn't exist"} ],
  "failed_terms": []
}

{
  "message": "Unable to update list. Watchlist does not exist.",
  "watchlist": "test_field"
}

{
  "message": "Successfully updated list.",
  "watchlist": "test_field",
  "terms": [
    { "term": "term2", "notes": "updated second note" }
  ]
}

Remove

Remove an existing term.

If you attempt to remove a term that doesn't exist in the watchlist, it will be included in non_existent_terms in the response. If there is at least one non-existent term,"Some terms may not exist in list." will be added to message in the response.

{
  "watchlist": "test_field",  // This is your auto-generated API value.
  "terms": ["term1", "term2", "term4"] // Watchlist terms to remove.
}

{
  "message": "Successfully removed from list.", // If there is at least one non-existent term, the following message will be added: "Some terms may not exist in list".
  "watchlist": "test_field",
  "removed_terms": ["term1", "term2"],
  "non_existent_terms": ["term4"],
  "failed_terms": []
}

{
  "message": "Unable to remove from list. Watchlist does not exist.",
  "watchlist": "test_field"
}

{
  "message": "Successfully removed from list.",
  "watchlist": "test_field",
  "terms": ["term1", "term2"]
}

Creating Rules With Watchlists

After you've created a watchlist and added terms, you can use it within one of your custom moderation rules. Navigate to the Rules tab and click on the "+ Create Rule" button. For a detailed guide on creating a new rule, please refer to the following documentation.

In the Conditions section of the Create New Rule window, you can set one or more of the following rule triggers:

1. Post Contains Terms in Watch Lists
2. Any Selected Content Metadata Field Contains Terms in Watch List
3. Any Selected User Metadata Field Contains Terms in Watch List

You can also select which watchlist(s) this trigger should apply to, as well as what actions the rule should take.

After configuring the rule, you can start sending submissions.

Submissions

When you send a submission, make sure to add check_watchlists: true to the body of your cURL request. A sample request and response are shown below. If a rule associated with one of your watchlists was triggered, it will show up in triggered_rules.

curl --request POST \
  --url https://api.hivemoderation.com/api/v1/task/sync \
  --header 'authorization: token <YOUR_TOKEN>' \
  --header 'content-type: application/json' \
  --data '{
    "patron_id": "celebrate-03",
    "post_id": "hive-bio-value-manual-126274",
    "text_data": "This is a lovely day for a brand new watch. Call me at 210858063",
    "check_watchlists": true,
    "content_metadata": {
      "username": "cheapPhones4U",
      "Center": {
        "Phone": "2108528063"
      }
    },
    "user_metadata": {
      "Center": {
        "Name": "vansh"
      }
    }
  }'

{
  "task_id": "d7e683e0-5dce-11f0-9f97-17407ee833d8",
  "post_id": "hive-bio-value-manual-126274",
  "user_id": "celebrate-03",
  "content_id": "1wI6qiAXaQ98YCrNFDiozQ_2025-07-10T20:45:41.512Z_0U0TVGlciG0X2elhbKOSb8",
  "triggered_rules": [
    {
      "rule_id": "3uICgZDUyy8bcGwXdTpVBA",
      "rule_name": "Watchlist Test Rule",
      "action_params": [
        { "id": "send_post_to_review", "policies": [], "action_reason_ids": [] }
      ]
    }
  ],
  "triggered_background_rules": []
}