Every piece of user-generated content must be submitted to Moderation Dashboard as its own task. But on many online platforms, user-generated content comes in groups—images and their captions, comments and replies, conversations, and frames of a livestream. To make sure this important context is visible to moderators while moderating, there are several different ways to capture the relationship between different tasks as you send them to Moderation Dashboard. On this page, we'll outline each of those ways, what kinds of content they're used for, and what special fields to include in those submissions.

🚧
Regardless of the type of submission you use, all posts must include a post_id and user_id. The post_id should always be unique for every submission to Moderation Dashboard.

General Submissions

Submitting a Single Task

Some tasks may not need to be part of groups at all. For example, a single image posted with no caption can be submitted without the use of any special fields. For more technical information about submitting an API request, see our API reference page. The example below shows a single task submission with no group. All submissions must include post_id and user_id fields.

Grouping Tasks Together in a Thread

There are several special fields you can use that allow you to submit pieces of content to be moderated individually, while still grouping the content together and capturing a hierarchy between the tasks. This is especially helpful for social media posts that include multiple elements, such as images, a caption, several comments, and replies to those comments.

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.

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.

The example below shows how to capture the relationship between different parts of the same social media post with group_id and parent_id:

📘
What should the parent ID be?
If you're replying to a group, the parent_id will be the group_id of that group. If you're replying to a single post, the parent_id will be that post's post_id.

Below are example cURL requests using parent_id and group_id. Submissions without either of those fields will still be in default threads format, but will not include any sort of post hierarchy.

curl --location 'https://api.hivemoderation.com/api/v2/task/sync' \
--header 'authorization: token 123' \
--header 'Content-Type: application/json' \
--data '{
    "user_id":"user-id-1",
    "post_id": "post-id_1",
    "group_id": "group-id-1",
    "text_data": "Example of post with group ID",
    "user_metadata": {
        "user_age": 20
    },
    "models": ["text"]
}'

curl --location 'https://api.hivemoderation.com/api/v1/task/sync' \
--header 'authorization: token 123' \
--header 'Content-Type: application/json' \
--data '{
    "user_id":"user-id-1",
    "post_id": "post-id-1",
    "parent_id": "parent-id-1",
    "text_data": "Missing out on all the fun with you guys! :weary: Make sure to bring back some of that aloha spirit with you. Can'\''t wait to catch up",
    "user_metadata": {
        "user_age": 20
    }
}'

Click into a Review Task to view the entire post and all associated comments — Click into a review task to view the entire post and all associated comments

Conversations

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.

Sending Conversations to the Dashboard

To start sending conversations to Moderation Dashboard, you will need to include a conversation_id field and optionally a timestamp field within the API request. Moderation Dashboard will use the conversation_id to group all related messages in the correct order. The example below shows one conversation submitted as five separate API requests:

📘
Use separate API requests
Each post (message) should still be sent in a separate API request. Moderation Dashboard will use the conversation_id to group all related posts.
Conversation_ids must be unique ids that are separate from post_ids and user_ids.

curl --location --request POST 'https://api.hivemoderation.com/api/v2/task/sync' \
--header 'authorization: token 123456789' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user_id":"user-1",
    "post_id": "post-1",
    "text_data": "Hey, hows it going?",
    "conversation_id": "123",
    "timestamp": 1682723130065,
     "models": ["text"]
}'

View Conversational Context

Once you start submitting the conversation ID, you will be able to view the context surrounding a given Review Feed task.

All messages sent by the user whose task is in review will be on the right side of the task tile.
All unique users part of the conversation will have their own task color.
By default, 15 proceeding and 15 subsequent posts from the review task will be shown. If however, a moderator requires additional context, they can click into the review task and view the entire conversation history.

Click into a Review Task to view the entire conversation — Click into a review task to view the entire conversation

Livestreams

Use the special fields stream_id and stream_url to submit a livestream to Moderation Dashboard. Once you have a livestream project set up, you can then create rules to route violative livestreams to the Review Feed. Moderators can view the exact frame that was flagged along with the ongoing livestream side-by-side.

Submitting a Livestream

To submit a livestream to the Moderation Dashboard, you can submit individual frames from a livestream as separate tasks to the Visual Moderation model while also submitting a stream URL that will displayed alongside the frame from the livestream.

Submitting as Individual Frames

When submitting a livestream as a series of individual frames, you should include the same stream_id and stream_url across all frames. See the example below to illustrate how this is done. Include frame_urlto submit each livestream frame along with the timestamp in epoch milliseconds.

Below is an example cURL request for an individual frame.

curl --location 'https://api.hivemoderation.com/api/v2/task/sync' \
--header 'authorization: token 123' \
--header 'Content-Type: application/json' \
--data '{
    "user_id":"user1",
    "stream_id": "livestream-oct17-1",
    "stream_url": "www.example-livestream-url.com",
    "frame_url": "https://d24edro6ichpbm.thehive.ai/demo_static_media/moderation/nsfw_5.jpg",
    "timestamp": 1743802954120,
    "models": ["visual"]
}'

Regardless of the type of submission you use, all posts must include a post_id and user_id. The post_id should always be unique for every submission to Moderation Dashboard.

General Submissions

Submitting a Single Task

Grouping Tasks Together in a Thread

What should the parent ID be?

Conversations

Sending Conversations to the Dashboard

Use separate API requests

View Conversational Context

Livestreams

Submitting a Livestream

Submitting as Individual Frames

Regardless of the type of submission you use, all posts must include a `post_id` and `user_id`. The `post_id` should always be unique for every submission to Moderation Dashboard.