Freshworks Freshservice API

openapi: 3.1.0
info:
  title: Freshworks Freshservice API
  description: >-
    The Freshservice API v2 is a RESTful API for managing IT service desk
    operations programmatically. It provides endpoints for tickets, problems,
    changes, releases, assets, requesters, agents, and other ITSM resources.
    The API supports Cross-Origin Resource Sharing (CORS) for web-based
    applications, uses API key authentication via Base64-encoded authorization
    headers, and allows organizations to automate IT service management
    workflows and integrate Freshservice with other enterprise tools.
  version: '2.0'
  contact:
    name: Freshworks Support
    url: https://support.freshservice.com/
  termsOfService: https://www.freshworks.com/terms/
externalDocs:
  description: Freshservice API Documentation
  url: https://api.freshservice.com/
servers:
  - url: https://{domain}.freshservice.com/api/v2
    description: Freshservice Production Server
    variables:
      domain:
        default: yourdomain
        description: Your Freshservice subdomain
tags:
  - name: Agents
    description: >-
      Manage service desk agents and their configurations.
  - name: Assets
    description: >-
      Manage IT assets including hardware, software, and configurations.
  - name: Changes
    description: >-
      Manage change requests for controlled modifications to IT infrastructure.
  - name: Conversations
    description: >-
      Manage ticket conversations including replies and notes.
  - name: Departments
    description: >-
      Manage organizational department records.
  - name: Locations
    description: >-
      Manage office and facility locations.
  - name: Problems
    description: >-
      Manage problem records for root cause analysis of recurring incidents.
  - name: Products
    description: >-
      Manage product records tracked in the service desk.
  - name: Releases
    description: >-
      Manage release records for deploying changes to production.
  - name: Requesters
    description: >-
      Manage requesters who submit tickets to the service desk.
  - name: Service Catalog
    description: >-
      Manage service catalog items available for request.
  - name: Tickets
    description: >-
      Manage IT service desk tickets including incidents, service requests,
      and their lifecycle.
  - name: Vendors
    description: >-
      Manage vendor records for IT procurement and contracts.
security:
  - basicAuth: []
