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.
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.
user_id*	String	ID of the user that published the content. (No underscores in the ID)
post_id*	String	ID tied to the post that was published. (No underscores in the ID)
content_metadata	JSON Object	Content metadata (can be different for each piece of content under the same postID). View this metadata on the Dashboard when you click into a piece of content.
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.
ocr_url	String	Publicly accessible url for sending images and videos (max 1 hr) you would like to go through the OCR Moderation model. To test OCR Moderation, please reach out to [email protected].

🚧
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. To submit more than one related content, you can use the same post_id to tie the different pieces of content under one post.

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

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.
url	String	Publicly accessible url for sending images and videos. You can only submit one piece of content (text_data OR url) per API request.
user_id*	String	ID of the user that published the content
post_id*	String	ID tied to the post that was published
callback_url*	String	Callback url where Hive will post model response
content_metadata	JSON Object	Content metadata (can be different for each piece of content under the same postID). View this metadata on the Dashboard when you click into a piece of content.
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.

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

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
}

Authentication

📘

Submitting a Task to the Dashboard via API

Sync Request

🚧Please Note:

Async Request

Responses

🚧
Please Note: