Help.Center Article Management

intent

use this skill when the user wants to create, update, read, search, or manage help center articles through the help.center api. trigger on requests like "write a help article", "update the docs", "publish an article", "add to the help center", "create a knowledge base article", "edit the getting started guide", or when the user mentions help.center, help articles, knowledge base content management, article search, draft management, category changes, or publish/unpublish workflows.

inputs

api credentials (required before any api call)

• HC_API_KEY: api key from help.center dashboard (settings > general > api). must have appropriate scopes:
  • content.read: search and read articles
  • content.write: create, update articles and categories
  • content.publish: publish/unpublish articles
  • content.delete: delete articles or categories
• HC_CENTER_ID: center id from the same dashboard page

store both as environment variables:

export HC_API_KEY="the_api_key"
export HC_CENTER_ID="the_center_id"

external connection

• help.center api endpoint: https://api.help.center
• all requests require header: Authorization: Bearer $HC_API_KEY

edge cases to handle

• missing or invalid api key (401 response)
• insufficient permissions for requested scope (403 response)
• article or center not found (404 response)
• missing required fields like title (400 response)
• rate limiting (429 response, implement exponential backoff)
• network timeout or connection failures
• empty search result sets
• pagination limits (max 100 articles per request)
• auth token expiry during long sessions

procedure

step 1: validate credentials and gather context

• confirm HC_API_KEY and HC_CENTER_ID are set as environment variables
• if missing, ask the user to provide them from the help.center dashboard
• test connection by making a simple get request to /v0/centers/$HC_CENTER_ID
• input: user request (create, update, read, search, or manage)
• output: confirmed credentials or prompt for missing values

step 2: determine action type

• parse user request to identify intent: create new article, update existing article, search/read articles, manage drafts, publish/unpublish, manage categories, or upload images
• input: user's stated action
• output: action type (create, update, read, search, manage_draft, publish, unpublish, category, image)

step 3: search for existing articles (if updating or checking for duplicates)

execute GET request to search endpoint:

curl -s -X GET \
  -H "Authorization: Bearer $HC_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.help.center/v0/centers/$HC_CENTER_ID/articles?search=SEARCH_TERM&expand[]=content"

• input: search term (article topic or title), pagination cursor if needed
• output: list of matching articles with ids, titles, and metadata. if result set exceeds 100 articles, use starting_after parameter with last article id to fetch next page
• on empty result set, proceed to create new article or confirm with user

step 4a: for CREATE workflow

1. list available categories:

curl -s -X GET \
  -H "Authorization: Bearer $HC_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.help.center/v0/centers/$HC_CENTER_ID/articles/categories"

• input: (none)
• output: list of category ids and names

2. write article content as clean, well-structured html, following content guidelines:

   • use semantic html: <h1> for main title, <h2> for sections, <h3> for subsections
   • use <p> tags for paragraphs, <ul>/<ol> for lists
   • use <code> for inline code, <pre><code> for code blocks
   • use <strong> for key term emphasis
   • use <a href="..."> for links
   • keep tone clear, helpful, concise
   • structure for scanning: descriptive headings, short paragraphs (2-3 sentences max), numbered steps for procedures, concrete examples, screenshots/visual references where helpful
   • input: user's article content requirements
   • output: validated html content

3. create article via POST:

curl -s -X POST \
  -H "Authorization: Bearer $HC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Article Title",
    "content": {
      "html": "<h1>Title</h1><p>Content here...</p>"
    },
    "category_id": "category-slug",
    "metadata": {
      "seo": {
        "title": "SEO Title (50-60 chars)",
        "description": "SEO Description (150-160 chars)"
      }
    }
  }' \
  "https://api.help.center/v0/centers/$HC_CENTER_ID/articles"

• input: title, html content, category_id, optional seo metadata
• output: article id, created article object, publication status (draft by default)
• handle 400 errors (missing required fields), 403 errors (insufficient permissions), 429 errors (rate limit, wait and retry)

step 4b: for UPDATE workflow

1. fetch full article with current content:

curl -s -X GET \
  -H "Authorization: Bearer $HC_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.help.center/v0/centers/$HC_CENTER_ID/articles/ARTICLE_ID?expand[]=content"

• input: article_id
• output: full article object including current html content

