canonical: https://jentic.com/apis/freshdesk.com/freshdesk

# Freshdesk API v2

Jentic publishes the only available OpenAPI specification for Freshdesk API v2, keeping it validated and agent-ready. Freshdesk's helpdesk API exposes tickets, conversations, contacts, companies, agents, groups, time entries, satisfaction ratings, solutions articles, and canned responses across 84 endpoints. Tickets and contacts have full CRUD plus search, while solutions and canned responses cover the knowledge-base side of the helpdesk. The API uses HTTP basic auth where the username is your API key and the password is X.

## For AI agents

Open and update support tickets, manage contacts and companies, search the helpdesk, and post replies, notes, and time entries on behalf of agents.

## Scope

Does not handle live chat sessions, telephony, or marketing automation - use for helpdesk ticketing, contacts, knowledge base, and time tracking only.

## Capabilities

- Create, update, and search support tickets across all helpdesk groups
- Post public replies and private notes against an existing ticket
- Manage contact and company records that drive ticket routing
- Forward an existing ticket reply chain to a new external recipient
- Log time entries against a ticket for billing and reporting
- Publish and update knowledge-base solution articles for self-service
- Restore a previously deleted ticket within the retention window

## Use cases

### Automated Ticket Triage

When a new support email or webform submission arrives, an agent creates a Freshdesk ticket via POST /tickets, looks up the contact by email, and applies a priority and group based on keyword rules. Replies and notes flow through POST /tickets/{id}/reply and POST /tickets/{id}/notes. End-to-end triage including search and contact lookup runs against the v2 API in well under a second per ticket.

Example prompt: Create a Freshdesk ticket with priority=2, source=2, and a known contact email, then POST a reply and set status=3

### Customer 360 Lookup

Build an internal panel that, given a customer email, calls GET /contacts and GET /search/tickets to assemble that customer's full helpdesk history including open tickets, recent conversations, and CSAT scores. Useful inside CRM dashboards and AI agents that brief reps before a call.

Example prompt: Search Freshdesk contacts by email, retrieve their open tickets via /search/tickets, and return a summary with last reply timestamp

### Time Logging and Billing

Service teams need accurate billable time per ticket. After resolving a ticket, an agent posts a time entry against the ticket and tags it billable so reports roll up by company. The conversation thread, reply timestamps, and attachments are all available alongside time entries on the same ticket resource.

Example prompt: Add a 45-minute billable time entry to ticket 12345 with a note about the work performed

### Knowledge Base Publishing

Editorial teams script article publishing into the Freshdesk solutions hierarchy. Articles, folders, and categories are managed through the solutions endpoints, allowing batch import of help-centre content from another CMS into the customer-facing knowledge base.

Example prompt: Create a new solutions article in folder 42 with title and HTML body, then mark it published

### Agent-Driven Support Resolution

An AI agent reads an inbound chat message, opens or updates the matching Freshdesk ticket, posts a draft reply for human review, and logs time when the conversation closes. With Jentic the agent calls these operations through one searchable interface and never sees the raw API key.

Example prompt: Search Jentic for 'create a support ticket', load the POST /tickets schema, and execute with a contact email and ticket body

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /tickets | Create a new support ticket |
| GET | /tickets/{id} | Retrieve a ticket by ID |
| PUT | /tickets/{id} | Update a ticket's status, priority, or assignment |
| POST | /tickets/{id}/reply | Post a public reply to a ticket |
| POST | /tickets/{id}/notes | Add an internal note to a ticket |
| GET | /search/tickets | Search tickets using query filters |
| GET | /contacts | List or filter customer contacts |

## Key resources

- **Tickets** — Create, update, search, restore, and reply to support tickets
- **Contacts** — Manage customer contact records that own tickets
- **Companies** — Group contacts by organisation for routing and reporting
- **Conversations** — Post replies, notes, and forwards on a ticket
- **Time Entries** — Log billable and non-billable time against tickets
- **Solutions** — Publish and organise knowledge-base articles
- **Canned Responses** — Manage reusable reply templates for agents

## Why Jentic

- **Setup:** Wiring Freshdesk by hand means setting up basic auth with your API key as the username and 'X' as the password, pointing at your own {domain}.freshdesk.com subdomain, and learning the ticket, contact, and search routes yourself. Through Jentic you install once, import Freshdesk from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** Freshdesk puts the ticket id in the URL path (/tickets/{id}), so you limit the agent to the operations it needs, such as creating a ticket, posting a reply, or searching tickets. You choose which operations it may call, so deleting or updating tickets is not included unless you add it.
- **Credential handling:** Your Freshdesk API key is stored once, encrypted, by your own Jentic One instance and injected into the Authorization header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a support ticket' or 'post a reply to a ticket', and Jentic returns the matching POST /tickets or POST /tickets/{id}/reply operation with its full request schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Zendesk** — Larger helpdesk platform with a similar ticket and contact model
- **Intercom** — Conversational support platform with messenger-first ticketing
- **Help Scout** — Email-centric helpdesk with a lighter feature set
- **Kayako** — Multi-channel customer service platform

## FAQ

### Why is there no official OpenAPI spec for Freshdesk API v2?

Freshdesk does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Freshdesk API v2 via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Freshdesk API v2 use?

Freshdesk uses HTTP basic authentication where the username is your API key and the password is the literal letter X. Jentic stores that API key encrypted in your Jentic One instance and injects it into the basic-auth header at execution time, so the agent never sees the key.

### Can I post a reply to a Freshdesk ticket through the API?

Yes. POST to /tickets/{id}/reply with a body and optional cc and attachment fields to add a public reply, or POST to /tickets/{id}/notes for an internal-only note. Both create entries on the ticket conversation thread.

### What are the rate limits for the Freshdesk API v2?

Freshdesk applies per-account rate limits that vary with plan tier and typically sit between 100 and 500 requests per minute. The API returns 429 with a Retry-After header when exceeded, so back off and retry on the indicated interval.

### How do I open a ticket through Jentic?

Search Jentic for 'create a support ticket', load the POST /tickets schema, and execute with the email, subject, description, status, and priority fields. Jentic injects your Freshdesk API key from the vault into the basic-auth header.

### Can I restore a ticket that was deleted by mistake?

Yes. Call PUT /tickets/{id}/restore within the Freshdesk retention window to undo a delete. The ticket reappears with its original conversation thread intact.

### Can I limit what my agent is allowed to do with the Freshdesk API?

Yes. Because Jentic One is self-hosted, you set the rules for which Freshdesk operations your agent can call, so you can allow just the ones it needs, such as creating a ticket with POST /tickets, posting a reply with POST /tickets/{id}/reply, or searching with GET /search/tickets. Operations you do not grant, like deleting or updating a ticket, stay off limits until you add them. Your Freshdesk API key is stored encrypted by your own instance and injected at execution time, so the agent never sees it.