实时评论 API

资源使用

需要注意的是，从 API 获取数据会计入您账户的使用量。

每个资源将在其各自的章节中列出相应的使用情况。

某些资源的服务成本高于其他资源。每个端点都有固定的每次 API 调用所需积分。对于某些端点，积分数量会根据选项和响应大小而变化。

可以在 计费分析 页面查看 API 使用情况，且该数据每几分钟更新一次。

注意！

我们建议先阅读 Pages 文档，以帮助在确定向评论 API 传递的 urlId 值时减少混淆。

Webhook

Webhook 订阅有其专属指南。POST、GET 和 DELETE /api/v1/webhooks，以及 GET /api/v1/webhooks/sample-payloads，在 通过 API 管理订阅 中有文档说明，事件负载在 Webhook 结构 中说明。

FastComments 是一个 OAuth 2.1 授权服务器。应用程序可以获取一个绑定到某个 FastComments 账户的令牌，并在本指南中的每个端点上使用它来代替 API 密钥。Zapier 应用、MCP 服务器以及其他第三方集成就是通过这种方式连接的。

令牌通过带 PKCE 的授权码流程颁发。不支持客户端凭据授权或隐式授权。

发现

端点位置、支持的授权类型和认证方法发布在标准的元数据 URL 上：

授权服务器元数据

Copy

1

2https://fastcomments.com/.well-known/oauth-authorization-server

3

它所描述的端点：

OAuth 端点

Copy

1

2GET https://fastcomments.com/oauth/authorize

3POST https://fastcomments.com/oauth/token

4POST https://fastcomments.com/oauth/revoke

5POST https://fastcomments.com/oauth/register

6

EU 区域的账户使用 https://eu.fastcomments.com 作为 issuer，路径相同。

注册客户端

客户端在开始流程之前需要一个 client_id 和一个已注册的 redirect_uri。有两种获取方式：

• 动态客户端注册。 按照 RFC 7591 使用 JSON 请求体调用 POST /oauth/register（包含 redirect_uris、client_name、client_uri、logo_uri、token_endpoint_auth_method）。响应中包含 client_id，对于机密客户端还包括 client_secret。注册无需认证，并按 IP 进行速率限制。
• 客户端 ID 元数据文档。 客户端使用其控制的 https URL 作为 client_id。FastComments 会抓取该 URL 并从中读取相同的元数据字段。无需调用注册接口。

FastComments 控制面板中列出的合作伙伴应用（如 Zapier）由 FastComments 直接注册。如果您正在构建市场应用列表并需要第一方客户端，请联系支持团队。

作用域

作用域

Copy

1

2read GET 和 HEAD 请求

3write 其他所有方法

4

未请求任何作用域的请求将同时获得两者。用户会在同意页面上看到所请求的作用域。请求这两个作用域之外的任何作用域都会失败并返回 invalid_scope。

第 1 步 - 授权请求

将用户的浏览器重定向到授权端点。每个客户端都必须使用 S256 方法的 PKCE。

授权请求

Copy

1

2GET https://fastcomments.com/oauth/authorize

3 ?response_type=code

4 &client_id=YOUR_CLIENT_ID

5 &redirect_uri=https://example.com/oauth/callback

6 &scope=read%20write

7 &state=RANDOM_STATE

8 &code_challenge=BASE64URL_SHA256_OF_VERIFIER

9 &code_challenge_method=S256

10

授权请求参数

Copy

1

2interface OAuthAuthorizeQueryParams {

3 response_type: 'code'

4 client_id: string

5 /** 必须与客户端已注册的重定向 URI 之一完全匹配。 **/

6 redirect_uri: string

7 /** 以空格分隔。省略则请求两个作用域。 **/

8 scope?: 'read' | 'write' | 'read write'

9 /** 在重定向时原样返回。用它将回调绑定到发起流程的会话。 **/

10 state?: string

11 /** base64url(sha256(code_verifier))。 **/

12 code_challenge: string

13 code_challenge_method: 'S256'

14 /** 可选的 RFC 8707 资源指示器。如果发送，则必须向令牌端点发送相同的值。 **/

15 resource?: string

16}

17

用户如需登录 FastComments，登录后会看到一个同意页面，其中列明您的应用程序、将要连接的账户以及所请求的作用域。用户必须在该账户上拥有 API Admin 权限；其他任何人都只会看到权限错误，而不是同意表单。批准后，浏览器将被重定向到您的 redirect_uri，并附带 code 和 state。拒绝则以 error=access_denied 重定向。

授权码有效期为 10 分钟，且只能兑换一次。对同一授权码的第二次兑换会撤销第一次兑换产生的所有令牌。

第 2 步 - 令牌请求

用授权码兑换令牌。请求体为表单编码。机密客户端使用 client_secret_basic（HTTP Basic）或 client_secret_post（密钥放在请求体中）进行认证。公共客户端只发送 client_id。

令牌请求 cURL 示例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/oauth/token' \

4 --header 'Content-Type: application/x-www-form-urlencoded' \

5 --data 'grant_type=authorization_code' \

6 --data 'client_id=YOUR_CLIENT_ID' \

7 --data 'client_secret=YOUR_CLIENT_SECRET' \

8 --data 'code=fcac_...' \

9 --data 'code_verifier=YOUR_PKCE_VERIFIER' \

10 --data 'redirect_uri=https://example.com/oauth/callback'

11

令牌请求体（authorization_code）

Copy

1

2interface OAuthTokenRequestAuthorizationCode {

3 grant_type: 'authorization_code'

4 client_id: string

5 /** 仅限机密客户端。也可以改用 HTTP Basic 认证发送。 **/

6 client_secret?: string

7 code: string

8 code_verifier: string

9 /** 如果发送，必须与授权请求中的值匹配。 **/

10 redirect_uri?: string

11 resource?: string

12}

13

令牌响应结构

Copy

1

2interface OAuthTokenResponse {

3 /** 前缀为 fcat_。有效期为一小时。 **/

4 access_token: string

5 token_type: 'bearer'

6 /** 访问令牌到期前的秒数。3600。 **/

7 expires_in: number

8 /** 前缀为 fcrt_。自颁发起有效期为 30 天。 **/

9 refresh_token: string

10 /** 以空格分隔的已授予作用域。 **/

11 scope: string

12}

13

错误遵循 RFC 6749：返回包含 error 和 error_description 的 JSON 请求体；invalid_request、invalid_grant、invalid_scope、invalid_target 和 unsupported_grant_type 返回 HTTP 400；invalid_client 返回 HTTP 401；被速率限制时返回 HTTP 429。

第 3 步 - 调用 API

