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 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. You can only submit one piece of content (text_data OR url) per API request.

patron_id*

String

ID of the user that published the content

post_id*

String

ID tied to the post that was published

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.

patron_metadata

JSON Object

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

🚧

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 lGqhHDletUtTv7sONMTqWJ' \
--header 'Content-Type: application/json' \
--data-raw '{
    "patron_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 lGqhHDletUtTv7sONMTqWJ',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "patron_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({
  "patron_id": "945455793",
  "post_id": "7756488575",
  "url": "https://d24edro6ichpbm.thehive.ai/demo_static_media/nsfw/nsfw_2.jpg"
})
headers = {
  'authorization': 'token lGqhHDletUtTv7sONMTqWJ',
  '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    \"patron_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 lGqhHDletUtTv7sONMTqWJ")
  .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.

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

patron_metadata

JSON Object

Patron 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 lGqhHDletUtTv7sONMTqWJ' \
--header 'Content-Type: application/json' \
--data-raw '{
    "patron_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 lGqhHDletUtTv7sONMTqWJ',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "patron_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({
  "patron_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 lGqhHDletUtTv7sONMTqWJ',
  '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    \"patron_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 lGqhHDletUtTv7sONMTqWJ")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

Responses

Dashboard API Sample Response:

{
    "patron_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",
    "patron_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
}