Resource Usage

It should be noted that fetching data from the API is counted as usage on your account.

Each resource will list what that usage is in its own section.

Some resources cost more to serve than others. Each endpoint has a set cost of credits per API call. For some endpoints, the number of credits varies based on the options and response sizes.

API usage can be checked on the Billing Analytics page and is updated every few minutes.

Note!

We suggest reading the Pages documentation first, to help limit confusion when determining what values to pass for urlId in the Comment API.

This API Aggregates documents by grouping them (if groupBy is provided) and applying multiple operations. Different operations (e.g. sum, countDistinct, avg, etc.) are supported.

The cost is variable. Every 500 objects scanned costs 1 API credit.

The max memory usage allowed per API call by default is 64MB, and by default you may only have one aggregation running at a time. If you submit multiple aggregations simultaneously, they will be queued and ran in the order submitted. Pending aggregations will wait a maximum of 60 seconds, after that the request will time out. Individual aggregations may run for up to 5 minutes.

If you have managed tenants, you can aggregate all child tenant resources in one call by passing the parentTenantId query param.

Examples

Example: Count Unique

Count Unique Values cURL Example

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

Count Unique Values Response

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

Example: Count Distinct

Count Distinct Values cURL Example

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

Response:

Count Distinct Values Response

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

Example: Sum Values of Multiple Fields

Sum Values cURL Example

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

Response:

Sum Values Response

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

Example: Average Values of Multiple Fields

Average Values cURL Example

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

Response:

Average Values Response

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

Example: Min/Max Values of Multiple Fields

Min/Max Values cURL Example

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

Response:

Min/Max Values Response

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

Example: Count Unique Values of Multiple Fields

Count Unique Values cURL Example

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

Response:

Count Unique Values Response

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

Example: Query Creation Example

Query Creation cURL Example

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

Response:

Query Creation Response

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

Example: Count Comments Pending Review

Count Pending Review Comments cURL Example

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

Response:

Count Pending Review Comments Response

Copy

1

2{

3 "status": "success",

4 "data": [

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

6 ],

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

8}

9

Example: Breakdown of Approved, Reviewed, and Spam Comments

Breakdown of Comments cURL Example

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

Response:

Breakdown of Comments Response

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

Structures

Aggregate Request Structure

Copy

1

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

3

4/** An operation that will be applied on a field */

5export interface AggregationOperation {

6 /** The field to operate on */

7 field: string;

8 /** The type of operation */

9 op: AggregationOpType;

10 /** Optional alias for the output; if not provided, a default alias is computed */

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'

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

Aggregate Response Structure

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

The following resources can be aggregated:

• 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

This API uses pagination, provided by the skip, before, and after parameters. AuditLogs are returned in pages of 1000, ordered by when and id.

Fetching every 1000 logs has a credit cost of 10.

By default, you will receive a list with the newest items first. This way, you can poll starting with skip=0, paginating until you find the last record you've consumed.

Alternatively, you can sort oldest-first, and paginate until there are no more records.

Sorting can be done by setting order to either ASC or DESC. The default is ASC.

Querying by date is possible via before and after as timestamps with milliseconds. before and after are NOT inclusive.

AuditLog cURL Example

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 Request Structure

Copy

1

2interface CommentsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 order?: 'ASC' | 'DESC'

6 skip?: number

7 before?: number

8 after?: number

9}

10

AuditLog Response Structure

Copy

1

2interface CommentsResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

6 /** Included on failure. **/

7 reason?: string

8 /** The logs! **/

9 auditLogs: AuditLog[]

10}

11

This API is used to get comments for displaying to a user. For example, it automatically filters out unapproved or spam comments.

Pagination

Pagination can be done in one of two ways, depending on performance requirements and use case:

1. Fastest: Precalculated Pagination:
   1. This is how FastComments works when you use our prebuilt widgets and clients.
   2. Clicking "next" simply increases the page count.
   3. You can think of this as being retrieved by a key-value store.
   4. In this way, simply define a page parameter starting at 0 and a sort direction as direction.
   5. Page sizes can be customized via customization rules.
