Docs
Contents

Content Moderation API

Moderation configuration and moderation logs for writable resources within a project (database collections / Storage buckets): for table text, pre mode reviews writes before persistence; storage images are written to the device first and then reviewed according to configuration. Starting from 2.9.0, the post mode (persist first, then moderate asynchronously) and the hybrid mode (routed by platform text length threshold) are added—create or update requests can select these only when Phase Two is enabled; when disabled, existing configurations execute synchronously. Phase Two also introduces requireManualReviewOnViolation (violations routed to human review) and document moderationStatus (checking / pending / published / quarantined / private_hold / action_error); 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.

Service and resource boundaries

The Content Moderation API (/v1/moderation-configs*, /v1/moderation-logs*) provides a declarative content safety defense line for structured data tables (collections) and object storage buckets (buckets) within a project: it supports three moderation modes—prerequisite synchronous interception (pre), post-hoc asynchronous moderation (post), and length-based hybrid moderation (hybrid)—automatically runs compliance detection on text columns in tables or images in buckets, and records complete moderation decision audit logs.

Resources and Base Paths

Authentication and Permissions

See General Conventions for authentication and request header conventions. Scopes for this domain: moderation.config.read / moderation.config.write (configuration), moderation.log.read (logs).

Endpoint overview

The Moderation module provides a total of 6 endpoints: including 4 resource-level moderation policy configuration endpoints (create, read by resourceType/resourceId, update, delete) and 2 moderation decision log query endpoints (paginated list and single-item detail).

Endpoint List

Method + pathPurpose
POST /moderation-configsCreate moderation configuration
GET /moderation-configs/{resourceType}/{resourceId}Read configuration
PATCH /moderation-configs/{resourceType}/{resourceId}Update configuration
DELETE /moderation-configs/{resourceType}/{resourceId}Delete configuration
GET /moderation-logsModeration log list
GET /moderation-logs/{logId}Moderation log detail

Endpoint details

Once a moderation rule is enabled on a target table or bucket (enabled: true), the business side does not need to modify existing database createRow/updateRow or storage createFile call code; the system processes writes according to resource and environment configuration. In asynchronous table moderation, violations enter quarantined or private_hold according to requireManualReviewOnViolation; visibility remains subject to the moderation-state check and existing permissions.

Requests and Responses

Complete specifications are given per endpoint below: input (field-level tables for path / query / body), output (return model and key fields), examples (copyable curl), and response examples.

POST /v1/moderation-configs

Creates a content moderation configuration for a writable resource: once created and enabled=true, writes and updates to that resource pass through the moderation gate (pre prerequisite interception; Phase Two's post / hybrid are asynchronous post-hoc).

Input:

ParameterLocationTypeRequiredDefault/enumDescription
resourceTypebodystringYesEnum collections, bucketsResource type: collections (data table) / buckets (storage bucket).
resourceIdbodystringYes—Resource ID (table ID or bucket ID); a resource has at most one configuration; duplicate creation returns 409.
databaseIdbodystringNo—Required when resourceType=collections: the owning database ID.
modebodystringYesEnum pre, post, hybrid (from 2.9.0)Moderation mode: pre (prerequisite interception on write); post / hybrid are Phase Two asynchronous post-hoc modes, create or update requests reject them when Phase Two is disabled; existing configurations execute as pre.
requireManualReviewOnViolationbodybooleanNoDefault trueRoute violations to human review (2.9.0): true quarantine violating documents (quarantined); false private hold (private_hold), subject to the moderation-state check and existing permissions.
contentTypesbodystring[]Yes—Array of content types to moderate: pass ["text"] for tables (string/varchar/text/mediumtext/longtext columns automatically selected based on the table schema, including array columns); pass ["image"] for buckets (availability depends on environment, project, bucket configuration, and the moderation service).
enabledbodybooleanNo—Whether to enable; defaults to true at creation. Actual moderation also depends on environment, project, and resource configuration.

output : returns 201 + moderationConfig:

FieldTypeDescription
$idstringConfiguration ID.
$createdAtstringConfiguration creation time (ISO 8601).
$updatedAtstringConfiguration last update time (ISO 8601).
resourceTypestringResource type: collections / buckets.
resourceIdstringID of the moderated resource (table or bucket).
databaseIdstringOwning database ID when resourceType=collections.
enabledbooleanWhether moderation is enabled: content is only actually moderated when the configuration exists and enabled=true.
modestringModeration mode: pre / post / hybrid (post / hybrid are Phase Two modes, create or update requests reject them when Phase Two is disabled; existing configurations execute as pre).
requireManualReviewOnViolationbooleanRoute violations to human review switch (default true).
contentTypesstring[]Content types to moderate: text / image (availability depends on environment, project, bucket configuration, and the moderation service).
statusstringConfiguration status: active / disabled_by_global (disabled by the project-level master switch).

Call example:

curl -X POST "https://<your-endpoint>/v1/moderation-configs" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceType": "collections",
    "resourceId": "comments",
    "databaseId": "forum",
    "mode": "pre",
    "contentTypes": ["text"],
    "enabled": true
  }'

