FastComments Docs

The FastComments API

FastComments provides an API for interacting with many resources. Build integrations with our platform, or even build your own clients!

In this documentation, you will find all supported resources by the API documented with their request and response types.

For Enterprise customers, all API access is captured in the Audit Log.

Authentication

The API is authenticated by passing your api key as either an X-API-KEY header or API_KEY query parameter. You will also need your tenantId for making API calls. This can be retrieved from the same page as your api key.

Authentication Option One - Headers

Header: X-API-KEY
Header: X-TENANT-ID

Authentication Option Two - Query Parameters

Query Param: API_KEY
Query Param: tenantId

API Resources

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.

AuditLog Structure

An AuditLog is an object that represents an audited event for tenants that have access to this feature.

The structure for the AuditLog object is as follows:

AuditLog Structure

Copy

interface AuditLog {
    id: string;
    userId?: string;
    username?: string;
    resourceName: string;
    crudType: 'c' | 'r' | 'u' | 'd' | 'login';
    from: string;
    url?: string;
    ip?: string;
    when: string;
    description?: string;
    serverStartDate: string;
    objectDetails?: object;
}

The audit log is immutable. It also cannot be written to manually. FastComments.com may only decide when to write to the audit log. However, you may read from it via this API.

Events in the audit log expire after two years.

GET /api/v1/audit-logs

Resource: AuditLog as GET /api/v1/audit-logs Credit Cost: 10

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

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

AuditLog Request Structure

Copy

interface CommentsRequestQueryParams {
    tenantId: string
    API_KEY: string
    order?: 'ASC' | 'DESC'
    skip?: number
    before?: number
    after?: number
}

AuditLog Response Structure

Copy

interface CommentsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    /** The logs! **/
    auditLogs: AuditLog[]
}

Comment Structure

A Comment object represents a comment left by a user.

The relationship between parent and child comments is defined via parentId.

The structure for the Comment object is as follows:

Comment Structure

Copy

interface Comment {
    /** READONLY: Set to true if the spam engine determined the comment was spam. **/
    aiDeterminedSpam?: boolean
    /** Whether the comment is approved to show. Set to true when saving the comment, else it will be hidden. **/
    approved?: boolean
    /** The user's avatar. **/
    avatarSrc?: string
    /** The commenter's raw comment. **/
    comment: string
    /** READONLY: The commenter's comment parsed into HTML. **/
    commentHTML?: string
    /** The commenter's email. Required if anonymous commenting is off. **/
    commenterEmail?: string
    /** The commenter's link (for example, their blog). **/
    commenterLink?: string
    /** The commenter's name. Always required. If not available, set to something like "Anonymous". **/
    commenterName: string
    /** The date the comment was left, in UTC epoch. **/
    date: number
    /** The "display label" for the comment - for example "Admin", "Moderator", or something like "VIP User". **/
    displayLabel?: string
    /** The domain the comment was posted on. **/
    domain?: string
    /** READONLY: The number of times the comment was flagged. **/
    flagCount?: number
    /** READONLY: The #hashtags written in the comment that were successfully parsed. **/
    hashTags?: CommentHashTag[]
    /** READONLY: Does the comment contain images? **/
    hasImages?: boolean
    /** READONLY: Does the comment contain links? **/
    hasLinks?: boolean
    /** READONLY: The unique comment id. **/
    id: string
    /** READONLY: Did the current user block the user that wrote this comment? **/
    isBlocked?: boolean
    /** READONLY: Is the comment by an admin? Automatically set based on userId. **/
    isByAdmin?: boolean
    /** READONLY: Is the comment by a moderator? Automatically set based on userId. **/
    isByModerator?: boolean
    /** READONLY: Is the flagged by the currently logged-in user (contextUserId)? **/
    isFlagged?: boolean
    /** Is the comment pinned? **/
    isPinned?: boolean
    /** Is the comment spam? **/
    isSpam?: boolean
    /** READONLY: Is the comment voted down for the current user (contextUserId)? **/
    isVotedDown?: boolean
    /** READONLY: Is the comment voted up for the current user (contextUserId)? **/
    isVotedUp?: boolean
    /** The locale the comment is in. If not provided, will be derived from the language accept HTTP header. **/
    locale?: 'de_de' | 'en_us' | 'es_es' | 'fr_fr' | 'it_it' | 'ja_jp' | 'ko_kr' | 'pl_pl' | 'pt_br' | 'ru_ru' | 'tr_tr' | 'zh_cn' | 'zh_tw'
    /** READONLY: The @mentions written in the comment that were successfully parsed. **/
    mentions?: CommentUserMention[]
    /** Optional metadata associated with the comment. **/
    meta?: Record<string, string | number | boolean>
    /** The optional list of moderation group ids associated with this comment. **/
    moderationGroupIds?: string[]|null
    /** READONLY: The id of the vote object that corresponds to the vote from the current user (contextUserId) on this comment. **/
    myVoteId?: string
    /** Whether notifications were sent for this comment for commenters. To prevent notifications being sent on imports, set this to true. **/
    notificationSentForParent?: boolean
    /** Whether notifications were sent for this comment for tenant users. To prevent notifications being sent on imports, set this to true. **/
    notificationSentForParentTenant?: boolean
    /** The title of the page this comment was on. **/
    pageTitle?: string
    /** If we're replying to a comment, this is the ID that we are replying to. **/
    parentId?: string|null
    /** Whether the comment is marked reviewed. **/
    reviewed: boolean
    /** The tenant id where the comment belongs. **/
    tenantId: string
    /** The user that wrote the comment. Created automatically when saving a comment with a name/email. **/
    userId?: string|null
    /** The URL to the location that this comment is visible, like a blog post. **/
    url: string
    /** A "cleaned" version of the urlId you passed us. When saving, you specify this field, but when you fetch the comment back this will be "cleaned" and your original value moved to "urlIdRaw". **/
    urlId: string
    /** READONLY: The original urlId you passed us. **/
    urlIdRaw?: string
    /** Is the user and this comment verified? **/
    verified: boolean
    /** Number of votes up. **/
    votesUp?: number
    /** Number of votes down. **/
    votesDown?: number
    /** The "karma" of the comment (= votes up - votes down). **/
    votes?: number
}

Some of these fields are marked READONLY - these are returned by the API but cannot be set.

Comment Text Structure

Comments are written in a FastComments flavor of markdown, which is just markdown plus traditional bbcode style tags for images, like [img]path[/img].

Text is stored in two fields. The text the user entered is stored unmodified in the comment field. This is rendered and stored in the commentHTML field.

The allowed HTML tags are b, u, i, strike, pre, span, code, img, a, strong, ul, ol, li, and br.

It's recommended to render the HTML, since it is a very small subset of HTML, building a renderer is pretty straightforward. There are multiple libraries for React Native and Flutter, for instance, to help with this

You may choose to render the un-normalized value of the comment field. An example parser is here..

The example parser could also be adjusted to work with HTML, and transform the HTML tags into expected elements to render for your platform.

Tagging

When users are tagged in a comment, the information is stored in a list called mentions. Each object in that list has the following structure.

The Comment Mentions Object

Copy

Run

interface CommentUserMention {
    /** The user id. For SSO users, this will have your tenant id prefixed. **/
    id: string
    /** The final @mention tag text, including the @ symbol. **/
    tag: string
    /** The original @mention tag text, including the @ symbol. **/
    rawTag: string
    /** What type of user was tagged. user = FastComments.com account. sso = SSOUser. **/
    type: 'user'|'sso'
    /** If the user opts out of notifications, this will still be set to true. **/
    sent: boolean
}

HashTags

When hashtags are used and successfully parsed, the information is stored in a list called hashTags. Each object in that list has the following structure.

The Comment HashTag Object

Copy

Run

interface CommentHashTag {
    /** The hashtag id. **/
    id: string
    /** The final #hashtag tag text, including the # symbol. **/
    tag: string
    /** If the hashtag is associated with a custom URL, this will be defined. **/
    url?: string
}

GET /api/v1/comments

Resource: Comment as GET /api/v1/comments Credit Cost: 1

Pagination

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

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.
Most Flexible: Flexible Pagination:
1. In this way you can define custom limit and skip parameters.
2. Sort direction is also supported.
3. limit is the total number to return after skip is applied.
  1. Example: set skip = 200, limit = 100 when page size = 100 and page = 2.

Threads

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

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.
1. In this case, define a contextUserId query parameter.
For fetching comments from your backend for custom integrations.
1. The platform will default to this without contextUserId.

Comments Precalculated Pagination cURL Example

Copy

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

Comments Flexible Pagination cURL Example

Copy

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

Comments Flexible Pagination in User Context cURL Example

Copy

curl --request GET \
  --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'

Comments Flexible Pagination in User Context for Top Level Comments Only cURL Example

Copy

curl --request GET \
  --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'

Comments Request Structure

Copy

