Open workspace
Quickstart

Send your first moderation event

Send one sync POST /v1/events, store the incident id, and map the decision in your app.

Review event schemaSee response shapes
Before you begin

Prerequisites

You need a workspace and one scoped Bearer API key. A normal public signup includes 1,000 one-time evaluation credits, so this attachment-free basic-text request can produce a real verdict before checkout. Standard image and video requests use the same evaluation balance; the NSFW daily allowance is a separate eligible path.

Create a key with moderation access

Open API keys, create a Bearer key, and keep it in a server-side environment variable. Never expose it in browser code.

Step 1

Send one synchronous moderation request

Post a normalized event to /v1/events. Replace the key and identifiers with values from your workspace.

curlPOST /v1/events
Request
curl -X POST https://api.neomechanical.com/v1/events \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "sync",
    "event": {
      "workspaceSlug": "your-workspace",
      "source": "community",
      "adapter": "primary-content-adapter",
      "eventType": "content",
      "externalId": "evt_123456",
      "actor": {
        "externalId": "user_123456789"
      },
      "context": {
        "scopeId": "community_11223344",
        "channelId": "feed_99887766"
      },
      "content": {
        "text": "claim reward wallet connect"
      },
      "metadata": {
        "customInfo": {
          "scopeLabel": "Acme community (1465340840250704106)",
          "scopeId": "1465340840250704106",
          "actorExternalId": "user_123456789",
          "sourceShard": "eu-west-1a"
        }
      }
    },
    "options": {
      "includeRecommendedActions": true,
      "persistence": "store_metadata_only"
    }
  }'
Step 2

Review the decision and persist its identifiers

Use the decision for your local enforcement path and store the event and incident ids for support and audit work.

JSONSynchronous response
200 OK
{
  "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
}
Adapter boundary

Platform moderates; your app enforces

The platform returns decisions and ledger data. Your adapter keeps all source-of-truth behavior for publication, billing tiers, routing rules, and customer-specific policy logic.

The adapter decides when to callTreat platform like an external moderation API. Your adapter decides when moderation is required, collects content, and sends normalized input.
The adapter owns settings and plansScope, channel, tenant, or plan logic stays in your product. Convert those settings into generic platformPolicy and platformProcessing inputs before calling the API.
The adapter owns spend policyPlatform measures actual credit consumption, but your product still decides which tier can afford a request, how much scan depth to buy, and when to reject or downgrade a call.
Platform returns a verdict, not adapter control-plane stateThe response is a moderation decision plus optional suggested actions and analysis detail. Your adapter still owns message deletes, role changes, or other source-product enforcement.
Prefer sync for user-facing flowsUse sync when you need an immediate allow, review, or block decision before publish. Use async for backfills and large historical imports.
Modes

Choose sync for gating and async for background volume

Both modes hit the same event endpoint. The choice is really about whether your source product needs an immediate moderation decision before content becomes visible.

syncUse this for publish gating
Immediate verdictWait for clean, review, or blocked in the same request before the content is shown.
Recommended surfacesMessages, profiles, comments, uploads, listings, or any action that needs inline moderation.
asyncUse this for imports and audits
Queued acceptanceThe API accepts the work and returns a queued job id instead of the final moderation decision.
Recommended surfacesBackfills, historical review, low-priority feeds, and cases where latency matters less than throughput.