Sync Request

POST https://api.hivemoderation.com/api/v1/custom_index/{custom_index_id}/add/sync

Sends a request to add an item to the specified custom index. The synchronous endpoint keeps the HTTP request open until the request completes, then sends the results directly in the response message.

Example Request

curl -X POST https://api.hivemoderation.com/api/v1/custom_index/{custom_index_id}/add/sync \
  -H "Authorization: token <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://d24edro6ichpbm.thehive.ai/demo_static_media/nsfw/nsfw_2.jpg",
    "metadata": { "my_key1": "my_value1" },
    "content_variant": "bio_pic"
  }'

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 (* required)	Type	Description
custom_index_id *	String	ID of the custom index to add the item to. This value should go in the URL path.
url / media *	String	Publicly accessible URL for the media to be sent.
metadata	Object	JSON object of key value pairs that can be custom-defined.
content_variant	String	Custom category/tag to associate with the item.

Sync Response

Response Fields

Field	Type	Always Returned	Description
custom_index_item_id	String	Yes	ID for the custom index item created.
task_id	String	Yes	Task ID for the add request.
message	String	Yes	Status message.

Example Responses

Example Success (200 OK)

{
  "custom_index_item_id": "2bM21a29PFBc9vB5xxKoHL_e2aa8d0b-9ff1-4f57-88e9-3fc3e748623e_0_405832b8477858e58dd9151917418adafcf41e64e628330def3e53a8691df536",
  "task_id": "f0ef74b1-3914-11f1-93fb-150c74186375",
  "message": "Media successfully added to the index"
}

Example Error Response (400 Bad Request)

{
  "error": true,
  "status": 400,
  "error_code": "INVALID_CUSTOM_INDEX",
  "message": "This Custom Index with client ID: my-index-id does not exist",
  "show_alert": false
}

Async Request

POST https://api.hivemoderation.com/api/v1/custom_index/{custom_index_id}/add/async

Adds an item to a custom index. The asynchronous endpoint immediately sends a response acknowledging receipt of the request, along with a unique task_id. It then closes the connection. Once the task is completed, Hive will send a POST request to the provided callback_url containing the completed task's results.

Example Request

curl -X POST https://api.hivemoderation.com/api/v1/custom_index/{custom_index_id}/add/async \
  -H "Authorization: token <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://d24edro6ichpbm.thehive.ai/demo_static_media/nsfw/nsfw_2.jpg",
    "metadata": { "my_key1": "my_value1" },
    "content_variant": "bio_pic",
    "callback_url": "my-callback-url.com"
  }'

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

The async endpoint has all the same parameters as the sync endpoint, plus the following:

Parameter	Type	Required	Description
callback_url	String	No	URL to receive callback when task completes.

Async Response

An async task request will immediately return a response to the user. This will be a response to let the user know that the request has been received (or if an error occurred). After the async task is completed, another response will be sent to the callback_url provided in the initial request. This response will be identical to the sync task's response, which will indicate details about the custom index item id, task id, and API response message.

Response Fields

Field	Type	Always Returned	Description
task_id	String	Yes	Task ID for the add request.
message	String	Yes	Status message.

Example Responses

Example Success (200 OK)

{
  "task_id": "0e853172-3921-11f1-93fb-150c74186375",
  "message": "We received your task (add item to index)."
}

Example Error Response (400 Bad Request)

{
  "error": true,
  "status": 400,
  "error_code": "REQUIRE_AT_LEAST_ONE_PARAM",
  "message": "should have at least one of media,url.",
  "show_alert": false
}

Common Errors

Status Code	Behavior
400	Missing required parameter, invalid type, or invalid index ID.
500	Unable to add custom index.
502	Invalid url/media provided.