interface CommentsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The urlId (page url, or article id) the comments are associated with. **/
    urlId: string
    /** The sort direction. Default is MR (Most Relevant). Other options are OF (Oldest First) and NF (Newest First). **/
    direction?: 'MR' | 'OF' | 'NF'
    /** Precalculated Pagination: The page to fetch, starting with 0. Pass -1 for all comments. **/
    page?: number
    /** Flexible Pagination: How many comments should we return? **/
    limit?: number
    /** Flexible Pagination: How many comments should we skip? **/
    skip?: number
    /** For determining blocked and flagged comments. **/
    contextUserId?: string
    /** For fetching child comments. **/
    parentId?: string
}

Comments Response Structure

Copy

interface CommentsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'missing-date' | 'unauthorized-page'
    /** Included on failure. **/
    reason?: string
    /** The comments! **/
    comments: Comment[]
}

Helpful Tip

The Comment API requires a urlId. You can call the Pages API first, to see what the urlId values available to you look like.

GET /api/v1/comments/:id

Resource: Comment as GET /api/v1/comments/:id Credit Cost: 1

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

Comments Get-By-Id cURL Example

Copy

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

Comment Get-By-Id Request Structure

Copy

interface CommentsGetByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Comments Get-By-Id Response Structure

Copy

interface CommentGetByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'missing-id'
    /** Included on failure. **/
    reason?: string
    /** The comment! **/
    comment?: Comment
}

POST /api/v1/comments

Resource: Comment as POST /api/v1/comments Credit Cost: 1

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 is a comment, that will show in the comment widget, is as follows:

Minimum Comment POST cURL Example

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true' \
  --header 'Content-Type: application/json' \
  --data '{
    "approved": true,
    "comment": "some-comment",
    "commenterName": "some-commenter-name",
    "date": 1622644382148,
    "urlId": "some-place",
    "url": "https://exmaple.com/some-page",
    "verified": true
}'

A more realistic request may look like:

Comment POST cURL Example

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true&doSpamCheck=true' \
  --header 'Content-Type: application/json' \
  --data '{
    "approved": true,
    "avatarSrc": "https://static.fastcomments.com/1605337537848-DSC_0841.JPG",
    "comment": "some-comment",
    "commenterName": "some-commenter-name",
    "commenterEmail": "fordperfect@spaceship.com",
    "date": 1622644382148,
    "isSpam": false,
    "locale": "en_us",
    "notificationSentForParent": true,
    "notificationSentForParentTenant": true,
    "reviewed": true,
    "urlId": "some-place",
    "url": "https://exmaple.com/some-page",
    "verified": true,
    "votes": 1,
    "votesUp": 2,
    "votesDown": 1
}'

Comment POST Request Structure

Copy

interface CommentPostQueryParams {
    tenantId: string
    API_KEY: string
    doSpamCheck?: 'true' | 'false'
    /** 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. **/
    isLive?: 'true' | 'false'
    sendEmails?: 'true' | 'false'
    populateNotifications?: 'true' | 'false'
}

Comment POST Response Structure

Copy

interface CommentPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    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';
    /** Included on failure. **/
    reason?: string
    /** The created comment. **/
    comment?: Comment
    /** The associated user, which may or may not have already existed. **/
    user?: User
}

PATCH /api/v1/comments/:id

Resource: Comment as PATCH /api/v1/comments/:id Credit Cost: 1

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

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true' \
  --header 'Content-Type: application/json' \
  --data '{
    "comment": "some-new-comment-text"
}'

Comment PATCH Request Structure

Copy

interface CommentPatchQueryParams {
    tenantId: string
    API_KEY: string
    doSpamCheck?: 'true' | 'false'
    /** 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. **/
    isLive?: 'true' | 'false'
}

Comment PATCH Response Structure

Copy

interface CommentPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    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'
    /** Included on failure. **/
    reason?: string
}

DELETE /api/v1/comments/:id

Resource: Comment as DELETE /api/v1/comments/:id Credit Cost: 1

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

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json'

Comment DELETE Request Structure

Copy

interface CommentDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** 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. **/
    isLive?: 'true' | 'false'
}

Comment DELETE Response Structure

Copy

interface CommentDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
}

POST /api/v1/comments/:id/flag

Resource: Comment as POST /api/v1/comments/:id/flag Credit Cost: 1

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

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/flag?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \
  --header 'Content-Type: application/json'

Comment Flag Request Structure

Copy

interface CommentFlagQueryParams {
    tenantId: string
    API_KEY: string
    userId: string
}

Comment Flag Response Structure

Copy

interface CommentFlagResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id'
    /** Included on failure. **/
    reason?: string
    /** Was the comment un-approved (hidden) due to being flagged too many times? **/
    wasUnapproved?: boolean;
}

POST /api/v1/comments/:id/un-flag

Resource: Comment as POST /api/v1/comments/:id/un-flag Credit Cost: 1

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

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-flag?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \
  --header 'Content-Type: application/json'

Comment Un-Flag Request Structure

Copy

interface CommentFlagQueryParams {
    tenantId: string
    API_KEY: string
    userId: string
}

Comment Un-Flag Response Structure

Copy

interface CommentUnFlagResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id'
    /** Included on failure. **/
    reason?: string
}

POST /api/v1/comments/:id/block

Resource: Comment as POST /api/v1/comments/:id/block Credit Cost: 1

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

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/block?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \
  --header 'Content-Type: application/json'

Comment Block Request Structure

Copy

interface CommentBlockQueryParams {
    tenantId: string
    API_KEY: string
    userId: string
    commentIdsToCheck?: string[]
}

Comment Block Response Structure

Copy

interface CommentBlockResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'comment-cannot-be-blocked'
    /** Included on failure. **/
    reason?: string
    /** If commentIdsToCheck is defined, entries in this map with true are also blocked. **/
    commentStatuses?: Record<string, boolean>;
}

POST /api/v1/comments/:id/un-block

Resource: Comment as POST /api/v1/comments/:id/un-block Credit Cost: 1

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

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-block?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \
  --header 'Content-Type: application/json'

Comment Un-Block Request Structure

Copy

interface CommentUnBlockQueryParams {
    tenantId: string
    API_KEY: string
    userId: string
    commentIdsToCheck?: string[]
}

Comment Un-Block Response Structure

Copy

interface CommentUnBlockResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'comment-cannot-be-blocked'
    /** Included on failure. **/
    reason?: string
    /** 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. **/
    commentStatuses?: Record<string, boolean>;
}

HashTag Structure

A HashTag object represents a tag that can be left by a user. HashTags can be used to link to an external piece of content or to tie related comments together.

The structure for the HashTag object is as follows:

HashTag Structure

Copy

interface HashTag {
    /** Should start with the "#" or desired character. **/
    tag: string
    /** An optional URL that the hashtag can point to. Instead of filtering comments by hashtag, the UI will redirect to this upon click. **/
    url?: string
    /** READONLY **/
    createdAt: string
}

Notes:

In some API endpoints you will see that the hashtag is used in the URL. Remember to URI-Encoded values. For example, # should instead be represented as %23.
Some of these fields are marked READONLY - these are returned by the API but cannot be set.

GET /api/v1/hash-tags

Resource: HashTag as GET /api/v1/hash-tags Credit Cost: 1

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

HashTag cURL Example

Copy

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

HashTag Request Structure

Copy

interface HashTagsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The page to fetch, starting with 0. **/
    page: number
}

HashTag Response Structure

Copy

interface HashTagsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    /** The hashtags! **/
    hashTags: HashTag[]
}

PATCH /api/v1/hash-tags/:tag

Resource: HashTag as PATCH /api/v1/hash-tags/:tag Credit Cost: 1

This route provides the ability to update a single HashTag.

HashTag Update cURL Example

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/hash-tags/%23example_hash_tag?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com/some-`page`"
}'

HashTag Update Request Structure

Copy

interface HashTagPatchQueryParams {
    tenantId: string
    API_KEY: string
}

HashTag Update Response Structure

Copy

interface HashTagPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    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'
    /** Included on failure. **/
    reason?: string
    hashTag?: HashTag; // We return the complete updated hashtag on success.
}

POST /api/v1/hash-tags

Resource: HashTag as POST /api/v1/hash-tags Credit Cost: 1

This route provides the ability to add a single HashTag.

HashTag Create cURL Example

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/hash-tags?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "tag": "#example",
    "url": "https://example.com/some-page"
}'

HashTag Create Request Structure

Copy

interface HashTagPostQueryParams {
    tenantId: string
    API_KEY: string
}

HashTag Create Response Structure

Copy

interface HashTagPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    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'
    /** Included on failure. **/
    reason?: string
    hashTag?: HashTag; // We return the complete created hashtag on success.
}

POST /api/v1/hash-tags/bulk

Resource: HashTag as POST /api/v1/hash-tags/bulk Credit Cost: 1

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

