FastComments Docs

The FastComments API

FastComments provides an API for searching and fetching data in your account.

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

API Resources

The FastComments API exposes the following resources to you:

Comments
Pages
SSO Users
Votes

Pages and Votes are currently read-only.

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.

If a resource says "1 Page Load: = 1000 Votes Max", this means that a request that returns 1000 votes will count as one page load (or credit) on your account. Your account has a limited number of these based on its tier (the same as page loads). If the API returns 1,500 Vote objects, this would count as two page loads on your account. If you make two API calls, and each return 10 Votes, that also counts as two page loads as they are separate requests.

Note!

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

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
interface Comment {
    id: string;
    /** The user that wrote the comment. Created automatically when saving a comment with a name/email. **/
    userId?: string|null;
    /** 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;
    /** The URL to the location that this comment is visible, like a blog post. **/
    url: string;
    /** The title of the page this comment was on. **/
    pageTitle?: string;
    /** The commenter's name. Always required. If not available, set to something like "Anonymous". **/
    commenterName: 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 raw comment. **/
    comment: string;
    /** The locale the comment is in. If not provided, will be derived from the language accept HTTP header. **/
    locale?: 'en_us' | 'es_es' | 'fr_fr' | 'pl_pl' | 'de_de' | 'it_it' | 'ru_ru' | 'ja_jp';
    /** READONLY: The commenter's comment parsed into HTML. **/
    commentHTML?: string;
    /** If we're replying to a comment, this is the ID that we are replying to. **/
    parentId?: string|null;
    /** The date the comment was left, in UTC epoch. **/
    date: number;
    /** The "karma" of the comment (= votes up + votes down). **/
    votes?: number;
    /** Is the user and this comment verified? **/
    verified: boolean;
    /** The user's avatar. **/
    avatarSrc?: string;
    /** READONLY: Does the comment contain images? **/
    hasImages?: boolean;
    /** READONLY: Does the comment contain links? **/
    hasLinks?: boolean;
    /** READONLY: Is the comment by an admin? **/
    isByAdmin?: boolean;
    /** READONLY: Is the comment by a moderator? **/
    isByModerator?: boolean;
    /** Is the comment pinned? **/
    isPinned?: boolean;
    /** The "display label" for the comment - for example "Admin", "Moderator", or something like "VIP User". **/
    displayLabel?: string;
    /** A star rating. **/
    rating?: number;
    /** Whether or not notifications were sent for this comment for commenters. To prevent notifications being sent on imports, set this to true. **/
    notificationSentForParent?: boolean;
    /** Whether or not notifications were sent for this comment for tenant users. To prevent notifications being sent on imports, set this to true. **/
    notificationSentForParentTenant?: boolean;
}

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

GET /api/v1/comments

Resource: Comment as GET /api/v1/comments Cost: 1 Page Load = 30 Comments Max

Comments must be fetched by-page. You can fetch comments for all pages at once, but use caution.

Comments cURL Example

2curl --request GET \

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

Comments Request Structure
interface CommentsRequestQueryParams {
    tenantId: string;
    API_KEY: string;
    /** The urlId (page url, or article id) the comments are associated with. **/
    urlId: string;
    /** The page to fetch, starting with 0. Pass -1 for all comments. **/
    page: number;
    /** The sort direction. Default is MR (Most Relevant). Other options are OF (Oldest First) and NF (Newest First). **/
    direction: 'MR' | 'OF' | 'NF';
}

