Comments API

Public API

The comment read and submit endpoints are part of Studio's public, versioned API (/api/comments/v1/), designed to be called directly from the site that renders the entry. Moderation, thread locking and import are part of the internal application API.

Studio-managed comments attach to content entries. Comments live in the Studio database (never in Git) and are served to any site through the public API. Per-model configuration lives on the model definition next to form, so it travels with the repository.

Enabling Comments on a Model

Comments are enabled per model with a comments block, saved through the model update route (workspace owner or admin). Only collection and document models can carry comments.

PATCH /api/workspaces/:workspaceId/projects/:projectId/models/:modelId

json

{
  "comments": {
    "enabled": true,
    "requireApproval": true,
    "captcha": "turnstile"
  }
}

Key	Default	Description
`enabled`	`false`	Accept comments on this model's entries
`requireApproval`	`true`	New comments start `pending`; `false` publishes immediately (needs `comments.auto_approve`, otherwise it stays `true`)
`maxDepth`	`4`	Reply nesting cap for new public submissions (`0` = flat, max `10`). Imports are never clamped.
`requireEmail`	`true`	Commenters must supply an email; it is never shown publicly
`honeypot`	`true`	Hidden `_hp` field; a filled honeypot is silently accepted and dropped
`notifications`	`true`	Email the workspace owners and admins when a comment arrives
`captcha`	`null`	`'turnstile'` to require a Cloudflare Turnstile token (needs `comments.captcha`, otherwise it is reset to `null`)
`rateLimitPerIp`	`5`	Submissions per IP per minute on one entry (1 to 60)
`maxBodyLength`	`5000`	Body length cap for public submissions (100 to 20000)

