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.

In 2.12.0, bucket image moderation is supported when platform and project switches, bucket configuration, and the moderation service are enabled. The upload path reads image bytes and submits them using the Base64 adapter. Check object and record cleanup after errors; do not assume zero residual data.

2.9.0 additions: createConfig supports mode: 'post' | 'hybrid' (asynchronous post-review; can be selected for create or update only when Phase Two is enabled; when disabled, new requests reject these modes and existing configurations execute synchronously) 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; the moderation-state check permits the creator, last modifier, and privileged identities; actual reads remain subject to applicable authentication and database permissions. Lists with attribute filters may overcount total.

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'(需平台开启审核二期;关闭时新建或更新不接受这两种模式)
     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 prepareRequest = client.prepareRequest.bind(client);
  client.prepareRequest = (...args) => {
    const request = prepareRequest(...args);
    request.options.redirect = 'error';
    return request;
  };
}
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.

These actions are independent; disabling or deleting affects moderation, so confirm the target and impact first. For Node.js and Python, first define the resource variable in the query block in the same session.

Read the configuration.

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

const current = await moderation.getConfig(tableResource);

Disable moderation after confirming the impact.

await moderation.updateConfig({ ...tableResource, enabled: false });   // Disable but keep the configuration

Enable moderation.

await moderation.updateConfig({ ...tableResource, enabled: true });    // Reopen

Delete the configuration only when no longer needed.

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>' });