Response example:

{
  "$id": "mc_forum_comments",
  "$createdAt": "2026-09-14T02:00:00.000+00:00",
  "$updatedAt": "2026-09-14T02:00:00.000+00:00",
  "resourceType": "collections",
  "resourceId": "comments",
  "databaseId": "forum",
  "enabled": true,
  "mode": "pre",
  "contentTypes": [
    "text"
  ],
  "status": "active"
}

GET /v1/moderation-configs/{resourceType}/{resourceId}

Reads the moderation configuration of a resource.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
resourceTypepathstringYesEnum collections, bucketsResource type: collections / buckets.
resourceIdpathstringyes—Resource ID.
databaseIdquerystringNo—Owning database ID, required when resourceType=collections (passed via query).

Output: Returns moderationConfig:

FieldTypeDescription
$idstringConfiguration ID.
$createdAtstringConfiguration creation time (ISO 8601).
$updatedAtstringConfiguration last update time (ISO 8601).
resourceTypestringResource type: collections / buckets.
resourceIdstringID of the moderated resource (table or bucket).
databaseIdstringOwning database ID when resourceType=collections.
enabledbooleanWhether moderation is enabled: content is only actually moderated when the configuration exists and enabled=true.
modestringModeration mode: pre / post / hybrid (post / hybrid are Phase Two modes, create or update requests reject them when Phase Two is disabled; existing configurations execute as pre).
requireManualReviewOnViolationbooleanRoute violations to human review switch (default true).
contentTypesstring[]Content types to moderate: text / image (availability depends on environment, project, bucket configuration, and the moderation service).
statusstringConfiguration status: active / disabled_by_global (disabled by the project-level master switch).

Call example:

curl "https://<your-endpoint>/v1/moderation-configs/collections/comments?databaseId=forum" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "$id": "mc_forum_comments",
  "$createdAt": "2026-09-14T02:00:00.000+00:00",
  "$updatedAt": "2026-09-14T02:00:00.000+00:00",
  "resourceType": "collections",
  "resourceId": "comments",
  "databaseId": "forum",
  "enabled": true,
  "mode": "pre",
  "contentTypes": [
    "text"
  ],
  "status": "active"
}

PATCH /v1/moderation-configs/{resourceType}/{resourceId}

Updates the moderation configuration: toggle enable/disable, adjust content types or mode; only passed fields are updated; omitting contentTypes preserves the original configuration.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
resourceTypepathstringYesEnum collections, bucketsResource type: collections / buckets.
resourceIdpathstringyes—Resource ID.
databaseIdbodystringNo—Required when resourceType=collections.
modebodystringNoEnum pre, post, hybridModeration mode; post / hybrid are rejected on create or update when Phase Two is disabled; existing configurations execute as pre.
requireManualReviewOnViolationbodybooleanNoDefault trueRoute violations to human review (2.9.0): true quarantine violating documents (quarantined); false private hold (private_hold), subject to the moderation-state check and existing permissions.
contentTypesbodystring[]No—Array of content types to moderate.
enabledbodybooleanNo—true enable / false pause (the configuration is retained and can be re-enabled at any time).

Output: Returns the updated moderationConfig:

FieldTypeDescription
$idstringConfiguration ID.
$createdAtstringConfiguration creation time (ISO 8601).
$updatedAtstringConfiguration last update time (ISO 8601).
resourceTypestringResource type: collections / buckets.
resourceIdstringID of the moderated resource (table or bucket).
databaseIdstringOwning database ID when resourceType=collections.
enabledbooleanWhether moderation is enabled: content is only actually moderated when the configuration exists and enabled=true.
modestringModeration mode: pre / post / hybrid (post / hybrid are Phase Two modes, create or update requests reject them when Phase Two is disabled; existing configurations execute as pre).
requireManualReviewOnViolationbooleanRoute violations to human review switch (default true).
contentTypesstring[]Content types to moderate: text / image (availability depends on environment, project, bucket configuration, and the moderation service).
statusstringConfiguration status: active / disabled_by_global (disabled by the project-level master switch).

Call example:

curl -X PATCH "https://<your-endpoint>/v1/moderation-configs/collections/comments" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false, "databaseId": "forum" }'

Response example:

{
  "$id": "mc_forum_comments",
  "$createdAt": "2026-09-14T02:00:00.000+00:00",
  "$updatedAt": "2026-09-14T02:05:00.000+00:00",
  "resourceType": "collections",
  "resourceId": "comments",
  "databaseId": "forum",
  "enabled": false,
  "mode": "pre",
  "contentTypes": [
    "text"
  ],
  "status": "active"
}

DELETE /v1/moderation-configs/{resourceType}/{resourceId}

Deletes the moderation configuration: after removal, the resource is no longer moderated; historical logs are unaffected.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
resourceTypepathstringYesEnum collections, bucketsResource type: collections / buckets.
resourceIdpathstringyes—Resource ID.
databaseIdbodystringNo—Required when resourceType=collections (passed via body).

Output: 204 No Content, no response body.

