> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Freshdesk plugin

> Manage support tickets, customer records, agents, groups, knowledge base content, and account settings through Freshdesk REST API v2.

Use **Freshdesk** through Corsair: one client, typed API calls.

Every Freshdesk account has its own hostname (for example `acme.freshdesk.com`), so each connected account supplies it as the `domain` field with its API key; the `domain` plugin option overrides it for single-account setups. Freshdesk API v2 does not support custom CNAMEs. The API key is sent using HTTP Basic authentication with `X` as the password.

Freshdesk applies per-minute account and API sublimits. List operations accept `page` (1-based) and `per_page` (maximum 100). A 429 includes `Retry-After`; automatic retries are limited to safe GET requests.

Ticket create/update/reply, note creation, contact avatar create/update, conversation updates, and outbound email with attachments accept `{ filename, contentType, base64 }` entries and send multipart/form-data. Contact and company imports take one CSV the same way. Contact avatars use the `avatar` file part, imports use `file`, and the other upload routes use `attachments[]`. Object fields in a multipart request go out as bracketed parts (`custom_fields[cf_name]`, `fields[name]`).

Pass path parameters in `pathParams` under their camelCase names (`[ticket_id]` becomes `ticketId`) and each route's documented request fields through its `body` object. Each route's input schema lists its own path parameters and body fields, and the plugin validates field names and primitive types; tenant-defined `custom_fields` and nested object values remain open JSON. Responses are validated as JSON values to preserve optional embeds and custom fields; consult the linked route for resource-specific response fields.

The plugin covers the documented v2 REST routes. Freshdesk marks v1 deprecated/restricted for new users. No webhook delivery contract is documented here.

**What you get:**

* 256 typed API operations

## Setup

**1. Install**

```bash npm theme={null}
npm install corsair @corsair-dev/freshdesk better-sqlite3
npm install --save-dev @types/better-sqlite3
```

```bash yarn theme={null}
yarn add corsair @corsair-dev/freshdesk better-sqlite3
yarn add --dev @types/better-sqlite3
```

```bash pnpm theme={null}
pnpm install corsair @corsair-dev/freshdesk better-sqlite3
pnpm install --save-dev @types/better-sqlite3
```

```bash bun theme={null}
bun add corsair @corsair-dev/freshdesk better-sqlite3
bun add --dev @types/better-sqlite3
```

**2. Add the plugin**

```ts corsair.ts theme={null}
import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { freshdesk } from '@corsair-dev/freshdesk';

export const corsair = createCorsair({
	plugins: [
		freshdesk(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});
```

With `multiTenancy: true`, scope calls with `corsair.withTenant(id)`. See [Quick start](https://docs.corsair.dev/quick-start.md) for KEK + Hub keys, and [Multi-tenancy](https://docs.corsair.dev/concepts/multi-tenancy.md) for account isolation.

**3. Choose authentication**

> [tab] API Key (Recommended)
>
> Store the Freshdesk API key before the first call: `pnpm corsair setup --plugin=freshdesk --tenant=acme api_key=<your-key>` (leave out `--tenant` without `multiTenancy`), or pass it as `key` in the plugin options. With Hub, each tenant enters their own key on the connect page. See [API key auth](https://docs.corsair.dev/concepts/api-key).
>
> Each connected account stores its own Freshdesk hostname (the `domain` field) next to its API key: `pnpm corsair setup --plugin=freshdesk --tenant=acme domain=acme.freshdesk.com`, or the connect page with Hub. Set the `domain` option only for a single-account setup; it overrides the stored value.
>
> ```ts theme={null}
> freshdesk()
> ```
>
> More: [API Key](https://docs.corsair.dev/concepts/api-key)

**4. Connect a tenant**

Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see [Connect / OAuth](https://docs.corsair.dev/management/connect).

```ts theme={null}
const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'freshdesk',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl
```

## Example API calls

**List recent tickets**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.freshdesk.api.routes.listAllTicketsGetTickets.run({
	query: { per_page: 30 },
});
```

**Add a private note to a ticket**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.freshdesk.api.routes.addNoteToATicketPostNotes.run({
	pathParams: { ticketId: '123' },
	body: { body: 'Internal note', private: true },
});
```

See the full list on the [API](https://docs.corsair.dev/plugins/freshdesk/api.md) page.

## What's next

> [card] [API reference](https://docs.corsair.dev/plugins/freshdesk/api.md)
>
> Every `freshdesk.api.*` operation with input and output types.

> [card] [Connect / OAuth](https://docs.corsair.dev/management/connect)
>
> createLink, Hub delivery, and tenant connect flows.

> [card] [Use with agents](https://docs.corsair.dev/mcp-adapters/mcp-adapters)
>
> Expose this plugin's operations as MCP tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.