HashTag Bulk Create cURL Example

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/hash-tags/bulk?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "tags": [
        {
            "tag": "#example",
            "url": "https://example.com/some-page"
        }
    ]
}'

HashTag Bulk Create Request Structure

Copy

interface HashTagPostQueryParams {
    tenantId: string
    API_KEY: string
}

HashTag Bulk Create Response Structure

Copy

interface HashTagBulkPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    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'
    /** Included on failure. **/
    reason?: string
    results?: HashTagPostResponse[]; // We return a list of HashTagPostResponse objects for each provided tag.
}

DELETE /api/v1/hash-tags/:tag

Resource: HashTag as DELETE /api/v1/hash-tags/:tag Credit Cost: 1

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

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

HashTag Removal Request Structure

Copy

interface HashTagDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

HashTag Removal Response Structure

Copy

interface HashTagDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist'
    /** Included on failure. **/
    reason?: string
}

Moderator Structure

A Moderator object represents configuration for a moderator.

There are three types of moderators:

Administrator users that have the isCommentModeratorAdmin flag.
SSO Users with the isCommentModeratorAdmin flag.
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

interface Moderator {
    name: string
    email: string
    tenantId: string
    userId?: string|null
    acceptedInvite?: boolean
    markReviewedCount?: number
    deletedCount?: number
    markedSpamCount?: number
    approvedCount?: number
    editedCount?: number
    bannedCount?: number
    createdAt: string
    moderationGroupIds?: string[]|null
}

GET /api/v1/moderators/:id

Resource: Moderator as GET /api/v1/moderators/:id Credit Cost: 1

This route returns a single moderator by their id.

Moderator By ID cURL Example

Copy

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

Moderator Request Structure

Copy

interface ModeratorByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Moderator Response Structure

Copy

interface ModeratorByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
    moderator?: Moderator
}

GET /api/v1/moderators

Resource: Moderator as GET /api/v1/moderators Credit Cost: 1

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

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

Moderator Request Structure

Copy

interface ModeratorsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The number of moderators to skip for pagination. **/
    skip?: number
}

Moderator Response Structure

Copy

interface ModeratorsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    moderators?: Moderator[]
}

PATCH /api/v1/moderators/:id

Resource: Moderator as PATCH /api/v1/moderators/:id Credit Cost: 1

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

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/moderators/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some New Name",
}'

Moderator PATCH Request Structure

Copy

interface ModeratorPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Moderator PATCH Response Structure

Copy

interface ModeratorPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'name-required' | 'email-required' | 'unexpected-param' | 'not-found';  
    /** Included on failure. **/
    reason?: string
}

POST /api/v1/moderators

Resource: Moderator as POST /api/v1/moderators Credit Cost: 1

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

curl --request POST \
  --url 'https://fastcomments.com/api/v1/moderators?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some Name",
    "email": "someone@someone.com"
}'

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

curl --request POST \
  --url 'https://fastcomments.com/api/v1/moderators?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some Name",
    "email": "someone@someone.com",
    "userId": "some-tenant-user-id"
}'

Moderator Create Request Structure

Copy

interface ModeratorPostQueryParams {
    tenantId: string
    API_KEY: string
}

Moderator Create Response Structure

Copy

interface ModeratorPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'name-required' | 'email-required' | 'unexpected-param' | 'not-found'
    /** Included on failure. **/
    reason?: string
    moderator?: Moderator; // We return the complete created moderator on success.
}

POST /api/v1/moderators/:id/send-invite

Resource: Moderator as POST /api/v1/moderators/:id/send-invite Credit Cost: 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

curl --request POST \
  --url 'https://fastcomments.com/api/v1/moderators/xyz/send-invite?tenantId=demo&API_KEY=DEMO_API_SECRET&fromName=Bob' \
  --header 'Content-Type: application/json'

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

Moderator Invite Request Structure

Copy

interface ModeratorSendInviteQueryParams {
    tenantId: string
    API_KEY: string
    /** The email sent to the user will appear to be sent from this name. **/
    fromName: string
}

Moderator Invite Response Structure

Copy

interface ModeratorSendInviteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'not-found | 'from-name-required' | 'from-name-invalid'
    /** Included on failure. **/
    reason?: string
}

DELETE /api/v1/moderators/:id

Resource: Moderator as DELETE /api/v1/moderators/:id Credit Cost: 5

This route provides the removal of a Moderator by id.

Moderator Removal cURL Example

Copy

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

Moderator Removal Request Structure

Copy

interface ModeratorDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Moderator Removal Response Structure

Copy

interface ModeratorDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found'
    /** Included on failure. **/
    reason?: string
}

Page Structure

A Page object represents the page that many comments may belong to. This relationship is defined by urlId.

A Page stores information such as the page title, comment count, and urlId.

The structure for the Page object is as follows:

Page Structure

Copy

interface Page {
    id: string
    urlId: string
    url: string
    title?: string
    createdAt: string
    commentCount: number
    rootCommentCount: number
    /** Setting this to null means all SSO users can see the page. An empty list means it is closed to all users. **/
    accessibleByGroupIds?: string[] | null
}

GET /api/v1/pages

Resource: Page as GET /api/v1/pages Credit Cost: 10

You can currently only fetch all pages (or a single page via /by-url-id) associated with your account. If you'd like more fine-grained searching, reach out to us.

Pages cURL Example

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/pages?tenantId=demo&API_KEY=DEMO_API_SECRET'

Pages Request Structure

Copy

interface PagesRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Pages Response Structure

Copy

interface PagesResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    pages: Page[]
}

Helpful Tip

The Comment API requires a urlId. You can call the Pages API first, to see what the urlId values available to you look like.

GET /api/v1/pages/by-url-id

Resource: Page as GET /api/v1/pages/by-url-id Credit Cost: 1

Individual pages can be fetched by their corresponding urlId. This can be useful for looking up page titles or comment counts.

Page by URL ID cURL Example

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/pages/by-url-id?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=example-id-or-url'

Page By URL ID Request Structure

Copy

interface PagesRequestQueryParams {
    tenantId: string
    API_KEY: string
    urlId: string
}

Page by URL ID Response Structure

Copy

interface PagesResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id'
    /** Included on failure. **/
    reason?: string
    page?: Page[] | null
}

Helpful Tip

Remember to URI Encode values like the urlId.

PATCH /api/v1/pages/:id

Resource: Page as PATCH /api/v1/pages/:id Credit Cost: 1

This route provides the ability to update a single Page.

Page Update cURL Example

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/pages/my-page-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com/some-page"
}'

Page Update Request Structure

Copy

interface PagePatchQueryParams {
    tenantId: string
    API_KEY: string
}

Page Update Response Structure

Copy

interface PagePatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'missing-id' | 'page-does-not-exist' | 'empty-request' | 'internal' | 'invalid-input' | 'invalid-title' | 'extra-params' | 'accessible-by-group-ids-not-array' | 'too-many-group-ids' | 'group-id-too-large'
    /** Included on failure. **/
    reason?: string
    user?: Page; // We return the complete updated page on success.
}

Note

Some parameters in the Page object get automatically updated. These are the counts and title attributes. Counts cannot be updated via the API since they are calculated values. The page title can be set via the API, but would get overwritten if the comment widget is used on a page with the same urlId and a different page title.

POST /api/v1/pages

Resource: Page as POST /api/v1/pages Credit Cost: 1

This API endpoint provides the ability to create pages.

A common use cases is access control.

Notes:

If you've commented on a comment thread, or called the API to create a Comment, you've already created a Page object! You can try fetching it via the /by-url-id Page route, passing in the same urlId passed to the comment widget.
The Page structure contains some calculated values. Currently, these are commentCount and rootCommentCount. They are populated automatically and cannot be set by the API. Attempting to do so will cause the API to return an error.

Page POST cURL Example

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/pages?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Test Page",
    "url": "some0-url",
    "urlId": "page2",
    "accessibleByGroupIds": ["SOME_GROUP_ID"]
}'

Page POST Request Structure

Copy

interface PagePostQueryParams {
    tenantId: string
    API_KEY: string
}

Page POST Response Structure

Copy

interface PagePostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-request' | 'internal' | 'invalid-input' | 'invalid-title' | 'extra-params' | 'accessible-by-group-ids-not-array' | 'too-many-group-ids' | 'group-id-too-large';  
    /** Included on failure. **/
    reason?: string
    /** The created page. **/
    page?: Page
}

DELETE /api/v1/pages/:id

Resource: Page as DELETE /api/v1/pages/:id Credit Cost: 1

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

Note that interacting with the comment widget for a page with the same urlId will simply recreate the Page seamlessly.

Page Removal cURL Example

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/pages/some-page-id?tenantId=demo&API_KEY=DEMO_API_SECRET'

Page Removal Request Structure

Copy

interface PageDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Page Removal Response Structure

Copy

