Dashboard API Reference

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.

📘
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 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. 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 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	To send content to the AI Generated Text/Media, OCR or Demographics model, you will need to specify a model in the models array. AI-Generated Media Recognition array element : "ai_generated_media" AI-Generated Text Detection array element : "ai_generated_text" OCR array element: "ocr" Demographics array element: "demographic" Audio array element: "audio" 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.

🚧
Please Note:
You can only send one piece of content per API request. You will not be able to send both text_data and url in the same request. Please ensure all post_ids are unique.

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();

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	To send content to the AI Generated Text/Media, OCR or Demographics model, you will need to specify a model in the models array. AI-Generated Media Recognition array element : "ai_generated_media" AI-Generated Text Detection array element : "ai_generated_text" OCR array element: "ocr" Demographics array element: "demographic" Audio array element: "audio" 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();

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
}