2. Most Flexible: Flexible Pagination:
   1. In this way you can define custom limit and skip parameters. Do not pass page.
   2. Sort direction is also supported.
   3. limit is the total number to return after skip is applied.
      • Example: set skip = 200, limit = 100 when page size = 100 and page = 2.
   4. Child comments still count in the pagination. You can get around this using the asTree option.
      • You can paginate children via limitChildren and skipChildren.
      • You can limit the depth of the threads returned via maxTreeDepth.

Threads

1. When using Precalculated Pagination, comments are grouped by page and comments in threads affect the overall page.
   1. In this way, threads can be determined on the client based on parentId.
   2. For example, with a page with one top-level comment, and 29 replies, and setting page=0 in the API - you will get just the top level comment and the 29 children.
   3. Example image here illustrating multiple pages.
2. When using Flexible Pagination, you may define a parentId parameter.
   1. Set this to null to only get top-level comments.
   2. Then to view threads, call the API again and pass parentId.
   3. A common solution is to make an API call for the top-level comments and then make parallel API calls to get comments for the children of each comment.
3. NEW As of Feb 2023! Fetch as a tree using &asTree=true.
   1. You can think of this as Flexible Pagination as a Tree.
   2. Only the top-level comments count in the pagination.
   3. Set parentId=null to start the tree at the root (you must set parentId).
   4. Set skip and limit for pagination.
   5. Set asTree to true.
   6. The credits cost increases by 2x, as our backend has to do much more work in this scenario.
   7. Set maxTreeDepth, limitChildren, and skipChildren as desired.

Trees Explained

When using asTree, it can be hard to reason about pagination. Here's a handy graphic:

Tree Pagination Diagram

Fetching Comments in The Context of a User

The /comments API can be used in two contexts, for different use cases:

• For returning comments sorted and tagged with information for building your own client.
  • In this case, define a contextUserId query parameter.
• For fetching comments from your backend for custom integrations.
  • The platform will default to this without contextUserId.

Comments Precalculated Pagination

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

Comments Flexible Pagination

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

Comments Flexible Pagination in User Context

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

Comments Flexible Pagination in User Context for Top Level Comments Only

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

Get Comments as a Tree

It's possible to get the comments returned as a tree, with pagination only counting the top-level comments.

Comments As-A-Tree in User Context

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

Want to only get the top level comments and the immediate children? Here's one way:

Comments As-A-Tree with Max Depth

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

However, in your UI you might need to know whether to show a "show replies" button on each comment. When fetching comments via a tree there is a hasChildren property tagged onto comments when applicable.

Get Comments as a Tree, Searching by Hash Tag

It's possible to search by hashtag using the API, across your entire tenant (not limited to one page, or urlId).

In this example, we omit urlId, and we search by multiple hashtags. The API will only return comments that have all requested hashtags.

Comments As-A-Tree in User Context, By Hash Tag

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

All Request Params

Comments Request Structure

Copy

1

2interface CommentsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** The urlId (page url, or article id) the comments are associated with. **/

6 urlId?: string

7 /** Limit the comments returned by this user. **/

8 userId?: string

9 /** Use this to search by hashtag. To drill down to the intersection of multiple hashtags, do &hashTag=a&hashTag=b. **/

10 hashTag?: string

11 /** The sort direction. Default is MR (Most Relevant). Other options are OF (Oldest First) and NF (Newest First). **/

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

13 /** Precalculated Pagination: The page to fetch, starting with 0. Pass -1 for all comments (up to 250). **/

14 page?: number

15 /** Flexible Pagination: How many comments should we return? **/

16 limit?: number

17 /** Flexible Pagination: How many child comments should we return for each parent? **/

18 limitChildren?: number

19 /** Flexible Pagination: How many comments should we skip? **/

20 skip?: number

21 /** Flexible Pagination: How many child comments should we skip for each parent? **/

22 skipChildren?: number

23 /** For determining blocked and flagged comments. **/

24 contextUserId?: string

25 /** For determining blocked and flagged comments. **/

26 anonUserId?: string

27 /** For fetching child comments. **/

28 parentId?: string

29 /** For fetching as a tree. **/

30 asTree?: boolean

31 /** How far into the tree should we return data? 0 returns no children. 1 returns immediate children, etc. **/