interface PageDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'page-does-not-exist'
    /** Included on failure. **/
    reason?: string
}

SSOUser Structure

FastComments provides an easy to use SSO solution. Updating a user's information with the HMAC-based integration is as simple as having the user load the page with an updated payload.

However, it may be desirable to manage a user outside that flow, to improve consistency of your application.

The SSO User API provides a way to CRUD objects that we call SSOUsers. These objects are different from regular Users and kept separate for type safety.

The structure for the SSOUser object is as follows:

SSOUser Structure

Copy

interface SSOUser {
    id: string
    username: string
    email?: string
    websiteUrl?: string
    signUpDate: number
    createdFromUrlId?: string
    loginCount?: number
    avatarSrc?: string
    optedInNotifications?: boolean
    displayLabel?: string
    displayName?: string
    isAccountOwner?: boolean
    isAdminAdmin?: boolean
    isCommentModeratorAdmin?: boolean
    /** If null, Access Control will not be applied to the user. If an empty list, this user will not be able to see any pages or @mention other users. **/
    groupIds?: string[] | null
    createdFromSimpleSSO?: boolean
    /** Don't let other users see this user's activity, including comments, on their profile. Default is true to provide secure profiles by default. **/
    isProfileActivityPrivate?: boolean
}

Access Control

Users can be broken into groups. This is what the groupIds field is for, and is optional.

@Mentions

By default @mentions will use username to search for other sso users when the @ character is typed. If displayName is used, then results matching username will be ignored when there is a match for displayName, and the @mention search results will use displayName.

GET /api/v1/sso-users

Resource: SSOUser as GET /api/v1/sso-users Credit Cost: 10

This route returns SSO Users in pages of 100. Pagination is provided by the skip parameter. Users are sorted by their signUpDate and id.

SSOUsers cURL Example

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/sso-users?tenantId=demo&API_KEY=DEMO_API_SECRET'

SSOUsers Request Structure

Copy

interface SSOUsersRequestQueryParams {
    tenantId: string
    API_KEY: string
    skip?: number
}

SSOUsers Response Structure

Copy

interface SSOUsersResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    users: SSOUser[]
}

GET /api/v1/sso-users/by-id/:id

Resource: SSOUser as GET /api/v1/sso-users/by-id/:id Credit Cost: 1

This route returns a single SSO user by their id.

SSOUser By ID cURL Example

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/sso-users/by-id/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

SSOUser Request Structure

Copy

interface SSOUserRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
}

SSOUser Response Structure

Copy

interface SSOUserByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'user-does-not-exist'
    /** Included on failure. **/
    reason?: string
    user: SSOUser
}

GET /api/v1/sso-users/by-email/:email

Resource: SSOUser as GET /api/v1/sso-users/by-email/:email Credit Cost: 1

This route returns a single SSO user by their email.

SSOUser By Email cURL Example

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/sso-users/by-email/someone@somewhere.com?tenantId=demo&API_KEY=DEMO_API_SECRET'

SSOUser Request Structure

Copy

interface SSOUserRequestByEmailQueryParams {
    tenantId: string
    API_KEY: string
}

SSOUser Response Structure

Copy

interface SSOUserByEmailResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-email' | 'user-does-not-exist'
    /** Included on failure. **/
    reason?: string
    user: SSOUser
}

PATCH /api/v1/sso-users/:id

Resource: SSOUser as PATCH /api/v1/sso-users/:id Credit Cost: 1

This route provides the ability to update a single SSO user.

SSOUser Update cURL Example

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/sso-users/my-user-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "notfordperfect"
}'

SSOUser Update Request Structure

Copy

interface SSOUserPatchQueryParams {
    tenantId: string
    API_KEY: string
    /** When email or username is changed, you can set this to true to also update the user's comments. This will double the credit cost. **/
    updateComments: 'true' | 'false'
}

SSOUser Update Response Structure

Copy

interface SSOUserPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-does-not-exist'
    /** Included on failure. **/
    reason?: string
    user?: SSOUser; // We return the complete updated user on success.
}

POST /api/v1/sso-users

Resource: SSOUser as POST /api/v1/sso-users Credit Cost: 1

This route provides the creation of a single SSO user.

Trying to create two users with the same ID will result in an error.

SSOUser Creation cURL Example

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/sso-users?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "my-user-id",
    "username": "fordperfect",
    "displayName": "Ford Perfect",
    "email": "fordperfect@galaxy.com",
    "groupIds": ["some-optional-group-id"]
}'

In this example we specify groupIds for access control, but this is optional.

SSOUser Creation Request Structure

Copy

interface SSOUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

SSOUser Creation Response Structure

Copy

interface SSOUserPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-exists'
    /** Included on failure. **/
    reason?: string
    user?: SSOUser; // We return the created user on success.
}

Integration Note

Data passed by the API can be overridden simply by passing a different SSO User HMAC payload. For example, if you set a username via the API, but then pass a different one via the SSO flow on page load, we will automatically update their username.

We will not update user parameters in this flow unless you explicitly specify them or set them to null (not undefined).

PUT /api/v1/sso-users/:id

Resource: SSOUser as PUT /api/v1/sso-users Credit Cost: 1

This route provides the ability to update a single SSO user.

SSOUser Update cURL Example

Copy

curl --request PUT \
  --url 'https://fastcomments.com/api/v1/sso-users/my-user-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "fordperfect",
    "displayName": "Ford Perfect",
    "email": "fordperfect@galaxy.com",
    "groupIds": ["some-optional-group-id"]
}'

In this example we specify groupIds for access control, but this is optional.

SSOUser Update Request Structure

Copy

interface SSOUserPutQueryParams {
    tenantId: string
    API_KEY: string
    /** When email or username is changed, you can set this to true to also update the user's comments. This will double the credit cost. **/
    updateComments: 'true' | 'false'
}

SSOUser Update Response Structure

Copy

interface SSOUserPutResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-exists'
    /** Included on failure. **/
    reason?: string
    user?: SSOUser; // We return the update user on success.
}

DELETE /api/v1/sso-users/:id

Resource: SSOUser as DELETE /api/v1/sso-users/:id Credit Cost: 1

This route provides the removal of a single SSO user by their id.

Note that loading the comment widget again with a payload for this user will simply recreate the user seamlessly.

Deleting the user's comments is possible via the deleteComments query parameter. Note that if this is true:

All the user's comments will be deleted live.
All child (now orphan) comments will also be deleted.
The creditsCost becomes 2.

SSOUser Removal cURL Example

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/sso-users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

SSOUser Removal Request Structure

Copy

interface SSOUsersDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** You can set this to true to also delete the user's comments. This will double the credit cost. **/
    deleteComments: 'true' | 'false'
}

SSOUser Removal Response Structure

Copy

interface SSOUsersResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'user-does-not-exist'
    /** Included on failure. **/
    reason?: string
    user?: SSOUser; // We return the removed user on success.
}

TenantDailyUsage Structure

A TenantDailyUsage object represents the usage for a tenant on a given day. If there was no activity for a given tenant on a given day, that day will not have a TenantDailyUsage object.

The TenantDailyUsage object is not real time and may be minutes behind actual usage.

The structure for the TenantDailyUsage object is as follows:

TenantDailyUsage Structure

Copy

export interface TenantDailyUsage {
    yearNumber: number
    monthNumber: number
    dayNumber: number
    commentFetchCount?: number
    commentCreateCount?: number
    conversationCreateCount?: number
    voteCount?: number
    accountCreatedCount?: number
    userMentionSearch?: number
    hashTagSearch?: number
    gifSearchTrending?: number
    gifSearch?: number
    apiCreditsUsed?: number
    createdAt: string
    billed: boolean
    /** Ignored for billing. **/
    ignored: boolean
}

GET /api/v1/tenant-daily-usage

Resource: TenantDailyUsage as GET /api/v1/tenant-daily-usage Credit Cost: 1

This route allows searching for the usage of a tenant by year, month, and day. Up to 365 objects can be returned, and the cost is 1 api credit per 10 objects.

Response objects are sorted by the date they are created (the oldest first).

TenantDailyUsage Search cURL Example

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenant-daily-usage?tenantId=demo&API_KEY=DEMO_API_SECRET&yearNumber=2022&monthNumber=2&dayNumber=10'

TenantDailyUsage Request Structure

Copy

interface TenantDailyUsageQueryParams {
    tenantId: string
    API_KEY: string
    /** Based on UTC. **/
    yearNumber?: number
    /** Zero-based. Based on UTC. **/
    monthNumber?: number
    /** One-based. Based on UTC. **/
    dayNumber?: number
}

TenantDailyUsage Response Structure

Copy

interface TenantDailyUsageResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
    tenantDailyUsages: TenantDailyUsage[]
}

Tenant Structure

The Tenant defines a FastComments.com customer. They can be created via the API by tenants with white labeling access. White labeled tenants cannot create other white labeled tenants (only one level of nesting is allowed).