2. merge user changes into existing html content. preserve all sections not being modified. if entire content replacement is requested, confirm explicitly with user first.

   • input: current html, user's change request (specific section or full replacement)
   • output: merged html content ready for submission

3. update article draft via PATCH:

curl -s -X PATCH \
  -H "Authorization: Bearer $HC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Title (if changed)",
    "html": "<h1>Updated full HTML content with changes merged in</h1>"
  }' \
  "https://api.help.center/v0/centers/$HC_CENTER_ID/articles/ARTICLE_ID/draft"

• input: article_id, updated title (optional), merged html
• output: updated draft object with new revision

4. optionally update seo metadata via PATCH to metadata endpoint:

curl -s -X PATCH \
  -H "Authorization: Bearer $HC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "seo": {
      "title": "New SEO Title",
      "description": "New SEO Description"
    }
  }' \
  "https://api.help.center/v0/centers/$HC_CENTER_ID/articles/ARTICLE_ID/metadata"

• input: article_id, new seo title and description
• output: metadata confirmation

step 4c: for READ/SEARCH workflow

execute GET request:

curl -s -X GET \
  -H "Authorization: Bearer $HC_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.help.center/v0/centers/$HC_CENTER_ID/articles?search=SEARCH_TERM&expand[]=content"

or fetch specific article:

curl -s -X GET \
  -H "Authorization: Bearer $HC_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.help.center/v0/centers/$HC_CENTER_ID/articles/ARTICLE_ID"

• input: search term or article_id
• output: article object(s) with title, content, metadata, publication status

step 4d: for DRAFT MANAGEMENT workflow

list all drafts:

curl -s -X GET \
  -H "Authorization: Bearer $HC_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.help.center/v0/centers/$HC_CENTER_ID/articles/drafts"

• input: (none)
• output: list of all draft articles

discard a draft:

curl -s -X POST \
  -H "Authorization: Bearer $HC_API_KEY" \
  "https://api.help.center/v0/centers/$HC_CENTER_ID/articles/ARTICLE_ID/draft/discard"

• input: article_id
• output: confirmation that draft was discarded

step 4e: for PUBLISH/UNPUBLISH workflow

publish an article:

curl -s -X POST \
  -H "Authorization: Bearer $HC_API_KEY" \
  "https://api.help.center/v0/centers/$HC_CENTER_ID/articles/ARTICLE_ID/publish"

• input: article_id
• output: published article object with publication timestamp

unpublish an article:

curl -s -X POST \
  -H "Authorization: Bearer $HC_API_KEY" \
  "https://api.help.center/v0/centers/$HC_CENTER_ID/articles/ARTICLE_ID/unpublish"

• input: article_id
• output: unpublished article object, moved back to draft status

step 4f: for CATEGORY MANAGEMENT workflow

create category:

curl -s -X POST \
  -H "Authorization: Bearer $HC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Getting Started",
    "description": "Articles for new users",
    "icon": "<svg>...</svg>",
    "parent_id": "parent-cat-id"
  }' \
  "https://api.help.center/v0/centers/$HC_CENTER_ID/articles/categories"

• input: category name, description, optional custom svg icon, optional parent_id (for subcategories, one level only)
• output: created category object with id

update category:

curl -s -X PATCH \
  -H "Authorization: Bearer $HC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "description": "Updated description",
    "icon": "<svg>...</svg>"
  }' \
  "https://api.help.center/v0/centers/$HC_CENTER_ID/articles/categories/CATEGORY_ID"

• input: category_id, updated name/description/icon
• output: updated category object

delete category:

curl -s -X DELETE \
  -H "Authorization: Bearer $HC_API_KEY" \
  "https://api.help.center/v0/centers/$HC_CENTER_ID/articles/categories/CATEGORY_ID"

• input: category_id
• output: deletion confirmation (fails with 400 if any articles still use this category)

step 4g: for IMAGE UPLOAD workflow

upload image:

curl -s -X POST \
  -H "Authorization: Bearer $HC_API_KEY" \
  -F "image=@/path/to/image.jpg" \
  "https://api.help.center/v0/centers/$HC_CENTER_ID/articles/images"

• input: image file path (jpeg, png, gif, webp, or svg, max 10mb)
• output: json object with url (cdn url for use in article html), filename, size
• use returned url in article html as <img src="https://cdn.help.center/images/..." alt="description">

