Content Moderation API
Moderation configuration and moderation logs for writable resources within a project (database collections / Storage buckets): after a configuration is created, write and update requests are moderated before being persisted (pre); 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—these only take effect after the platform Admin enables Moderation Phase Two; when not enabled, they are equivalent to pre. Phase Two also introduces requireManualReviewOnViolation (violations routed to human review) and document moderationStatus (checking / pending / published / quarantined / private_hold / action_error); unpublished documents are hidden from non-creators, and events are re-sent after publishing.
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 platform gateway layer automatically intercepts or asynchronously scans written content, and on violation sets the record to requireManualReviewOnViolation (quarantined pending review) or quarantined (visible only to the creator) according to private_hold.
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, equivalent to pre when the platform has not enabled Phase Two. |
requireManualReviewOnViolation | body | boolean | No | Default true | Route violations to human review (2.9.0): true quarantine violating documents (quarantined); false private hold visible only to the creator (private_hold). |
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 (the image moderation pipeline is currently unavailable; do not enable in production). |
enabled | body | boolean | No | — | Whether to enable; defaults to false at creation, i.e., the configuration is created but not active. |
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, equivalent to pre when Phase Two is not enabled). |
requireManualReviewOnViolation | boolean | Route violations to human review switch (default true). |
contentTypes | string[] | Content types to moderate: text / image (the image moderation pipeline is currently unavailable). |
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, equivalent to pre when Phase Two is not enabled). |
requireManualReviewOnViolation | boolean | Route violations to human review switch (default true). |
contentTypes | string[] | Content types to moderate: text / image (the image moderation pipeline is currently unavailable). |
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 equivalent to pre when the platform has not enabled Phase Two. |
requireManualReviewOnViolation | body | boolean | No | Default true | Route violations to human review (2.9.0): true quarantine violating documents (quarantined); false private hold visible only to the creator (private_hold). |
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, equivalent to pre when Phase Two is not enabled). |
requireManualReviewOnViolation | boolean | Route violations to human review switch (default true). |
contentTypes | string[] | Content types to moderate: text / image (the image moderation pipeline is currently unavailable). |
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* |