v1 - Dashboard API Reference (Single Model Submission)
The Moderation API is the interface you will use to send user generated data to the Dashboard. It will then return a response with the rules that were auto-triggered along with additional data depending on your needs.
Authentication
Each 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 the 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
The 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 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 https://docs.thehive.ai/docs/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 https://docs.thehive.ai/docs/types-of-submissions for more information. |
content_metadata | JSON Object | Content metadata (can be different for each post). View this metadata on the 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 | JSON Object | User metadata tied to each userID on the Dashboard (send with every API request). View this metadata on the Dashboard when you open the User Detailed View. |
models | Array | Specify the models you want to use in the models array: Visual Moderation array element : "visual" Text Moderation array element : "text" AI-Generated Media Recognition array element : "ai_generated_media" AI-Generated Text Detection array element : "ai_generated_text" OCR array element: "ocr" Deepfake array element: "deepfake" Demographics array element: "demographic" Audio array element: "audio" Custom Index array element: "<your_custom_index_id>" (defined when Index is created from the Dashboard) Please 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 to both OCR and Visual Moderation, refer to our API v2 docs https://docs.thehive.ai/docs/dashboard-api-reference-v2-multi-model-support |
Please 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 docs https://docs.thehive.ai/docs/dashboard-api-reference-v2-multi-model-support
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 (Please 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 under"_", ";"scores 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 https://docs.thehive.ai/docs/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 https://docs.thehive.ai/docs/types-of-submissions for more information. |
content_metadata | JSON Object | Content metadata (can be different for each post). View this metadata on the 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 | JSON Object | User metadata tied to each userID on the Dashboard (send with every API request). View this metadata on the Dashboard when you open the User Detailed View. |
models | Array | Specify the models you want to use in the models array: Visual Moderation array element : "visual" Text Moderation array element : "text" AI-Generated Media Recognition array element : "ai_generated_media" AI-Generated Text Detection array element : "ai_generated_text" OCR array element: "ocr" Deepfake array element: "deepfake" Demographics array element: "demographic" Audio array element: "audio" Custom Index array element: "<your_custom_index_id>" (defined when Index is created from the Dashboard) Please 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 (Please note to 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
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"
}
]
}
Dashboard API Legacy Response: The 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 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
Example 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 3 months ago