32 maxTreeDepth?: number

33}

34

The Response

Comments Response Structure

Copy

1

2interface CommentsResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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 /** Included on failure. **/

7 reason?: string

8 /** The comments! **/

9 comments: Comment[]

10}

11

Helpful Tips

URL ID

You probably want to use the Comment API with the urlId parameter. You can call the Pages API first, to see what the urlId values available to you look like.

Anonymous Actions

For anonymous commenting you probably want to pass anonUserId when fetching comments, and when performing flagging and blocking.

(!) This is required for many app stores as users must be able to flag user-created content they can see, even if they are not logged in. Not doing so may cause your app to be removed from said store.

Comments Not Being Returned

Check that your comments are approved, and are not spam.

This API provides the ability to fetch a single comment by id.

Comments Get-By-Id cURL Example

Copy

1

2curl --request GET \

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

4

Comment Get-By-Id Request Structure

Copy

1

2interface CommentsGetByIdQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Comments Get-By-Id Response Structure

Copy

1

2interface CommentGetByIdResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

6 /** Included on failure. **/

7 reason?: string

8 /** The comment! **/

9 comment?: Comment

10}

11

This API endpoint provides the ability to create comments.

Common use cases are custom UIs, integrations, or imports.

Notes:

• This API can update the comment widget "live" if desired (this increases creditsCost from 1 to 2).
• This API will automatically create user objects in our system if email is provided.
• Trying to save two comments with different emails, but the same username, will result in an error for the second comment.
• If you are specifying parentId, and a child comment has notificationSentForParent as false, we will send notifications for the parent comment. This is done every hour (we batch the notifications together to decrease the number of emails sent).
• If you want to send welcome emails when creating users, or comment verification emails, set sendEmails to true in query parameters.
• Comments created via this API will show up in the Analytics and Moderation pages of the admin app.
• "bad words" are still masked in the commenter names and comment text if the setting is turned on.
• Comments created via this API can still be checked for spam if desired.
• Configuration such as max comment length, if configured via the Customization Rule admin page, will apply here.

The minimum data required to submit that will show in the comment widget, is as follows:

Minimum Comment POST cURL Example

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

A more realistic request may look like:

Comment POST cURL Example

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

Comment POST Request Structure

Copy

1

2interface CommentPostQueryParams {

3 tenantId: string

4 API_KEY: string

5 doSpamCheck?: 'true' | 'false'

6 /** Whether the comment should appear "live" to users viewing instances of the comment widget with the same urlId. NOTE: Doubles credit cost from 1 to 2. **/

7 isLive?: 'true' | 'false'

8 sendEmails?: 'true' | 'false'

9 populateNotifications?: 'true' | 'false'

10}

11

Comment POST Response Structure

Copy

1

2

3interface CommentPostResponse {

4 status: 'success' | 'failed'

5 /** Included on failure. **/

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 /** Included on failure. **/

8 reason?: string

9 /** The created comment. **/

10 comment?: Comment

11 /** The associated user, which may or may not have already existed. **/

12 user?: User

13}

14

This API endpoint provides the ability to update a single comment.

Notes:

• This API can update the comment widget "live" if desired (this increases base creditsCost from 1 to 2).
  • This can make migrating comments between pages "live" (changing urlId).
  • Migrations cost an additional 2 credits as pages are precalculated and this is CPU intensive.
• Unlike the create API, this API will NOT automatically create user objects in our system if email is provided.
• Comments updated via this API can still be checked for spam if desired.
• Configuration such as max comment length, if configured via the Customization Rule admin page, will apply here.
• To allow users to update their comment text, you can just specify comment in the request body. We will generate the resulting commentHTML.
  • If you define both comment and commentHTML we will not automatically generate the HTML.
  • If the user adds mentions or hashtags in their new text, it will still be processed like the POST API.
• When updating commenterEmail on a comment, it is best to also specify userId. Otherwise, you must ensure the user with this email belongs to your tenant, or the request will fail.

Minimum Comment PATCH cURL Example

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

Comment PATCH Request Structure

Copy

1

2interface CommentPatchQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** The user doing the update. If desired can be used to check that they can edit the comment. **/

