🛂Virtual Moderator endpoint

The Virtual Moderator endpoint provides an easy way to integrate with our Virtual Trust & Safety Agents. These agents leverage a blended solution of AI and humans for our most advanced understanding of content, giving you human-level accuracy quickly and reliably.

1. Authenticate

Please follow the API Authentication instructions first in order to authenticate with Unitary's API. This will generate a token that is valid for 24 hours and must be used in subsequent API requests.

2. AI Pre-filter request (optional)

Please refer to the documentation in Standard & Premium: Policy Classification endpoints for how to send an AI Pre-filter request. Make sure to keep the job_id returned in the AI Pre-filter response which will be used as the classification_job_id field in your Virtual Moderator request.

3. Sending your first request

Use the following POST endpoint to send your first request to the Virtual Moderator endpoint.

Moderate Content

POST/moderate

Authorization

JWTBearer

Body

application/json

main_content*Main Content

MediaMainContentTextMainContent

classification_job_idClassification Job Id

string (uuid)null

attachments*Attachments

callback_url*Callback Url

Response

200404422

Successful Response

Body

application/json

moderation_job_id*Moderation Job Id

The moderation job ID, which has a 'vmod' prefix

Pattern: ^vmod_[0-7][0-9a-hjkmnp-tv-z]{25}$

external_idExternal Id

Optional external ID as specified in the request

stringnull

classification_job_id*Classification Job Id

The job ID of the initial classification

string (uuid)null

Request

JavaScriptCurlPython

const response = await fetch('/moderate', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "main_content": {
        "external_id": "text",
        "value": "https://example.com",
        "type": "image"
      },
      "attachments": [
        {
          "mime_type": "text/markdown",
          "value": "text"
        }
      ],
      "callback_url": "https://example.com"
    }),
});
const data = await response.json();

Response

200422

{
  "moderation_job_id": "text",
  "external_id": "text",
  "classification_job_id": "123e4567-e89b-12d3-a456-426614174000"
}

4. Webhooks

In order to have a scalable end-to-end integration, the last step is to set up the receiving of webhooks as described in the following guide: Integrating Webhooks

Example successful response:

{
  "classification_job_id": "123e4567-e89b-12d3-a456-426614174",
  "content_type": "image",
  "decision_type": "fully_automated",
  "escalate": true,
  "escalate_reasons": ["self-harm"],
  "external_id": "the source file_id specified in the request",
  "is_error": false,
  "moderation_job_id": "vmod_01h45ytscbebyvny4gc8cr8ma2"
  "policy_categories": [
    {
      "name": "SEXUAL",
      "risk_level": "high"
    }
  ],
}

Note: This structure is also used for a detailed error response where the is_error field will be true and policy_categories field will be empty. This type of error response occurs after fatal errors occur that are not retried, e.g. when unsupported file types are provided.

Generic error response after retries:

{
  "classification_job_id": "123e4567-e89b-12d3-a456-426614174",
  "error_message": "the error message for the request",
  "external_id": "the source file_id specified in the request",
  "moderation_job_id": "vmod_01h45ytscbebyvny4gc8cr8ma2"
}

This basic error response may be returned after exceeding all API retries, e.g. unreachable human moderation platform. However, for this case our API usually recovers and sends back the AI moderation results, so this type of error response should rarely occur.