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

A synchronous endpoint is preferred for users who have real-time needs, low latency requirements, and are submitting continuous / cyclical requests. It keeps the HTTP request open until results have finished processing and then sends the results directly in the response message.

Request

Note: This is an example request intended to show the expected formatting. It contains all the required and optional parameters, some of which cannot be sent together in the same request. More specific examples are outlined in the following sections.

curl -X POST https://api.hivemoderation.com/api/v2/task/sync \
  -H "Authorization: token <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "text_data": "Sample text data.",
    "url": "sample-url.com",
    "patron_id": "patron-id-1",
    "post_id": "post-1",
    "models": ["visual", "ocr"],
    "group_id": "group-id-1",
    "conversation_id": "conversation-id-1",
    "parent_id": "parent-id-1",
    "content_metadata": {
      "content_metadata_1": "sample-content-metadata-1",
    },
    "content_variant": "content-variant-1",
    "user_metadata": {
      "user_metadata_1": "sample-user-metadata-1",
    }
    "stream_url": "stream-url.com",
    "stream_id": "stream-id-1",
    "frame_url": "frame-url.com",
    "thorn_enabled": true,
    "timestamp": 123456789,
    "user_tags": "["tag1", "tag2"],
    "reference_url": "sample-reference-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

Parameter (* required)	Type	Description
text_data *	String	Raw text data for task submission.
url *	String	Publicly accessible URL for sending images and videos.
patron_id / user_id *	String	ID of the user that published the content (No "_", ";" in the ID).
post_id *	String	ID tied to the post that was published (unique for each submission, no "_", ";" in the ID).
models *	List`<String>`	Specify the models you want to use in the models array: Visual Moderation : "visual" Text Moderation: "text" AI-Generated Image and Video Detection: "ai_generated_media" AI-Generated Text Detection: "ai_generated_text" AI-Generated Audio Detection: "ai_generated_audio" OCR: "ocr" Deepfake Detection: "deepfake" Demographics: "demographic" Audio: "audio" People Counting: "people_counting" Common Object Detection: "object_detection" Celebrity: "celebrity" Logo: "logo" Custom Index: "`<your_custom_index_id>`" (defined when Index is created from the Dashboard) Face Similarity: "face_similarity" (include url field for target image, and reference_url field for reference image)
group_id	String	To group a series of posts together, they should all be submitted with the same group_id. The group_id is a unique id that is different from the post_id and parent_id. This is especially useful to group together images and their captions, comments that include an image, or AI-generated images and their prompts. Refer to Types of Submissions for more information.
conversation_id	String	For direct messaging, multi-user chats, and gaming live chats, you can instead include the conversation_id field to group tasks together as part of one conversation. This allows the moderator to view conversational context within Moderation Dashboard while moderating. Refer to Types of Submissions for more information.
parent_id	String	The parent_id field captures the hierarchy between different posts by indicating a post's parent. For example, when grouping together a comment and a reply to that comment, the parent_id of the reply will be the post_id of the comment it is replying to. This hierarchy can span multiple levels—a post that has a parent can itself be a parent to a different post. Refer to Types of Submissions for more information.
content_metadata	JSON Object	Content metadata (can be different for each post). View this metadata on Moderation Dashboard when you click into a piece of content.
content_variant	String	Differentiate different types on content published on your platform through content variants. Once you create your content variants on the Settings page, you can send this optional field in the API request and create rules using this field.
user_metadata / patron_metadata	JSON Object	User metadata tied to each user ID on Moderation Dashboard (send with every API request). View this metadata on Moderation Dashboard when you open the User Detailed View.
stream_url	String	Livestream URL. Requires stream_id. Cannot use with frame/frame_url/post_id for non-livestream models.
stream_id	String	Required if stream_url is provided.
frame_url	String	Frame URL for livestream. Requires both timestamp and stream_id.
thorn_enabled	Boolean	Enables Thorn detection. If true, makes models optional.
timestamp	Integer	A Unix timestamp (milliseconds). Must be within ±14 days of current time. If not provided, uses the current time.
user_tags	Array	String array of user_tags to apply to the user.
reference_url	String	Required when models includes face_similarity.

Example Submission to Visual, OCR, and Audio Moderation Models

curl --request POST \
  --url https://api.hivemoderation.com/api/v2/task/sync \
  --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
    }
}'

Example Submission to Text Moderation Model

curl --request POST \
  --url https://api.hivemoderation.com/api/v2/task/sync \
  --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"]
  }'

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/sync>  
  --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",
    "models": ["your_custom_index_id"],  
    "content_metadata":{  
        "content": "paying"  
    },  
    "user_metadata": {  
        "user_age": 20  
    }  
}'

Response

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.
sanitized_text	String	No	Text with blocked portions removed.
project_status_map	JSON Object	Yes	ID of the post about which the appeal was made.
triggered_rules	List`<Object>`	Yes	List of triggered rules. Empty list if none triggered.
triggered_background_rules	List`<Object>`	Yes	List of triggered background rules. Empty list if none triggered.
csam_results	List`<String>`	No	Array of CSAM detection results.

Project Status Map Object

Field	Type	Always Returned	Description
moderation_type	String	Yes	Moderation type based on the model that the task was submitted to.
task_id	String	Yes	Unique identifier for the task.
status	String	Yes	Status of the task (success, failed).

Triggered Rules / Triggered Background Rules Object

Field	Type	Always Returned	Description
rule_id	String	Yes	Unique identifier for the rule triggered.
rule_name	String	Yes	Name of the rule triggered.
action_params	List`<Object>`	Yes	List of object(s) of the action(s) triggered. Contains `id`, `display_name`, and `policies` for that action.

Example Responses

Example Success (200 OK)

{
  "task_ids": [
    "8b37e8d1-2fb1-11f1-bc58-ffcbeeed39a2",
    "8b379ab1-2fb1-11f1-ab76-8d376e934c14"
  ],
  "post_id": "709502",
  "user_id": "test-user-id-1",
  "group_id": "1",
  "project_status_map": {
    "12345": {
      "moderation_type": "visual",
      "task_id": "8b37e8d1-2fb1-11f1-bc58-ffcbeeed39a2",
      "status": "success"
    },
    "67890": {
      "moderation_type": "ocr",
      "task_id": "8b379ab1-2fb1-11f1-ab76-8d376e934c14",
      "status": "success"
    }
  },
  "url": "https://my-test-image.url",
  "content_id": "2hOv4qOOw63yEN4VnWRsXr_2026-04-03T23:05:01.486Z_2bM21a29PFBc9vB5xxKoHL",
  "triggered_rules": [
    {
      "rule_id": "6QAg1Vemg0nHjd2e8wMW4M",
      "rule_name": "Rule Test Mode",
      "action_params": [
        {
          "id": "send_post_to_review",
          "display_name": "Flag For Review",
          "policies": []
        }
      ]
    },
    {
      "rule_id": "4P2lHViNAZdeQa9CIRnZQB",
      "rule_name": "If post contains Violence, Sexual, then remove post",
      "action_params": [
        {
          "id": "remove_post",
          "display_name": "Delete Post",
          "policies": []
        }
      ]
    }
  ],
  "triggered_background_rules": []
}

Example Error Response (400 Bad Request)

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