Help center API

Help articles in categories, for your customers and your support team.

Module code help_center · 8 actions · 2 data models · 7 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: help_center (everything), help_center:read (read only) or help_center:<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

help_center.archive_article

Archive — Retires an article without deleting it.

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

• Canonical address: POST /api/v1/actions/help_center.archive_article

Input

Preconditions

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

Events it publishes: help_center.article_archived

What it writes: help_article (update) — Marks it archived

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

{
  "ok": true,
  "result": "…",
  "events": [
    "help_center.article_archived"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.helpArticles.archiveArticle("HELP_ARTICLE_ID")

era help_articles archive_article HELP_ARTICLE_ID

{
  "name": "era__help_center__archive_article",
  "arguments": {
    "id": "HELP_ARTICLE_ID"
  }
}

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

help_center.create_article

Draft an article — A new help article, as a draft.

Needs help_center:write · changes data

• Canonical address: POST /api/v1/actions/help_center.create_article

Input

Preconditions

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

Events it publishes: help_center.article_created

What it writes: help_article (insert) — Writes the draft

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

{
  "ok": true,
  "result": "…",
  "events": [
    "help_center.article_created"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.helpArticles.createArticle({
  title: "Title"
})

era help_articles create_article \
  --title "Title"

{
  "name": "era__help_center__create_article",
  "arguments": {
    "title": "Title"
  }
}

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

help_center.delete_article

Delete an article — Removes an article for good. Archive it instead to keep it.

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

• Canonical address: POST /api/v1/actions/help_center.delete_article

Input

Preconditions

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

Events it publishes: help_center.article_deleted

What it writes: help_article (delete) — Deletes the article

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

{
  "ok": true,
  "result": "…",
  "events": [
    "help_center.article_deleted"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.helpArticles.deleteArticle("HELP_ARTICLE_ID")

era help_articles delete_article HELP_ARTICLE_ID

{
  "name": "era__help_center__delete_article",
  "arguments": {
    "id": "HELP_ARTICLE_ID"
  }
}

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

help_center.delete_category

Delete a category — Removes an empty category.

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

• Canonical address: POST /api/v1/actions/help_center.delete_category

Input

Preconditions

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

Events it publishes: help_center.category_changed

What it writes: help_category (delete) — Deletes the category

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

{
  "ok": true,
  "result": "…",
  "events": [
    "help_center.category_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.helpCategories.deleteCategory("HELP_CATEGORY_ID")

era help_categories delete_category HELP_CATEGORY_ID

{
  "name": "era__help_center__delete_category",
  "arguments": {
    "id": "HELP_CATEGORY_ID"
  }
}

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

help_center.publish_article

Publish — Makes the article public — Chatwoot’s published state, content required.

Needs help_center:write · reaches outside (sends, publishes or charges)

• Canonical address: POST /api/v1/actions/help_center.publish_article

Input

Preconditions

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

Events it publishes: help_center.article_published

What it writes: help_article (update) — Marks it published

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

{
  "ok": true,
  "result": "…",
  "events": [
    "help_center.article_published"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.helpArticles.publishArticle("HELP_ARTICLE_ID")

era help_articles publish_article HELP_ARTICLE_ID

{
  "name": "era__help_center__publish_article",
  "arguments": {
    "id": "HELP_ARTICLE_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold help_center:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 help_article_not_found, help_article_already_in_state, help_article_needs_content · 429 slow down

help_center.save_category

Save a category — Creates a help category, or renames and moves one.

Needs help_center:manage · changes data

• Canonical address: POST /api/v1/actions/help_center.save_category

Input

Preconditions

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

Events it publishes: help_center.category_changed

What it writes: help_category (upsert) — Writes the category

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

{
  "ok": true,
  "result": "…",
  "events": [
    "help_center.category_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.helpCategories.saveCategory("HELP_CATEGORY_ID", {
  name: "Name"
})

era help_categories save_category HELP_CATEGORY_ID \
  --name "Name"

{
  "name": "era__help_center__save_category",
  "arguments": {
    "id": "HELP_CATEGORY_ID",
    "name": "Name"
  }
}

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

help_center.unpublish_article

Back to draft — Takes a published or archived article back to a draft.

Needs help_center:write · reaches outside (sends, publishes or charges)

• Canonical address: POST /api/v1/actions/help_center.unpublish_article

Input

Preconditions

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

Events it publishes: help_center.article_unpublished

What it writes: help_article (update) — Marks it a draft

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

{
  "ok": true,
  "result": "…",
  "events": [
    "help_center.article_unpublished"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.helpArticles.unpublishArticle("HELP_ARTICLE_ID")

era help_articles unpublish_article HELP_ARTICLE_ID

{
  "name": "era__help_center__unpublish_article",
  "arguments": {
    "id": "HELP_ARTICLE_ID"
  }
}

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

help_center.update_article

Edit an article — Changes an article’s title, summary, content or category.

Needs help_center:write · changes data

• Canonical address: POST /api/v1/actions/help_center.update_article

Input

Preconditions

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

Events it publishes: help_center.article_updated

What it writes: help_article (update) — Rewrites the article

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

{
  "ok": true,
  "result": "…",
  "events": [
    "help_center.article_updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.helpArticles.updateArticle("HELP_ARTICLE_ID", {
  title: "Title"
})

era help_articles update_article HELP_ARTICLE_ID \
  --title "Title"

{
  "name": "era__help_center__update_article",
  "arguments": {
    "id": "HELP_ARTICLE_ID",
    "title": "Title"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold help_center:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 help_article_not_found, help_category_not_found, help_article_needs_content, help_article_invalid_tags · 429 slow down

Data models

HelpArticle

Table help_article · Resource help_articles

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

Primary key: id

Unique: workspace_id, locale, slug

Checks:

• CHECK ((cardinality(meta_tags) <= 30))
• CHECK (((meta_title IS NULL) OR (length(meta_title) <= 255)))
• CHECK (((status <> 'published'::text) OR (length(TRIM(BOTH FROM content)) > 0)))
• CHECK ((slug ~ '^[a-z0-9]+(-[a-z0-9]+)*$'::text))
• CHECK ((length(TRIM(BOTH FROM title)) > 0))

HelpCategory

Table help_category · Resource help_categories

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

Primary key: id

Unique: workspace_id, locale, slug

Checks:

• CHECK ((length(TRIM(BOTH FROM name)) > 0))
• CHECK ((slug ~ '^[a-z0-9]+(-[a-z0-9]+)*$'::text))

Events

Workflows and webhooks react to these events.