将访问令牌作为 bearer 令牌发送。租户由令牌隐含，因此 tenantId 是可选的。如果提供了该参数，它必须与令牌匹配，否则请求将失败。

Bearer 令牌 cURL 示例

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/me' \

4 --header 'Authorization: Bearer fcat_...'

5

GET /api/v1/me 返回租户、授权用户以及已授予的作用域，因此它是连接测试的理想调用。使用已过期或已撤销令牌的请求会返回 HTTP 401。请求方法所需的作用域未被令牌持有时会返回 HTTP 403。

第 4 步 - 刷新

刷新请求 cURL 示例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/oauth/token' \

4 --header 'Content-Type: application/x-www-form-urlencoded' \

5 --data 'grant_type=refresh_token' \

6 --data 'client_id=YOUR_CLIENT_ID' \

7 --data 'client_secret=YOUR_CLIENT_SECRET' \

8 --data 'refresh_token=fcrt_...'

9

令牌请求体（refresh_token）

Copy

1

2interface OAuthTokenRequestRefreshToken {

3 grant_type: 'refresh_token'

4 client_id: string

5 client_secret?: string

6 refresh_token: string

7 /** 可选。将作用域缩小为最初授予的作用域的子集。 **/

8 scope?: string

9 resource?: string

10}

11

响应的结构与授权码兑换相同。刷新令牌会轮换：每次刷新都会返回一个新的 refresh_token，并在 30 秒的宽限期（用于并发请求）之后撤销旧令牌。提交一个已轮换超过 30 秒的刷新令牌会被视为重放攻击，并撤销整个授权。由 FastComments 注册的合作伙伴应用不受轮换限制，会返回相同的刷新令牌，其有效期再延长 30 天。

刷新时还会重新检查授权用户是否仍拥有该账户的 API Admin 权限。如果没有，授权将被撤销，响应为 invalid_grant。

撤销

撤销请求 cURL 示例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/oauth/revoke' \

4 --header 'Content-Type: application/x-www-form-urlencoded' \

5 --data 'client_id=YOUR_CLIENT_ID' \

6 --data 'client_secret=YOUR_CLIENT_SECRET' \

7 --data 'token=fcrt_...' \

8 --data 'token_type_hint=refresh_token'

9

撤销刷新令牌会撤销同一授权颁发的所有访问令牌。撤销访问令牌只撤销该令牌本身。无论是否找到该令牌，该端点都返回 HTTP 200 和一个空的 JSON 对象，遵循 RFC 7009。

用户还可以在 FastComments 控制面板的 Connected Apps 中撤销连接。该应用程序的所有令牌将立即失效。

此 API 通过对文档进行分组（如果提供了 groupBy）并应用多个操作来进行聚合。 支持不同的操作（例如 sum、countDistinct、avg 等）。

费用是 可变 的。每扫描 500 个对象消耗 1 个 API 积分。

默认情况下，每次 API 调用允许的最大内存使用量为 64MB，且默认情况下您一次只能运行一个聚合。如果您同时提交多个聚合，它们将按提交顺序排队并运行。待处理的聚合最多等待 60 秒，之后请求将超时。单个聚合最多可运行 5 分钟。

如果您有托管租户，您可以通过传递 parentTenantId 查询参数在一次调用中聚合所有子租户资源。

示例

示例：统计唯一值

统计唯一值 cURL 示例

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "distinct", "field": "urlId", "alias": "urlId" },

6 { "op": "distinct", "field": "commenterEmail", "alias": "commenterEmail" }

7 ]

8}'

9

统计唯一值 响应

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "commenterEmail": {

7 "distinctCounts": {

8 "someone@somewhere.com": 1,

9 "someone2@somewhere.com": 1

10 }

11 }

12 },

13 {

14 "urlId": {

15 "distinctCounts": {

16 "some-page": 2

17 }

18 }

19 }

20 ],

21 "stats": { "scanned": 2 }

22}

23

示例：统计不同值

统计不同值 cURL 示例

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "countDistinct", "field": "urlId", "alias": "urlId" },

6 { "op": "countDistinct", "field": "commenterEmail", "alias": "commenterEmail" }

7 ]

8}'

9

响应：

统计不同值 响应

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "commenterEmail": { "distinctCount": 2 },

7 "urlId": { "distinctCount": 1 }

8 }

9 ],

10 "stats": { "scanned": 2 }

11}

12

示例：多个字段求和

求和值 cURL 示例

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "sum", "field": "votes", "alias": "votes" },

6 { "op": "sum", "field": "votesUp", "alias": "votesUp" }

7 ]

8}'

9

响应：

求和值 响应

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "votes": { "numericValue": 2 },

7 "votesUp": { "numericValue": 2 }

8 }

9 ],

10 "stats": { "scanned": 2 }

11}

12

示例：多个字段平均值

平均值 cURL 示例

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "avg", "field": "votes", "alias": "votes" },

6 { "op": "avg", "field": "votesUp", "alias": "votesUp" }

7 ]

8}'

9

响应：

平均值 响应

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "votes": { "numericValue": 1 },

7 "votesUp": { "numericValue": 1 }

8 }

9 ],

10 "stats": { "scanned": 2 }

11}

12

示例：多个字段最小/最大值

最小/最大值 cURL 示例

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "min", "field": "votes", "alias": "votes" },

6 { "op": "min", "field": "votesUp", "alias": "votesUp" },

7 { "op": "max", "field": "votes", "alias": "votes" },

8 { "op": "max", "field": "votesUp", "alias": "votesUp" }

9 ]

10}'

11

响应：

最小/最大值 响应

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "votes": { "numericValue": 0 },

7 "votesUp": { "numericValue": 0 },

8 "votes": { "numericValue": 2 },

9 "votesUp": { "numericValue": 2 }

10 }

11 ],

12 "stats": { "scanned": 2 }

13}

14

示例：多个字段统计唯一值

统计唯一值 cURL 示例

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "distinct", "field": "urlId", "alias": "urlId" },

6 { "op": "distinct", "field": "commenterEmail", "alias": "commenterEmail" }

7 ]

8}'

9

响应：

统计唯一值 响应

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "commenterEmail": {

7 "distinctCounts": {

8 "someone@somewhere.com": 1,

9 "someone2@somewhere.com": 1

10 }

11 },

12 "urlId": {

13 "distinctCounts": {

14 "some-page": 2

15 }

16 }

17 }

18 ],

19 "stats": { "scanned": 2 }

20}

21

示例：创建查询示例

查询创建 cURL 示例

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "groupBy": ["commenterName"],