The structure for the Tenant object is as follows:

Tenant Structure

Copy

export enum SiteType {
    Unknown = 0,
    WordPress = 1
}
/** This can also be handled via the DomainConfig API. **/
export interface TenantDomainConfig {
    domain: string
    emailFromName?: string
    emailFromEmail?: string
    createdAt?: string,
    siteType?: FastCommentsSiteType, // you probably want Unknown
    logoSrc?: string, // raw image path
    logoSrc100px?: string, // resized for thumbnails
    footerUnsubscribeURL?: string,
    emailHeaders?: Record<string, string>,
    disableUnsubscribeLinks?: boolean,
    dkim?: {
        domainName: string,
        keySelector: string,
        privateKey: string
    }
}
export interface TenantBillingInfo {
    name: string
    address: string
    city: string
    state: string
    zip: string
    country: string
}
export enum TenantPaymentFrequency {
    Monthly = 0,
    Annually = 1
}
export interface Tenant {
    id: string
    name: string
    email: string
    signUpDate: number; // number due to "legacy" reasons
    packageId?: string | null
    paymentFrequency?: TenantPaymentFrequency
    billingInfoValid?: boolean
    billingHandledExternally?: boolean
    createdBy?: string
    isSetup?: boolean
    domainConfiguration: FastCommentsAPITenantDomainConfig[]
    billingInfo?: FastCommentsAPITenantBillingInfo
    stripeCustomerId?: string
    stripeSubscriptionId?: string
    stripePlanId?: string
    enableProfanityFilter?: boolean
    enableSpamFilter?: boolean
    lastBillingIssueReminderDate?: string
    removeUnverifiedComments?: boolean
    unverifiedCommentsTTLms?: number
    commentsRequireApproval?: boolean
    autoApproveCommentOnVerification?: boolean
    sendProfaneToSpam?: boolean
    /** @readonly - Is calculated based on packageId. **/
    hasFlexPricing?: boolean
    /** @readonly **/
    flexLastBilledAmount?: number
    /** @readonly - Is calculated based on packageId. **/
    hasAuditing?: boolean
}

GET /api/v1/tenants/:id

Resource: Tenant as GET /api/v1/tenants/:id Credit Cost: 1

This route returns a single Tenant by id.

Tenant By ID cURL Example

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenants/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

Tenant Request Structure

Copy

interface TenantByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Tenant Response Structure

Copy

interface TenantByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'unauthorized'
    /** Included on failure. **/
    reason?: string
    tenant?: Tenant
}

GET /api/v1/tenants

Resource: Tenant as GET /api/v1/tenants Credit Cost: 1

This API returns tenants that are managed by your tenant.

Pagination is provided by the skip query parameter. Tenants are returned in pages of 100, ordered by signUpDate, and id.

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

Tenant cURL Example

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenants?tenantId=demo&skip=0&API_KEY=DEMO_API_SECRET'

Tenant Request Structure

Copy

interface TenantsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The number of tenants to skip for pagination. **/
    skip?: number
}

Tenant Response Structure

Copy

interface TenantsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    tenants?: Tenant[]
}

POST /api/v1/tenants

Resource: Tenant as POST /api/v1/tenants Credit Cost: 1

This route provides the ability to add a single Tenant.

Creating a Tenant has the following restrictions:

A name is required.
A email is required.
domainConfiguration is required.
The following values may not be provided when creating a Tenant:
- hasFlexPricing
- lastBillingIssueReminderDate
- flexLastBilledAmount
The signUpDate may not be in the future.
The name may not be longer than 200 characters.
The email may not be longer than 300 characters.
The email must be unique across all of FastComments.com tenants.
You may not create tenants if the parent tenant does not have a valid TenantPackage defined.
- If your tenant was created via FastComments.com, this shouldn't be an issue.
You may not create more tenants than defined under maxWhiteLabeledTenants in your package.
You must specify the tenantId query param which is the id of your parent tenant with white labeling enabled.

We can create a Tenant with only a few parameters:

Tenant Create cURL Example

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/tenants?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some Name",
    "email": "someone@someone.com",
    "domainConfiguration": [ { "domain": "somedomain.com" } ]
}'

Tenant Create Request Structure

Copy

interface TenantPostQueryParams {
    tenantId: string
    API_KEY: string
}

Tenant Create Response Structure

Copy

interface TenantPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' | 'unexpected-param' | 'sign-up-date-in-future' | 'payment-frequency-invalid' | 'cannot-change-payment-frequency' | 'name-invalid' | 'email-invalid' | 'email-taken' | 'no-package' | 'invalid-package' | 'unauthorized' | 'tenant-limit-reached' | 'cannot-move-tenant' | 'cannot-change-package' | 'invalid-billing-info'
    /** Included on failure. **/
    reason?: string
    tenant?: Tenant; // We return the complete created tenant on success.
}

PATCH /api/v1/tenants/:id

Resource: Tenant as PATCH /api/v1/tenants/:id Credit Cost: 1

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

Updating a Tenant has the following restrictions:

The following values may not be updated:
- hasFlexPricing
- lastBillingIssueReminderDate
- flexLastBilledAmount
- managedByTenantId
The signUpDate may not be in the future.
The name may not be longer than 200 characters.
The email may not be longer than 300 characters.
The email must be unique across all of FastComments.com tenants.
When setting billingInfoValid to true, billingInfo must be provided in the same request.
You may not update the packageId associated with your own tenant.
You may not update the paymentFrequency associated with your own tenant.

Tenant PATCH cURL Example

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/tenants/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some New Name",
}'

Tenant PATCH Request Structure

Copy

interface TenantPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Tenant PATCH Response Structure

Copy

interface TenantPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' | 'unexpected-param' | 'sign-up-date-in-future' | 'payment-frequency-invalid' | 'cannot-change-payment-frequency' | 'name-invalid' | 'email-invalid' | 'email-taken' | 'no-package' | 'invalid-package' | 'unauthorized' | 'tenant-limit-reached' | 'cannot-move-tenant' | 'cannot-change-package' | 'invalid-billing-info'; 
    /** Included on failure. **/
    reason?: string
}

DELETE /api/v1/tenants/:id

Resource: Tenant as DELETE /api/v1/tenants/:id Credit Cost: 1,000

This route provides the removal of a Tenant and all associated data (users, comments, etc) by id.

The following restrictions exist around removing tenants:

The tenant must be your own, or a white labeled tenant that you manage.
The sure query parameter must be set to true.

Tenant Removal cURL Example

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/tenants/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

Tenant Removal Request Structure

Copy

interface TenantDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Tenant Removal Response Structure

Copy

interface TenantDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized' | 'unsure'
    /** Included on failure. **/
    reason?: string
}

Tenant Package Structure

The TenantPackage defines package information available to a Tenant. A tenant may have many packages available, but only one in use at a given time.

A Tenant cannot be used for any products until its packageId points to a valid TenantPackage.

There are two types of TenantPackage objects:

Fixed-pricing packages - where hasFlexPricing is false.
Flexible pricing - where hasFlexPricing is true.

In both case limits are defined on the account using the package, however with Flex the tenant is charged a base price plus what they used, defined by the flex* parameters.

A tenant may have multiple tenant packages and have the ability to change the package themselves from the Billing Info Page.

If you will be handling billing for tenants yourselves, you will still need to define a package for each tenant to define their limits. Simply set billingHandledExternally to true on the Tenant and they will not be able to change their billing information, or active package, themselves.

You may not create packages with higher limits than the parent tenant.

The structure for the TenantPackage object is as follows:

TenantPackage Structure

Copy

export interface TenantPackage {
    id: string
    name: string
    tenantId: string
    createdAt: string
    monthlyCostUSD: number
    yearlyCostUSD: number
    monthlyStripePlanId?: string
    yearlyStripePlanId?: string
    maxMonthlyPageLoads: number
    maxMonthlyAPICredits: number
    maxMonthlyComments: number
    maxConcurrentUsers: number
    maxTenantUsers: number
    maxSSOUsers: number
    maxModerators: number
    maxDomains: number
    maxWhiteLabeledTenants: number
    hasWhiteLabeling: boolean
    hasDebranding: boolean
    forWhoText: string
    featureTaglines: string[]
    hasAuditing: boolean
    hasFlexPricing: boolean
    flexPageLoadCostCents?: null
    flexPageLoadUnit?: null
    flexCommentCostCents?: null
    flexCommentUnit?: null
    flexSSOUserCostCents?: null
    flexSSOUserUnit?: null
    flexAPICreditCostCents?: null
    flexAPICreditUnit?: null
    flexModeratorCostCents?: null
    flexModeratorUnit?: null
    flexAdminCostCents?: null
    flexAdminUnit?: null
    flexDomainCostCents?: null
    flexDomainUnit?: null
    flexMinimumCostCents?: null
}