6 contextUserId?: string

7 /** Should we check if the new comment looks like spam? **/

8 doSpamCheck?: 'true' | 'false'

9 /** Whether the comment should appear "live" to users viewing instances of the comment widget with the same urlId. NOTE: Doubles credit cost from 1 to 2. **/

10 isLive?: 'true' | 'false'

11}

12

Comment PATCH Response Structure

Copy

1

2

3interface CommentPatchResponse {

4 status: 'success' | 'failed'

5 /** Included on failure. **/

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'

7 /** Included on failure. **/

8 reason?: string

9}

10

This API endpoint provides the ability to delete a comment.

Notes:

• This API can update the comment widget "live" if desired (this increases creditsCost from 1 to 2).
• This API will delete all child comments.

Comment DELETE cURL Example

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 Request Structure

Copy

1

2interface CommentDeleteQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** The user doing the update. If desired can be used to check that they can delete the comment. **/

6 contextUserId?: string

7 /** Whether the comment should be deleted "live" to users viewing instances of the comment widget with the same urlId. NOTE: Doubles credit cost from 1 to 2. **/

8 isLive?: 'true' | 'false'

9}

10

Comment DELETE Response Structure

Copy

1

2

3interface CommentDeleteResponse {

4 status: 'success' | 'failed'

5 /** Included on failure. **/

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

7 /** Included on failure. **/

8 reason?: string

9}

10

This API endpoint provides the ability to flag a comment for a specific user.

Notes:

• This call must always be made in the context of a user. The user can be a FastComments.com User, SSO User, or Tenant User.
• If a flag-to-hide threshold is set, the comment will be automatically hidden live after it has been flagged the defined number of times.
• After it is automatically un-approved (hidden) - the comment can only be re-approved by an administrator or moderator. Un-flagging will not re-approve the comment.

Comment Flag cURL Example

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

For anonymous flagging, we must specify an anonUserId. This can be an ID that represents the anonymous session, or a random UUID. This allows us to support flagging and un-flagging comments even if a user is not logged in. This way, the comment can be marked as flagged when comments are fetched with the same anonUserId.

Anonymous Comment Flag cURL Example

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

Comment Flag Request Structure

Copy

1

2interface CommentFlagQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7}

8

Comment Flag Response Structure

Copy

1

2

3interface CommentFlagResponse {

4 status: 'success' | 'failed'

5 /** Included on failure. **/

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 /** Included on failure. **/

8 reason?: string

9 /** Was the comment un-approved (hidden) due to being flagged too many times? **/

10 wasUnapproved?: boolean;

11}

12

This API endpoint provides the ability to un-flag a comment for a specific user.

Notes:

• This call must always be made in the context of a user. The user can be a FastComments.com User, SSO User, or Tenant User.
• After a comment is automatically un-approved (hidden) - the comment can only be re-approved by an administrator or moderator. Un-flagging will not re-approve the comment.

Comment Un-Flag cURL Example

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

For anonymous flagging, we must specify an anonUserId. This can be an ID that represents the anonymous session, or a random UUID.

Anonymous Comment Flag cURL Example

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

Comment Un-Flag Request Structure

Copy

1

2interface CommentFlagQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7}

8

Comment Un-Flag Response Structure

Copy

1

2

3interface CommentUnFlagResponse {

4 status: 'success' | 'failed'

5 /** Included on failure. **/

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 /** Included on failure. **/

8 reason?: string

9}

10

This API endpoint provides the ability to block a user that wrote a given comment. It supports blocking from comments written by FastComments.com Users, SSO Users, and Tenant Users.

It supports a commentIdsToCheck body parameter to check if any other potentially visible comments on the client should be blocked/unblocked after this action is performed.

Notes:

• This call must always be made in the context of a user. The user can be a FastComments.com User, SSO User, or Tenant User.
• The userId in the request is the user that is doing the blocking. For example: User A wants to Block User B. Pass userId=User A and the comment id that User B wrote.
• Completely anonymous comments (no user id, no email) cannot be blocked and an error will be returned.

Comment Block cURL Example

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