5 "query": [

6 { "key": "approved", "value": true, "operator": "eq" },

7 { "key": "commenterName", "value": "some-username-2", "operator": "eq" }

8 ],

9 "operations": [

10 { "op": "sum", "field": "votes", "alias": "votes" }

11 ]

12}'

13

响应：

查询创建 响应

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "groups": { "commenterName": "some-username-2" },

7 "votes": { "numericValue": 2 }

8 }

9 ],

10 "stats": { "scanned": 1 }

11}

12

示例：统计待审核评论

统计待审核评论 cURL 示例

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "query": [

5 { "key": "reviewed", "value": true, "operator": "not_eq" }

6 ],

7 "operations": [

8 { "op": "count", "field": "id", "alias": "count" }

9 ]

10}'

11

响应：

统计待审核评论 响应

Copy

1

2{

3 "status": "success",

4 "data": [

5 { "count": { "numericValue": 2 } }

6 ],

7 "stats": { "scanned": 2 }

8}

9

示例：已批准、已审核和垃圾评论的分类统计

评论分类统计 cURL 示例

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "distinct", "field": "approved", "alias": "approved" },

6 { "op": "distinct", "field": "reviewed", "alias": "reviewed" },

7 { "op": "distinct", "field": "isSpam", "alias": "isSpam" }

8 ]

9}'

10

响应：

评论分类统计 响应

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "approved": { "distinctCounts": { "true": 2 } },

7 "reviewed": { "distinctCounts": { "false": 2 } },

8 "isSpam": { "distinctCounts": { "false": 2 } }

9 }

10 ],

11 "stats": { "scanned": 2 }

12}

13

结构

聚合请求结构

Copy

1

2export type AggregationOpType = 'sum' | 'countDistinct' | 'distinct' | 'avg' | 'min' | 'max' | 'count';

3

4/** 将应用于字段的操作 */

5export interface AggregationOperation {

6 /** 操作的字段 */

7 field: string;

8 /** 操作类型 */

9 op: AggregationOpType;

10 /** 输出的可选别名；如果未提供，将计算默认别名 */

11 alias?: string;

12 expandArray?: boolean;

13}

14

15export interface QueryPredicate {

16 key: string

17 value: string | number | boolean

18 operator: 'eq' | 'not_eq' | 'greater_than' | 'less_than' | 'contains'

19}

20

21export interface AggregationRequest {

22 query?: QueryPredicate[];

23 resourceName: string;

24 groupBy?: string[];

25 operations: AggregationOperation[];

26 sort?: {

27 field: string;

28 dir: 'asc' | 'desc';

29 };

30}

31

32type DistinctAccumulator = Record<string, number>;

33type GroupValues = Record<string, string>;

34

35export type AggregationValue = {

36 distinctCounts?: DistinctAccumulator

37 distinctCount?: number

38 numericValue?: number

39 stringValue?: string

40 groups?: GroupValues

41};

42

聚合响应结构

Copy

1

2export type AggregationItem = Record<string, AggregationValue> & { groups?: GroupValues };

3

4export interface AggregationResponse {

5 status: APIStatus,

6 data: AggregationItem[];

7 stats?: {

8 scanned: number;

9 timeMS: number;

10 };

11}

12

以下资源可被聚合：

• AffiliateEvent
• AnonymousVote
• BannedUser
• BatchJob
• BlockedUser
• Comment
• CommentDeleted
• CommentIdToSyncOutbound
• CommentScheduled
• CommentSyncLog
• CustomConfig
• CustomEmailTemplateRenderError
• EmailToSend
• EventLogEntry
• ImportedCommentScheduled
• ModerationGroup
• Moderator
• Page
• PageReact
• PendingVote
• QuestionResult
• SSOUser
• SentEmail
• SpamEvent
• Tenant
• TenantAuditLog
• TenantBadge
• TenantDailyUsage
• TenantInvoiceHistory
• TenantPackage
• User
• UserBadge
• UserBadgeProgress
• UserNotification
• UserSubscription
• UserUsage
• Vote

此 API 使用分页，由 skip、limit、before 和 after 参数提供。AuditLogs 默认以 1000 条为一页返回，最大 limit 为 10000，按 when 和 id 排序。由于此端点通常用于一次性导出历史记录，而不是交互式分页浏览，页面会比较大。

每返回 100 条日志消耗 1 积分。

默认情况下，您将收到 最新的项目在前 的列表。这样，您可以从 skip=0 开始轮询，分页直到找到您已消费的最后一条记录。

或者，您可以按最旧的在前排序，并分页直到没有更多记录。

通过将 order 设置为 ASC 或 DESC 可以进行排序。默认是 DESC。

可以使用 before 和 after（以毫秒为单位的时间戳）按日期查询。before 和 after 为非包含性，可单独使用其中任意一个。

查找某人的操作记录

每个事件记录了执行者（username、userId、ip）以及被操作的对象。targetLabel 是该对象的可读标签，例如 jsmith (jsmith@example.com)，targetId 是其 ID。当您知道某人的姓名或电子邮件但不知道其 ID 时，可使用 target 对标签进行大小写不敏感的子字符串匹配。

删除操作会在事件发生时捕获标签，因此即使底层记录已被删除，仍可识别被删除的用户或版主。

托管租户

如果您的租户管理其他租户，请将 includeManagedTenants=true，以在单个响应中返回您租户及其管理的所有租户的事件。每条返回的日志的 tenantId 指示其来源租户。

AuditLog cURL 示例

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/audit-logs?tenantId=demo&API_KEY=DEMO_API_SECRET&skip=0&order=ASC&before=123&after=456'

4

AuditLog 请求结构

Copy

1

2interface AuditLogsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 order?: 'ASC' | 'DESC'

6 /** 最大 10000。默认 1000。 **/

7 limit?: number

8 skip?: number

9 before?: number

10 after?: number

11 /** 仅限此用户名执行的事件。 **/

12 username?: string

13 /** 仅限此 IP 地址的事件。 **/

14 ip?: string

15 /** 仅限此类型的事件。 **/

16 crudType?: 'c' | 'r' | 'u' | 'd' | 'login'

17 /** 仅限此资源的事件，例如用户或版主。 **/

18 resourceName?: string

19 /** 仅限受影响对象具有此 ID 的事件。 **/

20 targetId?: string

21 /** 对受影响对象标签的大小写不敏感的子字符串匹配。 **/

22 target?: string

23 /** 还返回此租户管理的租户的事件。 **/

24 includeManagedTenants?: boolean

25}

26

AuditLog 响应结构

Copy

1

