},

"category_id": "category-slug"

}' \

"https://api.help.center/v0/centers/$HC_CENTER_ID/articles"

```

1. Publish if requested:

```bash

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"