GET /api/v1/tenant-packages/:id

Resource: TenantPackage as GET /api/v1/tenant-packages/:id Credit Cost: 1

This route returns a single Tenant Package by id.

TenantPackage By ID cURL Example

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenant-packages/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

TenantPackage Request Structure

Copy

interface TenantPackageByIdQueryParams {
    tenantId: string
    API_KEY: string
}

TenantPackage Response Structure

Copy

interface TenantPackageByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
    tenantPackage: TenantPackage
}

GET /api/v1/tenant-packages

Resource: TenantPackage as GET /api/v1/tenant-packages Credit Cost: 1

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

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

TenantPackage cURL Example

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenant-packages?tenantId=demo&skip=0&API_KEY=DEMO_API_SECRET'

TenantPackage Request Structure

Copy

interface TenantPackagesRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The number of tenant packages to skip for pagination. **/
    skip?: number
}

TenantPackage Response Structure

Copy

interface TenantPackagesResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    tenantPackages?: TenantPackage[]
}

POST /api/v1/tenant-packages

Resource: TenantPackage as POST /api/v1/tenant-packages Credit Cost: 1

This route provides the ability to add a single TenantPackage.

Creating a TenantPackage has the following restrictions:

The following parameters are required:
- name
- tenantId
- monthlyCostUSD - Can be null.
- yearlyCostUSD - Can be null.
- maxMonthlyPageLoads
- maxMonthlyAPICredits
- maxMonthlyComments
- maxConcurrentUsers
- maxTenantUsers
- maxSSOUsers
- maxModerators
- maxDomains
- hasDebranding
- forWhoText
- featureTaglines
- hasFlexPricing - If true, then all flex* parameters are required.
The name may not be longer than 50 characters.
Each forWhoText item may not be longer than 200 characters.
Each featureTaglines item may not be longer than 100 characters.
The TenantPackage must be "smaller" than the parent tenant. For example, all of the max* parameters must have lower values than the parent tenant.
A white labeled tenant may have a maximum of five packages.
Only tenants with white labeling access may create a TenantPackage.
You may not add packages to your own tenant. :)

We can create a TenantPackage as follows:

TenantPackage Create via Email cURL Example

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/tenant-packages?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Default Package",
  "tenantId": "some-child-tenant-id",
  "monthlyCostUSD": null,
  "yearlyCostUSD": null,
  "maxMonthlyPageLoads": 50000,
  "maxMonthlyAPICredits": 50000,
  "maxMonthlyComments": 50000,
  "maxConcurrentUsers": 50000,
  "maxTenantUsers": 10,
  "maxSSOUsers": 50000,
  "maxModerators": 100,
  "maxDomains": 3,
  "hasWhiteLabeling": false,
  "hasDebranding": true,
  "forWhoText": "For Everyone",
  "featureTaglines": [
    "Some Tag",
    "Some Other Tag"
  ],
  "hasFlexPricing": true,
  "flexPageLoadCostCents": 100,
  "flexPageLoadUnit": 100000,
  "flexCommentCostCents": 100,
  "flexCommentUnit": 100000,
  "flexSSOUserCostCents": 100,
  "flexSSOUserUnit": 1000,
  "flexAPICreditCostCents": 100,
  "flexAPICreditUnit": 50000,
  "flexModeratorCostCents": 500,
  "flexModeratorUnit": 1,
  "flexAdminCostCents": 1000,
  "flexAdminUnit": 1,
  "flexDomainCostCents": 1000,
  "flexDomainUnit": 1,
  "flexMinimumCostCents": 99
}'

TenantPackage Create Request Structure

Copy

interface TenantPackagePostQueryParams {
    tenantId: string
    API_KEY: string
}

TenantPackage Create Response Structure

Copy

interface TenantPackagePostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' 'white-labeling-not-allowed' | 'name-too-long' | 'for-who-text-too-long' | 'feature-tag-lines-too-long' | 'no-package' | 'invalid-package' | 'unauthorized' | 'child-tenant-too-large' | 'flex-param-missing' | 'unexpected-flex-param' | 'package-limit-reached' | 'flex-param-missing' | 'unexpected-flex-param'
    /** Included on failure. **/
    reason?: string
    tenantPackage?: TenantPackage; // We return the complete created tenant package on success.
}

PATCH /api/v1/tenant-packages/:id

Resource: TenantPackage as PATCH /api/v1/tenant-packages/:id Credit Cost: 1

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

Updating a TenantPackage has the following restrictions:

If you are setting hasFlexPricing to true, then all flex* parameters are required in that same request.
The name may not be longer than 50 characters.
Each forWhoText item may not be longer than 200 characters.
Each featureTaglines item may not be longer than 100 characters.
The TenantPackage must be "smaller" than the parent tenant. For example, all of the max* parameters must have lower values than the parent tenant.
You may not change the tenantId associated with a TenantPackage.

TenantPackage PATCH cURL Example

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/tenant-packages/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some New Name",
}'

TenantPackage PATCH Request Structure

Copy

interface TenantPackagePatchQueryParams {
    tenantId: string
    API_KEY: string
}

TenantPackage PATCH Response Structure

Copy

interface TenantPackagePatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' | 'white-labeling-not-allowed' | 'name-too-long' | 'for-who-text-too-long' | 'feature-tag-lines-too-long' | 'no-package' | 'invalid-package' | 'unauthorized' | 'child-tenant-too-large' | 'flex-param-missing' | 'unexpected-flex-param' | 'package-limit-reached' | 'flex-param-missing' | 'unexpected-flex-param'; 
    /** Included on failure. **/
    reason?: string
}

DELETE /api/v1/tenant-packages/:id

Resource: TenantPackage as DELETE /api/v1/tenant-packages/:id Credit Cost: 5

This route provides the removal of a TenantPackage by id.

You may not remove a TenantPackage that is in use (a tenant's packageId points to the package). Update the Tenant first.

TenantPackage Removal cURL Example

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/tenant-packages/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

TenantPackage Removal Request Structure

Copy

interface TenantPackageDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

TenantPackage Removal Response Structure

Copy

interface TenantPackageDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized' | 'package-in-use'
    /** Included on failure. **/
    reason?: string
}

Tenant User Structure

The TenantUser defines a User which is managed by a specific tenant. Their account is in complete control of the tenant they are associated with, and their account can be updated or deleted via the UI or API.

Tenant users can be administrators with all permissions and access to the Tenant, or they can be limited to specific permissions to moderate comments, access API keys, etc.

The structure for the TenantUser object is as follows:

TenantUser Structure

Copy

/** This is for notifications. **/
export enum UserDigestEmailFrequency {
    Disabled = -1,
    Daily = 0,
    Weekly = 1,
    Monthly = 2
}
export interface TenantUser {
    id: string
    tenantId: string
    username: string
    /** A link to the commenter's blog, for example. **/
    websiteUrl?: string
    email: string
    signUpDate: number
    createdFromUrlId: string
    createdFromTenantId: string
    verified: boolean
    loginCount: number
    optedInNotifications: boolean
    optedInTenantNotifications: boolean
    hideAccountCode: boolean
    avatarSrc?: string
    /** Does the user receive help requests from commenters? **/
    isHelpRequestAdmin: boolean
    isAccountOwner: boolean
    isAdminAdmin: boolean
    isBillingAdmin: boolean
    isAnalyticsAdmin: boolean
    isCustomizationAdmin: boolean
    isManageDataAdmin: boolean
    isCommentModeratorAdmin: boolean
    isAPIAdmin: boolean
    moderatorIds: string[]
    locale: FastCommentsLocale
    digestEmailFrequency: UserDigestEmailFrequency
    lastLoginDate: string
    displayLabel?: string
}

GET /api/v1/tenant-users/:id

Resource: TenantUser as GET /api/v1/tenant-users/:id Credit Cost: 1

This route returns a single TenantUser by id.

TenantUser By ID cURL Example

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenant-users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

TenantUser Request Structure

Copy

interface TenantUserByIdQueryParams {
    tenantId: string
    API_KEY: string
}

TenantUser Response Structure

Copy

interface TenantUserByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'unauthorized'
    /** Included on failure. **/
    reason?: string
    tenantUser?: TenantUser
}

GET /api/v1/tenant-users

Resource: TenantUser as GET /api/v1/tenant-users Credit Cost: 1

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

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

TenantUser cURL Example

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenant-users?tenantId=demo&page=0&API_KEY=DEMO_API_SECRET'

TenantUser Request Structure

Copy

interface TenantUsersRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The number of tenant users to skip for pagination. **/
    skip?: number
}

TenantUser Response Structure

Copy

interface TenantUsersResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    tenantUsers?: TenantUser[]
}

POST /api/v1/tenant-users

Resource: TenantUser as POST /api/v1/tenant-users Credit Cost: 1

This route provides the ability to add a single TenantUser.

Creating a TenantUser has the following restrictions:

