Freshdesk API Explained (v2, Auth & Rate Limits)

What the Freshdesk API can and can't do

The API is a full CRUD surface over the objects you see in the Freshdesk UI. You can create, read, update, and delete tickets, read and write contacts and companies, manage agents and groups, pull ticket conversations (the full reply thread), inspect ticket fields including your custom ones, and run server-side searches. Anything an agent can do to a ticket in the browser, you can generally script.

What it is not is a reasoning engine. The API will faithfully return a ticket's JSON or accept a new one, but it has no opinion about what the ticket means, what the right reply is, or which of your other systems holds the answer. It moves structured data in and out — the judgement stays with whatever (or whoever) is calling it. That distinction matters later when we talk about layering intelligence on top.

Base URL and API versioning

Every request goes to your account's own subdomain, under the /api/v2/ path. Per the Freshdesk developer documentation, the shape is:

https://{your-domain}.freshdesk.com/api/v2/{resource}

So listing tickets on an account at demousermacha.freshdesk.com is a GET to https://demousermacha.freshdesk.com/api/v2/tickets. The v2 in the path is the current stable version; v1 is legacy and should not be used for new work.

Authentication: your API key is the whole story

Freshdesk v2 uses HTTP Basic Authentication, but with a twist that confuses newcomers: your API key goes in the username field, and the password can be any non-empty string — X is the conventional throwaway value. There is no OAuth dance and no password to manage; the API key alone identifies and authorises you.

A minimal authenticated GET with curl looks like this:

curl -v -u YOUR_API_KEY:X \
  -H "Content-Type: application/json" \
  -X GET 'https://your-domain.freshdesk.com/api/v2/tickets'

Under the hood, -u YOUR_API_KEY:X base64-encodes the pair into an Authorization: Basic ... header. Your key lives in your agent Profile Settings — Freshdesk gates the reveal behind a reCAPTCHA, and we cover exactly where to click in how to find your Freshdesk API key. Treat the key like a password: it inherits your agent permissions, so a key belonging to an admin can do far more than one belonging to a restricted-scope agent.

Here is a real, successful call against a live demo account — a GET /api/v2/tickets returning 200 with the rate-limit headers and JSON body intact:

Rate limits: per minute, per account, per plan

This is the part that breaks integrations in production. Freshdesk enforces a per-minute call limit (it moved from an older per-hour model), and the ceiling depends on your plan. Per the Freshdesk support documentation on API rate limits and Truto's 2026 engineering guide, the current figures are:

Three properties bite people:

1. The limit is per account, not per key. Every script, integration, and installed app that touches your Freshdesk draws from the same per-minute bucket. Add a marketing sync and a BI export on top of your AI tool and they compete.
2. Even failed requests count. A 401 from a bad key or a 400 from a malformed body still consumes a call — so validate before you send.
3. Some endpoints have their own sub-limits. On Growth, for example, ticket create and update are individually capped even though the account ceiling is 200/min.

Reading the rate-limit headers

You never have to guess where you stand — Freshdesk tells you on every response via headers:

• X-RateLimit-Total — your account's ceiling for the window.
• X-RateLimit-Remaining — how many calls are left.
• X-RateLimit-Used-CurrentRequest — how many calls this request consumed (some operations cost more than one).
• Retry-After — present only on a 429, telling you how many seconds to back off.

The screenshot above shows x-ratelimit-remaining: 49 against an x-ratelimit-total: 50 on that trial account — that one call spent a single unit. A well-behaved client watches X-RateLimit-Remaining and slows itself before it hits zero, rather than hammering the API and reacting to 429s after the fact.

Common endpoints you'll reach for first

Most integrations live in a handful of resources. The essentials:

# List tickets (paginated, 30 per page by default)
GET  /api/v2/tickets

# Create a ticket
POST /api/v2/tickets

# Update a ticket (e.g. change status or priority)
PUT  /api/v2/tickets/{id}

# Pull the full conversation thread on a ticket
GET  /api/v2/tickets/{id}/conversations

# Contacts and companies
GET  /api/v2/contacts
GET  /api/v2/companies

# Discover fields, including custom ones
GET  /api/v2/ticket_fields

# Server-side search
GET  /api/v2/search/tickets?query="status:2"

A minimal ticket-creation body is just JSON — a subject, a description, a requester, a status, and a priority:

curl -v -u YOUR_API_KEY:X -H "Content-Type: application/json" \
  -X POST 'https://your-domain.freshdesk.com/api/v2/tickets' \
  -d '{
    "subject": "Order status question",
    "description": "Where is my order #4471?",
    "email": "[email protected]",
    "priority": 1,
    "status": 2
  }'

We walk through a real, verified version of that call — with the ticket it produced open in the UI — in how to create a ticket with the Freshdesk API.