Errors: 403 comments.upgrade (plan lacks comments.enabled, or the plan's model limit is reached), 400 comments.not_collection (model kind cannot carry comments).

Public Endpoints

These endpoints require no authentication. Both return Access-Control-Allow-Origin: *, and the OPTIONS preflight is answered with 204 (the preflight allows only the Content-Type header, so do not send Authorization).

Read Comments

Get the approved comment threads of one entry, plus the configuration your embed needs.

GET /api/comments/v1/:projectId/:modelId/:entryId

Parameter	Type	Default	Description
`locale`	`string`	project default	Entry locale. An invalid value falls back to the default.
`page`	`number`	`1`	Page of root comments
`limit`	`number`	`20`	Roots per page (1 to 100)
`sort`	`string`	`oldest`	`oldest` or `newest` (any other value means `oldest`)

Response

json

{
  "entry": { "modelId": "posts", "entryId": "a1b2c3d4e5f6", "locale": "en" },
  "config": {
    "closed": false,
    "requireApproval": true,
    "requireEmail": true,
    "maxDepth": 4,
    "maxBodyLength": 5000,
    "captcha": "turnstile",
    "captchaSiteKey": "0x4AAAA...",
    "honeypotField": "_hp"
  },
  "comments": [
    {
      "id": "uuid",
      "parentId": null,
      "depth": 0,
      "author": { "name": "Ada", "url": "https://ada.dev/", "isModerator": false },
      "body": "Plain text",
      "type": "comment",
      "createdAt": "2026-05-01T10:00:00.000Z",
      "replies": []
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}

Pagination is over root comments; every approved reply under the page's roots is nested inside them.
Only approved comments are returned. A reply whose parent is not approved is not shown.
Email, IP address, user agent and referrer are never returned.
body is plain text; render it escaped. author.url is an http(s) address or null.
config.closed is true when the thread is locked: render the comments but hide the form.
config.captcha is "turnstile" only when the model asks for it and the plan includes comments.captcha; captchaSiteKey is null until the operator sets NUXT_PUBLIC_TURNSTILE_SITE_KEY.

The read endpoint is limited per IP (429 comments.rate_limited).

Submit a Comment

Post a comment, or a reply to an approved comment.

POST /api/comments/v1/:projectId/:modelId/:entryId?locale=en

Request Body

Field	Type	Required	Description
`author.name`	`string`	Yes	Display name (max 120 characters)
`author.email`	`string`	Conditional	Required when `requireEmail` is on; never shown publicly
`author.url`	`string`	No	Author website (`http` or `https`)
`body`	`string`	Yes	Comment text (up to `maxBodyLength`); HTML is stripped
`parentId`	`string`	No	ID of the comment being replied to
`captchaToken`	`string`	Conditional	Turnstile token (when captcha is configured)
`_hp`	`string`	No	Honeypot field (must be empty -- bots fill it)

Response

Success:

json

{
  "success": true,
  "status": "pending",
  "comment": { "id": "uuid", "parentId": null, "depth": 0, "author": { "name": "Ada", "url": null, "isModerator": false }, "body": "Hello", "type": "comment", "createdAt": "2026-05-01T10:00:00.000Z", "replies": [] }
}

status is approved when the model does not require approval (and the plan allows it), otherwise pending. Pending comments are only echoed back to their author.

Validation error (HTTP 200):

json

{
  "success": false,
  "errors": [
    { "field": "author.email", "message": "..." }
  ]
}

Error field values: author.name, author.email, author.url, body, parentId (missing, not found, or nested too deep) and captcha.

Other Errors

Status	Cause
`403`	The thread is closed for this entry, or the plan lacks `comments.enabled` (also when the model is beyond the plan's model limit)
`404`	Unknown project or model, or comments are disabled on the model
`429`	Per-IP rate limit (`rateLimitPerIp`, per IP and entry), or the workspace's monthly comment quota
`402`	The workspace's billing is locked (also returned by the read endpoint). Do not retry; hide the widget.

A filled honeypot returns { "success": true, "status": "pending" } without storing anything.

Notifications and Webhooks

Unless the model sets notifications: false, Studio emails the workspace owners and admins when a comment arrives. Plans with comments.webhook_notification also dispatch comment.submitted and comment.approved webhook events.

Plan Features

Feature key	Purpose
`comments.enabled`	Comments at all
`comments.models`	Number of models with comments enabled
`comments.per_month`	Public comments per month (imports and moderator replies do not count)
`comments.captcha`	Turnstile captcha
`comments.auto_approve`	Publish without approval
`comments.import`	WordPress comment import
`comments.webhook_notification`	Comment webhook events

See Billing & Plans for the values per plan.

Moderation Endpoints

These endpoints require a session and a plan with comments.enabled (403 comments.upgrade). Listing is open to workspace owners and admins and to members assigned to the project; every other route is limited to workspace owners and admins. A comment outside the project returns 404 comments.comment_not_found.

List Comments

GET /api/workspaces/:workspaceId/projects/:projectId/comments

Parameter	Type	Default	Description
`status`	`string`	(all)	`pending`, `approved`, `rejected`, `spam`
`modelId`	`string`	--	Filter by model
`entryId`	`string`	--	Filter by entry
`locale`	`string`	--	Filter by locale
`page`	`number`	`1`	Page number
`limit`	`number`	`50`	Items per page (max `100`)
`sort`	`string`	`newest`	`newest` or `oldest`

Returns { comments, total, counts, page, limit }, where counts holds the number of comments per status.

Update Comment Status

PATCH /api/workspaces/:workspaceId/projects/:projectId/comments/:commentId

Field	Type	Required	Description
`status`	`'approved' \| 'rejected' \| 'spam' \| 'pending'`	Yes	New status

Returns the updated comment. 400 comments.invalid_status for any other value.

Delete Comment

DELETE /api/workspaces/:workspaceId/projects/:projectId/comments/:commentId

Replies are deleted with the comment. Returns { "deleted": true }.

Reply as Moderator

POST /api/workspaces/:workspaceId/projects/:projectId/comments/:commentId/reply

Field	Type	Required	Description
`body`	`string`	Yes	Reply text (max 20000 characters)

The reply is published immediately and marked as a moderator reply (isModerator). Replying to a comment that is not yet approved approves it first. Returns the created reply.

Bulk Update

POST /api/workspaces/:workspaceId/projects/:projectId/comments/bulk

Field	Type	Required	Description
`action`	`'approve' \| 'reject' \| 'spam' \| 'pending' \| 'delete'`	Yes	Action applied to every comment
`commentIds`	`string[]`	Yes	Comment IDs (max 50, else `400` `comments.bulk_limit`)

delete returns { "action", "results": [{ "id", "success", "error?" }], "succeeded": 3 } and writes an audit log entry per comment; the other actions return { "action", "updated": 3 }.

Open or Close a Thread

PATCH /api/workspaces/:workspaceId/projects/:projectId/comments/threads/:modelId/:entryId

Field	Type	Required	Description
`closed`	`boolean`	Yes	`true` to close, `false` to reopen
`locale`	`string`	No	Entry locale (project default when omitted)

A closed thread still shows its comments; the public submit endpoint refuses new ones with 403. Returns { modelId, entryId, locale, closed, closedAt }.

Import WordPress Comments

Import a contentrain-comments@1 export (the comments-export.json produced by the WordPress importer).

POST /api/workspaces/:workspaceId/projects/:projectId/comments/import

The body is the export document. The optional locale query parameter sets the default locale for entry references that carry none. Requires the comments.import plan feature (403 comments.upgrade). Up to 5000 comments per request; send larger exports in chunks.

Every comment whose post maps to an entry is inserted with its source date, status, type and parent link, and reply depth is never clamped. Rows are keyed on their source ID, so re-sending an export is safe. A comment whose post has no entry mapping is reported in unmapped, never dropped silently.

json

{
  "received": 3,
  "mapped": 2,
  "inserted": 2,
  "skippedExisting": 0,
  "unmapped": [{ "comment_id": 9, "post": 77 }],
  "orphanCount": 0,
  "orphanParents": [],
  "maxDepth": 3,
  "threadsClosed": 1,
  "datesDefaulted": 0
}

Forms API -- the same embedding model for form submissions
Webhooks API -- comment.submitted and comment.approved events

Comments API ​

Enabling Comments on a Model ​

Public Endpoints ​

Read Comments ​

Response ​

Submit a Comment ​

Request Body ​

Response ​

Other Errors ​

Notifications and Webhooks ​

Plan Features ​

Moderation Endpoints ​

List Comments ​

Update Comment Status ​

Delete Comment ​

Reply as Moderator ​

Bulk Update ​

Open or Close a Thread ​

Import WordPress Comments ​

Related Pages ​

Comments API

Enabling Comments on a Model

Public Endpoints

Read Comments

Response

Submit a Comment

Request Body

Response

Other Errors

Notifications and Webhooks

Plan Features

Moderation Endpoints

List Comments

Update Comment Status

Delete Comment

Reply as Moderator

Bulk Update

Open or Close a Thread

Import WordPress Comments

Related Pages