Hive ModelsModeration Dashboard
Docs
Log inSign up
Start typing to search…

v1 - Dashboard API Reference

The Moderation API is the interface you will use to send user-generated data to Moderation Dashboard. It will then return a response with the rules that were auto-triggered, along with additional data depending on your needs.


Authentication

Each Moderation Dashboard application has a unique API key that will need to be included in the API request. The API key will be sent via email after getting access to Moderation Dashboard.

📘

Authentication

Include the API Key in the header of your POST request ('authorization: token <YOUR_API_KEY>').


Submitting a Task to the Dashboard via API

Moderation Dashboard supports both synchronous (sync) and asynchronous (async) API interface protocols. Our technical team is happy to help you determine the submission process that best fits your use case.

As a general guideline:

Sync API

Async API

A synchronous endpoint is preferred for users who have real-time needs, low latency requirements, and are submitting continuous/cyclical requests.

The synchronous endpoint keeps the HTTP request open until results have finished processing and then sends the results directly in the response message.

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).

The asynchronous endpoint 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.


Sync Request

https://api.hivemoderation.com/api/v1/task/sync

Form Data

Field (*required)

Type

Description

text_data*

String

Raw text data. You can only submit one piece of content (text_data OR url) per API request with our v1 API.

If no models field is specified, text content will be sent to the Text Moderation API by default.

url*

String

Publicly accessible url for sending images and videos (max 1 hr). You can only submit one piece of content (text_data OR url) per API request with our v1 endpoint.

If no models field is specified, visual content will be sent to the Visual Moderation API by default.

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).

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 of 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

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.

models

Array

Specify the models you want to use in the models array:

Visual Moderation: "visual"

Text Moderation array: "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"

Likeness: "likeness"

Celebrity: "celebrity"

Custom Index: "<your_custom_index_id>" (defined when Index is created from Moderation Dashboard)

Note: Only one model is supported in this array for our v1 endpoint. This means that you can not submit to multiple models in one API call.

If you would like to submit multiple models at the same time, please refer to our v2 API documentation.

🚧

Note:

You can only send one piece of content per API request with the v1 endpoint. You will not be able to send both text_data and url in the same request.

To submit to multiple models in the same API request, refer to our v2 API documentation.


Submitting to Visual or Text Moderation API