paths:
  /tickets:
    get:
      operationId: listTickets
      summary: List all tickets
      description: >-
        Retrieves a paginated list of all tickets in the service desk.
        Results can be filtered by various criteria including status,
        priority, type, and requester.
      tags:
        - Tickets
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - name: filter
          in: query
          description: Pre-defined filter to apply.
          schema:
            type: string
        - name: requester_id
          in: query
          description: Filter tickets by requester ID.
          schema:
            type: integer
        - name: email
          in: query
          description: Filter tickets by requester email.
          schema:
            type: string
            format: email
        - name: updated_since
          in: query
          description: Return tickets updated after this timestamp.
          schema:
            type: string
            format: date-time
        - name: type
          in: query
          description: >-
            Filter tickets by type (Incident, Service Request).
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  tickets:
                    type: array
                    items:
                      $ref: '#/components/schemas/Ticket'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createTicket
      summary: Create a ticket
      description: >-
        Creates a new ticket in the service desk. Requires at minimum a
        requester identification, subject, description, status, and priority.
      tags:
        - Tickets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TicketCreate'
      responses:
        '201':
          description: Ticket created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ticket:
                    $ref: '#/components/schemas/Ticket'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /tickets/{ticket_id}:
    get:
      operationId: getTicket
      summary: View a ticket
      description: >-
        Retrieves the details of a specific ticket by its ID.
      tags:
        - Tickets
      parameters:
        - $ref: '#/components/parameters/TicketIdParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  ticket:
                    $ref: '#/components/schemas/Ticket'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateTicket
      summary: Update a ticket
      description: >-
        Updates the properties of an existing ticket.
      tags:
        - Tickets
      parameters:
        - $ref: '#/components/parameters/TicketIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TicketUpdate'
      responses:
        '200':
          description: Ticket updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ticket:
                    $ref: '#/components/schemas/Ticket'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteTicket
      summary: Delete a ticket
      description: >-
        Deletes a ticket from the service desk permanently.
      tags:
        - Tickets
      parameters:
        - $ref: '#/components/parameters/TicketIdParam'
      responses:
        '204':
          description: Ticket deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /tickets/{ticket_id}/restore:
    put:
      operationId: restoreTicket
      summary: Restore a deleted ticket
      description: >-
        Restores a previously deleted ticket.
      tags:
        - Tickets
      parameters:
        - $ref: '#/components/parameters/TicketIdParam'
      responses:
        '204':
          description: Ticket restored successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /tickets/{ticket_id}/conversations:
    get:
      operationId: listTicketConversations
      summary: List all conversations of a ticket
      description: >-
        Retrieves all conversations associated with a specific ticket.
      tags:
        - Conversations
      parameters:
        - $ref: '#/components/parameters/TicketIdParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  conversations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Conversation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /tickets/{ticket_id}/reply:
    post:
      operationId: replyToTicket
      summary: Reply to a ticket
      description: >-
        Adds a reply to a ticket visible to the requester.
      tags:
        - Conversations
      parameters:
        - $ref: '#/components/parameters/TicketIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - body
              properties:
                body:
                  type: string
                  description: HTML content of the reply.
                cc_emails:
                  type: array
                  items:
                    type: string
                    format: email
                  description: Email addresses to CC.
                bcc_emails:
                  type: array
                  items:
                    type: string
                    format: email
                  description: Email addresses to BCC.
      responses:
        '201':
          description: Reply created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  conversation:
                    $ref: '#/components/schemas/Conversation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /tickets/{ticket_id}/notes:
    post:
      operationId: createNote
      summary: Create a note on a ticket
      description: >-
        Adds a private or public note to a ticket.
      tags:
        - Conversations
      parameters:
        - $ref: '#/components/parameters/TicketIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - body
              properties:
                body:
                  type: string
                  description: HTML content of the note.
                private:
                  type: boolean
                  description: Whether the note is private.
                  default: true
      responses:
        '201':
          description: Note created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  conversation:
                    $ref: '#/components/schemas/Conversation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /problems:
    get:
      operationId: listProblems
      summary: List all problems
      description: >-
        Retrieves a paginated list of all problem records in the service
        desk for root cause analysis and resolution.
      tags:
        - Problems
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  problems:
                    type: array
                    items:
                      $ref: '#/components/schemas/Problem'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createProblem
      summary: Create a problem
      description: >-
        Creates a new problem record in the service desk for tracking
        and resolving the root cause of incidents.
      tags:
        - Problems
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProblemCreate'
      responses:
        '201':
          description: Problem created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  problem:
                    $ref: '#/components/schemas/Problem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /problems/{problem_id}:
    get:
      operationId: getProblem
      summary: View a problem
      description: >-
        Retrieves the details of a specific problem by its ID.
      tags:
        - Problems
      parameters:
        - $ref: '#/components/parameters/ProblemIdParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  problem:
                    $ref: '#/components/schemas/Problem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateProblem
      summary: Update a problem
      description: >-
        Updates the properties of an existing problem record.
      tags:
        - Problems
      parameters:
        - $ref: '#/components/parameters/ProblemIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProblemCreate'
      responses:
        '200':
          description: Problem updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  problem:
                    $ref: '#/components/schemas/Problem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteProblem
      summary: Delete a problem
      description: >-
        Deletes a problem record from the service desk.
      tags:
        - Problems
      parameters:
        - $ref: '#/components/parameters/ProblemIdParam'
      responses:
        '204':
          description: Problem deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /changes:
    get:
      operationId: listChanges
      summary: List all changes
      description: >-
        Retrieves a paginated list of all change requests in the service desk.
      tags:
        - Changes
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  changes:
                    type: array
                    items:
                      $ref: '#/components/schemas/Change'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createChange
      summary: Create a change request
      description: >-
        Creates a new change request for tracking controlled modifications
        to IT infrastructure and services.
      tags:
        - Changes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeCreate'
      responses:
        '201':
          description: Change created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  change:
                    $ref: '#/components/schemas/Change'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /changes/{change_id}:
    get:
      operationId: getChange
      summary: View a change request
      description: >-
        Retrieves the details of a specific change request by its ID.
      tags:
        - Changes
      parameters:
        - $ref: '#/components/parameters/ChangeIdParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  change:
                    $ref: '#/components/schemas/Change'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateChange
      summary: Update a change request
      description: >-
        Updates the properties of an existing change request.
      tags:
        - Changes
      parameters:
        - $ref: '#/components/parameters/ChangeIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeCreate'
      responses:
        '200':
          description: Change updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  change:
                    $ref: '#/components/schemas/Change'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteChange
      summary: Delete a change request
      description: >-
        Deletes a change request from the service desk.
      tags:
        - Changes
      parameters:
        - $ref: '#/components/parameters/ChangeIdParam'
      responses:
        '204':
          description: Change deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /releases:
    get:
      operationId: listReleases
      summary: List all releases
      description: >-
        Retrieves a paginated list of all release records in the service desk.
      tags:
        - Releases
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  releases:
                    type: array
                    items:
                      $ref: '#/components/schemas/Release'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createRelease
      summary: Create a release
      description: >-
        Creates a new release record for deploying changes to production.
      tags:
        - Releases
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReleaseCreate'
      responses:
        '201':
          description: Release created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  release:
                    $ref: '#/components/schemas/Release'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /releases/{release_id}:
    get:
      operationId: getRelease
      summary: View a release
      description: >-
        Retrieves the details of a specific release by its ID.
      tags:
        - Releases
      parameters:
        - name: release_id
          in: path
          required: true
          description: The ID of the release.
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  release:
                    $ref: '#/components/schemas/Release'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /assets:
    get:
      operationId: listAssets
      summary: List all assets
      description: >-
        Retrieves a paginated list of all IT assets tracked in the
        service desk including hardware, software, and other resources.
      tags:
        - Assets
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  assets:
                    type: array
                    items:
                      $ref: '#/components/schemas/Asset'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createAsset
      summary: Create an asset
      description: >-
        Creates a new IT asset record in the service desk.
      tags:
        - Assets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssetCreate'
      responses:
        '201':
          description: Asset created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  asset:
                    $ref: '#/components/schemas/Asset'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /assets/{asset_id}:
    get:
      operationId: getAsset
      summary: View an asset
      description: >-
        Retrieves the details of a specific IT asset by its display ID.
      tags:
        - Assets
      parameters:
        - $ref: '#/components/parameters/AssetIdParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  asset:
                    $ref: '#/components/schemas/Asset'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateAsset
      summary: Update an asset
      description: >-
        Updates the properties of an existing IT asset.
      tags:
        - Assets
      parameters:
        - $ref: '#/components/parameters/AssetIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssetCreate'
      responses:
        '200':
          description: Asset updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  asset:
                    $ref: '#/components/schemas/Asset'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteAsset
      summary: Delete an asset
      description: >-
        Permanently deletes an IT asset from the service desk.
      tags:
        - Assets
      parameters:
        - $ref: '#/components/parameters/AssetIdParam'
      responses:
        '204':
          description: Asset deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /requesters:
    get:
      operationId: listRequesters
      summary: List all requesters
      description: >-
        Retrieves a paginated list of all requesters in the service desk.
      tags:
        - Requesters
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - name: email
          in: query
          description: Filter requesters by email address.
          schema:
            type: string
            format: email
        - name: query
          in: query
          description: >-
            Search query to filter requesters by name or email.
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  requesters:
                    type: array
                    items:
                      $ref: '#/components/schemas/Requester'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createRequester
      summary: Create a requester
      description: >-
        Creates a new requester in the service desk.
      tags:
        - Requesters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequesterCreate'
      responses:
        '201':
          description: Requester created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  requester:
                    $ref: '#/components/schemas/Requester'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /requesters/{requester_id}:
    get:
      operationId: getRequester
      summary: View a requester
      description: >-
        Retrieves the details of a specific requester by their ID.
      tags:
        - Requesters
      parameters:
        - $ref: '#/components/parameters/RequesterIdParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  requester:
                    $ref: '#/components/schemas/Requester'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateRequester
      summary: Update a requester
      description: >-
        Updates the properties of an existing requester.
      tags:
        - Requesters
      parameters:
        - $ref: '#/components/parameters/RequesterIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequesterCreate'
      responses:
        '200':
          description: Requester updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  requester:
                    $ref: '#/components/schemas/Requester'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteRequester
      summary: Delete a requester
      description: >-
        Deletes a requester from the service desk.
      tags:
        - Requesters
      parameters:
        - $ref: '#/components/parameters/RequesterIdParam'
      responses:
        '204':
          description: Requester deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /agents:
    get:
      operationId: listAgents
      summary: List all agents
      description: >-
        Retrieves a paginated list of all service desk agents.
      tags:
        - Agents
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - name: email
          in: query
          description: Filter agents by email address.
          schema:
            type: string
            format: email
        - name: state
          in: query
          description: Filter agents by active state.
          schema:
            type: string
            enum:
              - fulltime
              - occasional
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  agents:
                    type: array
                    items:
                      $ref: '#/components/schemas/Agent'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /agents/{agent_id}:
    get:
      operationId: getAgent
      summary: View an agent
      description: >-
        Retrieves the details of a specific agent by their ID.
      tags:
        - Agents
      parameters:
        - $ref: '#/components/parameters/AgentIdParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  agent:
                    $ref: '#/components/schemas/Agent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /vendors:
    get:
      operationId: listVendors
      summary: List all vendors
      description: >-
        Retrieves a paginated list of all vendor records in the service desk.
      tags:
        - Vendors
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  vendors:
                    type: array
                    items:
                      $ref: '#/components/schemas/Vendor'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createVendor
      summary: Create a vendor
      description: >-
        Creates a new vendor record in the service desk.
      tags:
        - Vendors
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VendorCreate'
      responses:
        '201':
          description: Vendor created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  vendor:
                    $ref: '#/components/schemas/Vendor'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /products:
    get:
      operationId: listProducts
      summary: List all products
      description: >-
        Retrieves a list of all products tracked in the service desk.
      tags:
        - Products
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  products:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /locations:
    get:
      operationId: listLocations
      summary: List all locations
      description: >-
        Retrieves a list of all office and facility locations.
      tags:
        - Locations
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema

# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/freshworks/refs/heads/main/openapi/freshworks-freshservice-api-openapi.yml