Freshdesk Knowledge Base

Overview

Freshdesk's knowledge base is called Solutions and is organized as a nested, three-level hierarchy. Articles live inside folders, folders live inside categories. Surfacing the right article on a ticket deflects repeat questions and speeds resolution. This skill covers navigating the hierarchy, reading articles, and suggesting articles for tickets through tools named freshdesk_solutions_<action>.

Anti-triggers

Freshdesk Solutions is a customer-facing knowledge base published to the support portal. Writing internal MSP documentation here exposes it to customers.

• Internal runbooks, network diagrams, and client documentation — those belong in an MSP documentation platform; use hudu-articles or itglue-documents. Never draft an internal procedure into a Solutions article.
• Credentials or secrets referenced by a procedure — use hudu-passwords or itglue-passwords; nothing in the Solutions hierarchy is a safe place for them.
• Attaching the article to a ticket or replying with it — ticket replies and notes are freshdesk-ticketing; this skill finds the article, it does not send it.

The Three-Level Hierarchy

Category            (top level — e.g. "Email & Collaboration")
  └─ Folder         (grouping — e.g. "Outlook")
       └─ Article   (the content — e.g. "Fix Outlook disconnected status")

Level	Resource	Parent
Category	/solutions/categories	— (top level)
Folder	/solutions/folders	Category
Article	/solutions/articles	Folder

You traverse top-down: list categories, list the folders within a category, then list the articles within a folder.

Navigating the Hierarchy

List Categories

GET /api/v2/solutions/categories

Returns each category's id, name, and description.

List Folders in a Category

GET /api/v2/solutions/categories/{category_id}/folders

Returns each folder's id, name, description, and visibility (which audiences can see it — e.g. all users, logged-in users, or specific companies/agents).

List Articles in a Folder

GET /api/v2/solutions/folders/{folder_id}/articles

Returns article summaries within the folder.

Get a Single Article

GET /api/v2/solutions/articles/{article_id}

Key Article Fields

Field	Type	Description
id	Integer	Unique identifier
title	String	Article title
description	String (HTML)	Body content
status	Integer	1 = Draft, 2 = Published
folder_id	Integer	Parent folder
category_id	Integer	Parent category
tags	Array	Labels for retrieval
hits	Integer	View count (popularity signal)

Only published articles (status: 2) should be suggested to customers; drafts are internal-only.

Finding an Article — There Is No KB Search

Freshdesk's REST API exposes GET /api/v2/search/solutions?term=..., but this plugin cannot reach it. The MCP server registers no knowledge-base search handler — only list/get/create/update/delete over categories, folders and articles (freshdesk-mcp/src/domains/solutions.ts). Tickets, contacts and companies each get a search tool, so search reads as a house pattern; the knowledge base is the one surface that does not have it.

The real path to an article is the walk:

1. freshdesk_solutions_categories_list — the top level.
2. freshdesk_solutions_folders_list for the category that plausibly owns the topic (takes the parent category_id).
3. freshdesk_solutions_articles_list for that folder (takes folder_id), then freshdesk_solutions_articles_get on the candidates worth reading.

You do the keyword matching yourself, against article title and tags as you walk. The tree is small and changes rarely, so cache it for the session rather than re-listing it per ticket. When a request genuinely needs full-text search across article bodies, say the plugin cannot do it and point the operator at the Freshdesk portal search — do not present a walk as if it were an exhaustive search.

Suggesting KB Articles for a Ticket

A high-value MSP workflow is matching an incoming ticket to existing knowledge so the agent can resolve faster or deflect entirely:

1. Extract the symptom — pull the ticket subject and the first incoming message; identify keywords (product, error text, action).
2. Walk to candidates — pick the category and folder that plausibly own the topic and list their articles. There is no KB search tool; see above.
3. Filter to published — keep only status: 2 articles; ignore drafts.
4. Rank candidates — prefer exact title/tags keyword matches and higher hits (popularity); break ties by recency.
5. Present the top matches — surface 1-3 articles with title and link.
6. Act on the ticket — either attach the article link in a customer-facing reply (deflection) or cite it in an internal note as the resolution path.

Ticket: "Outlook shows Disconnected since this morning"
  walk: category "Email & Collaboration" -> folder "Outlook" -> articles
  candidates (published, ranked by title/tag match + hits):
    1. Fix Outlook disconnected status        (hits: 1,204)
    2. Rebuild the Outlook OST cache           (hits:   538)
  -> reply with article #1 link, or add internal note citing it

Error Handling

Error	Cause	Resolution
404 Not found	Unknown category/folder/article ID	Re-list the parent level to confirm IDs
400 Bad request	freshdesk_solutions_articles_create missing a required field	Supply all of folder_id, title, description, status
403 Forbidden	Folder visibility restricts access	Check folder visibility; the article may be internal

Best Practices

• Respect folder visibility — a folder restricted to agents or specific companies should not be shared more broadly.
• Cache the hierarchy — categories and folders change rarely; cache the tree within a session to reduce request volume.
• Track deflection — note when a suggested article resolved a ticket; it signals which articles to keep current.

Related Skills

• Freshdesk Ticketing - Replying with or citing KB articles on tickets
• Freshdesk API Patterns - Pagination and rate limits while walking the hierarchy
• Freshdesk Contacts & Companies - Company-scoped folder visibility