Webflow Comments API
The Webflow Comments API provides endpoints for listing comment threads and retrieving comment replies within a Webflow site.
OpenAPI Specification
openapi: 3.1.0
info:
title: Webflow Comments API
description: Webflow Data API v2 - Comments endpoints.
version: 2.0.0
contact:
name: Webflow Developer Relations
email: [email protected]
url: https://developers.webflow.com
termsOfService: https://webflow.com/legal/terms
license:
name: MIT
url: https://opensource.org/licenses/MIT
servers:
- url: https://api.webflow.com/v2
description: Webflow API v2
x-fern-server-name: Data API
security:
- OAuth2: []
- ApiKey: []
tags:
- name: Comments
- name: Sites
description: Sites are the sites in your Webflow workspace.
paths:
/sites/{site_id}/comments:
get:
x-fern-sdk-group-name:
- sites
- comments
x-fern-sdk-method-name: list-comment-threads
security:
- OAuth2:
- comments:read
operationId: list-comment-threads
summary: Webflow List Comment Threads
description: "List all comment threads for a site.\n\n<Note title=\"Timing of comment threads\">\n There may be a delay of up to 5 minutes before new comments appear in the system.\n</Note>\n\nRequired scope | `comments:read`\n"
tags:
- Comments
- Sites
parameters:
- name: site_id
in: path
description: Unique identifier for a Site
example: 580e63e98c9a982ac9b8b741
required: true
schema:
type: string
format: objectid
default:
- name: localeId
in: query
allowEmptyValue: true
example: 65427cf400e02b306eaa04a0
description: 'Unique identifier for a specific Locale.
[Lear more about localization.](/data/v2.0.0/docs/working-with-localization)
'
schema:
type: string
- in: query
example: 0
allowEmptyValue: true
name: offset
description: Offset used for pagination if the results have more than limit records
required: false
schema:
type: integer
- in: query
allowEmptyValue: true
name: limit
example: 100
description: 'Maximum number of records to be returned (max limit: 100)'
required: false
schema:
type: integer
- name: sortBy
in: query
allowEmptyValue: true
description: Sort results by the provided value. Only allowed when sortOrder is provided.
required: false
schema:
type: string
enum:
- createdOn
- lastUpdated
- name: sortOrder
in: query
allowEmptyValue: true
description: Sorts the results by asc or desc
required: false
schema:
type: string
enum:
- asc
- desc
responses:
'200':
description: Request was successful
content:
application/json:
schema:
description: 'A list of comment threads on the site. Contains the content of the first reply.
'
required:
- comments
- pagination
properties:
comments:
type: array
items:
description: 'A comment thread represents a conversation between users on a specific page. Each comment thread has a unique identifier and can contain multiple comments. Retrieve comment replies using the replies API endpoint.
'
type: object
required:
- id
- siteId
- pageId
- localeId
- itemId
- breakpoint
- url
- content
- isResolved
- author
- mentionedUsers
- createdOn
- lastUpdated
properties:
id:
type: string
example: 580e64008c9a982ac9b8b754
description: Unique identifier for the comment thread
siteId:
type: string
example: 580e64008c9a982ac9b8b754
description: The site unique identifier
pageId:
type: string
example: 580e64008c9a982ac9b8b754
description: The page unique identifier
localeId:
type: string
readOnly: true
example: 580e64008c9a982ac9b8b754
description: The locale unique identifier
nullable: true
itemId:
type: string
readOnly: true
example: 580e64008c9a982ac9b8b754
description: The item unique identifier
nullable: true
breakpoint:
type: string
example: main
description: The breakpoint the comment was left on
url:
type: string
example: https://webflow.com/design/site-slug-4ec832?workflow=comment&commentId=679d2ddb5196117ad04d1ff8&pageId=679826b3b20b045e176bc4bc
description: The URL of the page the comment was left on
content:
type: string
example: This is a comment reply
description: The content of the comment reply
isResolved:
type: boolean
default: false
description: Boolean determining if the comment thread is resolved
author:
type: object
required:
- userId
- email
- name
properties:
userId:
type: string
description: The unique identifier of the author
email:
type: string
description: Email of the author
name:
type: string
description: Name of the author
example:
id: 6287ec36a841b25637c663df
email: email
name: name
mentionedUsers:
type: array
description: List of mentioned users. This is an empty array until email notifications are sent, which can take up to 5 minutes after the comment is created.
items:
type: object
required:
- userId
- email
- name
properties:
userId:
type: string
description: The unique identifier of the mentioned user
email:
type: string
description: Email of the user
name:
type: string
description: Name of the User
example:
userId: 6287ec36a841b25637c663df
email: [email protected]
name: Arthur Dent
createdOn:
type: string
format: date-string
example: '2023-03-17T18:47:35.560Z'
description: The date the item was created
lastUpdated:
type: string
format: date-string
example: '2023-03-17T18:47:35.560Z'
description: The date the item was last updated
example:
value:
id: 679d2ddb5196117ad04d1ffa
siteId: 679826b3b20b045e176bc4b5
pageId: 679826b3b20b045e176bc4bc
localeId: 67993753d910db250db64b3e
itemId:
breakpoint: main
url: https://webflow.com/design/site-slug-4ec832?workflow=comment&commentId=679d2ddb5196117ad04d1ff8&pageId=679826b3b20b045e176bc4bc
content: 'This comment mentions another user [[6287ec36a841b25637c663df]] '
isResolved: false
author:
userId: 6287ec36a841b25637c663df
email: [email protected]
name: Ford Prefect
mentionedUsers:
- userId: 6287ec36a841b25637c663df
email: [email protected]
name: Arthur Dent
createdOn: '2025-01-31T20:08:59.759Z'
lastUpdated: '2025-01-31T20:08:59.759Z'
pagination:
type: object
required:
- limit
- offset
- total
properties:
limit:
type: integer
default: 100
description: The limit specified in the request (default 100)
offset:
type: integer
default: 0
description: The offset specified for pagination
total:
type: integer
description: Total number of comment threads
example:
comments:
- id: 679d2ddb5196117ad04d1ffa
siteId: 679826b3b20b045e176bc4b5
pageId: 679826b3b20b045e176bc4bc
localeId: 67993753d910db250db64b3e
itemId:
breakpoint: main
url: https://webflow.com/design/site-slug-4ec832?workflow=comment&commentId=679d2ddb5196117ad04d1ff8&pageId=679826b3b20b045e176bc4bc
content: 'Let''s go to the pub! [[6287ec36a841b25637c663df]] '
isResolved: false
author:
userId: 6287ec36a841b25637c663df
email: [email protected]
name: Ford Prefect
mentionedUsers:
- userId: 6287ec36a841b25637c663df
email: [email protected]
name: Arthur Dent
createdOn: '2025-01-31T20:08:59.759Z'
lastUpdated: '2025-01-31T20:08:59.759Z'
- id: 679d2ddb5196117ad04d1ffc
siteId: 679826b3b20b045e176bc4b5
pageId: 679826b3b20b045e176bc4bc
localeId: 67993753d910db250db64b3e
itemId:
breakpoint: main
url: https://webflow.com/design/site-slug-4ec832?workflow=comment&commentId=679d2ddb5196117ad04d1ff8&pageId=679826b3b20b045e176bc4bc
content: 'You have five minutes left to drink it [[6287ec36a841b25637c663df]] '
isResolved: false
author:
userId: 6287ec36a841b25637c663df
email: [email protected]
name: Ford Prefect
mentionedUsers:
- userId: 6287ec36a841b25637c663df
email: [email protected]
name: Arthur Dent
createdOn: '2025-01-31T20:08:59.759Z'
lastUpdated: '2025-01-31T20:08:59.759Z'
pagination:
limit: 2
offset: 0
total: 2
'400':
description: Request body was incorrectly formatted.
x-logErrorCode: 400
content:
application/json:
schema:
type: object
example:
code: not_authorized
message: Request not authorized
externalReference:
details: []
properties:
code:
type: string
description: Error code
example: not_authorized
enum:
- bad_request
- collection_not_found
- conflict
- duplicate_collection
- duplicate_user_email
- ecommerce_not_enabled
- forbidden
- forms_require_republish
- incompatible_webhook_filter
- internal_error
- invalid_auth_version
- invalid_credentials
- invalid_domain
- invalid_user_email
- item_not_found
- missing_scopes
- no_domains
- not_authorized
- not_enterprise_plan_site
- not_enterprise_plan_workspace
- order_not_found
- resource_not_found
- too_many_requests
- unsupported_version
- unsupported_webhook_trigger_type
- user_limit_reached
- user_not_found
- users_not_enabled
- validation_error
message:
type: string
description: Error message
example: Request not authorized
externalReference:
type: string
description: Link to more information
example: ''
details:
type: array
description: Array of errors
items:
- type: string
example: Invalid email address
description: Error message
- type: object
example:
field: email
message: Invalid email address
description: Error message
example: []
example:
code: bad_request
message: 'Bad Request: Request is malformed'
externalReference:
details: []
'401':
description: Provided access token is invalid or does not have access to requested resource
x-logErrorCode: 401
content:
application/json:
schema:
type: object
example:
code: not_authorized
message: Request not authorized
externalReference:
details: []
properties:
code:
type: string
description: Error code
example: not_authorized
enum:
- bad_request
- collection_not_found
- conflict
- duplicate_collection
- duplicate_user_email
- ecommerce_not_enabled
- forbidden
- forms_require_republish
- incompatible_webhook_filter
- internal_error
- invalid_auth_version
- invalid_credentials
- invalid_domain
- invalid_user_email
- item_not_found
- missing_scopes
- no_domains
- not_authorized
- not_enterprise_plan_site
- not_enterprise_plan_workspace
- order_not_found
- resource_not_found
- too_many_requests
- unsupported_version
- unsupported_webhook_trigger_type
- user_limit_reached
- user_not_found
- users_not_enabled
- validation_error
message:
type: string
description: Error message
example: Request not authorized
externalReference:
type: string
description: Link to more information
example: ''
details:
type: array
description: Array of errors
items:
- type: string
example: Invalid email address
description: Error message
- type: object
example:
field: email
message: Invalid email address
description: Error message
example: []
example:
code: not_authorized
message: Request not authorized
externalReference:
details: []
'404':
description: Requested resource not found
x-logErrorCode: 404
content:
application/json:
schema:
type: object
example:
code: not_authorized
message: Request not authorized
externalReference:
details: []
properties:
code:
type: string
description: Error code
example: not_authorized
enum:
- bad_request
- collection_not_found
- conflict
- duplicate_collection
- duplicate_user_email
- ecommerce_not_enabled
- forbidden
- forms_require_republish
- incompatible_webhook_filter
- internal_error
- invalid_auth_version
- invalid_credentials
- invalid_domain
- invalid_user_email
- item_not_found
- missing_scopes
- no_domains
- not_authorized
- not_enterprise_plan_site
- not_enterprise_plan_workspace
- order_not_found
- resource_not_found
- too_many_requests
- unsupported_version
- unsupported_webhook_trigger_type
- user_limit_reached
- user_not_found
- users_not_enabled
- validation_error
message:
type: string
description: Error message
example: Request not authorized
externalReference:
type: string
description: Link to more information
example: ''
details:
type: array
description: Array of errors
items:
- type: string
example: Invalid email address
description: Error message
- type: object
example:
field: email
message: Invalid email address
description: Error message
example: []
example:
code: resource_not_found
message: 'Requested resource not found: The site cannot be found'
externalReference:
details: []
'429':
description: The rate limit of the provided access_token has been reached. Please have your application respect the X-RateLimit-Remaining header we include on API responses.
x-logErrorCode: 429
headers:
X-RateLimit-Remaining:
description: Contains the number of available requests remaining in the current minute
schema:
type: number
X-RateLimit-Limit:
description: Contains your current overall rate limit per minute
schema:
type: number
content:
application/json:
schema:
type: object
example:
code: not_authorized
message: Request not authorized
externalReference:
details: []
properties:
code:
type: string
description: Error code
example: not_authorized
enum:
- bad_request
- collection_not_found
- conflict
- duplicate_collection
- duplicate_user_email
- ecommerce_not_enabled
- forbidden
- forms_require_republish
- incompatible_webhook_filter
- internal_error
- invalid_auth_version
- invalid_credentials
- invalid_domain
- invalid_user_email
- item_not_found
- missing_scopes
- no_domains
- not_authorized
- not_enterprise_plan_site
- not_enterprise_plan_workspace
- order_not_found
- resource_not_found
- too_many_requests
- unsupported_version
- unsupported_webhook_trigger_type
- user_limit_reached
- user_not_found
- users_not_enabled
- validation_error
message:
type: string
description: Error message
example: Request not authorized
externalReference:
type: string
description: Link to more information
example: ''
details:
type: array
description: Array of errors
items:
- type: string
example: Invalid email address
description: Error message
- type: object
example:
field: email
message: Invalid email address
description: Error message
example: []
example:
code: too_many_requests
message: Too many requests
externalReference:
details: []
'500':
description: We had a problem with our server. Try again later.
content:
application/json:
x-logErrorCode: 500
schema:
type: object
example:
code: not_authorized
message: Request not authorized
externalReference:
details: []
properties:
code:
type: string
description: Error code
example: not_authorized
enum:
- bad_request
- collection_not_found
- conflict
- duplicate_collection
- duplicate_user_email
- ecommerce_not_enabled
- forbidden
- forms_require_republish
- incompatible_webhook_filter
- internal_error
- invalid_auth_version
- invalid_credentials
- invalid_domain
- invalid_user_email
- item_not_found
- missing_scopes
- no_domains
- not_authorized
- not_enterprise_plan_site
- not_enterprise_plan_workspace
- order_not_found
- resource_not_found
- too_many_requests
- unsupported_version
- unsupported_webhook_trigger_type
- user_limit_reached
- user_not_found
- users_not_enabled
- validation_error
message:
type: string
description: Error message
example: Request not authorized
externalReference:
type: string
description: Link to more information
example: ''
details:
type: array
description: Array of errors
items:
- type: string
example: Invalid email address
description: Error message
- type: object
example:
field: email
message: Invalid email address
description: Error message
example: []
example:
code: internal_error
message: An Internal Error occurred
externalReference:
details: []
/sites/{site_id}/comments/{comment_thread_id}:
get:
x-fern-sdk-group-name:
- sites
- comments
x-fern-sdk-method-name: get-comment-thread
security:
- OAuth2:
- comments:read
operationId: get-comment-thread
summary: Webflow Get Comment Thread
description: "Get details of a specific comment thread.\n\n <Note title=\"Timing of comment threads\">\n There may be a delay of up to 5 minutes before new comments appear in the system.\n </Note>\n\nRequired scope | `comments:read`\n"
tags:
- Comments
- Sites
parameters:
- name: site_id
in: path
description: Unique identifier for a Site
example: 580e63e98c9a982ac9b8b741
required: true
schema:
type: string
format: objectid
default:
- name: comment_thread_id
in: path
description: Unique identifier for a Comment Thread
example: 580e63e98c9a982ac9b8b741
required: true
schema:
type: string
format: objectid
- name: localeId
in: query
allowEmptyValue: true
example: 65427cf400e02b306eaa04a0
description: 'Unique identifier for a specific Locale.
[Lear more about localization.](/data/v2.0.0/docs/working-with-localization)
'
schema:
type: string
- in: query
example: 0
allowEmptyValue: true
name: offset
description: Offset used for pagination if the results have more than limit records
required: false
schema:
type: integer
- in: query
allowEmptyValue: true
name: limit
example: 100
description: 'Maximum number of records to be returned (max limit: 100)'
required: false
schema:
type: integer
- name: sortBy
in: query
allowEmptyValue: true
description: Sort results by the provided value. Only allowed when sortOrder is provided.
required: false
schema:
type: string
enum:
- createdOn
- lastUpdated
- name: sortOrder
in: query
allowEmptyValue: true
description: Sorts the results by asc or desc
required: false
schema:
type: string
enum:
- asc
- desc
responses:
'200':
description: Request was successful
content:
application/json:
schema:
description: 'A comment thread represents a conversation between users on a specific page. Each comment thread has a unique identifier and can contain multiple comments. Retrieve comment replies using the replies API endpoint.
'
type: object
required:
- id
- siteId
- pageId
- localeId
- itemId
- breakpoint
- url
- content
- isResolved
- author
- mentionedUsers
- createdOn
- lastUpdated
properties:
id:
type: string
example: 580e64008c9a982ac9b8b754
description: Unique identifier for the comment thread
siteId:
type: string
example: 580e64008c9a982ac9b8b754
description: The site unique identifier
pageId:
type: string
example: 580e64008c9a982ac9b8b754
description: The page unique identifier
localeId:
type: string
readOnly: true
example: 580e64008c9a982ac9b8b754
description: The locale unique identifier
nullable: true
itemId:
type: string
readOnly: true
example: 580e64008c9a982ac9b8b754
description: The item unique identifier
nullable: true
breakpoint:
type: string
example: main
description: The breakpoint the comment was left on
url:
type: string
example: https://webflow.com/design/site-slug-4ec832?w
# --- truncated at 32 KB (76 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/webflow/refs/heads/main/openapi/webflow-comments-openapi.yml