Types of Submissions

Every piece of user-generated content must be submitted to the 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 the 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 the 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.

See below for example cURL requests using parent_id and group_id. Submissions without either of those fields will still be in default threads format, they just won't 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
    }
}'

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 the Dashboard while moderating.

Sending Conversations to the Dashboard

To start sending conversations to the Dashboard, you will need to include a conversation_id field and optionally a timestamp field within the API request. The 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. The 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 who's 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.

Livestreams

Use the special fields stream_id and stream_url to submit a livestream to the 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 Dashboard, you have two options. You can either submit individual frames from a livestream as separate tasks, or you can submit the entire livestream URL and our system will break up the frames for real-time moderation.

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.

An example cURL request for an individual frame is shown below.

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",
    "url": "www.example-image-url.com/image"
     "models": ["visual"]
}'

Submitting as One URL

Submitting a livestream as one singular URL only requires one API request. Our backend will do all of the work to split up the frames and moderate them individually. For these style of submissions, we only support ASYNC submissions. For more information on how to set this up, please contact our sales team at [email protected].

curl --location 'https://api.hivemoderation.com/api/v2/task/async' \
--header 'authorization: token 123' \
--header 'Content-Type: application/json' \
--data '{
    "user_id":"user1",
    "callback_url": "www.example-callback-URL.com",
    "stream_id": "livestream-oct17-1",
    "stream_url": "www.example-livestream-url.com",
    "models": ["livestream"]
}'