A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Freshdesk API is how an app or AI agent works with a support account: creating and updating tickets, replying to customers and adding internal notes, and managing the contacts and companies behind those tickets. Access is granted through a per-agent API key, and because Freshdesk has no permission scopes, the key can do exactly what its agent's role allows and no more. Events reach an app through webhook actions set on automation rules rather than a fixed subscription.
How an app or AI agent connects to Freshdesk determines what it can reach. There is one route for making calls, authenticated with an API key, and a route for receiving events through webhooks driven by automation rules. Freshdesk has no granular permission scopes, so a key inherits the role of the agent it belongs to.
The REST API answers at https://account.freshdesk.com/api/v2 and exchanges JSON over HTTPS. Every call authenticates with an API key sent as HTTP Basic auth, where the key is the username and any non-empty string is the password.
Freshworks publishes a first-party MCP server that lets an agent call Freshdesk over the Model Context Protocol. It is in beta through an Early Access Program for Enterprise-plan accounts, answers at https://account.freshdesk.com/mcp over HTTP transport, and authenticates with an API key. Access is limited to administrator and agent privileges.
Freshdesk has no standalone webhook subscription endpoint. An administrator adds a webhook action to a ticket-creation or ticket-update automation rule, sets the condition that fires it, picks the fields to send, and Freshdesk POSTs that JSON payload to the app's URL.
Each agent has a personal API key, shown on their profile in Freshdesk. It is sent as HTTP Basic auth, with the key as the username and any non-empty string as the password. The key carries no separate scopes; it inherits the role and permissions of the agent it belongs to, so what the key can do is exactly what that agent can do in the product.
The Freshdesk API is split into areas an agent can act on, like tickets, ticket conversations, contacts, companies, agents, and groups. Each area has its own methods, and writes in some areas reply to customers, change support records, or delete people's accounts.
Create, view, list, update, delete, and restore tickets, and send a proactive outbound email as a ticket. A ticket holds the requester, status, priority, group, and assigned agent.
Reply to a ticket, add a private note, and update or delete a conversation. A reply is sent to the customer; a note stays internal to the agents.
Create, view, list, update, soft-delete, restore, and merge contacts. A contact is a customer or requester who raises tickets.
Create, view, list, update, and delete companies. A company groups the contacts that belong to one customer organization.
View an agent, list agents, read the agent the key belongs to, and create, update, or delete agents. An agent is a support team member with a role.
Create, view, list, update, and delete groups. A group is a team that tickets are routed to and assigned within.
Create and view canned responses and create a canned response folder. A canned response is a reusable reply template available to agents.
Filter tickets, contacts, and companies with a query expression. Search returns matching records rather than changing anything.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
TicketsCreate, view, list, update, delete, and restore tickets, and send a proactive outbound email as a ticket. A ticket holds the requester, status, priority, group, and assigned agent.7 | ||||||
| POST | /api/v2/tickets | Create a ticket, setting the requester, subject, description, status, priority, group, and assigned agent. | write | — | Current | |
Freshdesk has no per-method scopes. The call succeeds only if the agent whose API key is used has permission to create tickets. Acts onticket Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit80 per minute on Growth, 160 on Pro, 280 on Enterprise SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/tickets/{id} | View a single ticket by id, optionally including its conversations, requester, company, and stats. | read | — | Current | |
Read-only. The agent's role and ticket-scope setting decide which tickets are visible. Acts onticket Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/tickets | List tickets, with filters for requester, company, updated time, and status. Deleted and spam tickets are excluded unless explicitly requested. | read | — | Current | |
Read-only. This endpoint carries its own tighter sub-limit, separate from the account rate. Acts onticket Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit20 per minute on Growth, 100 on Pro, 200 on Enterprise SourceOfficial documentation ↗ | ||||||
| PUT | /api/v2/tickets/{id} | Update a ticket's properties, such as status, priority, group, assigned agent, type, and tags. | write | — | Current | |
Needs the agent permission to edit the ticket. Carries its own tighter sub-limit. Acts onticket Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit80 per minute on Growth, 160 on Pro, 280 on Enterprise SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/tickets/{id} | Delete a ticket. This is a soft delete; the ticket can be brought back with restore. | write | — | Current | |
Needs the agent permission to delete tickets. Soft-deleted tickets are recoverable with restore. Acts onticket Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v2/tickets/{id}/restore | Restore a soft-deleted ticket so it is active again. | write | — | Current | |
Reverses a soft delete. Needs the agent permission to manage tickets. Acts onticket Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/tickets/outbound_email | Create a ticket by sending a proactive outbound email to a contact, rather than waiting for the customer to write in. | write | — | Current | |
Sends an email to the customer immediately, so it is a customer-facing write. Acts onticket Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ConversationsReply to a ticket, add a private note, and update or delete a conversation. A reply is sent to the customer; a note stays internal to the agents.4 | ||||||
| POST | /api/v2/tickets/{id}/reply | Reply to a ticket. The reply is sent to the requester and added to the ticket conversation. | write | — | Current | |
Customer-facing: a reply is emailed to the requester and cannot be unsent. Acts onconversation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/tickets/{id}/notes | Add a note to a ticket. A note can be private to the agents or public to the requester. | write | — | Current | |
A private note stays internal; a public note is visible to the requester in the portal. Acts onconversation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v2/conversations/{id} | Update the body of an existing reply or note on a ticket. | write | — | Current | |
Only the body of a note can be updated; outgoing replies that were emailed are not edited at the customer's end. Acts onconversation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/conversations/{id} | Delete a reply or note from a ticket conversation. | write | — | Current | |
Removes the message from the ticket record. Acts onconversation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ContactsCreate, view, list, update, soft-delete, restore, and merge contacts. A contact is a customer or requester who raises tickets.7 | ||||||
| POST | /api/v2/contacts | Create a contact, the customer or requester record that tickets are raised against. | write | — | Current | |
Stores personal details such as name, email, and phone. Needs the agent permission to manage contacts. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/contacts/{id} | View a single contact by id. | read | — | Current | |
Read-only. Returns the contact's personal and contact details. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/contacts | List contacts, with filters for email, mobile, company, and updated time. | read | — | Current | |
Read-only. Carries its own tighter sub-limit, separate from the account rate. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit20 per minute on Growth, 100 on Pro, 200 on Enterprise SourceOfficial documentation ↗ | ||||||
| PUT | /api/v2/contacts/{id} | Update a contact's details, such as name, email, phone, and company. | write | — | Current | |
Changes a customer's personal record. Needs the agent permission to manage contacts. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/contacts/{id} | Soft-delete a contact. A separate hard-delete endpoint removes a contact permanently. | write | — | Current | |
This is a soft delete, reversible with restore. A separate hard-delete call at /api/v2/contacts/{id}/hard_delete removes the contact for good. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v2/contacts/{id}/restore | Restore a soft-deleted contact so it is active again. | write | — | Current | |
Reverses a soft delete. A hard-deleted contact cannot be restored. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/contacts/merge | Merge two or more contacts into a single primary contact. | write | — | Current | |
Combines duplicate records; the secondary contacts are folded into the primary. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CompaniesCreate, view, list, update, and delete companies. A company groups the contacts that belong to one customer organization.5 | ||||||
| POST | /api/v2/companies | Create a company, the organization that groups a set of contacts. | write | — | Current | |
Needs the agent permission to manage companies. Acts oncompany Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/companies/{id} | View a single company by id. | read | — | Current | |
Read-only. Acts oncompany Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/companies | List all companies in the account. | read | — | Current | |
Read-only. Acts oncompany Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v2/companies/{id} | Update a company's details, such as name, domains, and notes. | write | — | Current | |
Needs the agent permission to manage companies. Acts oncompany Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/companies/{id} | Delete a company. Its contacts are not deleted but lose the company link. | write | — | Current | |
Needs the agent permission to manage companies. Acts oncompany Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AgentsView an agent, list agents, read the agent the key belongs to, and create, update, or delete agents. An agent is a support team member with a role.3 | ||||||
| GET | /api/v2/agents/me | Read the agent the API key belongs to, including the role and permissions behind every call. | read | — | Current | |
Read-only. Useful for an agent to confirm the identity and reach of the key it is using. Acts onagent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/agents/{id} | View a single agent by id, including their role and group membership. | read | — | Current | |
Read-only. Acts onagent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/agents | List agents, with filters for email, mobile, state, and name. | read | — | Current | |
Read-only. Acts onagent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
GroupsCreate, view, list, update, and delete groups. A group is a team that tickets are routed to and assigned within.3 | ||||||
| POST | /api/v2/groups | Create a group, the team that tickets are routed to and assigned within. | write | — | Current | |
An administrator-level action that shapes ticket routing. Acts ongroup Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/groups/{id} | View a single group by id, including its members. | read | — | Current | |
Read-only. Acts ongroup Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/groups | List all groups in the account. | read | — | Current | |
Read-only. Acts ongroup Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Canned responsesCreate and view canned responses and create a canned response folder. A canned response is a reusable reply template available to agents.3 | ||||||
| POST | /api/v2/canned_responses | Create a canned response, a reusable reply template for agents. | write | — | Current | |
Needs the agent permission to manage canned responses. Acts oncanned_response Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/canned_responses/{id} | View a single canned response by id. | read | — | Current | |
Read-only. Acts oncanned_response Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/canned_response_folder | Create a canned response folder to organize reply templates. | write | — | Current | |
Needs the agent permission to manage canned responses. Acts oncanned_response_folder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Search & filterFilter tickets, contacts, and companies with a query expression. Search returns matching records rather than changing anything.2 | ||||||
| GET | /api/v2/search/tickets | Filter tickets with a query expression over fields such as status, priority, type, tag, and dates. | read | — | Current | |
Read-only. The query is URL-encoded and limited to a defined set of filterable fields, with a cap on results returned. Acts onticket Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/search/contacts | Filter contacts with a query expression over fields such as company, tag, and creation time. | read | — | Current | |
Read-only. The query is URL-encoded and limited to a defined set of filterable fields. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Freshdesk can notify an app when something happens in an account, like a ticket being created or updated. There is no fixed event catalog: an administrator builds an automation rule with a webhook action, chooses the condition that fires it and the ticket fields to send, and Freshdesk posts that payload to the app's URL.
| Event | What it signals | Triggered by |
|---|
Freshdesk limits how fast an app can call by a request rate measured per minute, set by the account's plan, and applied across the whole account rather than per key. Some endpoints carry tighter sub-limits, and going over returns a 429 response with a Retry-After header.
Freshdesk meters requests per minute, and the ceiling is set by the account's plan, counted across the whole account rather than per API key, so every integration sharing the account draws from one bucket. The plan limits are 200 calls per minute on Growth, 400 on Pro, and 700 on Enterprise, with a trial account capped at 50. Some endpoints carry tighter sub-limits on top: listing tickets or contacts is held to 20 per minute on Growth, 100 on Pro, and 200 on Enterprise, while creating or updating tickets is held to 80, 160, and 280 across those plans. Every response reports the current state through the X-RateLimit-Total, X-RateLimit-Remaining, and X-RateLimit-Used-CurrentRequest headers, and going over returns a 429 with a Retry-After header giving the seconds to wait.
List endpoints use page-number pagination through the page parameter, which starts at 1, and the per_page parameter, which defaults to 30 and tops out at 100. When more pages exist, the response includes a Link header pointing at the next page, which should be followed rather than built by hand.
Responses are JSON. A list page returns at most 100 records, the maximum value of per_page. Filter (search) endpoints cap how many results a query can return and restrict filtering to a defined set of fields.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | invalid_json / validation error | The request was malformed or failed validation. The body holds a description and an errors array, each entry naming the field, a message, and a code such as missing_field, invalid_value, datatype_mismatch, or duplicate_value. | Read the errors array, correct the named field, and resend. |
| 401 | invalid_credentials | Authentication failed: the API key is missing, wrong, or sent incorrectly. | Confirm the API key and that it is sent as the Basic auth username with a non-empty password. |
| 403 | access_denied | The key is valid but the agent's role does not permit this action, or the feature is not on the plan. | Use a key for an agent whose role allows the action, or enable the required feature on the plan. |
| 404 | object not found | The resource does not exist, or is not visible to this agent. | Confirm the id and that the agent has access to the record. |
| 409 | inconsistent_state | The request conflicts with the current state, such as acting on a record that is in an incompatible state. | Refetch the current state and retry once the conflict is resolved. |
| 415 | unsupported_content_type | The request used a Content-Type other than application/json, which most write calls require. | Send the body as application/json. |
| 429 | rate_limit_exceeded | The account or an endpoint sub-limit was exceeded. Limits are per minute and counted across the whole account, not per key. | Wait the number of seconds in the Retry-After header before retrying, and spread calls out. |
The Freshdesk REST API is served under a single stable version, v2, in the path /api/v2. It does not use dated versions; changes are published in the developer API reference, and a v1 API still exists for older integrations.
The Freshdesk API v2 is the current stable version, served under the /api/v2 path on a per-account domain. It is not dated: there is one v2 surface, and changes are published in the developer API reference rather than as new dated versions. An older v1 API still exists for legacy integrations but is not recommended for new work. Every call authenticates with a per-agent API key over HTTP Basic auth, and access is governed by that agent's role rather than by token scopes.
The original Freshdesk API, v1, predates v2 and remains available for older integrations. It is not recommended for new work; v2 is the supported surface. Its reference is published separately.
Build against v2; v1 is older and not recommended for new integrations.
Freshdesk API reference ↗Bollard AI sits between a team's AI agents and Freshdesk. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.