Call example:

curl -X DELETE "https://<your-endpoint>/v1/moderation-configs/collections/comments" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "databaseId": "forum" }'

Response example: 204 No Content: no response body (configuration deleted).

GET /v1/moderation-logs

Paginated query of moderation logs: each record is one moderation decision, filterable by resource, decision result, and other attributes.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
queriesquerystring[]NoDefault []Array of Query query strings (generated by SDK Query), up to 100 items with each up to 4096 characters; can filter attributes such as resourceType, resourceId, databaseId, result, timestamp, userId, contentType.
totalquerybooleanNoDefault trueWhen set to false, the response total is always 0, skipping the count to speed up the query.

Output: Returns moderationLogList (total + logs[]), with elements of moderationLog:

FieldTypeDescription
$idstringLog ID.
$createdAtstringLog creation time (ISO 8601).
$updatedAtstringLog last update time (ISO 8601).
resourceTypestringResource type: collections / buckets.
resourceIdstringID of the moderated resource.
databaseIdstringOwning database ID when resourceType=collections.
userIdstringUser ID of the user who triggered the write.
timestampintegerTime the moderation occurred (Unix seconds).
contentTypestringContent type moderated in this moderation (text / image).
contentPreviewstringTruncated, desensitized preview of the moderated content.
resultstringDecision result: pass / block / review / error.
labelsstring[]Risk labels returned by the moderation service (e.g., porn, violence).
confidencenumberModeration service confidence (0–1).
suggestionstringModeration service suggestion: pass / review / block.
providerstringModeration service provider identifier (e.g., alibaba).
requestIdstringModeration service request ID, for tracing.
errorstringError message when result=error.
credentialSourcestringCredential source used for this moderation call: platform / project.

Call example:

curl "https://<your-endpoint>/v1/moderation-logs?queries%5B0%5D=equal(%22resourceId%22%2C%22comments%22)&queries%5B1%5D=equal(%22result%22%2C%22block%22)&total=true" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"
# It is recommended to generate the query string via SDK Query.equal('resourceId','comments') to avoid hand-written escaping

Response example:

{
  "total": 1,
  "logs": [
    {
      "$id": "ml_01J5Z8XK2Q",
      "$createdAt": "2026-09-14T02:31:00.000+00:00",
      "$updatedAt": "2026-09-14T02:31:00.000+00:00",
      "resourceType": "collections",
      "resourceId": "comments",
      "databaseId": "forum",
      "userId": "user_42",
      "timestamp": 1757812260,
      "contentType": "text",
      "contentPreview": "加微信立返现金…",
      "result": "block",
      "labels": [
        "porn",
        "violence"
      ],
      "confidence": 0.95,
      "suggestion": "block",
      "provider": "alibaba",
      "requestId": "req_9f2c8ab1",
      "error": "",
      "credentialSource": "platform"
    }
  ]
}

GET /v1/moderation-logs/{logId}

Reads the complete decision detail of a single moderation log.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
logIdpathstringYes—Log ID.

Output: Returns moderationLog:

FieldTypeDescription
$idstringLog ID.
$createdAtstringLog creation time (ISO 8601).
$updatedAtstringLog last update time (ISO 8601).
resourceTypestringResource type: collections / buckets.
resourceIdstringID of the moderated resource.
databaseIdstringOwning database ID when resourceType=collections.
userIdstringUser ID of the user who triggered the write.
timestampintegerTime the moderation occurred (Unix seconds).
contentTypestringContent type moderated in this moderation (text / image).
contentPreviewstringTruncated, desensitized preview of the moderated content.
resultstringDecision result: pass / block / review / error.
labelsstring[]Risk labels returned by the moderation service (e.g., porn, violence).
confidencenumberModeration service confidence (0–1).
suggestionstringModeration service suggestion: pass / review / block.
providerstringModeration service provider identifier (e.g., alibaba).
requestIdstringModeration service request ID, for tracing.
errorstringError message when result=error.
credentialSourcestringCredential source used for this moderation call: platform / project.

Call example:

curl "https://<your-endpoint>/v1/moderation-logs/ml_01J5Z8XK2Q" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "$id": "ml_01J5Z8XK2Q",
  "$createdAt": "2026-09-14T02:31:00.000+00:00",
  "$updatedAt": "2026-09-14T02:31:00.000+00:00",
  "resourceType": "collections",
  "resourceId": "comments",
  "databaseId": "forum",
  "userId": "user_42",
  "timestamp": 1757812260,
  "contentType": "text",
  "contentPreview": "加微信立返现金…",
  "result": "block",
  "labels": [
    "porn",
    "violence"
  ],
  "confidence": 0.95,
  "suggestion": "block",
  "provider": "alibaba",
  "requestId": "req_9f2c8ab1",
  "error": "",
  "credentialSource": "platform"
}

Errors and boundaries

Correspondence with the Server SDK

service.methodEndpoint
Moderation.createConfig / getConfig / updateConfig / deleteConfig/moderation-configs*
Moderation.listLogs / getLog/moderation-logs*