Pagination is easy to get wrong. List endpoints return 30 objects per page by default; you can raise that to a maximum of 100 with per_page. Standard list endpoints ask you to avoid page numbers over 500, and the search/filter endpoint is stricter still — pages 1 to 10 only, a 300-record ceiling. When more pages exist, Freshdesk returns a link header pointing at the next page; follow that rather than guessing offsets.

Error codes worth handling

The API uses standard HTTP status codes and returns a structured JSON error body with a code, a human message, and often the offending field. The ones you will actually hit:

• 400 Bad Request — a validation problem in your payload (wrong type, missing required field). Read the field and message to fix it.
• 401 Unauthorized — missing or wrong API key. The body says invalid_credentials.
• 403 Forbidden — the key is valid but the agent lacks permission for that action.
• 404 Not Found — the resource (or the whole path) doesn't exist.
• 429 Too Many Requests — rate limit hit; read Retry-After and back off.
• 500 — a server-side error on Freshdesk's end; retry with backoff.

We dig into the exact JSON shapes and a real 401 in Freshdesk API errors and rate limits.

The honest limits — where the raw API stops

Credit where it's due: the Freshdesk API is clean, predictable, and thoroughly documented. For moving data in and out — imports, exports, reporting, filing tickets from other systems — it's exactly what you want, and you rarely need anything more.

But the API is deliberately dumb, in the good sense. It hands you a ticket's JSON; it will not read that ticket, understand the customer's actual problem, and decide what to do. It enforces no logic of its own beyond validation. So the moment your goal shifts from "sync this data" to "answer this question," you're on the hook to build the hard part yourself: the reasoning, the retrieval from your other systems, the drafting, and — around all of it — the auth handling, pagination loops, retry-on-429 backoff, and rate-limit accounting we just covered. That's a real amount of engineering, and the per-account rate limit means every integration you add fights the same 200-to-700 calls-a-minute budget.

Some of this is also plan-gated in ways worth naming honestly: the Free plan has no API access at all, higher rate limits and per-endpoint headroom require paying up to Pro or Enterprise, and features like webhooks live behind automation tiers. None of that is a knock on Freshdesk — it's a normal SaaS shape — but it's the reality you're building against.

This is the seam where an AI agent layer fits, and it's worth understanding the build-versus-buy tradeoff before writing that plumbing yourself. The broader category of AI agents for customer service exists to do the reasoning the raw API can't. Macha is one such layer: it runs on top of the Freshdesk you already use as a native connector — it does not replace your help desk or its API. You connect Macha to Freshdesk with your subdomain and API key (the same credentials from this guide), and it handles the auth, pagination, and rate-limit backoff for you, then reads and writes the same tickets your integrations already touch — drafting grounded replies and looking up order or account status through a custom tool that turns one of your REST APIs into something the agent can call. (Macha's connector is for Freshdesk specifically — not Freshchat, Freshservice, or Freshcaller. And credits are consumed per AI action, not per resolution — see the pricing breakdown.)

The clean division of labour: keep the Freshdesk API as your reliable read/write plane, and let an agent layer own the reasoning and the HTTP housekeeping on top of it.

FAQ

How do I authenticate with the Freshdesk API? Use HTTP Basic Authentication with your API key as the username and any non-empty string (commonly X) as the password — for example curl -u YOUR_API_KEY:X. There's no OAuth flow; the key alone authorises the request and inherits your agent's permissions. You'll find the key in your Freshdesk agent Profile Settings.

What are the Freshdesk API rate limits? They're per-minute and per-account, and depend on your plan: roughly 200 calls/min on Growth, 400 on Pro, and 700 on Enterprise, with the Free plan having no API access and trials capped at 50/min. The limit is shared across every integration on the account, some endpoints have their own sub-caps, and even failed requests count. Confirm the exact figures against your own plan.

Which headers show my remaining rate limit? Every response includes X-RateLimit-Total (your ceiling), X-RateLimit-Remaining (calls left), and X-RateLimit-Used-CurrentRequest (what this call cost). On a 429, a Retry-After header tells you how many seconds to wait before retrying.

What's the base URL for the Freshdesk API? https://{your-domain}.freshdesk.com/api/v2/{resource} — always your own subdomain, over HTTPS, on the v2 path. For example, https://your-domain.freshdesk.com/api/v2/tickets to list tickets.

Can I add AI to Freshdesk through the API without replacing Freshdesk? Yes. An AI agent layer like Macha connects to Freshdesk using the same subdomain-and-API-key credentials from this guide and runs on top of your existing help desk — it doesn't replace it. It handles the auth, pagination, and rate-limit backoff for you, and reads and writes the same tickets your other integrations already touch.

Ready to build on your Freshdesk API without writing the plumbing? Start a free trial of Macha and connect it to your Freshdesk in minutes.