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.

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;
    /** READONLY: The @mentions written in the comment that were successfully parsed. **/
    mentions?: CommentUserMention[]
}

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

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

GET /api/v1/comments

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

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 Credit Cost: 10

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

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
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 of the 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

2curl --request GET \

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

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

HashTag Response Structure
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
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
interface HashTagPatchQueryParams {
    tenantId: string;
    API_KEY: string;
}

HashTag Update Response Structure
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
curl --request PATCH \
  --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
interface HashTagPostQueryParams {
    tenantId: string;
    API_KEY: string;
}

HashTag Create Response Structure
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
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
interface HashTagPostQueryParams {
    tenantId: string;
    API_KEY: string;
}

HashTag Bulk Create Response Structure
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

2curl --request DELETE \

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

HashTag Removal Request Structure
interface HashTagDeleteQueryParams {
    tenantId: string;
    API_KEY: string;
}

HashTag Removal Response Structure
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;
}

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;
    rootCommentCount: number;
    /** Setting this to null means all SSO users can see the page. An empty list means it is closed to call 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

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

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.

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

Page Update Response Structure
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
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
interface PagePostQueryParams {
    tenantId: string;
    API_KEY: string;
}

Page POST Response Structure
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

2curl --request DELETE \

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

Page Removal Request Structure
interface PageDeleteQueryParams {
    tenantId: string;
    API_KEY: string;
}

Page Removal Response Structure
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
interface SSOUser {
    id: string;
    username: string;
    websiteUrl: string;
    email: 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;
}

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 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 Credit Cost: 1

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 Credit Cost: 1

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 Credit Cost: 1

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

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

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

SSOUser Update Response Structure
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 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 SSOUsersDeleteQueryParams {
    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 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.
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[];
}

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

2curl --request GET \

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

DomainConfig GET Request Structure
interface GetDomainConfigsRequestQueryParams {
    tenantId: string;
    API_KEY: string;
}

DomainConfig GET Response Structure
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

2curl --request GET \

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

Domain Config by Domain Request Structure
interface DomainConfigsByDomainRequestQueryParams {
    tenantId: string;
    API_KEY: string;
}

Domain Config by Domain Response Structure
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
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
interface DomainConfigPostQueryParams {
    tenantId: string;
    API_KEY: string;
}

DomainConfig POST Response Structure
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
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
interface DomainConfigPatchQueryParams {
    tenantId: string;
    API_KEY: string;
}

DomainConfig PATCH Response Structure
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
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
interface DomainConfigPutQueryParams {
    tenantId: string;
    API_KEY: string;
}

DomainConfig PUT Response Structure
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

2curl --request DELETE \

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

DomainConfig Removal Request Structure
interface DomainConfigRequestQueryParams {
    tenantId: string;
    API_KEY: string;
}

DomainConfig Removal Response Structure
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

Comments

HashTags

Pages

SSO Users

Votes

Domain Configs

The FastComments API

API Resources

Resource Usage

Note!

Comment Structure

GET /api/v1/comments

Helpful Tip

POST /api/v1/comments

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

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

Vote Structure

GET /api/v1/votes

Types of Votes

DomainConfig Structure

For Authentication

For Email Customization

For DKIM

GET /api/v1/domain-configs

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

POST /api/v1/domain-configs

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

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

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

In Conclusion