curl --location --request POST 'https://api.hivemoderation.com/api/v1/task/sync' \
--header 'authorization: token <API Token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user_id": "945455793",
    "post_id": "7756488575",
    "url": "https://d24edro6ichpbm.thehive.ai/demo_static_media/nsfw/nsfw_2.jpg"
}'
var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://api.hivemoderation.com/api/v1/task/sync',
  'headers': {
    'authorization': 'token <API Token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "user_id": "945455793",
    "post_id": "7756488575",
    "url": "https://d24edro6ichpbm.thehive.ai/demo_static_media/nsfw/nsfw_2.jpg"
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
import requests
import json

url = "https://api.hivemoderation.com/api/v1/task/sync"

payload = json.dumps({
  "user_id": "945455793",
  "post_id": "7756488575",
  "url": "https://d24edro6ichpbm.thehive.ai/demo_static_media/nsfw/nsfw_2.jpg"
})
headers = {
  'authorization': 'token <API Token>',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"user_id\": \"945455793\",\n    \"post_id\": \"7756488575\",\n    \"url\": \"https://d24edro6ichpbm.thehive.ai/demo_static_media/nsfw/nsfw_2.jpg\"\n}");
Request request = new Request.Builder()
  .url("https://api.hivemoderation.com/api/v1/task/sync")
  .method("POST", body)
  .addHeader("authorization", "token <API Token>")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

Submitting to OCR or Demographics API

curl --location --request POST 'https://api.hivemoderation.com/api/v1/task/sync' \
--header 'authorization: token <API Token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user_id": "945455793",
    "post_id": "7756488575",
    "url": "https://d24edro6ichpbm.thehive.ai/demo_static_media/nsfw/nsfw_2.jpg",
    "models": ["demographic"],
}'
var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://api.hivemoderation.com/api/v1/task/sync',
  'headers': {
    'authorization': 'token <API Token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "user_id": "945455793",
    "post_id": "7756488575",
    "url": "https://d24edro6ichpbm.thehive.ai/demo_static_media/nsfw/nsfw_2.jpg",
    "models": ["demographic"],
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
import requests
import json

url = "https://api.hivemoderation.com/api/v1/task/sync"

payload = json.dumps({
  "user_id": "945455793",
  "post_id": "7756488575",
  "url": "https://d24edro6ichpbm.thehive.ai/demo_static_media/nsfw/nsfw_2.jpg",\
  "models": ["demographic"],
})
headers = {
  'authorization': 'token <API Token>',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"user_id\": \"945455793\",\n    \"post_id\": \"7756488575\",\n    \"url\": \"https://d24edro6ichpbm.thehive.ai/demo_static_media/nsfw/nsfw_2.jpg\",\n    \"models\": [\"demographic\"]\n}");
Request request = new Request.Builder()
  .url("https://api.hivemoderation.com/api/v1/task/sync")
  .method("POST", body)
  .addHeader("authorization", "token <API Token>")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

Submitting to Custom Index Search

Adding an Image to Your Index

curl --request POST \
  --url https://api.hivemoderation.com/api/v1/custom_index/your_custom_index_id/add/sync \
  --header 'authorization: token 123' \
  --header 'content-type: application/json' \
  --data '{
    "url": "https://d24edro6ichpbm.thehive.ai/demo_static_media/nsfw/nsfw_2.jpg",
    "metadata": {"my_key2": "my_value2"},
    "content_variant": "bio_pic"
}'

Removing an Image from Your Index

curl --request POST \
  --url https://api.hivemoderation.com/api/v1/custom_index/test-id/remove/sync \
  --header 'authorization: token 123' \
  --header 'content-type: application/json' \
  --data '{
  "custom_index_item_id": "5RgNW8ZGUQxn5Pgklh3AhV_828bc2f3-a604-4856-bd2f-e8fec93b7a25_121_350fc92b8db1062fddcfafaaa0d12493615c31a71089d3104ccd06686961e9cb"
}'

Task Submission to Custom Index Model (Note: Use v2 endpoint)

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  
    }  
}'

Async Request

https://api.hivemoderation.com/api/v1/task/async

Form Data

Field (*required)

Type

Description

text_data*

String

Raw text data. You can only submit one piece of content (text_data OR url) per API request.

If no models field is specified, text content will be sent to the Text Moderation API by default.

url*

String

Publicly accessible url for sending images and videos (max 1 hr). You can only submit one piece of content (text_data OR url) per API request.

If no models field is specified, visual content will be sent to the Visual Moderation API by default.

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).

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.

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 of 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

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.

models

Array

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"

OCR: "ocr"

Deepfake Detection: "deepfake"

Demographics: "demographic"

Audio: "audio"

Custom Index: "<your_custom_index_id>" (defined when Index is created from Moderation Dashboard)

Note: Currently, only one model is supported in this array. This means that you can not submit to multiple models in one API call. For example, if you would like to submit to both OCR and Visual Moderation, two different API requests will need to be made with the same post/user IDs.


Submitting to Visual or Text Moderation API