For anonymous blocking, we must specify an anonUserId. This can be an ID that represents the anonymous session, or a random UUID. This allows us to support blocking comments even if a user is not logged in by fetching the comments with the same anonUserId.

Anonymous Comment Block cURL Example

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

Comment Block Request Structure

Copy

1

2interface CommentBlockQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7 commentIdsToCheck?: string[]

8}

9

Comment Block Response Structure

Copy

1

2

3interface CommentBlockResponse {

4 status: 'success' | 'failed'

5 /** Included on failure. **/

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 /** Included on failure. **/

8 reason?: string

9 /** If commentIdsToCheck is defined, entries in this map with true are also blocked. **/

10 commentStatuses?: Record<string, boolean>;

11}

12

This API endpoint provides the ability to un-block a user that wrote a given comment. It supports un-blocking from comments written by FastComments.com Users, SSO Users, and Tenant Users.

It supports a commentIdsToCheck body parameter to check if any other potentially visible comments on the client should be blocked/unblocked after this action is performed.

Notes:

• This call must always be made in the context of a user. The user can be a FastComments.com User, SSO User, or Tenant User.
• The userId in the request is the user that is doing the un-blocking. For example: User A wants to Un-Block User B. Pass userId=User A and the comment id that User B wrote.
• Completely anonymous comments (no user id, no email) cannot be blocked and an error will be returned.

Comment Un-Block cURL Example

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

Anonymous Comment Un-Block cURL Example

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

Comment Un-Block Request Structure

Copy

1

2interface CommentUnBlockQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7 commentIdsToCheck?: string[]

8}

9

Comment Un-Block Response Structure

Copy

1

2

3interface CommentUnBlockResponse {

4 status: 'success' | 'failed'

5 /** Included on failure. **/

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 /** Included on failure. **/

8 reason?: string

9 /** If commentIdsToCheck is defined, entries in this map with true are still blocked. If false, you might want to un-hide the comments from the user so they don't have to refresh. **/

10 commentStatuses?: Record<string, boolean>;

11}

12

Individual EmailTemplates can be fetched by their corresponding id (NOT emailTemplateId).

EmailTemplate by ID cURL Example

Copy

1

2curl --request GET \

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

4

EmailTemplate by ID Request Structure

Copy

1

2interface EmailTemplatesByIdRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

EmailTemplate by ID Response Structure

Copy

1

2interface EmailTemplateResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

6 /** Included on failure. **/

7 reason?: string

8 emailTemplate?: EmailTemplate | null

9}

10

This API uses pagination, provided by the page query parameter. EmailTemplates are returned in pages of 100, ordered by createdAt and then id.

EmailTemplate cURL Example

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 Request Structure

Copy

1

2interface EmailTemplatesRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** The page to fetch, starting with 0. **/

6 page: number

7}

8

EmailTemplate Response Structure

Copy

1

2interface EmailTemplatesResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

6 /** Included on failure. **/

7 reason?: string

8 emailTemplates: EmailTemplate[]

9}

10

This API endpoint provides the ability to update an email template by only specifying the id and the attributes to update.

Note that all the same validations for creating a template also apply, for example:

• The template must render. This is checked with each update.
• You can't have duplicate templates for the same domain (otherwise one would be silently ignored).

EmailTemplate PATCH cURL Example

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 Request Structure

Copy

1

2interface EmailTemplatePatchQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

EmailTemplate PATCH Response Structure

Copy

1

2

3interface EmailTemplatePatchResponse {

4 status: 'success' | 'failed'

5 /** Included on failure. **/

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 /** Included on failure. **/

8 reason?: string

9 /** The updated email template. **/

10 emailTemplate?: EmailTemplate

11}

12

This API endpoint provides the ability to create email templates.

Notes:

• You can't have multiple templates with the same emailTemplateId with the same domain.
• But you can have a wildcard template (domain = * and a domain specific template for the same emailTemplateId).
• Specifying domain is only relevant if you have different domains, or want to use specific templates for testing (domain set to localhost etc).
• If you do specify domain it must match a DomainConfig. On error a list of valid domains is provided.
• The template syntax is EJS and is rendered with a 500ms timeout. P99 for rendering is <5ms, so if you hit 500ms something is wrong.
• Your template must render with your given testData to save. Render errors are aggregated and reported on in the dashboard (soon available via API).