2interface AuditLogsResponse {

3 status: 'success' | 'failed'

4 /** 失败时包含。 **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'invalid-limit' | 'invalid-skip'

6 /** 失败时包含。 **/

7 reason?: string

8 /** 日志！ **/

9 auditLogs: AuditLog[]

10}

11

此路由返回租户的所有类型的批处理作业，按最新排序，每页最多 100 条。使用 type 和 status 可缩小列表范围，使用 skip 进行分页。

BatchJob List cURL 示例

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/batch-jobs?tenantId=demo&API_KEY=DEMO_API_SECRET&type=migrate-pages&status=running'

4

BatchJob List 请求结构

Copy

1

2interface BatchJobsQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Only jobs of this type, for example migrate-pages. **/

6 type?: string

7 status?: 'requested' | 'running' | 'success' | 'failed'

8 /** How many jobs to skip, for paging. A non-negative integer. **/

9 skip?: number

10}

11

BatchJob List 响应结构

Copy

1

2interface BatchJobsResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'invalid-skip' | 'internal'

6 /** Included on failure. **/

7 reason?: string

8 /** Newest first, at most 100. **/

9 batchJobs?: BatchJob[]

10}

11

此路由返回单个批处理作业的状态、进度，并在完成后返回结果。可用于跟踪由 POST /api/v1/pages/migrations 或 POST /api/v1/pages/migrations/:undoId/undo 启动的作业。

当作业的 status 为 success 或 failed 时即表示完成。每次调用消耗 1 积分，因此请每隔几秒轮询一次，而不是持续请求。

按 ID 的 BatchJob cURL 示例

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/batch-jobs/my-batch-job-id?tenantId=demo&API_KEY=DEMO_API_SECRET'

4

按 ID 的 BatchJob 请求结构

Copy

1

2interface BatchJobQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

按 ID 的 BatchJob 响应结构

Copy

1

2interface BatchJobResponse {

3 status: 'success' | 'failed'

4 /** 失败时包含。 **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'internal'

6 /** 失败时包含。 **/

7 reason?: string

8 batchJob?: BatchJob

9}

10

已完成的页面迁移作业示例

Copy

1

2{

3 "status": "success",

4 "batchJob": {

5 "id": "my-batch-job-id",

6 "type": "migrate-pages",

7 "status": "success",

8 "createdAt": "2026-10-19T16:00:00.000Z",

9 "completedAt": "2026-10-19T16:00:12.000Z",

10 "processedCount": 2,

11 "totalCount": 2,

12 "pageMigrationResults": [

13 {"from": "old-post-id", "to": "new-post-id", "type": "urlId", "status": "success", "commentsMigrated": 42},

14 {"from": "old.example.com", "to": "new.example.com", "type": "domain", "status": "success", "commentsMigrated": 1250}

15 ],

16 "undoId": "my-undo-id"

17 }

18}

19

此 API 用于获取要展示给用户的评论。例如，它会自动过滤掉未通过审核或被标记为垃圾评论的内容。

分页

根据性能需求和用例，可以通过以下两种方式之一进行分页：

1. 最快：预计算分页：
   1. 当您使用我们的预构建组件和客户端时，FastComments 就是以这种方式工作的。
   2. 点击“下一页”只需增加页数。
   3. 您可以将其想象为通过键值存储进行检索。
   4. 通过这种方式，只需定义一个从 0 开始的 page 参数，并将排序方向定义为 direction。
   5. 页面大小可以通过自定义规则进行配置。
2. 最灵活：灵活分页：
   1. 通过这种方式，您可以定义自定义的 limit 和 skip 参数。不要传递 page。
   2. 也支持排序 direction。
   3. limit 是应用 skip 之后要返回的总数。
      • 示例：当 page size = 100 且 page = 2 时，设置 skip = 200, limit = 100。
   4. 子评论仍计入分页。您可以使用 asTree 选项来规避此问题。
      • 您可以通过 limitChildren 和 skipChildren 对子评论进行分页。
      • 您可以通过 maxTreeDepth 限制返回线程的深度。

线程

1. 使用 Precalculated Pagination 时，评论按页面分组，线程中的评论会影响整个页面。
   1. 通过这种方式，客户端可以根据 parentId 确定线程。
   2. 例如，对于一个包含一条顶级评论和 29 条回复的页面，在 API 中设置 page=0 后——您将只获得该顶级评论及其 29 条子评论。
2. 使用 Flexible Pagination 时，您可以定义 parentId 参数。
   1. 将其设置为 null 以仅获取顶级评论。
   2. 然后要查看线程，请再次调用 API 并传递 parentId。
   3. 一种常见的解决方案是先调用 API 获取顶级评论，然后并行调用 API 获取每条评论的子评论。
3. 2023 年 2 月新增！ 使用 &asTree=true 以树的形式获取。
   1. 您可以将其想象为 Flexible Pagination as a Tree。
   2. 分页中只计算顶级评论。
   3. 设置 parentId=null 以从根节点开始树（您必须设置 parentId）。
   4. 设置 skip 和 limit 进行分页。
   5. 将 asTree 设置为 true。
   6. 积分消耗增加 2x，因为在此场景下我们的后端需要做更多的工作。
   7. 根据需要设置 maxTreeDepth、limitChildren 和 skipChildren。

树结构说明

使用 asTree 时，分页可能难以理解。这里有一张实用的图示：

树分页图示

在用户上下文中获取评论

/comments API 可以在两种上下文中使用，适用于不同的用例：

• 用于返回已排序并带有信息的评论，以便构建您自己的客户端。
  • 在这种情况下，请定义 contextUserId 查询参数。
• 用于从您的后端获取评论以进行自定义集成。
  • 在没有 contextUserId 的情况下，平台将默认使用此方式。

评论预计算分页

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&page=0&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR'

4

评论灵活分页

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10'

4

用户上下文中的评论灵活分页

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id'

4

用户上下文中仅获取顶级评论的灵活分页

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null'

4

以树的形式获取评论

可以将评论以树的形式返回，分页只计算顶级评论。

用户上下文中以树形式获取评论

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null&asTree=true'

4

只想获取顶级评论及其直接子评论？这里有一种方法：

带最大深度的树形式评论

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null&asTree=true&maxTreeDepth=1&limitChildren=10'

4

但是，在您的 UI 中，您可能需要知道是否应在每条评论上显示“显示回复”按钮。通过树的形式获取评论时，在适用的情况下，评论上会附加一个 hasChildren 属性。

以树的形式获取评论，按话题标签搜索

可以通过 API 按话题标签进行搜索，覆盖您的整个租户（不限于单个页面或 urlId）。

在此示例中，我们省略了 urlId，并按多个话题标签进行搜索。API 将只返回包含所有请求话题标签的评论。

