Responses

Response model

The API returns moderation results, not a source-product workflow. Your adapter decides how blocked, review, and clean are enforced.

Open endpoint reference Read rollout checklist

Payloads

Sync returns the verdict now; async returns acceptance now

Use sync when the surface needs a moderation answer before content becomes visible. Use async when the important thing is absorbing work for later processing.

Sync responseImmediate moderation verdict

Reference

{
  "eventId": "evt_01JXYZ...",
  "incidentId": "inc_01JXYZ...",
  "persistence": {
    "mode": "store_metadata_only",
    "stored": true
  },
  "decision": {
    "status": "blocked",
    "severity": "high",
    "confidence": 0.982,
    "categories": {
      "sexual": 0.982
    },
    "recommendedActions": ["delete_message", "notify_moderators"],
    "rationale": ["Model moderation flagged the event."]
  },
  "creditsConsumed": 1
}

Async responseQueued job acknowledgement

Reference

{
  "jobId": "job_01JXYZ...",
  "eventId": "evt_01JXYZ...",
  "status": "queued",
  "persistence": {
    "mode": "store_full",
    "stored": true
  }
}

Decision states

Use the decision as an input into local workflow, not as the workflow itself

The moderation response should translate into your own enforcement model. Some products hide on review; others queue to moderators; some only rate-limit or hold until evidence is inspected.

cleanA clean verdict. If you did not request suggested actions, recommendedActions is empty.

reviewThe content should be queued for human review or temporarily hidden until an operator resolves it.

blockedAn enforcement threshold was crossed. Only apply decision.recommendedActions when you explicitly requested suggested actions and your surface allows those actions.

Suggested actions are optional

Only apply decision.recommendedActions when you explicitly requested them and the source product supports those actions. The platform does not directly delete or hide content for you.

Threshold behavior

Verdicts blend backend scores with the numeric hints you pass in policy

Category scores come from the moderation backend. The final sync decision applies server-side rules on top of those scores using merged thresholds from platform defaults and your own numeric policy hints.

How threshold merging works

Hints such as media.threshold, text.threshold, scam.reviewThreshold, and optional platformPolicy.thresholds are merged with compiled defaults. Omit a hint to keep the default for that category.