helpcenter（helpcenter 搜索）

Help.Center Article Management

Manage help center articles through the Help.Center API. Supports creating new articles, reading and updating existing ones, publishing/unpublishing, and organizing by category.

Prerequisites

Before making any API calls, you need two pieces of information from the user:

1. API Key - Created in Help.Center dashboard under Settings > General > API

- The key must have appropriate scopes: - content.read - Required for searching/reading articles - content.write - Required for creating/updating articles and categories - content.publish - Required for publishing/unpublishing articles - content.delete - Required for deleting articles or categories

1. Center ID - Found on the same page

If the user hasn't provided these, ask for them before proceeding. Store them as environment variables for the session:

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

Base URL

https://api.help.center

Authentication

All requests require the API key in the Authorization header:

Authorization: Bearer $HC_API_KEY

Workflow

When the user wants to UPDATE an existing article

1. Search for the article first to find its ID and 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?search=SEARCH_TERM&expand[]=content"

1. Read the full article using the article ID from search results:

   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"

1. Update only the specific part the user wants changed. Merge the user's changes into the existing HTML content, preserving everything else. Update via the draft endpoint:

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

1. Publish the updated article (ask the user first if they want to publish or keep as draft):

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

When the user wants to CREATE a new article

1. List categories so the article can be assigned properly:

   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"

1. Write the article content as clean, well-structured HTML. Follow these content guidelines:

- Use semantic HTML: <h1> for main title, <h2> for sections, <h3> for subsections - Use <p> tags for paragraphs - Use <ul>/<ol> for lists - Use <code> for inline code and <pre><code> for code blocks - Use <strong> for emphasis on key terms - Use <a href="..."> for links - Keep the tone clear, helpful, and concise - Structure content so users can scan and find what they need quickly

1. Create the article:

   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"
     }' \
     "https://api.help.center/v0/centers/$HC_CENTER_ID/articles"

1. Publish if requested:

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

Important Rules

1. Always search before creating. If the user says "write an article about X", search for existing articles on that topic first. If one exists, confirm with the user whether they want to update it or create a new one.

1. Preserve existing content when updating. Never overwrite an entire article when only a section needs changing. Fetch the current content, modify the relevant part, and send back the full updated HTML.

1. Always ask before publishing. Default to creating as draft. Only publish when the user explicitly asks for it.

1. Handle errors gracefully. Check HTTP status codes. Common issues:

- 401: API key is invalid or missing - 403: Insufficient permissions (missing required scope) - 404: Article or center not found - 400: Missing required fields (title is always required) - 429: Rate limited (wait and retry)

1. Use pagination for large result sets. The API returns max 100 articles per request. Use starting_after with the last article's ID to fetch more.

API Quick Reference

Content Writing Guidelines

When writing help center articles:

• Lead with the outcome. Start by telling the user what they'll be able to do after reading.
• Use short paragraphs. 2-3 sentences max per paragraph.
• Add step-by-step instructions with numbered lists for procedures.
• Include examples wherever possible to make abstract concepts concrete.
• Use screenshots or visuals references where helpful (use the image upload endpoint to host images, then reference the returned URL in your HTML).
• End with next steps or related articles when relevant.
• Write for scanning. Use descriptive headings so users can jump to what they need.

Category Management

Categories help organize your articles. You can create hierarchical categories with one level of subcategories.

Creating a 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>",  // Optional custom SVG icon
    "parent_id": "parent-cat-id"  // Optional, for subcategories
  }' \
  "https://api.help.center/v0/centers/$HC_CENTER_ID/articles/categories"

Updating a 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"

Deleting a category:

Categories can only be deleted if no articles are using them.

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

Image Upload

Upload images for use in your articles:

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"

Constraints:

• Maximum size: 10MB
• Supported formats: JPEG, PNG, GIF, WebP, SVG
• Use multipart/form-data with field name image

The response will include the image URL to use in your article HTML:

{
  "success": true,
  "data": {
    "url": "https://cdn.help.center/images/...",
    "filename": "image.jpg",
    "size": 1024576
  }
}

SEO Metadata

When creating articles, optionally include SEO metadata:

{
  "metadata": {
    "seo": {
      "title": "Concise, keyword-rich title (50-60 chars)",
      "description": "Clear summary of the article (150-160 chars)"
    }
  }
}

You can also update SEO metadata on existing articles via the metadata endpoint:

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