用户上下文中按话题标签以树形式获取评论

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null&asTree=true&hashTag=TestTag&hashTag=OtherTestTag'

4

所有请求参数

评论请求结构

Copy

1

2interface CommentsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** 评论所关联的 urlId（页面 URL 或文章 ID）。 **/

6 urlId?: string

7 /** 限制返回该用户的评论。 **/

8 userId?: string

9 /** 用于按话题标签搜索。要深入到多个话题标签的交集，请使用 &hashTag=a&hashTag=b。 **/

10 hashTag?: string

11 /** 排序方向。默认为 MR（最相关）。其他选项为 OF（最旧优先）和 NF（最新优先）。 **/

12 direction?: 'MR' | 'OF' | 'NF'

13 /** 预计算分页：要获取的页面，从 0 开始。传递 -1 获取所有评论（最多 250 条）。 **/

14 page?: number

15 /** 灵活分页：应返回多少条评论？ **/

16 limit?: number

17 /** 灵活分页：每个父评论应返回多少条子评论？ **/

18 limitChildren?: number

19 /** 灵活分页：应跳过多少条评论？ **/

20 skip?: number

21 /** 灵活分页：每个父评论应跳过多少条子评论？ **/

22 skipChildren?: number

23 /** 用于确定被屏蔽和被标记的评论。 **/

24 contextUserId?: string

25 /** 用于确定被屏蔽和被标记的评论。 **/

26 anonUserId?: string

27 /** 用于获取子评论。 **/

28 parentId?: string

29 /** 用于以树的形式获取。 **/

30 asTree?: boolean

31 /** 应返回树中多深的数据？0 表示不返回子评论。1 表示返回直接子评论，依此类推。 **/

32 maxTreeDepth?: number

33}

34

响应

评论响应结构

Copy

1

2interface CommentsResponse {

3 status: 'success' | 'failed'

4 /** 失败时包含。 **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'missing-date' | 'unauthorized-page' | 'invalid-pagination-request' | 'invalid-limit' | 'invalid-limit-children' | 'invalid-skip' | 'invalid-skip-children' | 'invalid-max-tree-depth'

6 /** 失败时包含。 **/

7 reason?: string

8 /** 评论！ **/

9 comments: Comment[]

10}

11

实用提示

URL ID

您可能希望使用带有 urlId 参数的 Comment API。您可以先调用 Pages API，查看可用的 urlId 值是什么样的。

匿名操作

对于匿名评论，您可能希望在获取评论以及执行标记和屏蔽操作时传递 anonUserId。

(!) 许多应用商店都要求这样做，因为用户必须能够标记他们可以看到的用户创建内容，即使他们未登录。不这样做可能导致您的应用从相应商店中被下架。

评论未被返回

请检查您的评论是否已通过审核，且不是垃圾评论。

此 API 提供按 ID 获取单条评论的功能。

按 ID 获取评论的 cURL 示例

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/comments/some-id?tenantId=demo&API_KEY=DEMO_API_SECRET'

4

按 ID 获取评论的请求结构

Copy

1

2interface CommentsGetByIdQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

按 ID 获取评论的响应结构

Copy

1

2interface CommentGetByIdResponse {

3 status: 'success' | 'failed'

4 /** 失败时包含。 **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'missing-id'

6 /** 失败时包含。 **/

7 reason?: string

8 /** 评论！ **/

9 comment?: Comment

10}

11

此 API 端点提供创建评论的功能。

常见用例包括自定义 UI、集成或导入。

注意：

• 如果需要，此 API 可以将评论小部件实时更新（这会将 creditsCost 从 1 增加到 2）。
• 如果提供了电子邮件地址，此 API 会在我们的系统中自动创建用户对象。
• 尝试保存两个电子邮件不同但用户名相同的评论，会导致第二条评论出现错误。
• 如果您指定了 parentId，并且子评论的 notificationSentForParent 为 false，我们会为父评论发送通知。此操作每小时进行一次（我们会将通知合并以减少发送的邮件数量）。
• 如果您希望在创建用户时发送欢迎邮件，或发送评论验证邮件，请在查询参数中将 sendEmails 设置为 true。
• 通过此 API 创建的评论会显示在管理应用的分析 (Analytics) 和审核 (Moderation) 页面中。
• 如果启用了该设置，评论者名称和评论文本中的“脏词”仍会被屏蔽。
• 通过此 API 创建的评论仍然可以（如需）进行垃圾评论检查。
• 通过自定义规则管理页面配置的设置（例如最大评论长度）也将适用于此处。

要在评论小部件中显示，提交的最低数据如下：

最小评论 POST cURL 示例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true' \

4 --header 'Content-Type: application/json' \

5 --data '{

6 "approved": true,

7 "comment": "some-comment",

8 "commenterName": "some-commenter-name",

9 "date": 1622644382148,

10 "urlId": "some-place",

11 "url": "https://exmaple.com/some-page",

12 "verified": true

13}'

14

更现实的请求可能如下所示：

评论 POST cURL 示例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true&doSpamCheck=true' \

4 --header 'Content-Type: application/json' \

5 --data '{

6 "approved": true,

7 "avatarSrc": "https://static.fastcomments.com/1605337537848-DSC_0841.JPG",

8 "comment": "some-comment",

9 "commenterName": "some-commenter-name",

10 "commenterEmail": "fordperfect@spaceship.com",

11 "date": 1622644382148,

12 "isSpam": false,

13 "locale": "en_us",

14 "notificationSentForParent": true,

15 "notificationSentForParentTenant": true,

16 "reviewed": true,

17 "urlId": "some-place",

18 "url": "https://exmaple.com/some-page",

19 "verified": true,

20 "votes": 1,

21 "votesUp": 2,

22 "votesDown": 1,

23 "ip": "123.456.789.000"

24}'

25

评论 POST 请求结构

Copy

1

2interface CommentPostQueryParams {

3 tenantId: string

4 API_KEY: string

5 doSpamCheck?: 'true' | 'false'

6 /** 指示该评论是否应对查看相同 urlId 的评论小部件实例的用户“实时”显示。注意：会将信用点消耗从 1 翻倍为 2。 **/

7 isLive?: 'true' | 'false'

8 sendEmails?: 'true' | 'false'

9 populateNotifications?: 'true' | 'false'

10}

11

评论 POST 响应结构

Copy

1

2

