Freshdesk API Guide: Auth, Rate Limits, Webhooks and MCP (2026)

The Freshdesk API is a REST API, version 2, that takes and returns plain JSON over HTTPS and authenticates with each agent's personal API key. Access starts on the Growth plan. The budget is counted per minute for the whole account: 100 calls on Growth, 400 on Pro and 700 on Enterprise, with 50 on every trial and none on the legacy Free program.^[1] Webhooks fired by your own automations spend that same budget. The verdict: well documented and predictable, but count your calls before you pick a plan.

Where the docs live and what version 2 covers

The documentation sits on Freshdesk's developer site, next to the App SDK and the web chat and widget APIs. Version 2 is the only production version: v1 is fully deprecated and closed to new users, and v2 dropped XML. Every request must use HTTPS through your *.freshdesk.com address; a custom CNAME will not work. The verbs are POST, GET, PUT and DELETE, and CORS is supported.^[2] Help-center articles badge API access for Growth, Pro and Enterprise only.

Coverage is broad. Endpoints reach tickets and conversations, contacts, companies, agents, groups, roles, skills, custom objects, canned responses, solution articles, CSAT surveys, time entries, mailboxes, SLA policies, automations and the audit log export. Two gaps matter in practice. Instagram tickets cannot be created through the API, only updated. Workspaces, the Enterprise feature that splits one account into teams, cannot be created through it either, so a multi-team rollout still needs an administrator in the web app.

The change policy is written down. When a new major version ships, the old one gets six months before deprecation, and breaking changes come with 60 days' notice unless legal, performance or security reasons force them sooner. Beta endpoints carry no such promise and can change without notice; the contact and company filter endpoints are currently marked beta. Wrap any beta call in one function of your own, so a change breaks one place instead of your whole sync.

Authentication: one key per agent, one role per key

Authentication is HTTP basic auth. The agent's API key is the username and any dummy password works, X by convention; if you build the header yourself, Base64-encode apikey:X into an Authorization header. Each agent finds the key under Profile settings, below the change-password section. The key carries that agent's permissions. An agent whose role cannot reply to tickets cannot reply through the API either, so the role you give an integration's agent is its real permission boundary.

Resetting a key is the kill switch. It is also blunt. Every app that used the old key disconnects until it receives the new one, and Freshdesk's advice for a stolen phone is a key reset, because a password change does not log the phone out. Keep a short list of which tools hold which agent's key, so a reset means minutes of reconfiguration instead of a morning spent finding which sync silently stopped.

OAuth needs a precise answer. The core REST API and the inbound MCP server use API keys, and Freshdesk's MCP security page says OAuth is not currently supported there. The other direction differs. When an AI agent built in AI Agent Studio calls your systems through an API action, it can authenticate with an API key, a bearer token, basic auth or OAuth 2.0, and the outbound MCP connections in those workflows use OAuth-based authentication.

Rate limits: one budget per minute for the whole account

The limit applies to the account regardless of how many agents or IP addresses send the calls, and each plan also caps four busy endpoints. Freshdesk is moving accounts from older per-hour limits to these per-minute limits in batches, so an older account may still be on an hourly limit for a while. The developer documentation lists these current numbers per minute.

Three things spend this budget that teams tend to forget. Invalid requests count. Calls made by custom apps count. Every webhook counts too, whether it fires from an automation rule or from an outside automation tool. Embedding related data costs extra: on View a Ticket each include adds one call and conversations add two, while on List All Tickets each include adds two. Responses report X-RateLimit-Total, X-RateLimit-Remaining and X-RateLimit-Used-CurrentRequest, and a 429 arrives with Retry-After in seconds.

By our arithmetic, the ceilings equal 6,000 calls an hour on Growth, 24,000 on Pro and 42,000 on Enterprise, if traffic is spread evenly. Bursts hit the endpoint caps first: a Growth account can create only 50 tickets a minute through the API. When that is not enough, an account can buy extra API calls, with sub-limits of up to 2,000 calls a minute in total, but Freshdesk does not publish that price. The published route is a plan upgrade.

Freshdesk's pricing page lists Growth at $19 per agent per month billed annually ($228 per agent a year) and Pro at $55 per agent per month billed annually ($660 per agent a year). Billing is per agent and every agent sits on the same plan, as our pricing guide explains. By our arithmetic, on annual billing the step from 100 to 400 calls a minute costs $432 per agent a year ($2,160 for five agents, $4,320 for ten); billed monthly it is $43 per agent a month. Ask for an extra-calls quote before upgrading for the API alone.

