zpe-comments

GET /_/api/v1/config One site's comment settings, its Turnstile sitekey and the length limit getConfig

One site's comment settings, its Turnstile sitekey and the length limit

Parameters

name	in	required	type	notes
`site`	query	yes	string	The site's slug — its address under this app's mount.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	This site's comment settings, its Turnstile site key, and its length and edit-window limits.	object
`404`	No site answers to that `site` slug.	object
`500`	This app failed while answering	object

Example

One site's comment settings, its Turnstile sitekey and the length limit, with a token from the door.

GET /_/api/v1/config

curl -X GET 'https://zpe.vc/comments/_/api/v1/config?site=string' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

GET /_/api/v1/bootstrap One post's comment tree, with the settings a composer needs getBootstrap

One post's comment tree, with the settings a composer needs

Parameters

name	in	required	type	notes
`site`	query	yes	string	The site's slug — its address under this app's mount.
`slug`	query	yes	string	The post's slug, as the site's own URLs spell it.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	One post's comment tree, with the settings and limits a composer needs.	object
`400`	`slug` is missing or malformed, so the post cannot be addressed.	object
`404`	No site answers to that `site` slug.	object
`500`	This app failed while answering	object

Example

One post's comment tree, with the settings a composer needs, with a token from the door.

GET /_/api/v1/bootstrap

curl -X GET 'https://zpe.vc/comments/_/api/v1/bootstrap?site=string&slug=string' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

GET /_/api/v1/comments One post's comment tree getComments

One post's comment tree

Parameters

name	in	required	type	notes
`site`	query	yes	string	The site's slug — its address under this app's mount.
`slug`	query	yes	string	The post's slug, as the site's own URLs spell it.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	One post's comment tree.	object
`400`	`slug` is missing or malformed, so the post cannot be addressed.	object
`404`	No site answers to that `site` slug.	object
`500`	This app failed while answering	object

Example

One post's comment tree, with a token from the door.

GET /_/api/v1/comments

curl -X GET 'https://zpe.vc/comments/_/api/v1/comments?site=string&slug=string' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

POST /_/api/v1/comments Post an anonymous comment behind a Turnstile answer postComments

Post an anonymous comment behind a Turnstile answer

Parameters

name	in	required	type	notes
`Idempotency-Key`	header	no	string	A value that names this attempt. Send the same one when retrying and the answer is the row the first call wrote (`200`) instead of a second row; present and empty is refused.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	Nothing new was written: this `Idempotency-Key` already made a comment here, and this is the row the first call wrote.	object
`201`	The comment was written. `status` is `approved`, or `pending` when the site holds first comments or the blocklist matched; `depth` is 1 for a top-level comment.	object
`400`	The body is not one JSON object, `site` or `slug` is missing or malformed, the name or the text is refused, the honeypot field is filled, the Turnstile answer was rejected, or `Idempotency-Key` was sent empty.	object
`401`	The credential is missing or does not open this account	object
`403`	The request came from another origin, comments are disabled on this site, or this address is banned.	object
`404`	No site answers to that `site` slug.	object
`415`	The request is not `application/json`.	object
`429`	This address posted too often; `retry-after` says when to try again.	object
`503`	This deployment holds no Turnstile secret, so no write can be checked.	object

Example

Post an anonymous comment behind a Turnstile answer, with a token from the door.

POST /_/api/v1/comments