3interface CommentPostResponse {

4 status: 'success' | 'failed'

5 /** 失败时包含。 **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-comment' | 'comment-too-big' | 'hash-tags-readonly' | 'mentions-readonly' | 'invalid-user' | 'unauthorized' | 'invalid-date' | 'invalid-name' | 'invalid-name-is-email' | 'banned' | 'invalid-email';

7 /** 失败时包含。 **/

8 reason?: string

9 /** 创建的评论。 **/

10 comment?: Comment

11 /** 关联的用户，可能已存在也可能是新创建的。 **/

12 user?: User

13}

14

此 API 端点提供更新单条评论的功能。

说明：

• 如果需要，此 API 可以“实时”更新评论小部件（这会将基础 creditsCost 从 1 增加到 2）。
  • 这可以使在页面之间迁移评论变为“实时”（更改 urlId）。
  • 迁移会额外消耗 2 个积分，因为页面会被预计算，这会消耗大量 CPU。
• 与创建 API 不同，如果提供了电子邮件，此 API 不会在我们的系统中自动创建用户对象。
• 通过此 API 更新的评论仍然可以根据需要进行垃圾评论检查。
• 如果通过“自定义规则”管理页面配置了诸如最大评论长度等设置，那么这些配置在此处仍然适用。
• 若要允许用户更新其评论文本，您只需在请求体中指定 comment。我们将生成相应的 commentHTML。
  • 如果同时定义了 comment 和 commentHTML，我们将不会自动生成 HTML。
  • 如果用户在新文本中添加了提及或标签，它仍将像 POST API 一样进行处理。
• 在更新评论的 commenterEmail 时，最好也指定 userId。否则，您必须确保具有该电子邮件的用户属于您的租户，否则请求将失败。
• 如果目标评论被锁定（isLocked: true），请求将以 code: 'locked' 被拒绝。请先解锁评论，进行更新，然后在需要时重新锁定。

最小评论 PATCH cURL 示例

Copy

1

2curl --request PATCH \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true' \

4 --header 'Content-Type: application/json' \

5 --data '{

6 "comment": "some-new-comment-text"

7}'

8

评论 PATCH 请求结构

Copy

1

2interface CommentPatchQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** 执行更新的用户。可用于检查他们是否可以编辑该评论。 **/

6 contextUserId?: string

7 /** 是否应该检查新评论是否看起来像垃圾评论？ **/

8 doSpamCheck?: 'true' | 'false'

9 /** 评论是否应对查看具有相同 urlId 的评论小部件实例的用户“实时”显示。NOTE: Doubles credit cost from 1 to 2. **/

10 isLive?: 'true' | 'false'

11}

12

评论 PATCH 响应结构

Copy

1

2

3interface CommentPatchResponse {

4 status: 'success' | 'failed'

5 /** 失败时包含。 **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-comment' | 'comment-too-big' | 'hash-tags-readonly' | 'mentions-readonly' | 'invalid-user' | 'unauthorized' | 'invalid-date' | 'invalid-name' | 'invalid-name-is-email' | 'banned' | 'invalid-email' | 'invalid-input' | 'missing-id' | 'not-found' | 'locked'

7 /** 失败时包含。 **/

8 reason?: string

9}

10

此 API 端点提供删除评论的功能。

注意事项：

• 如果需要，此 API 可以“实时”更新评论小部件（这会将 creditsCost 从 1 增加到 2）。
• 此 API 会删除所有子评论。
• 如果目标评论被锁定（isLocked: true），请求将被拒绝并返回 code: 'locked'。请先解锁评论，然后再删除。

Comment DELETE cURL 示例

Copy

1

2curl --request DELETE \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \

4 --header 'Content-Type: application/json'

5

Comment DELETE 请求结构

Copy

1

2interface CommentDeleteQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** 执行更新的用户。可用于校验其是否可以删除该评论。 **/

6 contextUserId?: string

7 /** 是否应对正在查看具有相同 urlId 的评论小部件实例的用户“实时”删除评论。注意：会将信用点消耗从 1 翻倍为 2。 **/

8 isLive?: 'true' | 'false'

9}

10

Comment DELETE 响应结构

Copy

1

2

3interface CommentDeleteResponse {

4 status: 'success' | 'failed'

5 /** 失败时包含。 **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'locked'

7 /** 失败时包含。 **/

8 reason?: string

9}

10

此 API 端点提供为特定用户标记评论的功能。

Notes:

• 此调用必须始终在用户上下文中进行。该用户可以是 FastComments.com 用户、SSO 用户或租户用户。
• 如果设置了用于隐藏的标记阈值，评论在被标记达到定义次数后将会被实时自动隐藏。
• 在评论被自动取消批准（隐藏）之后，只有管理员或版主可以重新批准该评论。取消标记不会重新批准评论。

评论标记 cURL 示例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/flag?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \

4 --header 'Content-Type: application/json'

5

对于匿名标记，我们必须指定一个 anonUserId。这可以是代表匿名会话的 ID，或随机 UUID。 这允许我们在用户未登录的情况下也支持对评论的标记和取消标记。这样，当使用相同的 anonUserId 获取评论时，该评论可以被标记为已标记。

匿名评论标记 cURL 示例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/flag?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \

4 --header 'Content-Type: application/json'

5

评论标记请求结构

Copy

1

2interface CommentFlagQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7}

8

评论标记响应结构

Copy

1

2

3interface CommentFlagResponse {

4 status: 'success' | 'failed'

5 /** 失败时包含。 **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id'

7 /** 失败时包含。 **/

8 reason?: string

9 /** 该评论是否因被标记过多而被取消批准（隐藏）？ **/

10 wasUnapproved?: boolean;

11}

12

此 API 端点提供取消特定用户对评论的标记的能力。

Notes:

• 此调用必须始终在用户上下文中进行。该用户可以是 FastComments.com 用户、SSO 用户或租户用户。
• 在评论被自动取消批准（隐藏）后——该评论只能由管理员或版主重新批准。取消标记不会重新批准该评论。

取消评论标记 cURL 示例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-flag?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \

4 --header 'Content-Type: application/json'

5

对于匿名标记，我们必须指定 anonUserId。这可以是表示匿名会话的 ID，或一个随机 UUID。

匿名评论取消标记 cURL 示例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-flag?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \

4 --header 'Content-Type: application/json'

5

取消评论标记 请求结构

Copy

1

2interface CommentFlagQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7}

8

取消评论标记 响应结构

Copy

1

2

3interface CommentUnFlagResponse {

4 status: 'success' | 'failed'

5 /** 失败时包含。 **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id'

7 /** 失败时包含。 **/

8 reason?: string

9}

10

此 API 端点提供封锁撰写特定评论的用户的能力。它支持对由 FastComments.com 用户、SSO 用户和租户用户撰写的评论进行封锁。

