🛂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

Authorizations

JWTBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

Request received by the API worker in the HTTP POST

main_contentone ofRequired

or

classification_job_idany ofOptional

string · uuidOptional

or

nullOptional

callback_urlstring · uri · min: 1 · max: 2083Required

Responses

200

Successful Response

application/json

moderation_job_idstringRequired

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

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

external_idany ofOptional

Optional external ID as specified in the request

stringOptional

or

nullOptional

classification_job_idany ofRequired

The job ID of the initial classification

string · uuidOptional

or

nullOptional

404

Not found

422

Validation Error

application/json

post

/moderate

HTTPcURLJavaScriptPython

POST /moderate HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 314

{
  "main_content": {
    "external_id": "text",
    "is_user_report": false,
    "value": "https://example.com",
    "type": "image"
  },
  "classification_job_id": "123e4567-e89b-12d3-a456-426614174000",
  "attachments": [
    {
      "relation_to_main_media": "post",
      "type": "text",
      "mime_type": "text/markdown",
      "value": "text"
    }
  ],
  "callback_url": "https://example.com"
}

{
  "moderation_job_id": "vmod_01h45ytscbebyvny4gc8cr8ma2",
  "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.