
API Resources
AuditLogs
Comments
HashTags
Moderators
Pages
SSO Users
Tenant Daily Usage
Tenants
Tenant Packages
Tenant Users
Votes
Domain Configs
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.
Authentication
The API is authenticated by passing your api key as either an API_KEY
header or query parameter.
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:

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



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:

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.


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.


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



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 
This API provides the ability to fetch a single comment by id.



POST /api/v1/comments 
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
from1
to2
). - 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 hasnotificationSentForParent
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
totrue
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:

A more realistic request may look like:



DELETE /api/v1/comments/:id 
This API endpoint provides the ability to delete a comment.
Notes:
- This API can update the comment widget "live" if desired (this increases
creditsCost
from1
to2
). - This API will delete all child comments.



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:

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 
This API uses pagination, provided by the page
query parameter. HashTags are returned in pages of 100
, ordered by tag
.



PATCH /api/v1/hash-tags/:tag 
This route provides the ability to update a single HashTag
.



POST /api/v1/hash-tags 
This route provides the ability to add a single HashTag
.



POST /api/v1/hash-tags/bulk 
This route provides the ability to add up to 100 HashTag
objects at once.



DELETE /api/v1/hash-tags/:tag 
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.



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:

GET /api/v1/moderators/:id 
This route returns a single moderator by their id.



GET /api/v1/moderators 
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.



PATCH /api/v1/moderators/:id 
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 sametenantId
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 aModerator
.



POST /api/v1/moderators 
This route provides the ability to add a single Moderator
.
Creating a Moderator
has the following restrictions:
- A
name
andemail
must always be provided. AuserId
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 sametenantId
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:

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



POST /api/v1/moderators/:id/send-invite 
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 than100 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:

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


DELETE /api/v1/moderators/:id 
This route provides the removal of a Moderator
by id.



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:

GET /api/v1/pages 
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.



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 
Individual pages can be fetched by their corresponding urlId
. This can be useful for looking up page titles or comment counts.



Helpful Tip
Remember to URI Encode values like the urlId
.
PATCH /api/v1/pages/:id 
This route provides the ability to update a single Page
.



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 
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 aPage
object! You can try fetching it via the/by-url-id
Page
route, passing in the sameurlId
passed to the comment widget. - The
Page
structure contains some calculated values. Currently, these arecommentCount
androotCommentCount
. They are populated automatically and cannot be set by the API. Attempting to do so will cause the API to return an error.



DELETE /api/v1/pages/:id 
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.



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:

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 
This route returns SSO Users in pages of 100
. Pagination is provided by the skip
parameter. Users are sorted by their signUpDate
and id
.



GET /api/v1/sso-users/by-id/:id 
This route returns a single SSO user by their id.



GET /api/v1/sso-users/by-email/:email 
This route returns a single SSO user by their email.



PATCH /api/v1/sso-users/:id 
This route provides the ability to update a single SSO user.



POST /api/v1/sso-users 
This route provides the creation of a single SSO user.
Trying to create two users with the same ID will result in an error.

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


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 
This route provides the ability to update a single SSO user.

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


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



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:

GET /api/v1/tenant-daily-usage 
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).



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:

GET /api/v1/tenants/:id 
This route returns a single Tenant by id.



GET /api/v1/tenants 
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.



POST /api/v1/tenants 
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 than200 characters
. - The
email
may not be longer than300 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 yourparent tenant
with white labeling enabled.
We can create a Tenant
with only a few parameters:



PATCH /api/v1/tenants/:id 
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 than200 characters
. - The
email
may not be longer than300 characters
. - The
email
must be unique across all of FastComments.com tenants. - When setting
billingInfoValid
totrue
,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.



DELETE /api/v1/tenants/:id 
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 totrue
.



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:

GET /api/v1/tenant-packages/:id 
This route returns a single Tenant Package by id.



GET /api/v1/tenant-packages 
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.



POST /api/v1/tenant-packages 
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 allflex*
parameters are required.
- The
name
may not be longer than50 characters
. - Each
forWhoText
item may not be longer than200 characters
. - Each
featureTaglines
item may not be longer than100 characters
. - The
TenantPackage
must be "smaller" than the parent tenant. For example, all of themax*
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:



PATCH /api/v1/tenant-packages/:id 
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 allflex*
parameters are required in that same request. - The
name
may not be longer than50 characters
. - Each
forWhoText
item may not be longer than200 characters
. - Each
featureTaglines
item may not be longer than100 characters
. - The
TenantPackage
must be "smaller" than the parent tenant. For example, all of themax*
parameters must have lower values than the parent tenant. - You may not change the
tenantId
associated with aTenantPackage
.



DELETE /api/v1/tenant-packages/:id 
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.



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:

GET /api/v1/tenant-users/:id 
This route returns a single TenantUser by id.



GET /api/v1/tenant-users 
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.



POST /api/v1/tenant-users 
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



POST /api/v1/tenant-users/:id/send-login-link 
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
theTenantUser
belongs to.
We can send a login link to a TenantUser
as follows:

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


PATCH /api/v1/tenant-users/:id 
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



DELETE /api/v1/tenant-users/:id 
This route provides the removal of a TenantUser
by id.



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:

GET /api/v1/votes 
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.



GET /api/v1/votes/for-user 
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
.



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



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 correspondingComment
.
DELETE /api/v1/votes/:id 
This route provides the ability to delete a single Vote
.



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 correspondingComment
.
DomainConfig Structure 
A DomainConfig
object represents configuration for a domain for a tenant.
The structure for the DomainConfig
object is as follows:


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 
This API provides the ability to fetch all DomainConfig
objects for a tenant.



GET /api/v1/domain-configs/:domain 
Individual DomainConfigs can be fetched by their corresponding domain
.



POST /api/v1/domain-configs 
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.



PATCH /api/v1/domain-configs/:domain 
This API endpoint provides the ability to update a domain configuration by only specifying the domain and the attribute to update.



PUT /api/v1/domain-configs/:domain 
This API endpoint provides the ability to replace a domain configuration.



DELETE /api/v1/domain-configs/:domain 
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).



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