它支持一个名为 commentIdsToCheck 的 body 参数，用于在执行此操作后检查客户端上是否有任何其他可能可见的评论应被封锁/解封。

Notes:

• 此调用必须始终在某个用户的上下文中进行。该用户可以是 FastComments.com 用户、SSO 用户或租户用户。
• 请求中的 userId 是正在执行封锁的用户。例如：User A 想封锁 User B。传入 userId=User A 以及 User B 所撰写的评论 ID。
• 完全匿名的评论（无用户 id、无电子邮件）无法被封锁，将返回错误。

评论封锁 cURL 示例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/block?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \

4 --header 'Content-Type: application/json'

5

对于匿名封锁，我们必须指定一个 anonUserId。这可以是表示匿名会话的 ID，或者是一个随机的 UUID。 这使我们能够即使在用户未登录的情况下也支持封锁评论，只要使用相同的 anonUserId 来获取评论。

匿名评论封锁 cURL 示例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/block?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \

4 --header 'Content-Type: application/json'

5

评论封锁 请求结构

Copy

1

2interface CommentBlockQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7 commentIdsToCheck?: string[]

8}

9

评论封锁 响应结构

Copy

1

2

3interface CommentBlockResponse {

4 status: 'success' | 'failed'

5 /** 在失败时包含。 **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id' | 'comment-cannot-be-blocked'

7 /** 在失败时包含。 **/

8 reason?: string

9 /** 如果定义了 commentIdsToCheck，该映射中为 true 的条目也会被封锁。 **/

10 commentStatuses?: Record<string, boolean>;

11}

12

此 API 端点提供解除对撰写给定评论的用户的封禁的功能。它支持对由 FastComments.com 用户、SSO 用户和租户用户撰写的评论进行解除封禁。

它支持一个 commentIdsToCheck 请求体参数，用于在执行此操作后检查客户端上其他可能可见的评论是否应被封禁/解封。

注意：

• 此调用必须始终在用户上下文中进行。该用户可以是 FastComments.com 用户、SSO 用户或租户用户。
• 请求中的 userId 是正在执行解除封禁操作的用户。例如：User A 想要解除对 User B 的封禁。传入 userId=User A 以及 User B 所写的评论 id。
• 完全匿名的评论（没有用户 id、没有电子邮件）无法被封禁，会返回错误。

评论 解除封禁 cURL 示例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-block?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \

4 --header 'Content-Type: application/json'

5

匿名评论 解除封禁 cURL 示例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-block?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \

4 --header 'Content-Type: application/json'

5

评论 解除封禁 请求结构

Copy

1

2interface CommentUnBlockQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7 commentIdsToCheck?: string[]

8}

9

评论 解除封禁 响应结构

Copy

1

2

3interface CommentUnBlockResponse {

4 status: 'success' | 'failed'

5 /** 失败时包含。 **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id' | 'comment-cannot-be-blocked'

7 /** 失败时包含。 **/

8 reason?: string

9 /** 如果定义了 commentIdsToCheck，则此映射中值为 true 的条目仍然被封禁。若为 false，则您可能需要对用户取消隐藏这些评论，以免他们需要刷新页面。 **/

10 commentStatuses?: Record<string, boolean>;

11}

12

可以通过相应的 id（不是 emailTemplateId）获取单个 EmailTemplate。

按 ID 获取 EmailTemplate 的 cURL 示例

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/email-templates/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

4

按 ID 获取 EmailTemplate 的请求结构

Copy

1

2interface EmailTemplatesByIdRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

按 ID 获取 EmailTemplate 的响应结构

Copy

1

2interface EmailTemplateResponse {

3 status: 'success' | 'failed'

4 /** 失败时包含。 **/

5 code?: 'internal' | 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found'

6 /** 失败时包含。 **/

7 reason?: string

8 emailTemplate?: EmailTemplate | null

9}

10

此 API 使用分页，由 page 查询参数提供。EmailTemplates 以每页 100 项返回，按 createdAt 然后 id 排序。

EmailTemplate cURL 示例

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/email-templates?tenantId=demo&page=0&API_KEY=DEMO_API_SECRET'

4

EmailTemplate 请求结构

Copy

1

2interface EmailTemplatesRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** 要获取的页码，从 0 开始。 **/

6 page: number

7}

8

EmailTemplate 响应结构

Copy

1

2interface EmailTemplatesResponse {

3 status: 'success' | 'failed'

4 /** 失败时包含。 **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'

6 /** 失败时包含。 **/

7 reason?: string

8 emailTemplates: EmailTemplate[]

9}

10

这个 API 端点允许通过仅指定 id 和要更新的属性来更新电子邮件模板。

请注意，创建模板时相同的所有验证也适用，例如：

• 模板必须能渲染。每次更新时都会检查这一点。
• 同一域名不能有重复的模板（否则其中一个将被静默忽略）。

EmailTemplate PATCH cURL 示例

Copy

1

2curl --request PATCH \

3 --url 'https://fastcomments.com/api/v1/email-templates/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \

4 --header 'Content-Type: application/json' \

5 --data '{

6 "displayName": "Some New Name",

7}'

8

EmailTemplate PATCH 请求结构

Copy

1

2interface EmailTemplatePatchQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

EmailTemplate PATCH 响应结构

Copy

1

2

3interface EmailTemplatePatchResponse {

4 status: 'success' | 'failed'

5 /** 失败时包含。 **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'not-found' | 'unexpected-param' | 'invalid-email-template-id' | 'unauthorized' | 'domain-invalid' | 'duplicate' | 'does-not-render';

7 /** 失败时包含。 **/

8 reason?: string

9 /** 已更新的电子邮件模板。 **/

10 emailTemplate?: EmailTemplate

11}

12

此 API 端点提供创建电子邮件模板的能力。

注意：

• 在相同域名下，不能有多个相同 emailTemplateId 的模板。
• 但你可以有一个通配符模板（domain = *）和同一 emailTemplateId 的域特定模板共存。
• 指定 domain 仅在你有不同域名，或想为测试使用特定模板（例如将 domain 设置为 localhost）时才相关。
• 如果你确实指定了 domain，它必须匹配一个 DomainConfig。发生错误时会提供一个有效域名列表。
• 模板语法为 EJS，渲染有 500ms 的超时。渲染的 P99 小于 5ms，因此如果达到 500ms 就说明有问题。
• 你的模板必须能使用提供的 testData 成功渲染 才能保存。渲染错误会被聚合并在仪表盘上报告（很快也会通过 API 提供）。

添加模板所需的最少数据如下：

