Open workspace
Event schema

Event schema

The event should describe what happened in your product without losing ids, scope, or raw content. Moderation policy and execution hints sit beside that event model.

Back to quickstartSee response behavior
Field guide

Model the content the way your product experienced it

Keep ids, routing context, attachments, and operator-facing metadata intact so incidents remain debuggable.

Where to put extra context

Put adapter-specific labels, duplicate ids, shard hints, or other operator-facing values in metadata.customInfo. That keeps the top-level event clean while still preserving what reviewers need to see in the console.

workspaceSlugRoutes the event into the correct workspace policy, billing ledger, incident feed, and API key scope.
sourceYour product surface. Use stable labels like website, community, marketplace, support, or email.
adapterThe connector or service that produced the normalized event. Keep this generic and stable for debugging.
eventTypeThe content shape you are submitting, for example content, profile, upload, listing, comment, or transcript.
actorWho created the content. Include your platform user id and any generic role labels that matter for your own adapter logic.
contextWhere the event happened. Include stable ids, a parent scope if relevant, a permalink when possible, and optional generic attributes.
contentThe raw text, attachments, or other artifacts to scan. Image attachments are OCR scanned by default, so send the original content rather than a preprocessed moderation summary. Do not reduce the event to your own moderation verdict before calling the API.
metadata.customInfoOptional operator-facing key/value pairs copied into the incident review sidebar (sorted, with full values). Use for anything that is not required for moderation itself but helps humans debug: tenant labels, shard, queue, or duplicate ids. Prefer string, number, or boolean values; nested objects are JSON-stringified for display.
metadata.moderationOptional ergonomic wrapper: put policy under moderation.policy and execution hints under moderation.processing. These merge into platformPolicy and platformProcessing. If you also send platformPolicy, those explicit fields win on conflicts.
metadata.platformPolicyScan thresholds and runtime hints for moderation: they configure the Python analysis backend and are merged with server defaults when deriving the sync decision. Send text.threshold, media.threshold, and scam.reviewThreshold as floats in [0, 1]; optional platformPolicy.thresholds can override individual category keys. Message text scanning uses text.messageScan, and image attachments are OCR scanned by default. For caller-defined rule scans, send text.rules, text.transcriptEntries, and text.suggestionSchema.
metadata.platformProcessingOptional execution hints such as scan depth or video frame caps. These are generic runtime hints, not platform-owned plan logic.
options.includeRecommendedActionsRequest suggested actions in the sync decision response. If you omit this flag or set it to false, decision.recommendedActions will be empty.
options.includeAnalysisDetailsInclude detailed sync analysis in the response. This is required when you want analysis.evidence.textRules, including caller-defined rule matches and returned suggestions.
options.persistenceControl how much of the event is stored. Use store_full for the current audit-first behavior, store_metadata_only to persist ids/context with redacted text and attachment payloads, or no_store to process the event in memory without storing it. no_store is sync-only because async jobs and incident persistence require a stored event row. Stateless integrations should prefer no_store.
Moderation wrapper

Use metadata.moderation when you want a friendlier payload shape

You can express policy under metadata.moderation.policy and runtime hints under metadata.moderation.processing. The platform merges those values into the canonical policy before analysis runs.

Readable aliases are supported

For NSFW text sources, prefer scanChatMessages and nsfwTextSources. Uploaded images are OCR scanned by default, so callers no longer need a dedicated OCR toggle.

Examplemetadata.moderation merged into platformPolicy
Reference
{
  "mode": "sync",
  "event": {
    "workspaceSlug": "default",
    "source": "community",
    "adapter": "community-bot",
    "eventType": "message",
    "externalId": "msg_123",
    "actor": { "externalId": "user_456" },
    "context": { "scopeId": "scope_789", "channelId": "channel_abc" },
    "content": {
      "text": "optional caption",
      "attachments": [{ "kind": "image", "url": "https://cdn.example.com/meme.png" }]
    },
    "metadata": {
      "customInfo": {
        "tenantLabel": "Acme workspace (123456789012345678)",
        "scopeId": "123456789012345678",
        "actorExternalId": "user_456",
        "ingestionPath": "chat-bot-v2"
      },
      "moderation": {
        "policy": {
          "text": {
            "enabled": true,
            "scanChatMessages": true,
            "nsfwTextSources": ["messages", "ocr"]
          },
          "media": { "enabled": true, "ocrLanguages": ["en"] },
          "scam": { "enabled": true, "checkLinks": true }
        },
        "processing": { "priority": true, "scanAccuracy": "balanced" }
      }
    }
  }
}
Processing hints

Execution hints should reflect your own product policy

These values are about runtime behavior, not platform-owned plans. Use them to express urgency or scan depth that your own adapter has already decided is allowed.

Modessync and async
syncWait for the verdict in the same request. Best for publish gating and inline product workflows.
asyncQueue the event and process it out of band. Best for imports, audits, and backfills.
Runtime hintsCaller-owned execution metadata
priorityBoolean hint used to request preferred processing order when your adapter wants faster turnaround.
scanAccuracyExecution quality hint. Supported values are fast, balanced, and high.
videoFrameLimitMaximum number of frames the platform should inspect for video or animated media.