POST https://api.hivemoderation.com/api/v1/watchlist/add
Adds one or more terms to an existing watchlist.
curl -X POST https://api.hivemoderation.com/api/v1/watchlist/add \
-H "Authorization: token <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"watchlist": "my-watchlist",
"terms": [
{ "term": "example term", "notes": "Optional context for this term." }
]
}'
| Header | Type | Required | Description |
|---|
| Authorization | string | Yes | API key from Hive Moderation Dashboard (per-application). |
| Content-Type | string | Yes | Submit JSON data in the request body. |
| Parameter | Type | Required | Description |
|---|
| watchlist | string | Yes | The unique API field name identifying the target watchlist. |
| terms | array | Yes | Array of term objects to add (see Term Object below). |
| Field | Type | Required | Description |
|---|
| term | string | Yes | The term to be added.
Maximum 1024 characters. |
| notes | string | No | Optional context for the term.
Maximum 1024 characters. |
- Terms are normalized to lowercase before matching.
- If a term already exists in the watchlist, any existing notes will be overwritten by the given value.
| Field | Type | Always Returned | Description |
|---|
| message | string | Yes | Human-readable result summary. |
| watchlist | string | Yes | The watchlist API field name provided in the request. |
| added_terms | array | Yes | Term objects successfully added to the watchlist. |
| pre_existing_terms | array | Yes | Term objects that already exist in the watchlist. |
| failed_terms | array | Yes | Terms that could not be processed due to an error. |
{
"message": "Successfully added to list.",
"watchlist": "my-watchlist",
"added_terms": [
{ "term": "example term", "notes": "Optional context for this term." }
],
"pre_existing_terms": [],
"failed_terms": []
}
{
"error": true,
"status": 400,
"error_code": "PARAM_REQUIRED",
"message": "watchlist is required.",
"show_alert": false
}
| Status Code | Error Code | Description |
|---|
| 403 | PARAM_REQUIRED | Missing required parameter or invalid type. |
| 400 | INVALID_API_KEY | No application matches the provided API key. |