Comments Response Structure
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';
    /** 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.

POST /api/v1/comments

Resource: Comment as POST /api/v1/comments Cost: 1 Page Load = 1 Comments Max

This API endpoint provides the ability to create comments.

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

Notes:

This API will automatically create user objects in our system.
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).
This API can be "live" if desired.
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.

Comment POST cURL Example
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 '{
    "urlId": "some-place",
    "comment": "some-comment",
    "commenterName": "some-commenter-name",
    "commenterEmail": "fordperfect@spaceship.com",
    "comment": "some comment",
    "votes": 1,
    "verified": true,
    "reviewed": true,
    "notificationSentForParent": true,
    "notificationSentForParentTenant": true,
    "avatarSrc": "https://static.fastcomments.com/1605337537848-DSC_0841.JPG",
    "isSpam": false,
    "approved": true,
    "locale": "en_us",
    "date": 1622644382148
}'

Comment POST Request Structure
// Note that urlId is not here - it is in the request body.
interface CommentPostQueryParams {
    tenantId: string;
    API_KEY: string;
    doSpamCheck?: 'true' | 'false';
    isLive?: 'true' | 'false';
}

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

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
interface Page {
    id: string;
    urlId: string;
    url: string;
    title: string;
    createdAt: string;
    commentCount: number;
}

GET /api/v1/pages

Resource: Page as GET /api/v1/pages Cost: 1 Page Load = 1000 Pages Max

You can currently only fetch all pages associated with your account. If you'd like more fine-grained searching, reach out to us.

Pages cURL Example

2curl --request GET \

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

Pages Request Structure
interface PagesRequestQueryParams {
    tenantId: string;
    API_KEY: string;
}

Pages Response Structure
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 Cost: 1 Page Load = 1 Pages Max

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

2curl --request GET \

3 --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
interface PagesRequestQueryParams {
    tenantId: string;
    API_KEY: string;
    urlId: string;
}

Page by URL ID Response Structure
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.

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
interface SSOUser {
    id: string;
    username: string;
    websiteUrl: string;
    email: string;
    signUpDate: number;
    createdFromUrlId: string;
    loginCount: number;
    avatarSrc: string;
    optedInNotifications: boolean;
    displayLabel: string;
    isAccountOwner?: boolean;
    isAdminAdmin?: boolean;
    isCommentModeratorAdmin?: boolean;
}

GET /api/v1/sso-users

Resource: SSOUser as GET /api/v1/sso-users Cost: 1 Page Load = 1000 SSOUsers Max

This route returns all SSO Users on your account.

SSOUsers cURL Example

2curl --request GET \

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

SSOUsers Request Structure
interface SSOUsersRequestQueryParams {
    tenantId: string;
    API_KEY: string;
}

SSOUsers Response Structure
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 Cost: 1 Page Load = 1 SSOUsers Max

This route returns a single SSO user by their id.

SSOUser By ID cURL Example

2curl --request GET \

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

SSOUser Request Structure
interface SSOUserRequestByIdQueryParams {
    tenantId: string;
    API_KEY: string;
}

SSOUser Response Structure
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-id/:id Cost: 1 Page Load = 1 SSOUsers Max

This route returns a single SSO user by their email.

SSOUser By Email cURL Example

2curl --request GET \

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

SSOUser Request Structure
interface SSOUserRequestByEmailQueryParams {
    tenantId: string;
    API_KEY: string;
}

SSOUser Response Structure
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 Cost: 1 Page Load = 1 SSOUsers Max

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

SSOUser Update cURL Example
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
interface SSOUserPatchQueryParams {
    tenantId: string;
    API_KEY: string;
}

SSOUser Update Response Structure
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/:id

Resource: SSOUser as POST /api/v1/sso-users Cost: 1 Page Load = 1 SSOUsers Max

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
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",
    "email": "fordperfect@galaxy.com"
}'

SSOUser Creation Request Structure
interface SSOUserPostQueryParams {
    tenantId: string;
    API_KEY: string;
}

SSOUser Creation Response Structure
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).

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

Resource: SSOUser as DELETE /api/v1/sso-users/:id Cost: 1 Page Load = 1 SSOUsers Max

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

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

SSOUser Removal cURL Example

2curl --request DELETE \

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

SSOUser Removal Request Structure
interface SSOUsersRequestQueryParams {
    tenantId: string;
    API_KEY: string;
}

SSOUser Removal Response Structure
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.
}

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
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 Cost: 1 Page Load = 1000 Votes Max

Votes must be fetched by urlId.

Types of Votes

There are three types of votes:

Authenticated Votes, which are applied to the corresponding comment.
Authenticated Votes, which are pending verification, and thus are not yet applied to the comment.
Anonymous Votes, which are applied to the corresponding comment.

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

Votes cURL Example

2curl --request GET \

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

Votes Request Structure
interface VotesRequestQueryParams {
    tenantId: string;
    API_KEY: string;
    urlId: string;
}

Votes Response Structure
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[];
}

In Conclusion

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