Skip to main content
Frappe Helpdesk provides a comprehensive REST API built on the Frappe Framework, allowing you to programmatically interact with all aspects of your helpdesk system.

​
Base URL

All API requests should be made to your Frappe Helpdesk instance URL: 
https://your-site.frappe.cloud/api/method/helpdesk.api.*
For self-hosted instances: 
https://your-domain.com/api/method/helpdesk.api.*

​
API Architecture

Frappe Helpdesk uses the Frappe Framework’s API conventions:
  • Custom Methods: Whitelisted Python functions in helpdesk/api/ modules
  • Standard CRUD: Built-in endpoints for DocTypes (frappe.client.*)
  • Real-time: WebSocket support via Socket.IO for live updates

​
Custom API Methods

Custom API endpoints are Python functions decorated with @frappe.whitelist(): 
# helpdesk/api/ticket.py
import frappe

@frappe.whitelist()
def assign_ticket_to_agent(ticket_id, agent_id=None):
    """Assign a ticket to an agent"""
    if not agent_id:
        agent_id = frappe.session.user
    
    ticket_doc = frappe.get_doc("HD Ticket", ticket_id)
    ticket_doc.assign_agent(agent_id)
    return ticket_doc
Access this endpoint at: 
POST /api/method/helpdesk.api.ticket.assign_ticket_to_agent

​
Standard CRUD Operations

For any DocType (HD Ticket, HD Agent, HD Article, etc.), you can use Frappe’s built-in client methods: 
// Get a document
GET /api/resource/HD Ticket/{ticket_id}

// Get a list of documents
GET /api/resource/HD Ticket?filters=[["status","=","Open"]]

// Create a document
POST /api/resource/HD Ticket

// Update a document
PUT /api/resource/HD Ticket/{ticket_id}

// Delete a document
DELETE /api/resource/HD Ticket/{ticket_id}

​
Request Format

​
HTTP Methods

  • GET - Retrieve data
  • POST - Create or execute custom methods
  • PUT - Update data
  • DELETE - Delete data

​
Content Type

All POST/PUT requests should use: 
Content-Type: application/json

​
Request Body

For custom methods, pass parameters as JSON: 
{
  "ticket_id": "HD-00042",
  "agent_id": "[email protected]"
}

​
Response Format

​
Success Response

Successful API calls return JSON with this structure: 
{
  "message": {
    // Response data
  }
}

​
Error Response

Errors return HTTP status codes with error details: 
{
  "exc_type": "PermissionError",
  "exception": "frappe.exceptions.PermissionError: Not permitted",
  "_server_messages": "[\"Error message\"]"
}

​
HTTP Status Codes

  • 200 - Success
  • 201 - Created
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 500 - Internal Server Error

​
Available Resources

Frappe Helpdesk provides APIs for the following resources:

Tickets

Create, update, and manage support tickets

Agents

Manage agents and send invitations

Contacts

Search and manage customer contacts

Articles

Create and manage knowledge base articles

Saved Replies

Template responses with Jinja2 rendering

Assignment Rules

Automated ticket routing and assignment

​
API Endpoints by Module

The Frappe Helpdesk API is organized by module:
ModuleLocationPurpose
Ticketshelpdesk.api.ticketTicket management and assignment
Agentshelpdesk.api.agentAgent invitations and management
Contactshelpdesk.api.contactContact search
Articleshelpdesk.api.articleKnowledge base operations
Knowledge Basehelpdesk.api.knowledge_baseArticle retrieval and search
Assignment Ruleshelpdesk.api.assignment_ruleRule management
Saved Replieshelpdesk.api.saved_repliesTemplate rendering
Dashboardhelpdesk.api.dashboardAnalytics and metrics
Searchhelpdesk.api.searchGlobal search

​
Rate Limiting

Frappe includes built-in rate limiting. Some endpoints use the @rate_limit decorator: 
from frappe.rate_limiter import rate_limit

@frappe.whitelist(allow_guest=True)
@rate_limit(limit=100, seconds=3600)
def get_article(name: str):
    # Limited to 100 calls per hour
    pass
Rate limits vary by endpoint. Monitor your usage to avoid hitting limits.

​
Pagination

For list queries, use limit_start and limit_page_length: 
GET /api/resource/HD Ticket?limit_start=0&limit_page_length=20
Default page size is 20 items.

​
Filtering and Sorting

Use Frappe’s filter syntax: 
// Filters: [["field", "operator", "value"]]
filters=[["status","=","Open"],["priority","in",["High","Urgent"]]]

// Sorting
order_by=creation desc

​
Real-time Updates

Frappe Helpdesk uses Socket.IO for real-time notifications. Connect to: 
wss://your-site.frappe.cloud/socket.io
Events are published for:
  • New ticket assignments
  • Status changes
  • New comments
  • Mentions

​
Testing the API

You can test API methods from the Frappe console: 
$ bench --site your-site.localhost console

>>> frappe.call("helpdesk.api.ticket.assign_ticket_to_agent", 
...     ticket_id="HD-00042",
...     agent_id="[email protected]")

​
Next Steps

Authentication

Learn about API authentication methods

Ticket API

Start with the most commonly used API

Build docs developers (and LLMs) love

Get started for freeTalk to us