最小 EmailTemplate POST cURL 示例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/email-templates?tenantId=demo&API_KEY=DEMO_API_SECRET' \

4 --header 'Content-Type: application/json' \

5 --data '{

6 "emailTemplateId": "comment-user-mention",

7 "displayName": "I'm a custom template.",

8 "ejs": "This is an @mention notification! My name is <%= comment.commenterName %>."

9}'

10

你可能希望为每个站点设置模板，在这种情况下你可以定义 domain：

EmailTemplate POST cURL 示例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/email-templates?tenantId=demo&API_KEY=DEMO_API_SECRET' \

4 --header 'Content-Type: application/json' \

5 --data '{

6 "emailTemplateId": "comment-user-mention",

7 "displayName": "I'm a custom template.",

8 "ejs": "This is some email content!",

9 "domain": "somespecificsite.com",

10}'

11

EmailTemplate POST 请求结构

Copy

1

2interface EmailTemplatePostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

EmailTemplate POST 响应结构

Copy

1

2

3interface EmailTemplatePostResponse {

4 status: 'success' | 'failed'

5 /** 失败时包含。 **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'unexpected-param' | 'invalid-email-template-id' | 'domain-invalid' | 'duplicate' | 'does-not-render';

7 /** 失败时包含的原因。 **/

8 reason?: string

9 /** 已创建的模板。 **/

10 emailTemplate?: EmailTemplate

11}

12

此 API 端点提供预览电子邮件模板的功能。

最小的 EmailTemplate 预览 POST cURL 示例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/email-templates/render?tenantId=demo&API_KEY=DEMO_API_SECRET' \

4 --header 'Content-Type: application/json' \

5 --data '{

6 "emailTemplateId": "comment-user-mention",

7 "displayName": "I'm a custom template.",

8 "ejs": "This is an @mention notification! My name is <%= comment.commenterName %>."

9}'

10

EmailTemplate POST 请求结构

Copy

1

2interface EmailTemplatePostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

EmailTemplate POST 响应结构

Copy

1

2

3interface EmailTemplatePostResponse {

4 status: 'success' | 'failed'

5 /** 在失败时包含。 **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'unexpected-param' | 'does-not-render';

7 /** 在失败时包含。 **/

8 reason?: string

9 /** 成功时渲染的 HTML。 **/

10 html?: string

11}

12

该路由用于通过 id 删除单个 EmailTemplate。

EmailTemplate 删除 cURL 示例

Copy

1

2curl --request DELETE \

3 --url 'https://fastcomments.com/api/v1/email-templates/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

4

EmailTemplate 删除 请求结构

Copy

1

2interface EmailTemplateRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

EmailTemplate 删除 响应结构

Copy

1

2interface EmailTemplateDeleteResponse {

3 status: 'success' | 'failed'

4 /** 失败时包含。 **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized'

6 /** 失败时包含。 **/

7 reason?: string

8}

9

获取 feed 中的帖子，按最新排序。分页基于游标：将您收到的最后一篇帖子的 _id 作为 afterId 传递，以获取下一页。

每返回十篇帖子消耗一个积分，最低消耗一个积分。

FeedPost cURL 示例

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/feed-posts?tenantId=demo&limit=10&API_KEY=DEMO_API_SECRET'

4

FeedPost 请求结构

Copy

1

2interface FeedPostsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** 返回此帖子 ID 之后的帖子。首次页面请省略。 **/

6 afterId?: string

7 /** 默认值为 10。最大值为 1000。 **/

8 limit?: number

9 /** 仅返回带有这些标签的帖子。若有多个标签，请重复该参数。 **/

10 tags?: string[]

11}

12

FeedPost 响应结构

Copy

1

2interface FeedPostsResponse {

3 status: 'success' | 'failed'

4 /** 失败时包含此字段。 **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'limit-invalid' | 'internal'

6 /** 失败时包含此字段。 **/

7 reason?: string

8 feedPosts: FeedPost[]

9}

10

此路由创建一个单独的 FeedPost。每个帖子都有作者，因此 fromUserId 为必填项，且必须是账户中已存在的 FastComments 或 SSO 用户的 ID。

FeedPost 创建 cURL 示例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/feed-posts?tenantId=demo&isLive=true&API_KEY=DEMO_API_SECRET' \

4 --header 'Content-Type: application/json' \

5 --data '{

6 "fromUserId": "some-user-id",

7 "title": "Release 2.0 is out",

8 "contentHTML": "<p>Read the notes and tell us what you think.</p>",

9 "tags": ["releases"],

10 "links": [

11 {

12 "url": "https://example.com/releases/2.0",

13 "title": "Release notes",

14 "description": "Everything that changed in 2.0."

15 }

16 ]

17}'

18

FeedPost 创建请求结构

Copy

1

2interface FeedPostPostQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** 将帖子推送到当前在浏览器中打开的 feed。默认值为 false。 **/

6 isLive?: boolean

7 /** 在保存之前通过垃圾信息引擎处理帖子。默认值为 false。 **/

8 doSpamCheck?: boolean

9 /** 跳过作为 doSpamCheck 一部分运行的重复内容检查。默认值为 false。 **/

10 skipDupCheck?: boolean

11 /** 最多 256 个字符。回显给实时监听者，以便客户端可以忽略自己的广播。 **/

12 broadcastId?: string

13}

14

15interface FeedPostPostBody {

16 /** 必填。FastComments 或 SSO 用户的 ID。 **/

17 fromUserId: string

18 title?: string

19 /** HTML。保存时会进行清理。 **/

20 contentHTML?: string

21 /** 覆盖从用户获取的显示名称。 **/

22 fromUserDisplayName?: string

23 tags?: string[]

24 media?: FeedPostMediaItem[]

25 links?: FeedPostLink[]

26 meta?: Record<string, string>

27}

28

FeedPost 创建响应结构

Copy

1

2interface FeedPostPostResponse {

3 status: 'success' | 'failed'

4 /** 失败时包含。 **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-from-user-id' | 'invalid-user' | 'broadcast-id-too-long' | 'spam-blocked' | 'user-rate-limited' | 'internal'

6 /** 失败时包含。 **/

7 reason?: string

8 feedPost?: FeedPost; // 成功时返回完整创建的帖子。

9}

10

此路由更新单个 FeedPost。仅发送您想更改的字段。

FeedPost 更新 cURL 示例

Copy

1

2curl --request PATCH \

3 --url 'https://fastcomments.com/api/v1/feed-posts/some-post-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \

4 --header 'Content-Type: application/json' \

5 --data '{

6 "title": "Release 2.0.1 is out",

7 "tags": ["releases", "hotfix"]

8}'

9