POST https://api.hivemoderation.com/api/v2/task/async

The asynchronous endpoint is preferred for users who are submitting their volume in large batches, or users submitting tasks containing large files (i.e. longer videos or audio clips). It immediately sends a response acknowledging receipt of the task, 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.

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

The async endpoint has all of 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.

Example Submission to Visual, OCR, and Audio Moderation Models

curl --request POST \
  --url https://api.hivemoderation.com/api/v2/task/async \
  --header 'authorization: token 123' \
  --header 'content-type: application/json' \
  --data '{
    "user_id":"hive-test-patron-392932",
    "post_id": "v2-hive-test-392932",
    "url": "https://d24edro6ichpbm.thehive.ai/demo_static_media/nsfw/nsfw_1.mp4",
    "models":["ocr","visual","audio"],
    "content_metadata":{
        "content": "paying"
    },
    "user_metadata": {
        "user_age": 20
    },
    "callback_url": "https://customer-callback-url.com"
}'

Example Submission to Text Moderation Model

curl --request POST \
  --url https://api.hivemoderation.com/api/v2/task/async \
  --header 'Authorization: token 123' \
  --header 'Content-Type: application/json' \
  --data '{
    "patron_id":"test-user-id-1",
    "post_id":"480035",
    "conversation_id":"4",
    "models":["text"],
    "text_data":"my text here",
    "user_tags":["tag1","tag2"],
    "callback_url": "https://customer-callback-url.com"
  }'

Example Submission to Custom Index Model

For adding and removing items from a custom index, refer to the following documentation: Custom Index (Add) and Custom Index (Remove).

curl --request POST  
  --url <https://api.hivemoderation.com/api/v2/task/async>  
  --header 'authorization: token 123'  
  --header 'content-type: application/json'  
  --data '{  
    "user_id":"945455793",  
    "post_id": "7756488575",  
    "url": "https://d24edro6ichpbm.thehive.ai/demo_static_media/nsfw/nsfw_2.jpg",
    "callback_url": "https://webhook.site/c9480f48-9df1-4681-947d-1fa19aeb461c",
    "models": ["your_custom_index_id"],  
    "content_metadata":{  
        "content": "paying"  
    },  
    "user_metadata": {  
        "user_age": 20  
    }  
}'

Response

An async task submission will immediately return a response to the user. This will be a response to let the user know that the submission 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 a sync task's response, which will indicate more details about the submission, including the task IDs, statuses, and triggered rules.

Response Fields

Field	Type	Always Returned	Description
task_ids	List`<String>`	Yes	Unique identifier for the task(s). A unique value is generated per model submission.
content_id	String	Yes	Timestamp (ISO 8601 format) when the appeal was created.
user_id	String	Yes	Unique user ID.
post_id	String	Yes	Unique post ID.
conversation_id	String	No	Echoed back if submitted.
group_id	String	No	Echoed back if submitted.
parent_id	String	No	Echoed back if submitted.
stream_id	String	No	Echoed back if submitted.
message	String	No	Returned if an error occurred (e.g. invalid user tags).
invalid_user_tags	List`<String>`	No	Array of invalid tag names that were submitted.
project_status_map	JSON Object	Yes	ID of the post about which the appeal was made.

Example Responses

Example Success (200 OK)

{
  "task_ids": [
    "ccb639c1-2fb0-11f1-aebe-2f17edb80305"
  ],
  "post_id": "939622",
  "user_id": "test-user-id-1",
  "conversation_id": "4",
  "project_status_map": {
    "12345": {
      "moderation_type": "text",
      "task_id": "ccb639c1-2fb0-11f1-aebe-2f17edb80305",
      "status": "pending"
    }
  },
  "invalid_user_tags": [
    "tag2",
    "tag1"
  ],
  "message": "We received your submission. Invalid User Tags: tag2,tag1"
}

Example Error Response (400 Bad Request)

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