step 5: publish if requested

ask user before publishing (default to draft). if user explicitly requests publish:

curl -s -X POST \
  -H "Authorization: Bearer $HC_API_KEY" \
  "https://api.help.center/v0/centers/$HC_CENTER_ID/articles/ARTICLE_ID/publish"

• input: article_id, user confirmation
• output: published article object with timestamp

step 6: handle errors and provide feedback

• 401: api key invalid or missing. prompt user to regenerate key from help.center dashboard
• 403: insufficient permissions. confirm user's api key has required scope for the operation (content.read, content.write, content.publish, content.delete)
• 404: article or center not found. verify article_id and HC_CENTER_ID are correct
• 400: missing required fields (title always required). validate all required fields are present before submission
• 429: rate limited. implement exponential backoff (wait 1s, then 2s, 4s, 8s) and retry up to 3 times
• network timeout: retry operation after 5 second wait, up to 2 attempts
• input: error response status and body
• output: clear error message to user with remediation steps

decision points

if user says "write an article about X"

• search for existing articles on topic X first
• if match found: ask user "found existing article [title]. do you want to update it or create a new one?"
  • if update: go to step 4b (update workflow)
  • if create new: confirm user understands duplicate will exist, then proceed to step 4a (create workflow)
• if no match: proceed to step 4a (create workflow)

if user wants to update an article but only specific section

• fetch full current content (step 4b.1)
• preserve all unchanged sections
• merge only the user's requested changes
• never overwrite entire article content without explicit user confirmation

if user creates article but doesn't request publish

• default to draft status (do not auto-publish)
• inform user article is saved as draft
• ask "want me to publish this now?" if user seems ready

if user tries to delete a category

• check if any articles reference that category
• if yes: reject deletion and inform user "category still has X articles using it. remove articles from category or delete articles first"
• if no: proceed with deletion

if api returns 429 rate limit error

• implement exponential backoff: wait 1s, retry; wait 2s, retry; wait 4s, retry
• if still failing after 3 attempts: inform user "help.center api is temporarily rate limited. try again in a few minutes"

if network connection fails or timeout occurs

• retry operation once after 5 second wait
• if retry fails: inform user "network error connecting to help.center api. check your connection and try again"

if search result set is larger than 100 articles

• use pagination with starting_after parameter
• fetch next batch using last article's id
• continue until all results reviewed or user stops requesting more

if user provides api key with insufficient scopes

• operation will return 403 forbidden
• ask user to regenerate api key with required scopes for their requested action

output contract

for create article success

• response json object containing:
  • id: unique article identifier
  • title: article title
  • status: "draft" (unless published in same flow)
  • created_at: iso 8601 timestamp
  • url: publicly accessible article url (if published)

for update article success

• response json object containing:
  • id: article identifier
  • title: updated title
  • status: "draft" (until published)
  • updated_at: iso 8601 timestamp

for search/read success

• array of article objects (or single object) containing:
  • id, title, html content, status, category_id, created_at, updated_at
  • empty array if no matches found

for publish success

• response json object containing:
  • id: article identifier
  • status: "published"
  • published_at: iso 8601 timestamp
  • url: public article url

for category operations success

• response json object containing:
  • id: category identifier
  • name, description, parent_id (if applicable)

for image upload success

• response json object containing:
  • url: cdn url string (use this in html)
  • filename: original filename
  • size: file size in bytes

for errors

• http status code (401, 403, 404, 400, 429)
• response json with error field describing issue
• user receives clear error message with remediation steps

outcome signal

the user knows the skill worked when:

• article created: skill confirms "created article [title]" with article id and reports status as draft or published
• article updated: skill confirms "updated article [title]" showing what changed and reporting new draft revision
• article read/searched: skill displays matching article(s) with titles, summaries, and metadata
• article published: skill confirms "published [title]" with public url user can click/access
• article unpublished: skill confirms article moved back to draft status
• draft discarded: skill confirms draft was discarded, existing published version unaffected
• category created/updated: skill confirms category is ready for article assignments
• image uploaded: skill displays public cdn url ready to insert in article html
• error handled gracefully: skill explains what failed (e.g. "missing api key", "article not found") and tells user how to fix it