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:
                type: object
                properties:
                  locations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Location'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /departments:
    get:
      operationId: listDepartments
      summary: List all departments
      description: >-
        Retrieves a list of all organizational departments.
      tags:
        - Departments
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  departments:
                    type: array
                    items:
                      $ref: '#/components/schemas/Department'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /service_catalog/items:
    get:
      operationId: listServiceCatalogItems
      summary: List all service catalog items
      description: >-
        Retrieves a list of all items available in the service catalog
        for requesters to browse and request.
      tags:
        - Service Catalog
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  service_items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ServiceItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /service_catalog/items/{item_id}:
    get:
      operationId: getServiceCatalogItem
      summary: View a service catalog item
      description: >-
        Retrieves the details of a specific service catalog item.
      tags:
        - Service Catalog
      parameters:
        - name: item_id
          in: path
          required: true
          description: The ID of the service catalog item.
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  service_item:
                    $ref: '#/components/schemas/ServiceItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        Use your API key as the username and X as the password. The API
        key can be found in your Freshservice profile settings.
  parameters:
    PageParam:
      name: page
      in: query
      description: Page number for pagination.
      schema:
        type: integer
        minimum: 1
        default: 1
    PerPageParam:
      name: per_page
      in: query
      description: Number of results per page (max 100).
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 30
    TicketIdParam:
      name: ticket_id
      in: path
      required: true
      description: The ID of the ticket.
      schema:
        type: integer
    ProblemIdParam:
      name: problem_id
      in: path
      required: true
      description: The ID of the problem.
      schema:
        type: integer
    ChangeIdParam:
      name: change_id
      in: path
      required: true
      description: The ID of the change request.
      schema:
        type: integer
    AssetIdParam:
      name: asset_id
      in: path
      required: true
      description: The display ID of the asset.
      schema:
        type: integer
    RequesterIdParam:
      name: requester_id
      in: path
      required: true
      description: The ID of the requester.
      schema:
        type: integer
    AgentIdParam:
      name: agent_id
      in: path
      required: true
      description: The ID of the agent.
      schema:
        type: integer
  responses:
    BadRequest:
      description: The request body or parameters are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Ticket:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the ticket.
        subject:
          type: string
          description: Subject of the ticket.
        description:
          type: string
          description: HTML description of the ticket.
        description_text:
          type: string
          description: Plain text description of the ticket.
        status:
          type: integer
          description: >-
            Status of the ticket. 2=Open, 3=Pending, 4=Resolved, 5=Closed.
        priority:
          type: integer
          description: >-
            Priority of the ticket. 1=Low, 2=Medium, 3=High, 4=Urgent.
        type:
          type: string
          description: Type of the ticket (Incident, Service Request).
        source:
          type: integer
          description: Source channel of the ticket.
        requester_id:
          type: integer
          description: ID of the requester.
        responder_id:
          type: integer
          description: ID of the assigned agent.
        group_id:
          type: integer
          description: ID of the assigned group.
        department_id:
          type: integer
          description: ID of the associated department.
        category:
          type: string
          description: Category of the ticket.
        sub_category:
          type: string
          description: Sub-category of the ticket.
        item_category:
          type: string
          description: Item category of the ticket.
        email:
          type: string
          format: email
          description: Email of the requester.
        tags:
          type: array
          items:
            type: string
          description: Tags associated with the ticket.
        due_by:
          type: string
          format: date-time
          description: Due date for ticket resolution.
        fr_due_by:
          type: string
          format: date-time
          description: Due date for first response.
        is_escalated:
          type: boolean
          description: Whether the ticket has been escalated.
        custom_fields:
          type: object
          additionalProperties: true
          description: Custom field values.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the ticket was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the ticket was last updated.
    TicketCreate:
      type: object
      required:
        - subject
        - description
        - email
        - status
        - priority
      properties:
        subject:
          type: string
          description: Subject of the ticket.
        description:
          type: string
          description: HTML description of the ticket.
        email:
          type: string
          format: email
          description: Email of the requester.
        requester_id:
          type: integer
          description: ID of the requester.
        status:
          type: integer
          description: Status of the ticket.
        priority:
          type: integer
          description: Priority of the ticket.
        type:
          type: string
          description: Type of the ticket.
        source:
          type: integer
          description: Source channel.
        responder_id:
          type: integer
          description: ID of the agent to assign.
        group_id:
          type: integer
          description: ID of the group to assign.
        department_id:
          type: integer
          description: ID of the department.
        category:
          type: string
          description: Category of the ticket.
        sub_category:
          type: string
          description: Sub-category.
        item_category:
          type: string
          description: Item category.
        tags:
          type: array
          items:
            type: string
          description: Tags to associate.
        cc_emails:
          type: array
          items:
            type: string
            format: email
          description: Email addresses to CC.
        custom_fields:
          type: object
          additionalProperties: true
          description: Custom field values.
    TicketUpdate:
      type: object
      properties:
        subject:
          type: string
          description: Subject of the ticket.
        description:
          type: string
          description: HTML description.
        status:
          type: integer
          description: Status of the ticket.
        priority:
          type: integer
          description: Priority of the ticket.
        responder_id:
          type: integer
          description: ID of the agent to assign.
        group_id:
          type: integer
          description: ID of the group to assign.
        type:
          type: string
          description: Type of the ticket.
        category:
          type: string
          description: Category.
        sub_category:
          type: string
          description: Sub-category.
        tags:
          type: array
          items:
            type: string
          description: Tags.
        custom_fields:
          type: object
          additionalProperties: true
          description: Custom field values.
    Conversation:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the conversation.
        body:
          type: string
          description: HTML content of the conversation.
        body_text:
          type: string
          description: Plain text content.
        incoming:
          type: boolean
          description: Whether the conversation is incoming.
        private:
          type: boolean
          description: Whether the conversation is private.
        user_id:
          type: integer
          description: ID of the user who created the conversation.
        to_emails:
          type: array
          items:
            type: string
            format: email
          description: Recipients.
        created_at:
          type: string
          format: date-time
          description: Timestamp when created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when last updated.
    Problem:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the problem.
        subject:
          type: string
          description: Subject of the problem.
        description:
          type: string
          description: HTML description.
        status:
          type: integer
          description: >-
            Status of the problem. 1=Open, 2=Change Requested, 3=Closed.
        priority:
          type: integer
          description: >-
            Priority. 1=Low, 2=Medium, 3=High, 4=Urgent.
        impact:
          type: integer
          description: >-
            Impact. 1=Low, 2=Medium, 3=High.
        agent_id:
          type: integer
          description: ID of the assigned agent.
        group_id:
          type: integer
          description: ID of the assigned group.
        department_id:
          type: integer
          description: ID of the department.
        known_error:
          type: boolean
          description: Whether this is a known error.
        due_by:
          type: string
          format: date-time
          description: Due date for resolution.
        created_at:
          type: string
          format: date-time
          description: Timestamp when created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when last updated.
    ProblemCreate:
      type: object
      required:
        - subject
        - description
        - status
        - priority
        - impact
      properties:
        subject:
          type: string
          description: Subject of the problem.
        description:
          type: string
          description: HTML description.
        status:
          type: integer
          description: Status of the problem.
        priority:
          type: integer
          description: Priority.
        impact:
          type: integer
          description: Impact level.
        agent_id:
          type: integer
          description: ID of the agent to assign.
        group_id:
          type: integer
          description: ID of the group to assign.
        department_id:
          type: integer
          description: ID of the department.
        known_error:
          type: boolean
          description: Whether this is a known error.
        due_by:
          type: string
          format: date-time
          description: Due date.
    Change:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the change.
        subject:
          type: string
          description: Subject of the change request.
        description:
          type: string
          description: HTML description.
        status:
          type: integer
          description: >-
            Status. 1=Open, 2=Planning, 3=Awaiting Approval,
            4=Pending Release, 5=Pending Review, 6=Closed.
        priority:
          type: integer
          description: >-
            Priority. 1=Low, 2=Medium, 3=High, 4=Urgent.
        impact:
          type: integer
          description: >-
            Impact. 1=Low, 2=Medium, 3=High.
        risk:
          type: integer
          description: >-
            Risk. 1=Low, 2=Medium, 3=High, 4=Very High.
        change_type:
          type: string
          description: Type of change (Standard, Normal, Emergency, Minor).
        agent_id:
          type: integer
          description: ID of the assigned agent.
        group_id:
          type: integer
          description: ID of the assigned group.
        department_id:
          type: integer
          description: ID of the department.
        planned_start_date:
          type: string
          format: date-time
          description: Planned start date.
        planned_end_date:
          type: string
          format: date-time
          description: Planned end date.
        created_at:
          type: string
          format: date-time
          description: Timestamp when created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when last updated.
    ChangeCreate:
      type: object
      required:
        - subject
        - description
        - status
        - priority
        - impact
        - risk
        - change_type
      properties:
        subject:
          type: string
          description: Subject of the change request.
        description:
          type: string
          description: HTML description.
        status:
          type: integer
          description: Status.
        priority:
          type: integer
          description: Priority.
        impact:
          type: integer
          description: Impact level.
        risk:
          type: integer
          description: Risk level.
        change_type:
          type: string
          description: Type of change.
        agent_id:
          type: integer
          description: ID of the agent to assign.
        group_id:
          type: integer
          description: ID of the group to assign.
        department_id:
          type: integer
          description: ID of the department.
        planned_start_date:
          type: string
          format: date-time
          description: Planned start date.
        planned_end_date:
          type: string
          format: date-time
          description: Planned end date.
    Release:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the release.
        subject:
          type: string
          description: Subject of the release.
        description:
          type: string
          description: HTML description.
        status:
          type: integer
          description: >-
            Status. 1=Open, 2=On Hold, 3=In Progress, 4=Incomplete, 5=Completed.
        priority:
          type: integer
          description: >-
            Priority. 1=Low, 2=Medium, 3=High, 4=Urgent.
        release_type:
          type: integer
          description: >-
            Type. 1=Minor, 2=Standard, 3=Major, 4=Emergency.
        planned_start_date:
          type: string
          format: date-time
          description: Planned start date.
        planned_end_date:
          type: string
          format: date-time
          description: Planned end date.
        created_at:
          type: string
          format: date-time
          description: Timestamp when created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when last updated.
    ReleaseCreate:
      type: object
      required:
        - subject
        - description
        - status
        - priority
        - release_type
        - planned_start_date
        - planned_end_date
      properties:
        subject:
          type: string
          description: Subject of the release.
        description:
          type: string
          description: HTML description.
        status:
          type: integer
          description: Status.
        priority:
          type: integer
          description: Priority.
        release_type:
          type: integer
          description: Type of release.
        planned_start_date:
          type: string
          format: date-time
          description: Planned start date.
        planned_end_date:
          type: string
          format: date-time
          description: Planned end date.
    Asset:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the asset.
        display_id:
          type: integer
          description: Display ID of the asset.
        name:
          type: string
          description: Name of the asset.
        description:
          type: string
          description: Description of the asset.
        asset_type_id:
          type: integer
          description: ID of the asset type.
        asset_tag:
          type: string
          description: Asset tag identifier.
        impact:
          type: string
          description: Impact level of the asset.
        usage_type:
          type: string
          description: Usage type (permanent, loaner).
        user_id:
          type: integer
          description: ID of the user assigned to the asset.
        department_id:
          type: integer
          description: ID of the department.
        location_id:
          type: integer
          description: ID of the location.
        agent_id:
          type: integer
          description: ID of the managing agent.
        assigned_on:
          type: string
          format: date-time
          description: Date when the asset was assigned.
        created_at:
          type: string
          format: date-time
          description: Timestamp when created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when last updated.
    AssetCreate:
      type: object
      required:
        - name
        - asset_type_id
      properties:
        name:
          type: string
          description: Name of the asset.
        description:
          type: string
          description: Description.
        asset_type_id:
          type: integer
          description: ID of the asset type.
        asset_tag:
          type: string
          description: Asset tag identifier.
        impact:
          type: string
          description: Impact level.
        usage_type:
          type: string
          description: Usage type.
        user_id:
          type: integer
          description: ID of the user to assign.
        department_id:
          type: integer
          description: ID of the department.
        location_id:
          type: integer
          description: ID of the location.
        agent_id:
          type: integer
          description: ID of the managing agent.
    Requester:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the requester.
        first_name:
          type: string
          description: First name.
        last_name:
          type: string
          description: Last name.
        primary_email:
          type: string
          format: email
          description: Primary email address.
        work_phone_number:
          type: string
          description: Work phone number.
        mobile_phone_number:
          type: string
          description: Mobile phone number.
        job_title:
          type: string
          description: Job title.
        department_id:
          type: integer
          description: ID of the department.
        location_id:
          type: integer
          description: ID of the location.
        is_agent:
          type: boolean
          description: Whether the requester is also an agent.
        active:
          type: boolean
          description: Whether the requester is active.
        custom_fields:
          type: object
          additionalProperties: true
          description: Custom field values.
        created_at:
          type: string
          format: date-time
          description: Timestamp when created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when last updated.
    RequesterCreate:
      type: object
      required:
        - first_name
        - primary_email
      properties:
        first_name:
          type: string
          description: First name.
        last_name:
          type: string
          description: Last name.
        primary_email:
          type: string
          format: email
          description: Primary email address.
        work_phone_number:
          type: string
          description: Work phone number.
        mobile_phone_number:
          type: string
          description: Mobile phone number.
        job_title:
          type: string
          description: Job title.
        department_id:
          type: integer
          description: ID of the department.
        location_id:
          type: integer
          description: ID of the location.
        custom_fields:
          type: object
          additionalProperties: true
          description: Custom field values.
    Agent:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the agent.
        first_name:
          type: string
          description: First name.
        last_name:
          type: string
          description: Last name.
        email:
          type: string
          format: email
          description: Email address.
        occasional:
          type: boolean
          description: Whether the agent is occasional.
        active:
          type: boolean
          description: Whether the agent is active.
        role_ids:
          type: array
          items:
            type: integer
          description: IDs of assigned roles.
        group_ids:
          type: array
          items:
            type: integer
          description: IDs of assigned groups.
        department_ids:
          type: array
          items:
            type: integer
          description: IDs of associated departments.
        created_at:
          type: string
          format: date-time
          description: Timestamp when created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when last updated.
    Vendor:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the vendor.
        name:
          type: string
          description: Name of the vendor.
        description:
          type: string
          description: Description.
        primary_contact:
          type: string
          description: Primary contact person.
        email:
          type: string
          format: email
          description: Vendor email address.
        phone:
          type: string
          description: Phone number.
        address:
          type: object
          description: Address of the vendor.
          properties:
            line1:
              type: string
              description: Address line 1.
            line2:
              type: string
              description: Address line 2.
            city:
              type: string
              description: City.
            state:
              type: string
              description: State or province.
            country:
              type: string
              description: Country.
            zip_code:
              type: string
              description: Postal or ZIP code.
        created_at:
          type: string
          format: date-time
          description: Timestamp when created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when last updated.
    VendorCreate:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Name of the vendor.
        description:
          type: string
          description: Description.
        primary_contact:
          type: string
          description: Primary contact person.
        email:
          type: string
          format: email
          description: Vendor email address.
        phone:
          type: string
          description: Phone number.
        address:
          type: object
          properties:
            line1:
              type: string
              description: Address line 1.
            line2:
              type: string
              description: Address line 2.
            city:
              type: string
              description: City.
            state:
              type: string
              description: State or province.
            country:
              type: string
              description: Country.
            zip_code:
              type: string
              description: Postal or ZIP code.
    Product:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the product.
        name:
          type: string
          description: Name of the product.
        description:
          type: string
          description: Description.
        asset_type_id:
          type: integer
          description: ID of the associated asset type.
        manufacturer:
          type: string
          description: Manufacturer name.
        mode_of_procurement:
          type: string
          description: Procurement mode.
        status:
          type: string
          description: Product status.
        created_at:
          type: string
          format: date-time
          description: Timestamp when created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when last updated.
    Location:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the location.
        name:
          type: string
          description: Name of the location.
        address:
          type: object
          description: Address of the location.
          properties:
            line1:
              type: string
              description: Address line 1.
            line2:
              type: string
              description: Address line 2.
            city:
              type: string
              description: City.
            state:
              type: string
              description: State or province.
            country:
              type: string
              description: Country.
            zip_code:
              type: string
              description: Postal or ZIP code.
        contact:
          type: object
          description: Contact information.
          properties:
            name:
              type: string
              description: Contact name.
            phone:
              type: string
              description: Contact phone.
            email:
              type: string
              format: email
              description: Contact email.
        created_at:
          type: string
          format: date-time
          description: Timestamp when created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when last updated.
    Department:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the department.
        name:
          type: string
          description: Name of the department.
        description:
          type: string
          description: Description.
        head_user_id:
          type: integer
          description: ID of the department head.
        prime_user_id:
          type: integer
          description: ID of the primary user.
        domains:
          type: array
          items:
            type: string
          description: Email domains associated with the department.
        custom_fields:
          type: object
          additionalProperties: true
          description: Custom field values.
        created_at:
          type: string
          format: date-time
          description: Timestamp when created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when last updated.
    ServiceItem:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the service item.
        name:
          type: string
          description: Name of the service item.
        description:
          type: string
          description: Description.
        short_description:
          type: string
          description: Short description for catalog listing.
        category_id:
          type: integer
          description: ID of the service category.
        display_id:
          type: integer
          description: Display ID for the item.
        delivery_time:
          type: integer
          description: Expected delivery time in hours.
        visibility:
          type: integer
          description: Visibility setting.
        created_at:
          type: string
          format: date-time
          description: Timestamp when created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when last updated.
    Error:
      type: object
      properties:
        description:
          type: string
          description: Human-readable error message.
        errors:
          type: array
          description: List of specific validation errors.
          items:
            type: object
            properties:
              field:
                type: string
                description: Field that caused the error.
              message:
                type: string
                description: Error message.
              code:
                type: string
                description: Error code.