For context, Help Scout's pricing page lists 200, 400 and 800 calls a minute across its paid tiers, and Zendesk sells an add-on that lifts its overall limit to 2,500 requests a minute for accounts with 10 or more agent seats. A team whose integration is the heavy user should compare those ceilings; a team that mostly works in the agent screen will rarely notice the difference.

Reading data at volume: pagination, search and exports

List endpoints return 30 objects per page by default and up to 100 with per_page; the link header carries the next page, and Freshdesk advises against paging past page 500. List All Tickets has a trap. By default it returns only tickets created in the past 30 days, up to 300 pages, so a historical sync must use the updated_since filter. For accounts created after 30 Nov 2018, the ticket description comes back only with include=description.

Filter Tickets is the search endpoint, and it is narrow. Queries are capped at 512 characters, results come 30 to a page and the page number cannot exceed 10, so one query returns at most 300 tickets by our arithmetic. It excludes archived tickets, and fresh updates take a few minutes to be indexed. Freshdesk archives closed tickets after 120 days without activity, so reporting on older tickets needs its own copy.

Writes at scale run as background jobs: bulk update and bulk delete return a job_id you poll, and deletes are soft, so Restore Ticket can bring a ticket back. Attachments go as multipart/form-data, capped at 20 MB per request. There is no built-in scheduler; you run your own script. For a full copy, an Account Administrator can trigger an account export in XML, which can take up to 10 business days, and data exports are limited to five per module each day.

Webhooks and Trigger API: pushing events out

Freshdesk pushes events through automation rules. The Trigger Webhook action, available from Growth, calls your endpoint when a ticket is created or updated. Trigger API, from Pro, goes further: it reads the response and can transform it in a JavaScript (V8) editor before updating the ticket, for date math or field mapping. Both act as an agent performing an update, and webhooks run asynchronously to the rest of the rule.^[3]

The delivery rules are strict. Callbacks are limited to 1,000 an hour, and anything above that waits in a buffer until the next hour; a webhook postponed for more than 24 hours is dropped with an alert. A failed call is retried every 30 minutes, 48 times in all, and administrators get an email with the reason. Only 2xx codes count as success. Webhooks do not fire from Hourly Triggers, so a time-based event such as no reply in four hours needs your own polling against the API.

A lighter option is the free Webhook Relay app from the Marketplace. It forwards five events (ticket create and update, conversation create and update, agent availability) to up to five HTTPS URLs as unchanged JSON POST requests. It adds no authentication headers, so your endpoint must protect itself. Our integrations guide covers the Marketplace apps that already wrap these calls, which can save building your own receiver.

MCP: letting AI tools into the help desk

Since 10 Sep 2026 Freshdesk has a generally available MCP server, so AI tools such as Claude Code, Claude Desktop, Cursor, Microsoft Copilot Studio and VS Code can work on live tickets, contacts, companies, agents, groups and knowledge base articles. The endpoint is subdomain.freshdesk.com/mcp, with no custom domains. Each user connects with their own API key, entered by hand, and permissions follow that key's role. There is no tool-level access control, and MCP is on by default until an admin switches it off.

Metering is separate from the REST budget. Growth includes 100 actions a month, Pro 500 and Enterprise 1,000, and a trial gets 1,000 once. One action is one successful tool call; 429 and 5xx responses are not counted, and allowances do not roll over.^[4] Between 100% and 110% use continues and the overage is billed; at 110% MCP pauses. Freshdesk's pricing page lists MCP action packs at $15 per 1,000 actions, a recurring pack added to each billing cycle; packs stack. By our arithmetic, a Growth account running 600 actions a month needs one pack. Freddy's side is in our AI playbook.

The bottom line

The Freshdesk API is a mature REST API with a written deprecation policy and a new MCP door for AI tools. Its constraints are about budget, not capability. Count your calls, including webhooks and includes, against 100 a minute on Growth before you build, and check whether the 300-result search ceiling and the 30-day default on ticket lists fit your sync. If the numbers fit, Growth is enough. If not, price extra API calls against the Pro upgrade, and give each integration a key whose role matches only what it should touch.