The minimum data required to add a template is as follows:

Minimum EmailTemplate POST cURL Example

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

You may want to have templates per-site, in which case you define domain:

EmailTemplate POST cURL Example

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 Request Structure

Copy

1

2interface EmailTemplatePostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

EmailTemplate POST Response Structure

Copy

1

2

3interface EmailTemplatePostResponse {

4 status: 'success' | 'failed'

5 /** Included on failure. **/

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 /** Included on failure. **/

8 reason?: string

9 /** The created template. **/

10 emailTemplate?: EmailTemplate

11}

12

This API endpoint provides the ability to preview email templates.

Minimum EmailTemplate Preview POST cURL Example

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 Request Structure

Copy

1

2interface EmailTemplatePostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

EmailTemplate POST Response Structure

Copy

1

2

3interface EmailTemplatePostResponse {

4 status: 'success' | 'failed'

5 /** Included on failure. **/

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

7 /** Included on failure. **/

8 reason?: string

9 /** The rendered HTML on success. **/

10 html?: string

11}

12

This route provides the removal of a single EmailTemplate by id.

EmailTemplate Removal cURL Example

Copy

1

2curl --request DELETE \

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

4

EmailTemplate Removal Request Structure

Copy

1

2interface EmailTemplateRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

EmailTemplate Removal Response Structure

Copy

1

2interface EmailTemplateDeleteResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

6 /** Included on failure. **/

7 reason?: string

8}

9

This API uses pagination, provided by the page query parameter. HashTags are returned in pages of 100, ordered by tag.

HashTag cURL Example

Copy

1

2curl --request GET \

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

4

HashTag Request Structure

Copy

1

2interface HashTagsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** The page to fetch, starting with 0. **/

6 page: number

7}

8

HashTag Response Structure

Copy

1

2interface HashTagsResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

6 /** Included on failure. **/

7 reason?: string

8 /** The hashtags! **/

9 hashTags: HashTag[]

10}

11

This route provides the ability to update a single HashTag.

HashTag Update cURL Example

Copy

1

2curl --request PATCH \

3 --url 'https://fastcomments.com/api/v1/hash-tags/%23example_hash_tag?tenantId=demo&API_KEY=DEMO_API_SECRET' \

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

5 --data '{

6 "url": "https://example.com/some-`page`"

7}'

8

HashTag Update Request Structure

Copy

1

2interface HashTagPatchQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

HashTag Update Response Structure

Copy

1

2interface HashTagPatchResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist' | 'url-too-long' | 'invalid-tag' | 'already-exists'

6 /** Included on failure. **/

7 reason?: string

8 hashTag?: HashTag; // We return the complete updated hashtag on success.

9}

10

This route provides the ability to add a single HashTag.

HashTag Create cURL Example

Copy

1

2curl --request POST \

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

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

5 --data '{

6 "tag": "#example",

7 "url": "https://example.com/some-page"

8}'

9

HashTag Create Request Structure

Copy

1

2interface HashTagPostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

HashTag Create Response Structure

Copy

1

2interface HashTagPostResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist' | 'url-too-long' | 'invalid-tag'

6 /** Included on failure. **/

7 reason?: string

8 hashTag?: HashTag; // We return the complete created hashtag on success.

9}

10

This route provides the ability to add up to 100 HashTag objects at once.

HashTag Bulk Create cURL Example

Copy

1

2curl --request PATCH \

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

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

5 --data '{

6 "tags": [

7 {

8 "tag": "#example",

9 "url": "https://example.com/some-page"

10 }

11 ]

12}'

13

HashTag Bulk Create Request Structure

Copy

1

2interface HashTagPostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

HashTag Bulk Create Response Structure

Copy

1

2interface HashTagBulkPostResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist' | 'url-too-long' | 'invalid-tag'

6 /** Included on failure. **/

7 reason?: string

8 results?: HashTagPostResponse[]; // We return a list of HashTagPostResponse objects for each provided tag.

9}

10

This route provides the removal of a HashTag user by the provided tag.