curl -X POST 'https://zpe.vc/comments/_/api/v1/comments' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{
  "comment": {
    "id": "string",
    "parent_id": null,
    "status": "approved",
    "created_at": 0,
    "body_html": "string",
    "author": {
      "name": "string"
    },
    "depth": 0
  }
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

PATCH /_/api/v1/comments/{id} Edit your own comment inside the edit window patchCommentsById

Edit your own comment inside the edit window

Parameters

name	in	required	type	notes
`id`	path	yes	string	The comment's id, as the tree answered it.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	The comment's text was replaced; `body_html` and `edited_at` carry the new row.	object
`400`	The body is not one JSON object, or the text is refused — empty, over the length limit, or otherwise unacceptable.	object
`403`	The request came from another origin, or this site's edit window is closed or has passed.	object
`404`	No comment with that id, or it is not this visitor's to edit. A deleted or spam-marked row answers the same, so a caller learns nothing about a comment it does not own.	object
`415`	The request is not `application/json`.	object
`500`	This app failed while answering	object

Example

Edit your own comment inside the edit window, with a token from the door.

PATCH /_/api/v1/comments/{id}

curl -X PATCH 'https://zpe.vc/comments/_/api/v1/comments/string' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

DELETE /_/api/v1/comments/{id} Delete your own comment, or any comment on a site you own deleteCommentsById

Delete your own comment, or any comment on a site you own

Parameters

name	in	required	type	notes
`id`	path	yes	string	The comment's id, as the tree answered it.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	The comment was deleted: by its author, or by the account that owns its site.	object
`403`	The request came from another origin.	object
`404`	No comment with that id, or it is neither this visitor's own nor on a site the caller owns.	object
`500`	This app failed while answering	object

Example

Delete your own comment, or any comment on a site you own, with a token from the door.

DELETE /_/api/v1/comments/{id}

curl -X DELETE 'https://zpe.vc/comments/_/api/v1/comments/string' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

POST /_/api/v1/comments/{id}/report Report a comment to the site's owner, once per reader postCommentsByIdReport

Report a comment to the site's owner, once per reader

Parameters

name	in	required	type	notes
`id`	path	yes	string	The id of the comment being reported.
`Idempotency-Key`	header	no	string	A value that names this attempt. Send the same one when retrying and the answer is the row the first call wrote (`200`) instead of a second row; present and empty is refused.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	Nothing new was written: this reader already reported this comment, or this `Idempotency-Key` already filed one. `duplicate` is `true`.	object
`201`	The report was filed and is open for the site's owner.	object
`400`	The body is not one JSON object, `reason` is missing, or `Idempotency-Key` was sent empty.	object
`401`	The credential is missing or does not open this account	object
`403`	The request came from another origin.	object
`404`	No comment answers to that id in any account this app serves.	object
`415`	The request is not `application/json`.	object
`429`	Too many requests	object

Example

Report a comment to the site's owner, once per reader, with a token from the door.

POST /_/api/v1/comments/{id}/report

curl -X POST 'https://zpe.vc/comments/_/api/v1/comments/string/report' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{
  "reported": false,
  "duplicate": false
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

GET /_/api/v1/operator/queue The moderation queue, with its open report counts getOperatorQueue

The moderation queue, with its open report counts

Parameters

No parameters.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	The moderation queue, with each comment's open report count.	object
`401`	No key and no session: this caller is not signed in at the door.	object
`403`	The key is revoked, is not granted this app, or belongs to an account the door will not scope here.	object
`429`	The key has spent its request ceiling; `retry-after` says when to try again.	object
`500`	This app failed while answering	object
`503`	The door or this deployment's key store did not answer, so the key could not be checked — not a verdict on the key.	object

Example

The moderation queue, with its open report counts, with a token from the door.

GET /_/api/v1/operator/queue

curl -X GET 'https://zpe.vc/comments/_/api/v1/operator/queue' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

POST /_/api/v1/operator/moderate Moderate, ban or unban with a key instead of the console postOperatorModerate

Moderate, ban or unban with a key instead of the console

Parameters

No parameters.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	The moderation action was applied, and `status` is the comment's new state.	object
`400`	The body is not one JSON object, names no action or an unknown one, or is missing the `comment_id` or `user_id` its action needs.	object
`401`	No key and no session: this caller is not signed in at the door.	object
`403`	The request came from another origin, or the key is revoked, not granted this app, or scoped to an account that may not moderate here.	object
`404`	No comment or commenter answers to that id in this account.	object
`415`	The request is not `application/json`.	object
`429`	The key has spent its request ceiling; `retry-after` says when to try again.	object
`500`	This app failed while answering	object
`503`	The door or this deployment's key store did not answer, so the key could not be checked — not a verdict on the key.	object

Example

Moderate, ban or unban with a key instead of the console, with a token from the door.

POST /_/api/v1/operator/moderate

curl -X POST 'https://zpe.vc/comments/_/api/v1/operator/moderate' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Matches in other apps

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example