Comments API

Notes and replies on any record, for your team.

Module code comments · 9 actions · 3 data models · 9 events. A key or token never does more here than the person behind it can; row-level security applies exactly as in the app. Scopes: comments (everything), comments:read (read only) or comments:<capability>.

Resources

Lists take limit (up to 200), cursor, order (e.g. -created_at), fields and q; every other query parameter is a column filter: ?status=paid, ?total[gte]=100, ?id[in]=a,b, ?x=null.

Actions

comments.delete

Delete a comment — Removes a comment from the thread. Replies stay and become roots.

Needs comments:read · removes or cannot be undone · asks a person to confirm when Era runs it

• REST alias: DELETE /api/v1/comments/{id}
• Canonical address: POST /api/v1/actions/comments.delete

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: comments.deleted

What it writes: comment (update) — Stamps deleted_at

curl -X POST https://app.getera.io/api/v1/comments/COMMENT_ID/actions/delete \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "comments.deleted"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.comments.delete("COMMENT_ID")

era comments delete COMMENT_ID

{
  "name": "era__comments__delete",
  "arguments": {
    "id": "COMMENT_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold comments:read · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 comment_not_found, cannot_delete_comment · 429 slow down

comments.edit

Edit a comment — Rewrites a comment you wrote, and says on screen that it changed.

Needs comments:read · changes data

• Canonical address: POST /api/v1/actions/comments.edit

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: comments.edited, comments.mentioned

What it writes: comment (update) — Rewrites the body and stamps edited_at; comment_mention (insert) — Records anyone newly mentioned

curl -X POST https://app.getera.io/api/v1/comments/COMMENT_ID/actions/edit \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"body":"Comment"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "comments.edited",
    "comments.mentioned"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.comments.edit("COMMENT_ID", {
  body: "Comment"
})

era comments edit COMMENT_ID \
  --body "Comment"

{
  "name": "era__comments__edit",
  "arguments": {
    "id": "COMMENT_ID",
    "body": "Comment"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold comments:read · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 comment_not_found, not_author, empty_body, mentioned_cannot_read · 429 slow down

comments.post

Comment on a record — Adds a comment to a record. Internal until somebody publishes it.

Needs comments:read · changes data

• Canonical address: POST /api/v1/actions/comments.post

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: comments.posted, comments.mentioned

What it writes: comment (insert) — Writes the comment; comment_mention (insert) — Records who was mentioned

curl -X POST https://app.getera.io/api/v1/comments/actions/post \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"recordType":"Record type","recordId":"RECORD_ID","body":"Comment"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "comments.posted",
    "comments.mentioned"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.comments.post({
  recordType: "Record type",
  recordId: "RECORD_ID",
  body: "Comment"
})

era comments post \
  --record-type "Record type" \
  --record-id "RECORD_ID" \
  --body "Comment"

{
  "name": "era__comments__post",
  "arguments": {
    "recordType": "Record type",
    "recordId": "RECORD_ID",
    "body": "Comment"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold comments:read · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 unknown_record_type, cannot_comment, empty_body, record_not_found, mentioned_cannot_read · 429 slow down

comments.publish

Publish a comment — Shows the comment on the storefront. Not something a default does.

Needs comments:read · reaches outside (sends, publishes or charges) · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/comments.publish

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: comments.published

What it writes: comment (update) — Sets is_public

curl -X POST https://app.getera.io/api/v1/comments/COMMENT_ID/actions/publish \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "comments.published"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.comments.publish("COMMENT_ID")

era comments publish COMMENT_ID

{
  "name": "era__comments__publish",
  "arguments": {
    "id": "COMMENT_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold comments:read · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 comment_not_found, cannot_manage_record, is_a_reply, already_public · 429 slow down

comments.react

React to a comment — Adds your reaction to a comment, or takes it back if you already gave it.

Needs comments:read · removes or cannot be undone

• Canonical address: POST /api/v1/actions/comments.react

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: comments.reacted

What it writes: comment_reaction (insert) — Adds the reaction; comment_reaction (delete) — Takes a reaction back

curl -X POST https://app.getera.io/api/v1/comment_reactions/actions/react \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"COMMENT_ID","reaction":"Reaction"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "comments.reacted"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.commentReactions.react({
  id: "COMMENT_ID",
  reaction: "Reaction"
})

era comment_reactions react \
  --id "COMMENT_ID" \
  --reaction "Reaction"

{
  "name": "era__comments__react",
  "arguments": {
    "id": "COMMENT_ID",
    "reaction": "Reaction"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold comments:read · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 invalid_reaction, comment_not_found, cannot_comment · 429 slow down

comments.reopen

Reopen a thread — Puts a resolved thread back on the list.

Needs comments:read · changes data

• Canonical address: POST /api/v1/actions/comments.reopen

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: comments.reopened

What it writes: comment (update) — Clears resolved_at

curl -X POST https://app.getera.io/api/v1/comments/COMMENT_ID/actions/reopen \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "comments.reopened"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.comments.reopen("COMMENT_ID")

era comments reopen COMMENT_ID

{
  "name": "era__comments__reopen",
  "arguments": {
    "id": "COMMENT_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold comments:read · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 comment_not_found, cannot_comment, not_resolved · 429 slow down

comments.reply

Reply to a comment — Answers a comment. Replies go one level deep and no further.

Needs comments:read · changes data

• Canonical address: POST /api/v1/actions/comments.reply

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: comments.posted, comments.mentioned

What it writes: comment (insert) — Writes the reply; comment_mention (insert) — Records who was mentioned

curl -X POST https://app.getera.io/api/v1/comments/COMMENT_ID/actions/reply \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"body":"Reply"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "comments.posted",
    "comments.mentioned"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.comments.reply("COMMENT_ID", {
  body: "Reply"
})

era comments reply COMMENT_ID \
  --body "Reply"

{
  "name": "era__comments__reply",
  "arguments": {
    "parentId": "COMMENT_ID",
    "body": "Reply"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold comments:read · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 parent_not_found, parent_is_a_reply, cannot_comment, empty_body, mentioned_cannot_read · 429 slow down

comments.resolve

Resolve a thread — Marks the thread as settled, so the panel is a list of what is left.

Needs comments:read · changes data

• Canonical address: POST /api/v1/actions/comments.resolve

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: comments.resolved

What it writes: comment (update) — Stamps resolved_at

curl -X POST https://app.getera.io/api/v1/comments/COMMENT_ID/actions/resolve \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "comments.resolved"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.comments.resolve("COMMENT_ID")

era comments resolve COMMENT_ID

{
  "name": "era__comments__resolve",
  "arguments": {
    "id": "COMMENT_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold comments:read · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 comment_not_found, cannot_comment, is_a_reply, already_resolved · 429 slow down

comments.unpublish

Unpublish a comment — Takes a published comment back off the storefront.

Needs comments:read · changes data

• Canonical address: POST /api/v1/actions/comments.unpublish

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: comments.unpublished

What it writes: comment (update) — Clears is_public

curl -X POST https://app.getera.io/api/v1/comments/COMMENT_ID/actions/unpublish \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "comments.unpublished"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.comments.unpublish("COMMENT_ID")

era comments unpublish COMMENT_ID

{
  "name": "era__comments__unpublish",
  "arguments": {
    "id": "COMMENT_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold comments:read · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 comment_not_found, cannot_manage_record, already_private · 429 slow down

Data models

CommentMention

Table comment_mention · Resource comment_mentions

• GET /api/v1/comment_mentions
• GET /api/v1/comment_mentions/{id}

Primary key: id

CommentReaction

Table comment_reaction · Resource comment_reactions

• GET /api/v1/comment_reactions
• GET /api/v1/comment_reactions/{id}

Primary key: id

Unique: comment_id, user_id, reaction

Checks:

• CHECK (((length(reaction) >= 1) AND (length(reaction) <= 32)))

Comment

Table comment · Resource comments

• GET /api/v1/comments
• GET /api/v1/comments/{id}
• DELETE /api/v1/comments/{id} → comments.delete

Primary key: id

Checks:

• CHECK ((length(btrim(body)) > 0))
• CHECK (((parent_id IS NULL) OR (parent_id <> id)))
• CHECK (((resolved_at IS NULL) OR (parent_id IS NULL)))
• CHECK (((resolved_at IS NULL) = (resolved_by_user_id IS NULL)))

Events

Workflows and webhooks react to these events.