Docs
Contents

Content Moderation

Overview and use cases

Moderation performs pre-review of content on the write path: the targets are database table text and bucket images. It complements rowSecurity — rowSecurity governs who can read and write data, while Moderation governs whether written content is allowed to be saved.

2.6.0 status: table text moderation is available; bucket image moderation is not yet available (the configuration API and code path are reserved, to be enabled once the image signed URL and moderation service chains are ready) — do not enable or rely on image moderation in production.

2.9.0 additions: createConfig supports mode: 'post' | 'hybrid' (asynchronous post-review; takes effect after the platform Admin enables phase two; if not enabled it is equivalent to pre) and requireManualReviewOnViolation (violations routed to manual review, enabled by default; when disabled, violating documents become private_hold instead of quarantined). Document reads return moderationStatus (checking / pending / published / quarantined / private_hold / action_error) and moderationJobId; unpublished documents are hidden from non-creators.

Prerequisites

Usage workflow

  1. Create the table text moderation configuration (first time only; repeated create against an existing configuration will fail):

    moderation.createConfig({
      resourceType: ResourceType.Collections,   // 或 'collections'
      resourceId: '<tableId>',
      databaseId: '<databaseId>',               // collections 必填
     mode: 'pre',                              // 2.9.0 起可选 'post' | 'hybrid'(需平台开启审核二期,未开启等同 pre)
     requireManualReviewOnViolation: true,     // 2.9.0:违规转人工复核(默认 true;false 时违规文档 private_hold)
      contentTypes: ['text'],                   // 首次 createConfig 必填
      enabled: true
    })
  2. Then continue normal TablesDB writes (createRow / updateRow etc.): moderation runs automatically on the write path — there is no explicit method like moderate(). Pass → write succeeds; block → write returns an error.

  3. Read configuration / adjust / delete: getConfig / updateConfig (change enabled or moderation parameters; when only switching enabled, contentTypes can be omitted and the existing configuration is preserved) / deleteConfig.

  4. Troubleshooting: listLogs({ queries: [Query.equal('result', 'block')], total: true }) filter audit logs by resourceType / resourceId / databaseId / result / timestamp / userId / contentType; getLog({ logId }) look up a single record.

Key parameters and returns

Errors and boundaries

SDK Category Differences

Example Guide

Examples by language

The following provides examples by language, item by item along the usage workflow; each card can switch languages (synced across the page).

Create a table text moderation configuration

Moderation configuration is a server-side management plane: the Web SDK has no Moderation service (the browser only perceives write success/failure), and the JS Console SDK has none either (configuration is done directly in Console pages).

import { Client, Moderation, ResourceType } from 'agentbase-node-sdk';

const client = new Client()
    .setEndpoint(process.env.APPBASE_ENDPOINT!)   // Must include /v1
    .setProject(process.env.APPBASE_PROJECT_ID!)
    .setKey(process.env.APPBASE_API_KEY!);        // moderation.config.write
const moderation = new Moderation(client);

await moderation.createConfig({
    resourceType: ResourceType.Collections,   // or 'collections'
    resourceId: 'tasks',
    databaseId: 'app-db',                     // collections is required
    mode: 'pre',                              // v1 only supports prerequisite review
    contentTypes: ['text'],                   // Required on first createConfig
    enabled: true
});
// First time only: repeated create on an existing configuration will fail; afterwards continue with normal TablesDB writes

Write data and trigger moderation

There is no explicit moderate() method: once a configuration is active, ordinary TablesDB writes (createRow / updateRow) automatically execute moderation in the pipeline——passing writes succeed, blocked writes return a moderation error.

import { TablesDB, ID } from 'agentbase-node-sdk';

const tablesDB = new TablesDB(client);   // client is the same as the "Create table text moderation config" card

await tablesDB.createRow('app-db', 'tasks', ID.unique(), { title: '待审核的文本' });
// Allow: write succeeds; block: write errors → use the "Troubleshooting audit logs" card to locate the cause

View, adjust and delete configuration

Do not repeat createConfig for an existing configuration (duplicate creation fails): query with getConfig, adjust/enable/disable with updateConfig (contentTypes can be omitted only when switching enabled; the original configuration is preserved), delete with deleteConfig. The Web SDK has no Moderation service.

const tableResource = {
    resourceType: ResourceType.Collections,   // or 'collections'
    resourceId: 'tasks',
    databaseId: 'app-db'
};

const current = await moderation.getConfig(tableResource);
await moderation.updateConfig({ ...tableResource, enabled: false });   // Disable but keep the configuration
await moderation.updateConfig({ ...tableResource, enabled: true });    // Reopen
await moderation.deleteConfig(tableResource);

Troubleshoot audit logs

When a write is blocked (a TablesDB write returns a moderation error), first check the logs to locate the cause, then check the project-level moderation switch and moderation service configuration. The Web SDK has no Moderation service (the browser only perceives write success/failure).

import { Query } from 'agentbase-node-sdk';

const blocked = await moderation.listLogs({
    queries: [Query.equal('result', 'block')],
    total: true
});   // Filterable by resourceType / resourceId / databaseId / result / timestamp / userId / contentType, etc.
const one = await moderation.getLog({ logId: '<logId>' });