🛂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

Authorizations

Body

callback_urlCallback Urlrequired

classification_job_idClassification Job Id

main_contentMain Contentrequired

attachmentsAttachmentsrequired

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/moderate' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{"callback_url":"https://example.com","main_content":{"external_id":"text","is_user_report":false,"value":"https://example.com","type":"image"},"attachments":[{"value":"text","relation_to_main_media":"post","type":"text","mime_type":"text/markdown"}]}'

200

404

422

200

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

Successful Response

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.