curl --location --request POST 'https://api.hivemoderation.com/api/v1/task/async' \
--header 'authorization: token <API Token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user_id": "945455793",
    "post_id": "7756488575",
    "text_data": "Hey reach out to me, my number is 546-855-5512",
    "callback_url": "https://webhook.site/c9480f48-9df1-4681-947d-1fa19aeb461c"
}'
var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://api.hivemoderation.com/api/v1/task/async',
  'headers': {
    'authorization': 'token <API Token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "user_id": "945455793",
    "post_id": "7756488575",
    "text_data": "Hey reach out to me, my number is 546-855-5512",
    "callback_url": "https://webhook.site/c9480f48-9df1-4681-947d-1fa19aeb461c"
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
import requests
import json

url = "https://api.hivemoderation.com/api/v1/task/async"

payload = json.dumps({
  "user_id": "945455793",
  "post_id": "7756488575",
  "text_data": "Hey reach out to me, my number is 546-855-5512",
  "callback_url": "https://webhook.site/c9480f48-9df1-4681-947d-1fa19aeb461c"
})
headers = {
  'authorization': 'token <API Token>',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"user_id\": \"945455793\",\n    \"post_id\": \"7756488575\",\n    \"text_data\": \"Hey reach out to me, my number is 546-855-5512\",\n    \"callback_url\": \"https://webhook.site/c9480f48-9df1-4681-947d-1fa19aeb461c\"\n}");
Request request = new Request.Builder()
  .url("https://api.hivemoderation.com/api/v1/task/async")
  .method("POST", body)
  .addHeader("authorization", "token <API Token>")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

Submitting to OCR or Demographics API

curl --location --request POST 'https://api.hivemoderation.com/api/v1/task/async' \
--header 'authorization: token <API Token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user_id": "945455793",
    "post_id": "7756488575",
    "text_data": "Hey reach out to me, my number is 546-855-5512",
    "models": ["demographic"],
    "callback_url": "https://webhook.site/c9480f48-9df1-4681-947d-1fa19aeb461c"
}'
var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://api.hivemoderation.com/api/v1/task/async',
  'headers': {
    'authorization': 'token <API Token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "user_id": "945455793",
    "post_id": "7756488575",
    "text_data": "Hey reach out to me, my number is 546-855-5512",
    "models": ["demographic"],
    "callback_url": "https://webhook.site/c9480f48-9df1-4681-947d-1fa19aeb461c"
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
import requests
import json

url = "https://api.hivemoderation.com/api/v1/task/async"

payload = json.dumps({
  "user_id": "945455793",
  "post_id": "7756488575",
  "text_data": "Hey reach out to me, my number is 546-855-5512",
  "models": ["demographic"],
  "callback_url": "https://webhook.site/c9480f48-9df1-4681-947d-1fa19aeb461c"
})
headers = {
  'authorization': 'token <API Token>',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"user_id\": \"945455793\",\n    \"post_id\": \"7756488575\",\n    \"text_data\": \"Hey reach out to me, my number is 546-855-5512\",\n    \"models\": [\"demographic\"],\n    \"callback_url\": \"https://webhook.site/c9480f48-9df1-4681-947d-1fa19aeb461c\"\n}");
Request request = new Request.Builder()
  .url("https://api.hivemoderation.com/api/v1/task/async")
  .method("POST", body)
  .addHeader("authorization", "token <API Token>")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

Submitting to Custom Index Search

Adding an Image to Your Index

curl --request POST \
  --url https://api.hivemoderation.com/api/v1/custom_index/your_custom_index_id/add/async \
  --header 'authorization: token 123' \
  --header 'content-type: application/json' \
  --data '{
    "url": "https://d24edro6ichpbm.thehive.ai/demo_static_media/nsfw/nsfw_2.jpg",
    "callback_url": "https://webhook.site/c9480f48-9df1-4681-947d-1fa19aeb461c",
    "metadata": {"my_key2": "my_value2"},
    "content_variant": "bio_pic"
}'

Removing an Image from Your Index

curl --request POST \
  --url https://api.hivemoderation.com/api/v1/custom_index/test-id/remove/async \
  --header 'authorization: token 123' \
  --header 'content-type: application/json' \
  --data '{
  "custom_index_item_id": "5RgNW8ZGUQxn5Pgklh3AhV_828bc2f3-a604-4856-bd2f-e8fec93b7a25_121_350fc92b8db1062fddcfafaaa0d12493615c31a71089d3104ccd06686961e9cb",
  "callback_url": "https://webhook.site/c9480f48-9df1-4681-947d-1fa19aeb461c"
}'