A username is required.
A email is required.
The signUpDate may not be in the future.
The locale must be in the list of Supported Locales.
The username must be unique across all of FastComments.com. If this is an issue, we suggest using SSO instead.
The email must be unique across all of FastComments.com. If this is an issue, we suggest using SSO instead.
You may not create more tenant users than defined under maxTenantUsers in your package.

We can create a TenantUser as follows

TenantUser Create cURL Example

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/tenants?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "Some Name",
    "email": "someone@someone.com"
}'

TenantUser Create Request Structure

Copy

interface TenantUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

TenantUser Create Response Structure

Copy

interface TenantUserPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'username-required' | 'email-required' | 'sign-up-date-in-future' | 'unsupported-locale' | 'unauthorized' | 'username-taken' | 'email-taken' | 'tenant-user-limit-reached'
    /** Included on failure. **/
    reason?: string
    tenantUser?: TenantUser; // We return the complete created tenant user on success.
}

Resource: TenantUser as POST /api/v1/tenant-users/:id/send-login-link Credit Cost: 10

This route provides the ability to send a login link to a single TenantUser.

Useful when batch creating users and not having to instruct them on how to login to FastComments.com. This will just send them a "magic link" to login that expires after 30 days.

The following restrictions exist to send a login link to a TenantUser:

The TenantUser must already exist.
You must have access to manage the Tenant the TenantUser belongs to.

We can send a login link to a TenantUser as follows:

TenantUser Login Link cURL Example

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/tenant-users/xyz/send-login-link?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json'

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

TenantUser Login Link Request Structure

Copy

interface TenantUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

TenantUser Login Link Response Structure

Copy

interface TenantUserPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'not-found'
    /** Included on failure. **/
    reason?: string
}

PATCH /api/v1/tenant-users/:id

Resource: TenantUser as PATCH /api/v1/tenant-users/:id Credit Cost: 1

This route provides the ability to update a single TenantUser.

Updating a TenantUser has the following restrictions:

The signUpDate may not be in the future.
The locale must be in the list of Supported Locales.
The username must be unique across all of FastComments.com. If this is an issue, we suggest using SSO instead.
The email must be unique across all of FastComments.com. If this is an issue, we suggest using SSO instead.
You cannot update the tenantId of a user.

We can create a TenantUser as follows

TenantUser Update cURL Example

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/tenant-users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "Some Name",
    "email": "someone@someone.com"
}'

TenantUser Update Request Structure

Copy

interface TenantUserPatchQueryParams {
    tenantId: string
    API_KEY: string
    /** When email or username is changed, you can set this to true to also update the user's comments. This will double the credit cost. **/
    updateComments: 'true' | 'false'
}

TenantUser Update Response Structure

Copy

interface TenantUserPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'sign-up-date-in-future' | 'unsupported-locale' | 'unauthorized' | 'username-taken' | 'email-taken' | 'unauthorized' | 'no-package' | 'invalid-package' | 'tenant-user-limit-reached' | 'user-does-not-exist'
    /** Included on failure. **/
    reason?: string
}

DELETE /api/v1/tenant-users/:id

Resource: TenantUser as DELETE /api/v1/tenant-users/:id Credit Cost: 5

This route provides the removal of a TenantUser by id.

Deleting the user's comments is possible via the deleteComments query parameter. Note that if this is true:

All the user's comments will be deleted live.
All child (now orphan) comments will also be deleted.
The creditsCost becomes 2.

TenantUser Removal cURL Example

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/tenant-users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

TenantUser Removal Request Structure

Copy

interface TenantUserDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** You can set this to true to also delete the user's comments. This will double the credit cost. **/
    deleteComments: 'true' | 'false'
}

TenantUser Removal Response Structure

Copy

interface TenantUserDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized'
    /** Included on failure. **/
    reason?: string
}

Vote Structure

A Vote object represents a vote left by a user.

The relationship between comments and vote is defined via commentId.

The structure for the Vote object is as follows:

Vote Structure

Copy

interface Vote {
    id: string
    urlId: string
    commentId: string
    userId: string
    direction: 1 | -1
    createdAt: string
}

GET /api/v1/votes

Resource: Vote as GET /api/v1/votes Credit Cost: 10

Votes must be fetched by urlId.

Types of Votes

There are three types of votes:

Authenticated Votes, which are applied to the corresponding comment. You can create these via this API.
Authenticated Votes, which are pending verification, and thus are not yet applied to the comment. These are created when a user uses the FastComments.com login to vote mechanism.
Anonymous Votes, which are applied to the corresponding comment. These are created along with anonymous commenting.

These are returned in separate lists in the API to reduce confusion.

Votes cURL Example

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/votes?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=test'

Votes Request Structure

Copy

interface VotesRequestQueryParams {
    tenantId: string
    API_KEY: string
    urlId: string
}

Votes Response Structure

Copy

interface VotesResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id'
    /** Included on failure. **/
    reason?: string
    /** Authorized, verified votes, applied to their corresponding comments. **/
    appliedAuthorizedVotes: Vote[]
    /** Anonymous votes, applied to their corresponding comments. **/
    appliedAnonymousVotes: Vote[]
    /** Votes pending verification, not yet applied to their corresponding comments. **/
    pendingVotes: Vote[]
}

GET /api/v1/votes/for-user

Resource: Vote as GET /api/v1/votes/for-user Credit Cost: 1

Allows fetching votes left by a user on a given urlId. Takes a userId which can be any FastComments.com or SSO User.

This is useful if you want to show if a user has voted on a comment. When fetching comments, simply call this API at the same time for the user with the same urlId.

Votes For User cURL Example

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/votes/for-user?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=test&userId=some-user-id'

Votes For User Request Structure

Copy

interface VotesForUserRequestQueryParams {
    tenantId: string
    API_KEY: string
    urlId: string
    userId: string
}

Votes For User Response Structure

Copy

interface VotesForUserResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'invalid-user-id'
    /** Included on failure. **/
    reason?: string
    /** Authorized, verified votes, applied to their corresponding comments. **/
    appliedAuthorizedVotes: Vote[]
    /** Votes pending verification, not yet applied to their corresponding comments. **/
    pendingVotes: Vote[]
}

POST /api/v1/votes

Resource: Vote as POST /api/v1/votes Credit Cost: 1

This route provides the ability to add a single authorized Vote. Votes can be up (+1) or down (-1).

Vote Create cURL Example

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/votes?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=user-id&commentId=comment-id&direction=up' \
  --header 'Content-Type: application/json'

Vote Create Request Structure

Copy

interface VotePostQueryParams {
    tenantId: string
    API_KEY: string
    userId: string
    commentId: string
    direction: 'up' | 'down'
}

Vote Create Response Structure

Copy

interface VotePostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-user-id' | 'invalid-user-id' | 'invalid-comment-id' | 'invalid-direction' | 'duplicate' | 'voting-disabled'
    /** Included on failure. **/
    reason?: string
    voteId?: string
}

Notes:

This API obeys tenant-level settings. For example, if you disable voting for a given page, and you attempt to create a vote via the API, it will fail with error code voting-disabled.
This API is live by default.
This API will update the votes of the corresponding Comment.

DELETE /api/v1/votes/:id

Resource: Vote as DELETE /api/v1/votes/:id Credit Cost: 1

This route provides the ability to delete a single Vote.

Vote Delete cURL Example

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/votes/some-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json'

Vote Delete Request Structure

Copy

interface VoteDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Vote Delete Response Structure

Copy

interface VoteDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id'
    /** Included on failure. **/
    reason?: string
}

Notes:

This API obeys tenant-level settings. For example, if you disable voting for a given page, and you attempt to create a vote via the API, it will fail with error code voting-disabled.
This API is live by default.
This API will update the votes of the corresponding Comment.

DomainConfig Structure

A DomainConfig object represents configuration for a domain for a tenant.

The structure for the DomainConfig object is as follows:

Domain Config Structure

Copy

interface DomainConfig {
    /** A domain, not a URL, like "fastcomments.com" or "www.example.com". Subdomain may be included if limiting to a subdomain is desired. Max 1000 characters. **/
    domain: string
    /** The From-Name used when sending emails. **/
    emailFromName?: string
    /** The From-Email used when sending emails. Ensure SPF is setup to allow mail.fastcomments.com to send emails as the domain used in this attribute. **/
    emailFromEmail?: string
    /** READONLY. When the object was created. **/
    createdAt: string
    /** The logo related to this domain. Used in emails. Use HTTPS. **/
    logoSrc?: string
    /** A smaller logo related to this domain. Use HTTPS. **/
    logoSrc100px?: string
    /** SSO ONLY. The URL used in the footer of every email sent. Supports a "[userId]" variable. **/
    footerUnsubscribeURL?: string
    /** SSO ONLY. The headers used in of every email sent. Useful for example for setting unsubscribe related headers to improve delivery. The List-Unsubscribe entry in this Record, if it exists, supports a "[userId]" variable. **/
    emailHeaders?: Record<string, string>
    /** Disable all unsubscribe links. Not recommended, may hurt delivery rates. **/
    disableUnsubscribeLinks?: boolean
    /** DKIM Configuration. **/
    dkim?: DomainConfigDKIM
}

