> ## Documentation Index > Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # HubSpot Knowledge Base > Import knowledge base articles from HubSpot Service Hub Import articles from HubSpot Service Hub into AGO as knowledge sources. ## Overview The HubSpot Knowledge Base connector allows you to import content from HubSpot Service Hub Knowledge Base, including: * **Categories**: Organizational groupings for articles * **Articles**: Individual knowledge base articles with rich HTML content The connector converts HTML content to Markdown format and preserves the hierarchical category-article structure. > **Note**: This connector imports from HubSpot's **Knowledge Base** (Service Hub). For HubSpot **ticketing** integration, see [HubSpot Ticketing](./hubspot-integration). ## Features * **Article Import**: Fetch published, draft, or all articles * **Category Support**: Import category hierarchy * **HTML to Markdown Conversion**: Automatically converts article HTML to Markdown * **Hierarchical Structure**: Preserves category-article parent-child relationships * **Category Filtering**: Import only specific categories by ID * **State Filtering**: Filter articles by publication state (Published, Draft, All) * **Incremental Updates**: Version-controlled imports with deduplication ## Prerequisites ### HubSpot Requirements 1. **Service Hub Professional or Enterprise**: The Knowledge Base feature requires a paid Service Hub tier 2. **Private App**: Create a private app with the required API scope 3. **Scope**: `cms.knowledge_base.articles.read` ### Creating a HubSpot Private App 1. In HubSpot, go to **Settings** > **Integrations** > **Private Apps** 2. Click **Create a private app** 3. Enter a name (e.g., `AGO Knowledge Base`) 4. Go to the **Scopes** tab 5. Under **CMS**, enable: `cms.knowledge_base.articles.read` 6. Click **Create app** 7. Copy the **Access Token** (store it securely) ### Finding Your Portal ID Your Portal ID appears in your HubSpot URL: ``` https://app.hubspot.com/contacts/12345678/... ^^^^^^^^ This is your Portal ID ``` ## Configuration ### Knowledge Source Setup Create a new Knowledge Source with the following configuration: 1. Navigate to **Knowledge** > **Sources** > **Add Source** 2. Select **HubSpot Knowledge Base** as the source type 3. Enter a name (e.g., "My HubSpot Knowledge Base") 4. Paste your Private App access token 5. Configure the import options described below 6. Click **Save** ### Configuration Parameters | Parameter | Type | Required | Description | | ----------------------- | ------- | -------- | ---------------------------------------------------------------------------- | | `portal_id` | string | No | HubSpot portal ID for constructing external links | | `knowledge_base_domain` | string | No | Custom domain for external knowledge base links | | `import_categories` | boolean | No | Whether to import category documents (default: true) | | `import_articles` | boolean | No | Whether to import article documents (default: true) | | `category_filter` | array | No | List of category IDs to import (empty = import all) | | `state_filter` | string | No | Article state: `PUBLISHED`, `DRAFT`, or empty for all (default: `PUBLISHED`) | ## Usage Examples ### Import Only Published Articles ```json theme={null} { "additional_info": { "portal_id": "12345678", "import_categories": true, "import_articles": true, "state_filter": "PUBLISHED" } } ``` ### Import Specific Categories Import only articles from selected categories: ```json theme={null} { "additional_info": { "portal_id": "12345678", "category_filter": ["cat_123", "cat_456"], "state_filter": "PUBLISHED" } } ``` ### Import All Content Including Drafts ```json theme={null} { "additional_info": { "portal_id": "12345678", "state_filter": "" } } ``` ## Content Processing ### HTML to Markdown Conversion Article content is automatically converted from HTML to Markdown: * Headings are converted to ATX format (`# Heading`) * Lists, links, and formatting are preserved * The article title is prepended as a top-level heading ### Metadata Preservation Each imported document retains key properties from HubSpot: | Property | Applies To | Description | | ----------------------- | -------------------- | -------------------------------------------------- | | Type | Categories, Articles | Whether the imported item is a category or article | | Position | Categories, Articles | Sort order within the parent group | | Created / Updated dates | Categories | Original timestamps from HubSpot | | Category | Articles | The parent category name and association | | Publication state | Articles | Whether the article is Published or Draft | | Path | Articles | The URL path of the article in HubSpot | ## Hierarchical Structure The connector preserves the HubSpot Knowledge Base hierarchy: ```mermaid theme={null} flowchart TD A["Category (parent: null)"] --> B["Article (parent: category)"] A --> C["Article (parent: category)"] D["Category (parent: null)"] --> E["Article (parent: category)"] ``` Articles without a matching category are imported as top-level documents. ## Error Handling The connector includes error handling for common scenarios: * **Invalid credentials**: Clear error messages for authentication failures * **Missing content**: Skips articles that fail to process without stopping the import * **Categories endpoint unavailable**: Falls back gracefully if the categories REST endpoint returns 404 * **Rate limiting**: HubSpot private apps are limited to 100 requests per 10 seconds ## Best Practices ### Improving Sync Speed 1. **Filter Content**: Use category and state filters for large knowledge bases 2. **Published Only**: Import only published articles unless drafts are needed 3. **Incremental Updates**: Version IDs track import iterations automatically ### Content Management 1. **Regular Syncs**: Schedule periodic imports to capture content updates 2. **Review Content**: Check imported documents for formatting issues after initial import 3. **Category Organization**: Use HubSpot categories to organize content before import ### Security 1. **Private App Security**: Use a dedicated private app with minimal scopes 2. **Token Rotation**: Rotate private app tokens periodically 3. **Scope Limitation**: Only grant `cms.knowledge_base.articles.read` scope ## Troubleshooting ### Common Issues * Verify the private app access token is correct and not revoked * Ensure the private app has the `cms.knowledge_base.articles.read` scope * Check that your HubSpot account has Service Hub Professional or Enterprise * Verify articles exist in your HubSpot Knowledge Base * Check that the `state_filter` matches your articles' publication state * Ensure `category_filter` IDs are correct (if set) * The categories REST endpoint may not be available in all HubSpot tiers * The connector falls back gracefully; articles are still imported without category hierarchy * Provide a `portal_id` in the configuration to enable external link generation * External links use the format `https://app.hubspot.com/knowledge/{portal_id}/articles/{path}` *** ## Related Documentation * [HubSpot Ticketing](./hubspot-integration) - HubSpot ticketing integration * [Knowledge Connectors](./knowledge-connectors) - All available knowledge connectors * [Knowledge Source Management](../features/knowledge-source-management) - Source configuration * [Zendesk Integration](./zendesk-integration) - Similar help center connector