Task Submission to Custom Index Model (Note: Use v2 endpoint)

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  
    }  
}'

Responses

Moderation Dashboard API Sample Response

{
    "user_id": "1111-122-331",
    "post_id": "23145",
    "task_id": "538e5b30-4d7a-11ec-a5d3-5de59255ac47",
    "triggered_rules": [
        {
            "rule_id": "5phrGLaFGCoURyvTn9AryD",
            "rule_name": "Post has text in Deny List"
        }
    ]
}

Moderation Dashboard API Legacy Response

Moderation Dashboard supports a legacy version of the API response that includes additional data returned from the model in the response (model scores, profanity, pii entities). If you are already using Hive's Moderation APIs, this will make the transition over to the Moderation Dashboard API easier. You can choose to receive this response by including "?legacy=1 " parameter at the end of the POST URL.

https://api.hivemoderation.com/api/v1/task/sync?legacy=1

Below is an example of a legacy response:

{
    "content_id": "3ghgevEKMQPE3kQDV1iwDl_2022-04-05T02:58:51.000Z_axImEu96VEaGDF7ee5m9wg_945455793",
    "user_id": "945455793",
    "post_id": "7756488575",
    "task_id": "53159ff0-b48c-11ec-adf2-19cd8b5f81b4",
    "triggered_rules": [
        {
            "id": "3yIkuqerrtsmzVj42Fn3MiEgD",
            "display_name": "Send to Review Feed",
            "application_id": "axImEugj96VEaGDF7ee5m9wg",
            "rule_type": "post",
            "cardinality": 1,
            "active": true,
            "action_id": "send_post_to_review",
            "conditions": [
                {
                    "subject": "post_needs_review"
                }
            ],
            "deleted": false,
            "trigger_frequency": "once",
            "created_at": "2022-03-24T20:25:34.599Z",
            "updated_at": "2022-03-30T12:16:19.546Z"
        }
    ],
    "id": "53159ff0-b48c-11ec-adf2-19cd8b5f81b4",
    "code": 200,
    "project_id": 32267,
    "user_id": 3121654,
    "created_on": "2022-04-05T02:58:52.577Z",
    "status": [
        {
            "status": {
                "code": "0",
                "message": "SUCCESS"
            },
            "response": {
                "input": {
                    "hash": "d36575127e4d1111f25f7e901dc76626",
                    "inference_client_version": "5.2.82",
                    "model": "pytorch_textmod_xlm_roberta_multilevel_03_23_2022",
                    "model_type": "TEXT_CLASSIFICATION",
                    "model_version": 1,
                    "text": "Hey reach out to me, my number is 546-855-5512",
                    "id": "53159ff0-b48c-11ec-adf2-19cd8b5f81b4",
                    "created_on": "2022-04-05T02:58:52.399Z",
                    "user_id": 3121654,
                    "project_id": 32267,
                    "charge": 0.003
                },
                "custom_classes": [],
                "text_filters": [],
                "pii_entities": [
                    {
                        "value": "546-855-5512",
                        "start_index": 34,
                        "end_index": 46,
                        "type": "U.S. Phone Number"
                    }
                ],
                "urls": [],
                "language": "EN",
                "moderated_classes": [
                    "sexual",
                    "hate",
                    "violence",
                    "bullying",
                    "spam",
                    "promotions"
                ],
                "output": [
                    {
                        "time": 0,
                        "start_char_index": 0,
                        "end_char_index": 46,
                        "classes": [
                            {
                                "class": "spam",
                                "score": 3
                            },
                            {
                                "class": "sexual",
                                "score": 0
                            },
                            {
                                "class": "hate",
                                "score": 0
                            },
                            {
                                "class": "violence",
                                "score": 0
                            },
                            {
                                "class": "bullying",
                                "score": 0
                            },
                            {
                                "class": "promotions",
                                "score": 3
                            }
                        ]
                    }
                ]
            }
        }
    ],
    "from_cache": false
}

Updated 2 days ago