Skip to main content

​
Overview

Articles are knowledge base content that help customers find answers to common questions. Articles are organized into categories and can be searched by customers and agents.

​
Article DocType Fields

The HD Article DocType contains the following fields:
​
name
string
Auto-generated hash identifier
​
title
string
required
Article title
​
content
HTML
Article content in HTML format
​
category
Link
Category the article belongs to (links to HD Article Category)
​
status
Select
default:"Draft"
Article status: Published, Draft, or Archived
​
author
Link
User who created the article
​
published_on
datetime
When the article was published
​
views
integer
default:"0"
Number of times the article has been viewed

​
Get Article

Retrieve a single article with all details.
This endpoint is defined in helpdesk/api/knowledge_base.py:11 and allows guest access
@frappe.whitelist(allow_guest=True)
def get_article(name: str):
    """Get article details
    
    Returns article with author info and user's feedback.
    Only published articles are accessible to non-agents.
    """
​
name
string
required
The article ID (hash identifier)

​
Response

​
name
string
Article ID
​
title
string
Article title
​
content
HTML
Article content
​
author
object
Author information from frappe.utils.get_user_info_for_avatar
​
creation
datetime
When the article was created
​
status
string
Article status
​
published_on
datetime
Publication date
​
modified
datetime
Last modification date
​
category_name
string
Display name of the category
​
category_id
string
Category ID
​
feedback
integer
Current user’s feedback (0 if none, or feedback value)

​
Permissions

  • Agents can view articles in any status
  • Non-agents (including guests) can only view Published articles
  • Throws PermissionError if non-agent tries to access non-published article

​
Example Request

import frappe

article = frappe.call(
    "helpdesk.api.knowledge_base.get_article",
    name="a9b8c7d6e5"
)

print(f"Title: {article['title']}")
print(f"Views: {article['views']}")

​
Search Articles

Search articles using natural language processing.
This endpoint is defined in helpdesk/api/article.py:44
@frappe.whitelist()
def search(query: str) -> list:
    """Search articles using NLP
    
    Uses TextBlob for noun phrase extraction and fallback strategies
    to find the most relevant articles.
    """
​
query
string
required
Search query text

​
Search Strategy

The search uses a progressive fallback approach:
  1. Sanitize query: Remove special characters, convert to lowercase
  2. Direct search: Search for the full query
  3. Noun phrases: Extract noun phrases using TextBlob and search
  4. Nouns only: Extract individual nouns and search
  5. Uses both AND and OR matching modes for better results

​
Response

Returns an array of article matches with relevance scoring.

​
Example Request

import frappe

results = frappe.call(
    "helpdesk.api.article.search",
    query="how to reset my password"
)

for article in results:
    print(f"Found: {article['title']}")

​
Delete Articles

Delete multiple articles at once. 
@frappe.whitelist()
def delete_articles(articles: list[str]):
    """Delete multiple articles"""
​
articles
array
required
Array of article IDs to delete

​
Example Request

import frappe

frappe.call(
    "helpdesk.api.knowledge_base.delete_articles",
    articles=["a1b2c3", "d4e5f6"]
)

​
Create Category

Create a new article category with an initial article. 
@frappe.whitelist()
def create_category(title: str):
    """Create category with initial article"""
​
title
string
required
Category name

​
Response

​
article
string
ID of the created article
​
category
string
ID of the created category

​
Example Request

import frappe

result = frappe.call(
    "helpdesk.api.knowledge_base.create_category",
    title="Billing FAQs"
)

print(f"Category: {result['category']}")
print(f"Article: {result['article']}")

​
Move Articles to Category

Move one or more articles to a different category. 
@frappe.whitelist()
def move_to_category(category: str, articles: list[str]):
    """Move articles to a different category"""
​
category
string
required
Target category ID
​
articles
array
required
Array of article IDs to move

​
Validation

  • Requires write permission on HD Article
  • Prevents moving the last article from a category (throws error)

​
Example Request

import frappe

frappe.call(
    "helpdesk.api.knowledge_base.move_to_category",
    category="new-category-id",
    articles=["article1", "article2"]
)

​
Get Categories

Retrieve all article categories with article counts. 
@frappe.whitelist()
def get_categories():
    """Get all categories sorted by article count"""

​
Response

Returns array of category objects:
​
name
string
Category ID
​
category_name
string
Display name
​
modified
datetime
Last modification date
​
article_count
integer
Number of published articles in this category

​
Behavior

  • Sorted by article count (descending)
  • Only includes categories with published articles
  • General category appears first if it exists

​
Example Request

import frappe

categories = frappe.call(
    "helpdesk.api.knowledge_base.get_categories"
)

for cat in categories:
    print(f"{cat['category_name']}: {cat['article_count']} articles")

​
Get Category Articles

Get all published articles in a specific category. 
@frappe.whitelist()
def get_category_articles(category: str):
    """Get published articles in a category"""
​
category
string
required
Category ID

​
Response

Returns array of article objects with:
  • name, title, published_on, modified
  • author (with avatar info)
  • content (truncated to 100 characters, HTML stripped)

​
Example Request

import frappe

articles = frappe.call(
    "helpdesk.api.knowledge_base.get_category_articles",
    category="getting-started"
)

for article in articles:
    print(f"{article['title']} by {article['author']['fullname']}")

​
Merge Categories

Merge one category into another, moving all articles. 
@frappe.whitelist()
def merge_category(source: str, target: str):
    """Merge source category into target"""
​
source
string
required
Source category ID to merge from
​
target
string
required
Target category ID to merge into

​
Validation

  • Requires delete permission on HD Article Category
  • Source and target must be different
  • Cannot merge the General category

​
Example Request

import frappe

frappe.call(
    "helpdesk.api.knowledge_base.merge_category",
    source="old-category",
    target="new-category"
)

​
Get General Category

Retrieve the ID of the “General” category. 
@frappe.whitelist()
def get_general_category():
    """Get the General category ID"""

​
Get Category Title

Get the display name of a category. 
@frappe.whitelist()
def get_category_title(category: str):
    """Get category display name"""

​
Increment Article Views

Track article views (rate-limited to once per hour per user). 
@frappe.whitelist()
@rate_limit(key="article", seconds=60 * 60)
def increment_views(article: str):
    """Increment article view count"""
​
article
string
required
Article ID

​
Rate Limiting

  • Limited to 1 request per hour per user
  • Uses Redis-based rate limiting

​
Example: Complete Article Workflow

import frappe

# 1. Create a category
result = frappe.call(
    "helpdesk.api.knowledge_base.create_category",
    title="Troubleshooting"
)

category_id = result['category']
article_id = result['article']

# 2. Update the article
article = frappe.get_doc("HD Article", article_id)
article.title = "How to Reset Your Password"
article.content = "<p>Step by step instructions...</p>"
article.save()

# 3. Publish the article
article.status = "Published"
article.save()

# 4. View the article
view_data = frappe.call(
    "helpdesk.api.knowledge_base.get_article",
    name=article_id
)

print(f"Published: {view_data['title']}")

Build docs developers (and LLMs) love

Get started for freeTalk to us