Note that unless automatic HashTag creation is disabled, hashtags can be re-created by a user providing the hashtag when commenting.

HashTag Removal cURL Example

Copy

1

2curl --request DELETE \

3 --url 'https://fastcomments.com/api/v1/hash-tags/%23example_hash_tag?tenantId=demo&API_KEY=DEMO_API_SECRET'

4

HashTag Removal Request Structure

Copy

1

2interface HashTagDeleteQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

HashTag Removal Response Structure

Copy

1

2interface HashTagDeleteResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist'

6 /** Included on failure. **/

7 reason?: string

8}

9

A Moderator object represents configuration for a moderator.

There are three types of moderators:

1. Administrator users that have the isCommentModeratorAdmin flag.
2. SSO Users with the isCommentModeratorAdmin flag.
3. Regular commenters, or FastComments.com users, that are invited as Moderators.

The Moderator structure is used to represent the Moderation State of use case 3.

If you want to invite a user to be a moderator, via the API, use the Moderator API by creating a Moderator and inviting them.

If the user does not have a FastComments.com account, the invite email will help them get setup. If they already have an account, they will be given moderation access to your tenant and the Moderator object's userId will be updated to point to their user. You will not have API access to their user, as in this case it belongs to themselves and managed by FastComments.com.

If you require complete management of the user's account, we recommend either using SSO, or adding them as a Tenant User and then adding a Moderator object to track their stats.

The Moderator structure can be used as a stat tracking mechanism for use cases 1 and 2. After creating the user, add a Moderator object with their userId defined and their stats will be tracked on the Comment Moderators Page.

The structure for the Moderator object is as follows:

Moderator Structure

Copy

1

2interface Moderator {

3 name: string

4 email: string

5 tenantId: string

6 userId?: string|null

7 acceptedInvite?: boolean

8 markReviewedCount?: number

9 deletedCount?: number

10 markedSpamCount?: number

11 approvedCount?: number

12 editedCount?: number

13 bannedCount?: number

14 createdAt: string

15 moderationGroupIds?: string[]|null

16}

17

This route returns a single moderator by their id.

Moderator By ID cURL Example

Copy

1

2curl --request GET \

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

4

Moderator Request Structure

Copy

1

2interface ModeratorByIdQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Moderator Response Structure

Copy

1

2interface ModeratorByIdResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

6 /** Included on failure. **/

7 reason?: string

8 moderator?: Moderator

9}

10

This API uses pagination, provided by the skip query parameter. Moderators are returned in pages of 100, ordered by createdAt and id.

The cost is based on the number of moderators returned, costing 1 credit per 10 moderators returned.

Moderator cURL Example

Copy

1

2curl --request GET \

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

4

Moderator Request Structure

Copy

1

2interface ModeratorsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** The number of moderators to skip for pagination. **/

6 skip?: number

7}

8

Moderator Response Structure

Copy

1

2interface ModeratorsResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

6 /** Included on failure. **/

7 reason?: string

8 moderators?: Moderator[]

9}

10

This API endpoint provides the ability to update a Moderator by id.

Updating a Moderator has the following restrictions:

• The following values may not be provided when updating a Moderator:
  • acceptedInvite
  • markReviewedCount
  • deletedCount
  • markedSpamCount
  • approvedCount
  • editedCount
  • bannedCount
  • verificationId
  • createdAt
• When a userId is specified, that user must exist.
• When a userId is specified, they must belong to the same tenantId specified in query params.
• Two moderators in the same tenant cannot be added with the same email.
• You may not change the tenantId associated with a Moderator.

Moderator PATCH cURL Example

Copy

1

2curl --request PATCH \

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

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

5 --data '{

6 "name": "Some New Name",

7}'

8

Moderator PATCH Request Structure

Copy

1

2interface ModeratorPatchQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Moderator PATCH Response Structure

Copy

1

2

3interface ModeratorPatchResponse {

4 status: 'success' | 'failed'

5 /** Included on failure. **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'name-required' | 'email-required' | 'unexpected-param' | 'not-found';

7 /** Included on failure. **/

8 reason?: string

9}

10

