LogoFastComments.com

Menu Icon

API Resources

API Resources

Comments

Comment Structure
GET /api/v1/comments
POST /api/v1/comments

Pages

Page Structure
GET /api/v1/pages

SSO Users

SSOUser Structure
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/:id
DELETE /api/v1/sso-users/:id

Votes

Vote Structure
GET /api/v1/votes

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

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

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
1
2interface Comment {
3 id: string;
4 /** The user that wrote the comment. Created automatically when saving a comment with a name/email. **/
5 userId?: string|null;
6 /** 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". **/
7 urlId: string;
8 /** READONLY: The original urlId you passed us. **/
9 urlIdRaw?: string;
10 /** The URL to the location that this comment is visible, like a blog post. **/
11 url: string;
12 /** The title of the page this comment was on. **/
13 pageTitle?: string;
14 /** The commenter's name. Always required. If not available, set to something like "Anonymous". **/
15 commenterName: string;
16 /** The commenter's email. Required if anonymous commenting is off. **/
17 commenterEmail?: string;
18 /** The commenter's link (for example, their blog). **/
19 commenterLink?: string;
20 /** The commenter's raw comment. **/
21 comment: string;
22 /** The locale the comment is in. If not provided, will be derived from the language accept HTTP header. **/
23 locale?: 'en_us' | 'es_es' | 'fr_fr' | 'pl_pl' | 'de_de' | 'it_it' | 'ru_ru';
24 /** READONLY: The commenter's comment parsed into HTML. **/
25 commentHTML?: string;
26 /** If we're replying to a comment, this is the ID that we are replying to. **/
27 parentId?: string|null;
28 /** The date the comment was left, in UTC epoch. **/
29 date: number;
30 /** The "karma" of the comment (= votes up + votes down). **/
31 votes?: number;
32 /** Is the user and this comment verified? **/
33 verified: boolean;
34 /** The user's avatar. **/
35 avatarSrc?: string;
36 /** READONLY: Does the comment contain images? **/
37 hasImages?: boolean;
38 /** READONLY: Does the comment contain links? **/
39 hasLinks?: boolean;
40 /** READONLY: Is the comment by an admin? **/
41 isByAdmin?: boolean;
42 /** READONLY: Is the comment by a moderator? **/
43 isByModerator?: boolean;
44 /** Is the comment pinned? **/
45 isPinned?: boolean;
46 /** The "display label" for the comment - for example "Admin", "Moderator", or something like "VIP User". **/
47 displayLabel?: string;
48 /** A star rating. **/
49 rating?: number;
50 /** Whether or not notifications were sent for this comment for commenters. To prevent notifications being sent on imports, set this to true. **/
51 notificationSentForParent?: boolean;
52 /** Whether or not notifications were sent for this comment for tenant users. To prevent notifications being sent on imports, set this to true. **/
53 notificationSentForParentTenant?: boolean;
54}
55

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

GET /api/v1/comments Internal Link

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
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&page=0&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR'
4
Comments Request Structure
1
2interface CommentsRequestQueryParams {
3 tenantId: string;
4 API_KEY: string;
5 /** The urlId (page url, or article id) the comments are associated with. **/
6 urlId: string;
7 /** The page to fetch, starting with 0. Pass -1 for all comments. **/
8 page: number;
9 /** The sort direction. Default is MR (Most Relevant). Other options are OF (Oldest First) and NF (Newest First). **/
10 direction: 'MR' | 'OF' | 'NF';
11}
12
Comments Response Structure
1
2interface CommentsResponse {
3 status: 'success' | 'failed';
4 /** Included on failure. **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'missing-date';
6 /** Included on failure. **/
7 reason?: string;
8 /** The comments! **/
9 comments: Comment[];
10}
11

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

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
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true&doSpamCheck=true' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "urlId": "some-place",
7 "comment": "some-comment",
8 "commenterName": "some-commenter-name",
9 "commenterEmail": "fordperfect@spaceship.com",
10 "comment": "some comment",
11 "votes": 1,
12 "verified": true,
13 "reviewed": true,
14 "notificationSentForParent": true,
15 "notificationSentForParentTenant": true,
16 "avatarSrc": "https://static.fastcomments.com/1605337537848-DSC_0841.JPG",
17 "isSpam": false,
18 "approved": true,
19 "locale": "en_us",
20 "date": 1622644382148
21}'
22
Comment POST Request Structure
1
2// Note that urlId is not here - it is in the request body.
3interface CommentPostQueryParams {
4 tenantId: string;
5 API_KEY: string;
6 doSpamCheck?: 'true' | 'false';
7 isLive?: 'true' | 'false';
8}
9
Comment POST Response Structure
1
2
3interface CommentPostResponse {
4 status: 'success' | 'failed';
5 /** Included on failure. **/
6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-comment';
7 /** Included on failure. **/
8 reason?: string;
9 /** The created comment. **/
10 comment?: Comment;
11 /** The associated user, which may or may not have already existed. **/
12 user?: User;
13}
14

Page Structure Internal Link

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
1
2interface Page {
3 id: string;
4 urlId: string;
5 url: string;
6 title: string;
7 createdAt: string;
8 commentCount: number;
9}
10

