Workspaces was introduced in the product in November of 2022. Originally, when asked about API endpoints, there were no expected API endpoints. Opened a forum topic here in Feb:
Workspaces Support - Product - Freshworks Developer Community
Being a partner, we leverage the API’s every day. Ticket and KB migrations, CMDB population, importing and setup of Agents and many other facets of Onboarding and maintenance of Freshservice. We are trying to create tools for our teams, which move a lot of data in and out of Freshservice and have even provided a Powershell library for the entire Freshworks community to make the Freshservice API command-line accessible:
PowerShell Gallery | FreshservicePS 0.1.3
Documentation
As new features rollout, providing API capabilities and documentation seem to be a low priority or never occur. Many of the API endpoints are highly dependent on the id of an object to be able to make associations. There have been some updates for Workspaces showing up in the documentation (api.freshservice.com), such as the move ticket requested in the post above. This requires the workspace_id, however, no published GET method for Workspace. Taking a guess, there is a Workspaces endpoint:
PS C:\Build\FreshservicePS> Get-FSWorkspace
created_at : 7/25/2023 1:25:30 PM
description :
id : 21000015068
logo :
name : My Team
preferences : @{personalized_email_replies=False; disable_agent_forward=False; email_spam_enabled=True; reply_to_based_tickets=True; remove_quoted_text=False}
primary : True
restricted : False
state : 1
template_name : it
updated_at : 7/25/2023 1:25:30 PM
Not in the documentation and more importantly, it does not have the workspace_id (e.g. display_id) required to associate for any public API endpoint reference. This requires someone to go into the interface to get information. Workspaces isn’t alone. For instance, On Call Schedule, been in the product for a year (It’s time! Sign up for On-Call Management Beta! | Freshworks Community), no API endpoint. The ocs_schedule_id is in the schema for Agent Groups, no endpoint published to GET the On Call Schedule.
There are many other ancillary impacted Workspace items, such as Agents. Recently, we had to determine how to assign business licenses and workspaces to many Agents. Nothing in the documentation, but first oddity is the Agent object schema changes when Business Licenses are added. Try to set workspace_info, API says no. Try to set workspace_ids, it works. Try to set license_type, it works. More often than not, we are trying to set endpoint properties or see if endpoints exist as there is no documentation. While this is not ideal, through trial and error we were able to perform these actions. However, if we want to update our public library, that is another case entirely as this is unpublished public functionality.
There was another conversation regarding search and default workspace behavior:
Different API Behavior in Multi-Workspace (Freshservice) - Product - Freshworks Developer Community
Found that using a Workspace Id of 0 will search all workspaces a user has access to, not in the documentation. There are many examples of missing important documentation.
What is the process for managing and updating the documentation?
Bug Remediation and Feature enhancements
The ability to move tickets between Workspaces showed up in the documentation approximately a month ago. Testing and adding this functionality, almost immediately found a bug, which was reported promptly to support:[#14272933] Move Workspace Ticket API bug : Freshservice
No reply or status, we asked someone to provide status and it was routed to Marketing. Marketing?!? We have reported many other bugs, documentation issues, missing endpoints and not only are they rarely corrected, but there is also no communication regardless of how it is reported.
How do we drive product enhancement and innovation with no communication?
Change Tracking
Trying to track what changes have occurred in the API have been challenging as well. For months, we have been just doing a find on the documentation to search for workspace updates. Most of the API news is deprecation of V1 in Release notes in community.freshworks.com. The changelog is not being maintained:
Service Desk API for Developers | Freshservice
How are developers supposed to find changes in the API docs?
General Information\Account Endpoints
There are many dependencies on Freshservice version (e.g. is Workspace installed) or other components like license availability, plan, etc., but there are no published methods to GET account information. Is there a plan to provide a public account details endpoint? Something like…
{
"instance_version": "2023.R07.06",
"account_primary_last_name": "Smith",
"data_center": "US",
"asset_licenses": 100,
"account_id": 54321,
"account_plan": "Enterprise",
"it_licenses": 50,
"business_licenses": 100,
"account_primary_email": "joe.smith@acme.com",
"account_primary_first_name": "Joe",
"account_name": "acmehelpdesk"
}
Having a general endpoint that is accessible by all API keys would allow methods to programmatically validate that a connection can be successfully made to the API without permission errors.