This route provides the ability to add a single Moderator.

Creating a Moderator has the following restrictions:

• A name and email must always be provided. A userId is optional.
• The following values may not be provided when creating a Moderator:
  • acceptedInvite
  • markReviewedCount
  • deletedCount
  • markedSpamCount
  • approvedCount
  • editedCount
  • bannedCount
  • verificationId
  • createdAt
• When a userId is specified, that user must exist.
• When a userId is specified, they must belong to the same tenantId specified in query params.
• Two moderators in the same tenant cannot be added with the same email.

We can create a Moderator for a user which we only know the email:

Moderator Create via Email cURL Example

Copy

1

2curl --request POST \

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

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

5 --data '{

6 "name": "Some Name",

7 "email": "someone@someone.com"

8}'

9

Or we can create a Moderator for a user which belongs to our tenant, to track their moderation stats:

Moderator Create via Tenant User cURL Example

Copy

1

2curl --request POST \

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

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

5 --data '{

6 "name": "Some Name",

7 "email": "someone@someone.com",

8 "userId": "some-tenant-user-id"

9}'

10

Moderator Create Request Structure

Copy

1

2interface ModeratorPostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Moderator Create Response Structure

Copy

1

2interface ModeratorPostResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'name-required' | 'email-required' | 'unexpected-param' | 'not-found'

6 /** Included on failure. **/

7 reason?: string

8 moderator?: Moderator; // We return the complete created moderator on success.

9}

10

This route provides the ability to invite a single Moderator.

The following restrictions exist to send an invite email to a Moderator:

• The Moderator must already exist.
• The fromName may not be longer than 100 characters.

Notes:

• If a user with the provided email already exists, they will be invited to moderate your tenant's comments.
• If a user with the provided email does not exist the invite link will guide them through creating their account.
• The invite will expire after 30 days.

We can create a Moderator for a user which we only know the email:

Moderator Invite cURL Example

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/moderators/xyz/send-invite?tenantId=demo&API_KEY=DEMO_API_SECRET&fromName=Bob' \

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

5

This will send an email like Bob at TenantName is inviting you to be a moderator...

Moderator Invite Request Structure

Copy

1

2interface ModeratorSendInviteQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** The email sent to the user will appear to be sent from this name. **/

6 fromName: string

7}

8

Moderator Invite Response Structure

Copy

1

2interface ModeratorSendInviteResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

6 /** Included on failure. **/

7 reason?: string

8}

9

This route provides the removal of a Moderator by id.

Moderator Removal cURL Example

Copy

1

2curl --request DELETE \

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

4

Moderator Removal Request Structure

Copy

1

2interface ModeratorDeleteQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Moderator Removal Response Structure

Copy

1

2interface ModeratorDeleteResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

6 /** Included on failure. **/

7 reason?: string

8}

9

This route returns a single NotificationCount by user id. With SSO, the user id is in the format <tenant id>:<user id>.

If there are no unread notifications, there won't be a NotificationCount - so you will get a 404.

This is different than notifications/count in that it is much faster, but does not allow filtering.

NotificationCount By ID cURL Example

Copy

1

2curl --request GET \

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

4# -> {"status":"success","data":{"count":1,"createdAt":"2023-03-06T18:45:01.726Z","expireAt":"2024-03-06T01:25:01.726Z","id":"example"}}

5

NotificationCount Request Structure

Copy

1

2interface NotificationCountGetQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

NotificationCount Response Structure

Copy

1

2interface NotificationCountGetResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

6 /** Included on failure. **/

7 reason?: string

8 data?: NotificationCount

9}

10

This route deletes a single NotificationCount by user id. With SSO, the user id is in the format <tenant id>:<user id>.

This will clear the user's unread notification count (the red bell in the comment widget will fade out and the count will go away).

DELETE NotificationCount cURL Example

Copy

1

2curl --request DELETE \

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

4# -> {"status":"success"}

5

NotificationCount Removal Request Structure

Copy

1

2interface NotificationCountDeleteQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

NotificationCount Removal Response Structure

Copy

1

2interface NotificationCountDeleteResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

6 /** Included on failure. **/

7 reason?: string

8}

9