GET /api/v1/pages Internal Link

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
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/pages?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
Pages Request Structure
1
2interface PagesRequestQueryParams {
3 tenantId: string;
4 API_KEY: string;
5}
6
Pages Response Structure
1
2interface PagesResponse {
3 status: 'success' | 'failed';
4 /** Included on failure. **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key';
6 /** Included on failure. **/
7 reason?: string;
8 pages: Page[]
9}
10

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.

SSOUser Structure Internal Link

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
1
2interface SSOUser {
3 id: string;
4 username: string;
5 websiteUrl: string;
6 email: string;
7 signUpDate: number;
8 createdFromUrlId: string;
9 loginCount: number;
10 avatarSrc: string;
11 optedInNotifications: boolean;
12 displayLabel: string;
13 isAccountOwner?: boolean;
14 isAdminAdmin?: boolean;
15 isCommentModeratorAdmin?: boolean;
16}
17

GET /api/v1/sso-users Internal Link

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
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/sso-users?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
SSOUsers Request Structure
1
2interface SSOUsersRequestQueryParams {
3 tenantId: string;
4 API_KEY: string;
5}
6
SSOUsers Response Structure
1
2interface SSOUsersResponse {
3 status: 'success' | 'failed';
4 /** Included on failure. **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key';
6 /** Included on failure. **/
7 reason?: string;
8 users: SSOUser[]
9}
10

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

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
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/sso-users/by-id/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
SSOUser Request Structure
1
2interface SSOUserRequestByIdQueryParams {
3 tenantId: string;
4 API_KEY: string;
5}
6
SSOUser Response Structure
1
2interface SSOUserByIdResponse {
3 status: 'success' | 'failed';
4 /** Included on failure. **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'user-does-not-exist';
6 /** Included on failure. **/
7 reason?: string;
8 user: SSOUser;
9}
10

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

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
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/sso-users/by-email/someone@somewhere.com?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
SSOUser Request Structure
1
2interface SSOUserRequestByEmailQueryParams {
3 tenantId: string;
4 API_KEY: string;
5}
6
SSOUser Response Structure
1
2interface SSOUserByEmailResponse {
3 status: 'success' | 'failed';
4 /** Included on failure. **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-email' | 'user-does-not-exist';
6 /** Included on failure. **/
7 reason?: string;
8 user: SSOUser;
9}
10

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

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
1
2curl --request PATCH \
3 --url 'https://fastcomments.com/api/v1/sso-users/my-user-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "username": "notfordperfect"
7}'
8
SSOUser Update Request Structure
1
2interface SSOUserPatchQueryParams {
3 tenantId: string;
4 API_KEY: string;
5}
6
SSOUser Update Response Structure
1
2interface SSOUserPatchResponse {
3 status: 'success' | 'failed';
4 /** Included on failure. **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-does-not-exist';
6 /** Included on failure. **/
7 reason?: string;
8 user?: SSOUser; // We return the complete updated user on success.
9}
10

POST /api/v1/sso-users/:id Internal Link

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
1
2curl --request POST \
3 --url 'https://fastcomments.com/api/v1/sso-users?tenantId=demo&API_KEY=DEMO_API_SECRET' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "id": "my-user-id",
7 "username": "fordperfect",
8 "email": "fordperfect@galaxy.com"
9}'
10
SSOUser Creation Request Structure
1
2interface SSOUserPostQueryParams {
3 tenantId: string;
4 API_KEY: string;
5}
6
SSOUser Creation Response Structure
1
2interface SSOUserPostResponse {
3 status: 'success' | 'failed';
4 /** Included on failure. **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-exists';
6 /** Included on failure. **/
7 reason?: string;
8 user?: SSOUser; // We return the created user on success.
9}
10

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

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
1
2curl --request DELETE \
3 --url 'https://fastcomments.com/api/v1/sso-users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
4
SSOUser Removal Request Structure
1
2interface SSOUsersRequestQueryParams {
3 tenantId: string;
4 API_KEY: string;
5}
6
SSOUser Removal Response Structure
1
2interface SSOUsersResponse {
3 status: 'success' | 'failed';
4 /** Included on failure. **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'user-does-not-exist';
6 /** Included on failure. **/
7 reason?: string;
8 user?: SSOUser; // We return the removed user on success.
9}
10

Vote Structure Internal Link

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
1
2interface Vote {
3 id: string;
4 urlId: string;
5 commentId: string;
6 userId: string;
7 direction: 1 | -1;
8 createdAt: string;
9}
10

GET /api/v1/votes Internal Link

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
1
2curl --request GET \
3 --url 'https://fastcomments.com/api/v1/votes?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=test'
4
Votes Request Structure
1
2interface VotesRequestQueryParams {
3 tenantId: string;
4 API_KEY: string;
5 urlId: string;
6}
7
Votes Response Structure
1
2interface VotesResponse {
3 status: 'success' | 'failed';
4 /** Included on failure. **/
5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id';
6 /** Included on failure. **/
7 reason?: string;
8 /** Authorized, verified votes, applied to their corresponding comments. **/
9 appliedAuthorizedVotes: Vote[];
10 /** Anonymous votes, applied to their corresponding comments. **/
11 appliedAnonymousVotes: Vote[];
12 /** Votes pending verification, not yet applied to their corresponding comments. **/
13 pendingVotes: Vote[];
14}
15

In Conclusion

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