DKIM Config Structure

Copy

interface DomainConfigDKIM {
    /** The domain name in your DKIM record. **/
    domainName: string
    /** The DKIM key selector to use. **/
    keySelector: string
    /** Your private key. Start with -----BEGIN PRIVATE KEY----- and end with -----END PRIVATE KEY----- **/
    privateKey: string
}

For Authentication

Domain Configuration is used to determine which sites can host the FastComments widget for your account. This is a basic form of authentication, meaning adding or removing any Domain Configurations can impact the availability of your FastComments installation in production.

Don't remove or update the domain property of a Domain Config for a domain that is currently in use unless disabling that domain is intended.

This has the same behavior as removing a domain from /auth/my-account/configure-domains.

Also note that removing a domain from the My Domains UI will remove any corresponding configuration for that domain that may have been added via this UI.

For Email Customization

The unsubscribe link in the email footer, and the one-click-unsubscribe feature offered by many email clients, can be configured via this API by defining footerUnsubscribeURL and emailHeaders, respectively.

For DKIM

After defining your DKIM DNS records, simply update the DomainConfig with your DKIM configuration using the defined structure.

GET /api/v1/domain-configs

Resource: Comment as GET /api/v1/domain-configs Credit Cost: 1

This API provides the ability to fetch all DomainConfig objects for a tenant.

DomainConfig GET cURL Example

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/domain-configs?tenantId=demo&API_KEY=DEMO_API_SECRET'

DomainConfig GET Request Structure

Copy

interface GetDomainConfigsRequestQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig GET Response Structure

Copy

interface GetDomainConfigsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    /** The configurations! **/
    configurations: DomainConfig[] | null
}

GET /api/v1/domain-configs/:domain

Resource: DomainConfig as GET /api/v1/domain-configs/:domain Credit Cost: 1

Individual DomainConfigs can be fetched by their corresponding domain.

Domain Config by Domain cURL Example

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/domain-configs/example.com?tenantId=demo&API_KEY=DEMO_API_SECRET'

Domain Config by Domain Request Structure

Copy

interface DomainConfigsByDomainRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Domain Config by Domain Response Structure

Copy

interface DomainConfigResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'internal' | 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'missing-domain' | 'update-would-create-duplicate' | 'domain-does-not-exist'
    /** Included on failure. **/
    reason?: string
    configuration?: DomainConfig | null
}

POST /api/v1/domain-configs

Resource: DomainConfig as POST /api/v1/domain-configs Credit Cost: 1

This API endpoint provides the ability to create domain configurations.

Adding configuration for a domain authorizes that domain for the FastComments account.

Common use cases of this API are initial setup, if many domains are desired to be added, or custom configuration for sending emails.

DomainConfig POST cURL Example

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/domain-configs?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "domain": "example.com",
    "emailFromName": "some from name",
    "emailFromEmail": "some@test.com",
    "logoSrc": "https://example.com/my-logo-big.png",
    "logoSrc100px": "https://example.com/my-logo-100px.png",
    "footerUnsubscribeURL": "http://example.com/unsubscribe-ui",
    "emailHeaders": {
        "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
        "List-Unsubscribe": "<https://example.com/opt-out/[userId]>"
    }
}'

DomainConfig POST Request Structure

Copy

interface DomainConfigPostQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig POST Response Structure

Copy

interface DomainConfigPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'missing-domain' | 'configuration-exists-for-domain' | 'domain-too-long' | 'domain-invalid';  
    /** Included on failure. **/
    reason?: string
    /** The created configuration. **/
    configuration?: DomainConfig
}

PATCH /api/v1/domain-configs/:domain

Resource: DomainConfig as PATCH /api/v1/domain-configs/:domain Credit Cost: 1

This API endpoint provides the ability to update a domain configuration by only specifying the domain and the attribute to update.

DomainConfig PATCH cURL Example

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/domain-configs/example.com?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "emailFromName": "Some New From Name",
}'

DomainConfig PATCH Request Structure

Copy

interface DomainConfigPatchQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig PATCH Response Structure

Copy

interface DomainConfigPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'missing-domain' | 'domain-does-not-exist' | 'update-would-create-duplicate' | 'domain-too-long' | 'domain-invalid';  
    /** Included on failure. **/
    reason?: string
    /** The updated configuration. **/
    configuration?: DomainConfig
}

PUT /api/v1/domain-configs/:domain

Resource: DomainConfig as PUT /api/v1/domain-configs/:domain Credit Cost: 1

This API endpoint provides the ability to replace a domain configuration.

DomainConfig PUT cURL Example

Copy

curl --request PUT \
  --url 'https://fastcomments.com/api/v1/domain-configs/example.com?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "domain": "new-domain-example.com",
    "emailFromName": "some from name",
    "emailFromEmail": "some@test.com",
    "logoSrc": "https://example.com/my-logo-big.png",
    "logoSrc100px": "https://example.com/my-logo-100px.png",
    "footerUnsubscribeURL": "http://example.com/unsubscribe-ui",
    "emailHeaders": {
        "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
        "List-Unsubscribe": "<https://example.com/opt-out/[userId]>"
    }
}'

DomainConfig PUT Request Structure

Copy

interface DomainConfigPutQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig PUT Response Structure

Copy

interface DomainConfigPutResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'missing-domain' | 'domain-does-not-exist' | 'update-would-create-duplicate' | 'domain-too-long' | 'domain-invalid';  
    /** Included on failure. **/
    reason?: string
    /** The updated configuration. **/
    configuration?: DomainConfig
}

DELETE /api/v1/domain-configs/:domain

Resource: DomainConfig as DELETE /api/v1/domain-configs/:domain Credit Cost: 1

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

Note: Removing a DomainConfig will un-authorize that domain from using FastComments.
Note: Re-adding a domain via the UI will recreate the object (with just domain populated).

DomainConfig Removal cURL Example

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/domain-configs/example.com?tenantId=demo&API_KEY=DEMO_API_SECRET'

DomainConfig Removal Request Structure

Copy

interface DomainConfigRequestQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig Removal Response Structure

Copy

interface DomainConfigDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-domain' | 'domain-config-does-not-exist'
    /** Included on failure. **/
    reason?: string
}

In Conclusion

We hope you've found our API documentation thorough and easy to understand. If you find any gaps, let us know below.

API Resources

AuditLogs

Comments

HashTags

Moderators

Pages

SSO Users

Tenant Daily Usage

Tenants

Tenant Packages

Tenant Users

Votes

Domain Configs

The FastComments API

Authentication

Authentication Option One - Headers

Authentication Option Two - Query Parameters

API Resources

Resource Usage

Note!

AuditLog Structure

GET /api/v1/audit-logs

Comment Structure

Comment Text Structure

Tagging

HashTags

GET /api/v1/comments

Pagination

Threads

Fetching Comments in The Context of a User

Helpful Tip

GET /api/v1/comments/:id

POST /api/v1/comments

PATCH /api/v1/comments/:id

DELETE /api/v1/comments/:id

POST /api/v1/comments/:id/flag

POST /api/v1/comments/:id/un-flag

POST /api/v1/comments/:id/block

POST /api/v1/comments/:id/un-block

HashTag Structure

GET /api/v1/hash-tags

PATCH /api/v1/hash-tags/:tag

POST /api/v1/hash-tags

POST /api/v1/hash-tags/bulk

DELETE /api/v1/hash-tags/:tag

Moderator Structure

GET /api/v1/moderators/:id

GET /api/v1/moderators

PATCH /api/v1/moderators/:id

POST /api/v1/moderators

POST /api/v1/moderators/:id/send-invite

DELETE /api/v1/moderators/:id

Page Structure

GET /api/v1/pages

Helpful Tip

GET /api/v1/pages/by-url-id

Helpful Tip

PATCH /api/v1/pages/:id

Note

POST /api/v1/pages

DELETE /api/v1/pages/:id

SSOUser Structure

Access Control

@Mentions

GET /api/v1/sso-users

GET /api/v1/sso-users/by-id/:id

GET /api/v1/sso-users/by-email/:email

PATCH /api/v1/sso-users/:id

POST /api/v1/sso-users

Integration Note

PUT /api/v1/sso-users/:id

DELETE /api/v1/sso-users/:id

TenantDailyUsage Structure

GET /api/v1/tenant-daily-usage

Tenant Structure

GET /api/v1/tenants/:id

GET /api/v1/tenants

POST /api/v1/tenants

PATCH /api/v1/tenants/:id

DELETE /api/v1/tenants/:id