What This Update Actually Is
HubSpot shipped a Knowledge Base API with 15 new endpoints on September 28, 2026. Before this, every article in your HubSpot knowledge base had to be created, edited, and published by hand inside the portal UI.
Now developers can interact with four resource types through the API:
- Knowledge Bases: list all knowledge bases in an account and read their settings, language, domain, and access type.
- Articles: create, retrieve, update, and unpublish articles. New articles start as DRAFT and need a separate publish call to go live.
- Drafts: retrieve, update, and publish draft versions independently so staged edits stay separate from the live article.
- Categories and Tags: read-only access to the organizational structure, including parent and subcategory relationships.
One important caveat: categories and tags are read-only. You can read the structure, but you can't create or modify it through the API today.
Why HubSpot Shipped This
The external problem is straightforward. Humans managing hundreds or thousands of knowledge base articles were stuck doing it one article at a time inside the HubSpot UI. There was no way to bulk import, no way to sync from Confluence, Notion, or a custom docs system, and no way to automate the article lifecycle.
The internal frustration is just as real. Teams that built polished documentation in another system couldn't get it into HubSpot without copy-paste marathons. That friction either meant content never made it to the knowledge base or it arrived stale.
HubSpot also flagged AI-powered content generation pipelines as a key use case. With the API open, teams can now wire Breeze or any external AI tool into an article creation workflow. That makes the knowledge base a living system instead of a static archive.
How to Use It Step by Step
Here's the practical path to get up and running:
- Confirm your account tier. The Knowledge Base feature requires Service Hub Professional or Enterprise. If it's not active, the API endpoints won't return data.
- Build or update your OAuth app. You'll need to request three scopes: cms.knowledge_base.articles.read for all GET and list calls, cms.knowledge_base.articles.write for creating and updating articles, and cms.knowledge_base.articles.publish for publishing and unpublishing.
- List your knowledge bases. Use the Knowledge Bases endpoint to pull the IDs, settings, and language configurations you'll need in subsequent calls.
- Read your categories and tags. Pull the organizational structure first so you can assign articles to the correct categories when you create them.
- Create articles as drafts. Post to the Articles endpoint. Every new article lands in DRAFT status automatically. Build your content, set metadata, and assign categories at this stage.
- Publish when ready. Make a separate publish call against the Drafts endpoint to push the article live. This two-step process gives you a staging layer before anything hits your customers.
- Automate updates and syncs. Once you have the create-and-publish flow working, wire it into your migration script, content sync pipeline, or AI generation workflow.
What It Touches in Your HubSpot Strategy
This update lives in Service Hub, but its ripple is wider than it looks.
On the service side, a well-maintained knowledge base directly reduces ticket volume. Humans on your support team spend less time answering the same questions when self-service content stays current. The API makes "current" achievable at scale.
On the RevOps and integrations side, this is the missing link for teams running documentation in Confluence, Notion, or a Git-based docs system. You can now treat HubSpot's knowledge base as a publish target rather than a source of truth. That separation is healthy for many orgs.
Key Takeaway
The two-step draft-then-publish flow isn't overhead. It's a staging layer that lets you run quality checks, AI content reviews, or approval gates before anything goes live to customers.
On the AI side, this is where things get interesting. Teams exploring AI-generated support content can now build a pipeline: generate an article draft with Breeze or an external model, post it to HubSpot via the API in draft status, run a review step, then publish. That loop keeps humans in control while removing the manual copy-paste bottleneck.
Pair this API with HubSpot's automatic similar ticket suggestions in Help Desk and you start to see a full self-service loop: tickets surface similar resolved cases, those resolved cases point to knowledge base articles, and the articles stay fresh because your pipeline keeps them updated.
Key Takeaway
Categories and tags are read-only in this release. Plan your knowledge base taxonomy inside the HubSpot UI first. The API can read it and assign articles to it, but it can't create or restructure it yet.
If your org is actively working on reducing post-sales churn, a scalable knowledge base is one of the highest-leverage tools you have. We've written about fixing common post-sales challenges with HubSpot and self-service content quality comes up every time.
Who Should Care Most
This update isn't for every HubSpot account. It's specifically valuable for a few profiles:
- Developer-led teams on Service Hub Pro or Enterprise who already maintain internal tooling and want to automate content operations.
- Companies migrating from Zendesk, Freshdesk, or another support platform that need to bulk-import hundreds of existing articles into HubSpot without a copy-paste project.
- RevOps and ops leaders running a multi-source documentation environment, where a Git-based or Confluence-managed docs set needs to stay synced with what customers see in HubSpot.
- AI-forward teams experimenting with automated content generation who want a publish target that doesn't require manual UI work after every generation run.
- SaaS companies with fast-moving product documentation that goes stale quickly and needs a programmatic update process, not a manual one.
If your knowledge base has fewer than 50 articles and your team updates it manually a few times a month, the API probably won't change your day-to-day. But if you're managing documentation at scale, this removes a real bottleneck.
George's Take
“The knowledge base has always been one of the most underused tools in Service Hub. Not because humans don't want to use it, but because keeping it current at any real scale was a manual nightmare. Now that the API is open, the knowledge base can finally behave like a living system. The teams that connect this to an AI generation pipeline and a solid review workflow are going to have a self-service layer that actually deflects tickets instead of just existing.”
We've audited a lot of HubSpot portals where the knowledge base section was either empty or years out of date. The friction wasn't a lack of will, it was the absence of tooling to keep it maintained without a dedicated person doing nothing else. The API doesn't solve the strategy problem, but it removes the execution wall. That's a meaningful shift.
If you're not sure whether your portal is set up to take advantage of updates like this one, our HubSpot portal audit checklist covers the service and content areas where we see the most unused potential.
Ready to build a documentation system that actually scales? Book a strategy call with the Sidekick team and we'll map out exactly how the Knowledge Base API fits your HubSpot setup.
Frequently Asked Questions
What is the HubSpot Knowledge Base API?
The HubSpot Knowledge Base API is a set of 15 new endpoints that lets developers programmatically create, update, retrieve, and publish knowledge base articles. It also provides read access to knowledge base settings, categories, and tags. It's available for Service Hub Professional and Enterprise accounts.
What HubSpot plan do I need to use the Knowledge Base API?
You need a Service Hub Professional or Enterprise account. Knowledge base functionality isn't available on Free or Starter tiers, so the API endpoints won't work without the right subscription in place.
Can I bulk import articles into HubSpot using the Knowledge Base API?
Yes. The Articles endpoints support creating multiple articles programmatically, which makes bulk imports possible. You can also sync content from external documentation systems by scripting the create and publish calls against your existing content library.
What OAuth scopes does the HubSpot Knowledge Base API require?
You need three scopes: cms.knowledge_base.articles.read for all GET and list calls, cms.knowledge_base.articles.write for creating and updating articles, and cms.knowledge_base.articles.publish for publishing and unpublishing articles. All three must be added to your OAuth app.
Can I create or modify knowledge base categories and tags through the API?
No, not in the current release. Categories and tags are read-only through the API. You can retrieve the full organizational structure and use it to assign articles to existing categories, but you can't create new categories or tags programmatically yet.
How does the draft and publish workflow work in the Knowledge Base API?
Every new article is created in DRAFT status automatically. To make it visible to customers, you call the separate publish endpoint against the draft. This two-step flow lets you stage edits, run reviews, or apply quality checks before anything goes live.
