Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. See our Privacy Policy and
Terms.
openapi: 3.2.0
info:
title: Freshdesk REST Groups API
description: The Freshdesk REST API (v2) provides programmatic access to helpdesk data and operations within Freshdesk, a customer support platform by Freshworks.
version: '2.0'
contact:
name: Freshdesk Support
url: https://support.freshdesk.com/
termsOfService: https://www.freshworks.com/terms/
servers:
- url: https://{domain}.freshdesk.com/api/v2
description: Freshdesk Production Server
variables:
domain:
default: yourdomain
description: Your Freshdesk subdomain, e.g. if your helpdesk URL is acme.freshdesk.com, use acme.
security:
- basicAuth: []
tags:
- name: Groups
description: Manage agent groups for ticket assignment and routing.
paths:
/groups:
get:
operationId: listGroups
summary: List all groups
description: Retrieves a paginated list of agent groups.
tags:
- Groups
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/perPage'
responses:
'200':
description: Successfully retrieved list of groups.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Group'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createGroup
summary: Create a group
description: Creates a new agent group in the helpdesk.
tags:
- Groups
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GroupCreate'
responses:
'201':
description: Group created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/groups/{group_id}:
get:
operationId: getGroup
summary: View a group
description: Retrieves the details of a specific group by ID.
tags:
- Groups
parameters:
- $ref: '#/components/parameters/groupId'
responses:
'200':
description: Successfully retrieved group details.
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: updateGroup
summary: Update a group
description: Updates the properties of an existing group.
tags:
- Groups
parameters:
- $ref: '#/components/parameters/groupId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GroupCreate'
responses:
'200':
description: Group updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteGroup
summary: Delete a group
description: Deletes a group from the helpdesk.
tags:
- Groups
parameters:
- $ref: '#/components/parameters/groupId'
responses:
'204':
description: Group deleted successfully.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
responses:
Unauthorized:
description: Authentication failed or credentials were not provided.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: The request is invalid or malformed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
parameters:
perPage:
name: per_page
in: query
description: Number of results per page (max 100).
schema:
type: integer
minimum: 1
maximum: 100
default: 30
groupId:
name: group_id
in: path
required: true
description: Unique identifier of the group.
schema:
type: integer
format: int64
page:
name: page
in: query
description: Page number for paginated results.
schema:
type: integer
minimum: 1
default: 1
schemas:
Group:
type: object
properties:
id:
type: integer
format: int64
description: Unique identifier of the group.
name:
type: string
description: Name of the group.
description:
type: string
nullable: true
description: Description of the group.
escalate_to:
type: integer
format: int64
nullable: true
description: ID of the agent to escalate to.
unassigned_for:
type: string
nullable: true
description: Duration after which unassigned tickets are escalated.
business_hour_id:
type: integer
format: int64
nullable: true
description: ID of the associated business hour schedule.
agent_ids:
type: array
items:
type: integer
format: int64
description: IDs of agents in the group.
auto_ticket_assign:
type: boolean
description: Whether tickets are auto-assigned within the group.
created_at:
type: string
format: date-time
description: Timestamp when the group was created.
updated_at:
type: string
format: date-time
description: Timestamp when the group was last updated.
GroupCreate:
type: object
required:
- name
properties:
name:
type: string
description: Name of the group.
description:
type: string
description: Description of the group.
escalate_to:
type: integer
format: int64
description: Agent ID to escalate to.
unassigned_for:
type: string
description: Duration for escalation.
agent_ids:
type: array
items:
type: integer
format: int64
description: Agent IDs to include.
auto_ticket_assign:
type: boolean
description: Enable auto-assignment.
Error:
type: object
properties:
description:
type: string
description: Human-readable error description.
errors:
type: array
items:
type: object
properties:
field:
type: string
description: Field that caused the error.
message:
type: string
description: Error message for the field.
code:
type: string
description: Error code.
securitySchemes:
basicAuth:
type: http
scheme: basic
description: Freshdesk uses API key-based authentication. Pass your API key as the username with any string (e.g. X) as the password using HTTP Basic Authentication.
externalDocs:
description: Freshdesk API Documentation
url: https://developers.freshdesk.com/api/