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
Base URL:
https://<your-endpoint>/v1。Configurations are located by resource:
resourceType(collections/buckets) +resourceId(collection or bucket ID);resourceType=collectionsmust be accompanied bydatabaseId(databases). A resource has at most one configuration.Logs:
moderationLog({logId}), recording every moderation decision.
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 + path | Purpose |
|---|---|
POST /moderation-configs | Create 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-logs | Moderation 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
resourceType | body | string | Yes | Enum collections, buckets | Resource type: collections (data table) / buckets (storage bucket). |
resourceId | body | string | Yes | — | Resource ID (table ID or bucket ID); a resource has at most one configuration; duplicate creation returns 409. |
databaseId | body | string | No | — | Required when resourceType=collections: the owning database ID. |
mode | body | string | Yes | Enum 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. |
requireManualReviewOnViolation | body | boolean | No | Default true | Route 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. |
contentTypes | body | string[] | 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). |
enabled | body | boolean | No | — | Whether to enable; defaults to true at creation. Actual moderation also depends on environment, project, and resource configuration. |
output : returns 201 + moderationConfig:
| Field | Type | Description |
|---|---|---|
$id | string | Configuration ID. |
$createdAt | string | Configuration creation time (ISO 8601). |
$updatedAt | string | Configuration last update time (ISO 8601). |
resourceType | string | Resource type: collections / buckets. |
resourceId | string | ID of the moderated resource (table or bucket). |
databaseId | string | Owning database ID when resourceType=collections. |
enabled | boolean | Whether moderation is enabled: content is only actually moderated when the configuration exists and enabled=true. |
mode | string | Moderation 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). |
requireManualReviewOnViolation | boolean | Route violations to human review switch (default true). |
contentTypes | string[] | Content types to moderate: text / image (availability depends on environment, project, bucket configuration, and the moderation service). |
status | string | Configuration status: active / disabled_by_global (disabled by the project-level master switch). |
Integrated with the write pipelines of databases / storage: moderation runs automatically during
createRow/updateRow, with no separate moderation call needed. In Phase Two mode, documents carrymoderationStatusandmoderationJobId(documentmodel fields added in 2.9.0).When a rejection rule is hit, the original write request is intercepted and returns
moderation_rejected, and amoderationLogis generated.
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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
resourceType | path | string | Yes | Enum collections, buckets | Resource type: collections / buckets. |
resourceId | path | string | yes | — | Resource ID. |
databaseId | query | string | No | — | Owning database ID, required when resourceType=collections (passed via query). |
Output: Returns moderationConfig:
| Field | Type | Description |
|---|---|---|
$id | string | Configuration ID. |
$createdAt | string | Configuration creation time (ISO 8601). |
$updatedAt | string | Configuration last update time (ISO 8601). |
resourceType | string | Resource type: collections / buckets. |
resourceId | string | ID of the moderated resource (table or bucket). |
databaseId | string | Owning database ID when resourceType=collections. |
enabled | boolean | Whether moderation is enabled: content is only actually moderated when the configuration exists and enabled=true. |
mode | string | Moderation 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). |
requireManualReviewOnViolation | boolean | Route violations to human review switch (default true). |
contentTypes | string[] | Content types to moderate: text / image (availability depends on environment, project, bucket configuration, and the moderation service). |
status | string | Configuration status: active / disabled_by_global (disabled by the project-level master switch). |
Returns
404+moderation_config_not_foundif the configuration does not exist.
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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
resourceType | path | string | Yes | Enum collections, buckets | Resource type: collections / buckets. |
resourceId | path | string | yes | — | Resource ID. |
databaseId | body | string | No | — | Required when resourceType=collections. |
mode | body | string | No | Enum pre, post, hybrid | Moderation mode; post / hybrid are rejected on create or update when Phase Two is disabled; existing configurations execute as pre. |
requireManualReviewOnViolation | body | boolean | No | Default true | Route 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. |
contentTypes | body | string[] | No | — | Array of content types to moderate. |
enabled | body | boolean | No | — | true enable / false pause (the configuration is retained and can be re-enabled at any time). |
Output: Returns the updated moderationConfig:
| Field | Type | Description |
|---|---|---|
$id | string | Configuration ID. |
$createdAt | string | Configuration creation time (ISO 8601). |
$updatedAt | string | Configuration last update time (ISO 8601). |
resourceType | string | Resource type: collections / buckets. |
resourceId | string | ID of the moderated resource (table or bucket). |
databaseId | string | Owning database ID when resourceType=collections. |
enabled | boolean | Whether moderation is enabled: content is only actually moderated when the configuration exists and enabled=true. |
mode | string | Moderation 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). |
requireManualReviewOnViolation | boolean | Route violations to human review switch (default true). |
contentTypes | string[] | Content types to moderate: text / image (availability depends on environment, project, bucket configuration, and the moderation service). |
status | string | Configuration 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
resourceType | path | string | Yes | Enum collections, buckets | Resource type: collections / buckets. |
resourceId | path | string | yes | — | Resource ID. |
databaseId | body | string | No | — | 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
queries | query | string[] | No | Default [] | 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. |
total | query | boolean | No | Default true | When 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:
| Field | Type | Description |
|---|---|---|
$id | string | Log ID. |
$createdAt | string | Log creation time (ISO 8601). |
$updatedAt | string | Log last update time (ISO 8601). |
resourceType | string | Resource type: collections / buckets. |
resourceId | string | ID of the moderated resource. |
databaseId | string | Owning database ID when resourceType=collections. |
userId | string | User ID of the user who triggered the write. |
timestamp | integer | Time the moderation occurred (Unix seconds). |
contentType | string | Content type moderated in this moderation (text / image). |
contentPreview | string | Truncated, desensitized preview of the moderated content. |
result | string | Decision result: pass / block / review / error. |
labels | string[] | Risk labels returned by the moderation service (e.g., porn, violence). |
confidence | number | Moderation service confidence (0–1). |
suggestion | string | Moderation service suggestion: pass / review / block. |
provider | string | Moderation service provider identifier (e.g., alibaba). |
requestId | string | Moderation service request ID, for tracing. |
error | string | Error message when result=error. |
credentialSource | string | Credential source used for this moderation call: platform / project. |
After a write is intercepted (
moderation_rejected), first check the logs for records withresult=blockandlabels.
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 escapingResponse 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
logId | path | string | Yes | — | Log ID. |
Output: Returns moderationLog:
| Field | Type | Description |
|---|---|---|
$id | string | Log ID. |
$createdAt | string | Log creation time (ISO 8601). |
$updatedAt | string | Log last update time (ISO 8601). |
resourceType | string | Resource type: collections / buckets. |
resourceId | string | ID of the moderated resource. |
databaseId | string | Owning database ID when resourceType=collections. |
userId | string | User ID of the user who triggered the write. |
timestamp | integer | Time the moderation occurred (Unix seconds). |
contentType | string | Content type moderated in this moderation (text / image). |
contentPreview | string | Truncated, desensitized preview of the moderated content. |
result | string | Decision result: pass / block / review / error. |
labels | string[] | Risk labels returned by the moderation service (e.g., porn, violence). |
confidence | number | Moderation service confidence (0–1). |
suggestion | string | Moderation service suggestion: pass / review / block. |
provider | string | Moderation service provider identifier (e.g., alibaba). |
requestId | string | Moderation service request ID, for tracing. |
error | string | Error message when result=error. |
credentialSource | string | Credential source used for this moderation call: platform / project. |
Returns
404+moderation_log_not_foundif the log does not exist; deleting a configuration does not delete historical logs.
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
Duplicate configuration:
409+moderation_config_already_exists; configuration/log not found:404+moderation_config_not_found/moderation_log_not_found.Rejection rule hit: the original write request is blocked, returning
moderation_rejected(with a decision summary), and a log entry is generated; if the review service is unavailable,moderation_unavailableis returned—when the configuration exists, whether the request is allowed or blocked depends on platform policy, and callers should not assume availability.presemantics unchanged: existing content is not retroactively reviewed; deleting the configuration does not delete historical logs. Underpost/hybrid(2.9.0, requires the platform to enable review phase two), violating content does not block writes but instead enters an asynchronous review state machine; if the configuration is missing or stuck, the platform reconcile task re-evaluates it according to current configuration semantics.resourceType=collectionsbut missingdatabaseId: parameter error.
Correspondence with the Server SDK
| service.method | Endpoint |
|---|---|
Moderation.createConfig / getConfig / updateConfig / deleteConfig | /moderation-configs* |
Moderation.listLogs / getLog | /moderation-logs* |