POST https://api.hivemoderation.com/api/v1/watchlist/update

Update the metadata (e.g. notes) of one or more existing terms in a watchlist.

Example Request

curl -X POST https://api.hivemoderation.com/api/v1/watchlist/update \
  -H "Authorization: token <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "watchlist": "my-watchlist",
    "terms": [
      { "term": "example term", "notes": "Updated context for this term." }
    ]
  }'

Request

Headers

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.

Request Body Parameters

Parameter	Type	Required	Description
watchlist	string	Yes	The unique API field name identifying the target watchlist.
terms	array	Yes	Array of term objects to be updated (see Term Object below).

Term Object

Field	Type	Required	Description
term	string	Yes	The term to update. Must already exist in the watchlist. Maximum 1024 characters.
notes	string	No	Updated notes for this term. Set to null to clear existing notes. Maximum 1024 characters.

Field

Type

Required

Description

term

string

Yes

The term to update. Must already exist in the watchlist.

Maximum 1024 characters.

notes

string

Updated notes for this term. Set to null to clear existing notes.

Maximum 1024 characters.

Notes

This endpoint only updates existing terms. Terms not found in the watchlist are returned under non_existent_terms and are not created.
Terms are normalized to lowercase before matching.

Responses

Response Fields

Field	Type	Always Returned	Description
message	string	Yes	Human-readable result summary.
watchlist	string	Yes	The watchlist API field name provided in the request.
updated_terms	array	Yes	Term objects successfully updated in the watchlist.
non_existent_terms	array	Yes	Term objects that were not found in the watchlist.
failed_terms	array	Yes	Terms that could not be processed due to an error.

Example Success (200 OK)

{
  "message": "Successfully updated list.",
  "watchlist": "my-watchlist",
  "updated_terms": [
    { "term": "example term", "notes": "Updated context for this term." }
  ],
  "non_existent_terms": [],
  "failed_terms": []
}

Example Error Response (400 Bad Request)

{
  "error": true,
  "status": 400,
  "error_code": "PARAM_REQUIRED",
  "message": "watchlist is required.",
  "show_alert": false
}

Common Errors

Status Code	Error Code	Description
400	PARAM_REQUIRED	Missing required parameter or invalid type.
403	INVALID_API_KEY	No application matches the provided API key.