agentbase-docs

内容审核 API

对项目内可写入资源(数据库集合 / Storage 桶)的内容审核配置与审核日志:创建配置后,写入与更新请求先经审核再落库(v1 仅前置拦截 pre)。

资源与基础路径

认证与权限

认证与请求头约定见 通用约定。本域 scope:moderation.config.read / moderation.config.write(配置)、moderation.log.read(日志)。

端点清单

方法 + 路径用途
POST /moderation-configs创建审核配置
GET /moderation-configs/{resourceType}/{resourceId}读取配置
PATCH /moderation-configs/{resourceType}/{resourceId}更新配置
DELETE /moderation-configs/{resourceType}/{resourceId}删除配置
GET /moderation-logs审核日志列表
GET /moderation-logs/{logId}审核日志详情

请求与响应

以下按端点给出完整规格:输入(path / query / body 字段级表格)、输出(返回模型与关键字段)、调用示例(可复制的 curl)与响应示例。

POST /v1/moderation-configs

为可写入资源创建内容审核配置:创建且 enabled=true 后,该资源的写入与更新先经审核再落库(v1 仅前置拦截 pre)。

输入:

参数位置类型必填默认/枚举说明
resourceTypebodystring是枚举 collections, buckets资源类型:collections(数据表)/ buckets(存储桶)。
resourceIdbodystring是—资源 ID(表 ID 或桶 ID);一个资源至多一份配置,重复创建返回 409。
databaseIdbodystring否—resourceType=collections 时必填:所属数据库 ID。
modebodystring是枚举 pre审核模式,v1 仅 pre。
contentTypesbodystring[]是—参与审核的内容类型数组:数据表传 ["text"](按表 schema 自动筛出 string/varchar/text/mediumtext/longtext 列,含数组列);桶传 ["image"](图片审核链路当前暂不可用,勿在生产开启)。
enabledbodyboolean否—是否启用;创建时缺省为 false,即先建配置不生效。

输出:返回 201 + moderationConfig:

字段类型说明
$idstring配置 ID。
$createdAtstring配置创建时间(ISO 8601)。
$updatedAtstring配置最近更新时间(ISO 8601)。
resourceTypestring资源类型:collections / buckets。
resourceIdstring被审核的资源 ID(表或桶)。
databaseIdstringresourceType=collections 时的所属库 ID。
enabledboolean是否启用审核:配置存在且 enabled=true 后内容才真正被审核。
modestring审核模式;v1 仅 pre(写入前置拦截)。
contentTypesstring[]参与审核的内容类型:text / image(图片审核链路当前暂不可用)。
statusstring配置状态:active / disabled_by_global(被项目级总开关停用)。

调用示例:

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

响应示例:

{
  "$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}

读取某资源的审核配置。

输入:

参数位置类型必填默认/枚举说明
resourceTypepathstring是枚举 collections, buckets资源类型:collections / buckets。
resourceIdpathstring是—资源 ID。
databaseIdquerystring否—resourceType=collections 时必填的所属库 ID(query 传入)。

输出:返回 moderationConfig:

字段类型说明
$idstring配置 ID。
$createdAtstring配置创建时间(ISO 8601)。
$updatedAtstring配置最近更新时间(ISO 8601)。
resourceTypestring资源类型:collections / buckets。
resourceIdstring被审核的资源 ID(表或桶)。
databaseIdstringresourceType=collections 时的所属库 ID。
enabledboolean是否启用审核:配置存在且 enabled=true 后内容才真正被审核。
modestring审核模式;v1 仅 pre(写入前置拦截)。
contentTypesstring[]参与审核的内容类型:text / image(图片审核链路当前暂不可用)。
statusstring配置状态:active / disabled_by_global(被项目级总开关停用)。

调用示例:

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>"

响应示例:

{
  "$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}

更新审核配置:切换启停、调整内容类型或模式;只更新传入字段,contentTypes 省略时保留原配置。

输入:

参数位置类型必填默认/枚举说明
resourceTypepathstring是枚举 collections, buckets资源类型:collections / buckets。
resourceIdpathstring是—资源 ID。
databaseIdbodystring否—resourceType=collections 时必填。
modebodystring否枚举 pre审核模式,v1 仅 pre。
contentTypesbodystring[]否—参与审核的内容类型数组。
enabledbodyboolean否—true 开启 / false 暂停(保留配置,可随时重新开启)。

输出:返回更新后的 moderationConfig:

字段类型说明
$idstring配置 ID。
$createdAtstring配置创建时间(ISO 8601)。
$updatedAtstring配置最近更新时间(ISO 8601)。
resourceTypestring资源类型:collections / buckets。
resourceIdstring被审核的资源 ID(表或桶)。
databaseIdstringresourceType=collections 时的所属库 ID。
enabledboolean是否启用审核:配置存在且 enabled=true 后内容才真正被审核。
modestring审核模式;v1 仅 pre(写入前置拦截)。
contentTypesstring[]参与审核的内容类型:text / image(图片审核链路当前暂不可用)。
statusstring配置状态:active / disabled_by_global(被项目级总开关停用)。

调用示例:

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" }'

响应示例:

{
  "$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}

删除审核配置:移除后该资源不再被审核;历史日志不受影响。

输入:

参数位置类型必填默认/枚举说明
resourceTypepathstring是枚举 collections, buckets资源类型:collections / buckets。
resourceIdpathstring是—资源 ID。
databaseIdbodystring否—resourceType=collections 时必填(body 传入)。

输出:204 No Content,无响应体。

调用示例:

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" }'

响应示例:204 No Content:无响应体(配置已删除)。

GET /v1/moderation-logs

分页查询审核日志:每条记录一次审核判定,可按资源、判定结果等属性过滤。

输入:

参数位置类型必填默认/枚举说明
queriesquerystring[]否默认 []Query 查询串数组(SDK Query 生成),最多 100 条、每条最长 4096 字符;可过滤 resourceType、resourceId、databaseId、result、timestamp、userId、contentType 等属性。
totalqueryboolean否默认 true设为 false 时响应 total 恒为 0,跳过计数以加速查询。

输出:返回 moderationLogList(total + logs[]),元素为 moderationLog:

字段类型说明
$idstring日志 ID。
$createdAtstring日志创建时间(ISO 8601)。
$updatedAtstring日志最近更新时间(ISO 8601)。
resourceTypestring资源类型:collections / buckets。
resourceIdstring被审核资源 ID。
databaseIdstringresourceType=collections 时的所属库 ID。
userIdstring触发写入的用户 ID。
timestampinteger审核发生时间(Unix 秒)。
contentTypestring本次审核的内容类型(text / image)。
contentPreviewstring被审核内容的截断预览(脱敏)。
resultstring判定结果:pass / block / review / error。
labelsstring[]审核服务返回的风险标签(如 porn、violence)。
confidencenumber审核服务置信度(0–1)。
suggestionstring审核服务建议:pass / review / block。
providerstring审核服务商标识(如 alibaba)。
requestIdstring审核服务请求 ID,用于追踪。
errorstringresult=error 时的错误信息。
credentialSourcestring本次审核调用使用的凭证来源:platform / project。

调用示例:

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>"
# 推荐经 SDK Query.equal('resourceId','comments') 生成查询串,避免手写转义

响应示例:

{
  "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}

读取单条审核日志的完整判定详情。

输入:

参数位置类型必填默认/枚举说明
logIdpathstring是—日志 ID。

输出:返回 moderationLog:

字段类型说明
$idstring日志 ID。
$createdAtstring日志创建时间(ISO 8601)。
$updatedAtstring日志最近更新时间(ISO 8601)。
resourceTypestring资源类型:collections / buckets。
resourceIdstring被审核资源 ID。
databaseIdstringresourceType=collections 时的所属库 ID。
userIdstring触发写入的用户 ID。
timestampinteger审核发生时间(Unix 秒)。
contentTypestring本次审核的内容类型(text / image)。
contentPreviewstring被审核内容的截断预览(脱敏)。
resultstring判定结果:pass / block / review / error。
labelsstring[]审核服务返回的风险标签(如 porn、violence)。
confidencenumber审核服务置信度(0–1)。
suggestionstring审核服务建议:pass / review / block。
providerstring审核服务商标识(如 alibaba)。
requestIdstring审核服务请求 ID,用于追踪。
errorstringresult=error 时的错误信息。
credentialSourcestring本次审核调用使用的凭证来源:platform / project。

调用示例:

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

响应示例:

{
  "$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"
}

错误与边界

与 Server SDK 的对应

service.method端点
Moderation.createConfig / getConfig / updateConfig / deleteConfig/moderation-configs*
Moderation.listLogs / getLog/moderation-logs*

事实源