Freshservice¶
Connect HolmesGPT to Freshservice (Freshworks ITSM) to work with tickets, problems, changes, releases, assets, requesters, agents, the service catalog, the knowledge base and every other Freshservice object via the Freshservice API v2.
Access is read-only by default. Create/update/delete tools can be enabled with enable_write_tools: true, and each write requires human approval unless you disable that too (see Write access).
Prerequisites¶
- A Freshservice instance (e.g.
https://your-domain.freshservice.com) - A Freshservice API key. In the Freshservice UI, click your profile picture → Profile settings — the API key is shown below the change password section.
The API key inherits the permissions of its user, so the tickets, changes and other objects HolmesGPT can read are determined by that user's role. Some object types (e.g. assets/CMDB) are only available on certain Freshservice plans; HolmesGPT reports the exact API error when an object type is not accessible.
Verify your credentials:
Configuration¶
Add the following to ~/.holmes/config.yaml. Create the file if it doesn't exist:
toolsets:
freshservice:
enabled: true
config:
api_url: <your Freshservice URL> # e.g. https://your-domain.freshservice.com
api_key: <your Freshservice API key>
# Optional
default_page_size: 30 # Records per page when the LLM doesn't specify (max 100)
timeout_seconds: 30 # HTTP timeout for Freshservice API requests
health_check_object: tickets # Object type listed on startup to verify connectivity
After making changes to your configuration, run:
To test, run:
First, create a Kubernetes secret with your Freshservice API key:
kubectl create secret generic freshservice-credentials \
--from-literal=api-key=your-freshservice-api-key \
-n holmes
Namespace must match Holmes' deployment
Create the secret in the same namespace where Holmes runs. The -n holmes flag in the Holmes Helm tab and -n default in the Robusta Helm tab match each chart's documented defaults — adjust if you installed Holmes/Robusta into a different namespace. A secret in the wrong namespace silently resolves to an empty env var and authentication will fail with no clear error.
Then add to your Holmes Helm values:
First, create a Kubernetes secret with your Freshservice API key:
kubectl create secret generic freshservice-credentials \
--from-literal=api-key=your-freshservice-api-key \
-n default
Namespace must match Holmes' deployment
Create the secret in the same namespace where Holmes runs. The -n holmes flag in the Holmes Helm tab and -n default in the Robusta Helm tab match each chart's documented defaults — adjust if you installed Holmes/Robusta into a different namespace. A secret in the wrong namespace silently resolves to an empty env var and authentication will fail with no clear error.
Then add to your Robusta Helm values:
holmes:
additionalEnvVars:
- name: FRESHSERVICE_API_KEY
valueFrom:
secretKeyRef:
name: freshservice-credentials
key: api-key
toolsets:
freshservice:
enabled: true
config:
api_url: <your Freshservice URL> # e.g. https://your-domain.freshservice.com
api_key: "{{ env.FRESHSERVICE_API_KEY }}"
Update your Helm values and run a Helm upgrade:
Optional Fields¶
| Option | Default | Description |
|---|---|---|
default_page_size |
30 |
Number of records returned per page when the LLM does not specify one (max 100). |
timeout_seconds |
30 |
Timeout for Freshservice API requests. |
health_check_object |
tickets |
Object type listed on startup to verify connectivity and permissions. Change this if your API key cannot access tickets. |
enable_write_tools |
false |
Expose tools that create, update and delete Freshservice objects. When false, only read tools are available. |
require_approval_for_writes |
true |
When write tools are enabled, require human approval before each create/update/delete call. Set to false for fully autonomous writes. |
Write Access (optional)¶
By default HolmesGPT can only read from Freshservice. To let it create, update and delete objects (tickets, problems, changes, notes, tasks, time entries, custom object records and more), enable write tools:
toolsets:
freshservice:
enabled: true
config:
api_url: <your Freshservice URL>
api_key: <your Freshservice API key>
enable_write_tools: true
# require_approval_for_writes: false # only for fully autonomous writes
With writes enabled, six additional tools become available: freshservice_create_object, freshservice_update_object, freshservice_delete_object and their *_related_object counterparts for notes, replies, tasks and time entries.
Warning
Every write call requires interactive human approval by default. Only set require_approval_for_writes: false in automated flows where the API key's own Freshservice role is scoped to what Holmes should be allowed to touch — deletes move tickets to trash and deactivate requesters/agents. Some object types are read-only in the Freshservice API itself (roles, workspaces, form fields, SLA policies, business hours, service catalog) regardless of this setting.
Multiple Instances¶
The Freshservice toolset can connect to more than one Freshservice instance. List each one under instances: with a unique name. Any config field set outside instances: becomes a default that every instance inherits, so shared settings only need to be written once.
toolsets:
freshservice:
enabled: true
config:
instances:
- name: prod
api_url: <your Freshservice URL>
api_key: <your Freshservice API key>
- name: staging
api_url: <your Freshservice URL>
api_key: <your Freshservice API key>
When more than one instance is configured, HolmesGPT automatically adds an instance parameter to every Freshservice tool (so it can pick which instance to query) and a freshservice_list_instances tool to list the configured instances. With a single instance — including the flat config without instances: — the tools are unchanged and fully backwards compatible.
See Multiple Instances for the full behaviour, including global defaults and health reporting.