> ## Documentation Index
> Fetch the complete documentation index at: https://developers.techwolf.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Breaking Changes

The list below provides an overview of breaking changes to the SkillEngine API.
Breaking changes are modifications that may cause your existing integrations to
stop working. These changes are only applied to your tenant when you request a
version update.

### July 2026

* Removed the deprecated `GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/recommended_courses` endpoint; use the `POST` variant on the same path instead.
* Removed the `POST /reports/job_architecture_benchmark` endpoint.

### March 2026

* The `proficiency_level`, `proficiency_float`, and `critical` response fields have been replaced
  with `governed_proficiency_level`, `inferred_proficiency_level`, `governed_proficiency_float`,
  `inferred_proficiency_float`, `governed_critical`, and `inferred_critical` on the following endpoints:
  * `GET /job_architecture/jobs/{job_external_id}/skill_profile`
  * `GET /job_architecture/job_families/{job_family_external_id}/skill_profile`
  * `POST /job_architecture/export/jobs/skill_profiles`
  * `POST /job_architecture/export/job_families/skill_profiles`
* The `validation_state` field is now always returned on each Skill in the Skill Profile response
  for the above endpoints. The `include=skill_validation_state` query/body parameter has been removed.
* Suggested Skills (with `validation_state: "suggested"`) are now included alongside governed Skills
  in the Skill Profile response for the above endpoints.

### December 2025

* Changed the `GET /reports/data_maturity_scan/employee_quality_matrix` endpoint
  to `POST` and added optional `filters` request body to filter by Employee external IDs.
* Changed the `GET /reports/data_maturity_scan/job_quality_matrix` endpoint
  to `POST` and added optional `filters` request body to filter by Job external IDs.

### September 2025

* Removed `translation_found` field from the `GET /employees/suggestions/skills` endpoint.
* Removed skill names from unsupported languages from the output of the `GET /employees/suggestions/skills` endpoint.

### August 2025

* Deprecated the `domains` response format from the
  `GET /courses/{course_external_id}/skill_profile` and the
  `GET /vacancies/{vacancy_external_id}/skill_profile` endpoints.

### March 2025

* Removed the `skill_vocab` and `external_id` fields from the
  `GET /taxonomy/skills` endpoint
* Removed the `skill_vocab` and `external_id` fields from the
  `GET /taxonomy/skills/{skill_id}` endpoint
* Removed the `skill_vocab` and `external_id` fields from the
  `GET /taxonomy/skill_clusters/{skill_cluster_external_id}/skills` endpoint
* Removed the `skill_vocab` and `external_id` fields from the
  `GET /taxonomy/export` endpoint

### February 2025

* Removed the `POST /integrations/file_load_task` endpoint.
* Removed the `GET /integrations/file_load_task/{task_id}` endpoint.
* Removed the `/job_architecture/jobs/{job_external_id}/market_skill_profile`
  endpoint.

### January 2025

* Removed the `response_format=trending` query paramter option for all
  `GET /<entity>/skill_profile` endpoints.

### December 2024

* Removed the `GET /employees/{external_id}/metrics/position_alignment`
  endpoint.

### November 2024

* Removed the `POST /vacancies/{external_id}/metrics/fillability` endpoint.
* Renamed the value of query parameter `include=description` to
  `include=skill_description` in the `GET /taxonomy/skills` endpoint.

### October 2024

* Changed the format for duplicate data examples from the
  `GET /reports/data_maturity_scan/data_improvement_actions` endpoint.
* Removed the `POST /reports/skills_alignment` endpoint.
* Removed the `POST /reports/workforce_alignment` endpoint.
* Removed the `POST /reports/strategy_map` endpoint.
* Removed the `POST /reports/skill_frequencies` endpoint.
* Removed the `POST /reports/organization_names` endpoint.
* Removed the `POST /reports/employee_skill_distribution` endpoint.
* Removed the `POST /reports/vacancy_skill_distribution` endpoint.

### September 2024

* Renamed the field `name` to `skill_name` in the
  `GET /employees/{external_id}/skill_profile` endpoint when the
  `response_format` query parameter is set to `skill_clusters` or `domains`.

### August 2024

* Removed the `GET /reports/succession_risk` endpoint.
* Removed the `GET /reports/employees/skills` endpoint.
* Removed the `GET /reports/employees/position_alignment` endpoint.
* Removed the `POST /reports/replacement_risk` endpoint.
* Removed `count` response body field from the `POST /employees/search`
  endpoint.
* Removed `count` response body field from the `POST /vacancies/search`
  endpoint.
* Removed `count` response body field from the `POST /companies/search`
  endpoint.
* Removed `count` response body field from the
  `POST /employees/{external_id}/recommended_courses` endpoint.
* Removed `count` response body field from the
  `POST /employees/{employee_external_id}/vacancies/{vacancy_external_id}/recommended_courses`
  endpoint.
* Removed `count` response body field from the
  `POST /employees/{employee_external_id}/jobs/{job_external_id}/recommended_courses`
  endpoint.
* Removed `count` response body field from the
  `POST /employees/{external_id}/matching_vacancies` endpoint.
* Removed `count` response body field from the
  `POST /employees/{external_id}/matching_companies` endpoint.
* Removed `count` response body field from the
  `POST /employees/{external_id}/matching_jobs` endpoint.
* Removed `count` response body field from the
  `POST /employees/{external_id}/matching_job_families` endpoint.
* Removed `count` response body field from the
  `POST /vacancies/{external_id}/matching_employees` endpoint.
* Removed `count` response body field from the
  `POST /companies/{external_id}/matching_employees` endpoint.
* Removed `count` response body field from the
  `POST /job_architecture/jobs/{external_id}/matching_employees` endpoint.
* Removed `count` response body field from the
  `POST /job_architecture/job_families/{external_id}/matching_employees`
  endpoint.

### July 2024

* Removed the `GET /reports/employees/employability` endpoint.
* Removed the `GET /employees/{external_id}/metrics/employability` endpoint.
* Removed the `GET /vacancies/{external_id}/metrics/fillability` endpoint.

### June 2024

* Removed support for the `language` filter in the
  `POST /companies/{external_id}/matching_employees` endpoint.
* Removed `feedback_format=skill_clusters` support for the
  `PATCH /vacancies/{external_id}/skill_profile` endpoint.
* Removed `feedback_format=skill_clusters` support for the
  `PATCH /courses/{external_id}/skill_profile` endpoint.
* Removed `response_format=skill_clusters` support for the
  `GET /vacancies/{external_id}/skill_profile` endpoint.
* Removed `response_format=skill_clusters` support for the
  `GET /courses/{external_id}/skill_profile` endpoint.
* Removed the `POST /reports/clustered_trending_skills` endpoint.
* Removed the `POST /reports/emerging_skills` endpoint.
* Removed the `POST /employees/{external_id}/similar` endpoint.
* Removed the `POST /vacancies/{external_id}/similar` endpoint.
* Removed the `POST /courses/{external_id}/similar` endpoint.
* Removed Occupation entity and its functionalities, along with the Reskilling
  & Deployment report

### May 2024

* Removed the `include=skill_match_scores` query parameter of
  `POST /employees/{external_id}/matching_job_families`
* Replaced the `skill_type` field with `skill_types` for the `skills` response
  body field of the `GET /job_architecture/job/{job_id}/skill_profile` and
  `GET /job_architecture/job_families/{job_family_id}/skill_profile`
  endpoints.
* Replaced the `skill_type` field with `skill_types` for the `skills` field of
  the `records` response body field of the
  `POST /job_architecture/export/jobs/skill_profiles`, and
  `POST /job_architecture/export/job_families/skill_profiles` endpoints.
* Replaced the `skill_type` field with `skill_types` for the `skills` field of
  `skill_clusters` field of the `records` response body field of the
  `POST /job_architecture/export/jobs/skill_clusters`.

### February 2024

* Removed the `include=skill_clusters` query parameter of
  `POST /vacancies/{external_id}/matching_employees` and
  `GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/match`.
* Moved the `relevant_experience` response body field of the
  `response_format=explained` query parameter to the newly added
  `include=relevant_experience` query parameter of the
  `GET /employees/{employee_external_id}/vacancies/{vacancy_external_id}/match`
  endpoint.
* Renamed the `skill` response body field to `skill_name` of the
  `GET employees/{external_id}/vacancies/{external_id}/gap` endpoint.

### January 2024

* The `GET /job_architecture/job/{job_id}/skill_profile` endpoint has a new
  Skill type called `Family-Specific`.
* The `GET /job_architecture/job_families/{job_family_id}/skill_profile`
  endpoint has a new Skill type called `Family-Specific`.

### December 2023

* The `skills` request body field of the `SkillProfileUpdateMessage` of the
  endpoint `PATCH /employees/{external_id}/skill_profile` now requires either
  a `skill` or a `skill_id`, not both.
* The `skills` request body field of the `SkillProfileUpdateMessage` of the
  endpoint `PATCH /job_architecture/jobs/{job_external_id}/skill_profile` now
  requires either a `skill` or a `skill_id`, not both.
* The `skills` request body field of the `SkillProfileUpdateMessage` of the
  endpoint
  `PATCH /job_architecture/job_families/{job_family_external_id}/skill_profile`
  now requires either a `skill` or a `skill_id`, not both.
* The `skills` request body field of the `SkillProfileUpdateMessage` of the
  endpoint `PATCH /vacancies/{external_id}/skill_profile` now requires either
  a `skill` or a `skill_id`, not both.
* The `skills` request body field of the `SkillProfileUpdateMessage` of the
  endpoint `PATCH /courses/{external_id}/skill_profile` now requires either a
  `skill` or a `skill_id`, not both.
* The `skills` request body field of the `SkillProfileUpdateMessage` of the
  endpoint `PATCH /occupations/{external_id}/skill_profile` now requires
  either a `skill` or a `skill_id`, not both.
* The `skills` request body field of the `SkillProfileUpdateMessage` of the
  endpoint `PATCH /vacancies/{external_id}/skill_profile` now requires either
  a `skill` or a `skill_id`, not both.
* The `skills` request body field of the `SkillProfileUpdateMessage` of the
  endpoint `PATCH /courses/{external_id}/skill_profile` now requires either a
  `skill` or a `skill_id`, not both.
* The `skills` request body field of the `SkillProfileUpdateMessage` of the
  endpoint `PATCH /occupations/{external_id}/skill_profile` now requires
  either a `skill` or a `skill_id`, not both.

### November 2023

* Removed the deprecated `GET /employees/{external_id}/profile/related`
  endpoint.
* Removed the deprecated `POST /employees/{external_id}/profile/related`
  endpoint.
* Removed the deprecated `GET /vacancies/{external_id}/profile/related`
  endpoint.
* Removed the deprecated `POST /vacancies/{external_id}/profile/related`
  endpoint.
* Removed the deprecated `GET /courses/{external_id}/profile/related`
  endpoint.
* Removed the deprecated `POST /courses/{external_id}/profile/related`
  endpoint.
* Removed the deprecated `GET /occupations/{external_id}/profile/related`
  endpoint.
* Removed the deprecated `POST /occupations/{external_id}/profile/related`
  endpoint.
* Removed the deprecated `GET /skills/{skill_name}/related` endpoint.

### October 2023

* Remove `POST /skill_clusters` in favor of `POST /taxonomy/skill_clusters`.
* Remove `DELETE /skill_clusters/{skill_cluster_id}` in favor of
  `DELETE /taxonomy/skill_clusters/{skill_cluster_id}`.
* Remove `PATCH /skill_clusters/{skill_cluster_id}` in favor of
  `PATCH /taxonomy/skill_clusters/{skill_cluster_id}`.

### June 2023

* Removed the deprecated `PUT {entity}/{external_id}/skill_profile` endpoint.

### April 2023

* A `skill_event` with `project_content` now assumes a textual description of
  a ticket from a ticketing system (e.g. Jira, Asana, Github issues, etc.).
  The previous functionality of general project descriptions is removed.

### February 2023

* The `desired_functions` and `non_desired_functions` fields of the Employee
  have been changed from lists of titles to list of Function objects. A
  Function object consists of a Function title and a relative importance.

### January 2023

* All instances of `competency`, `competencies` or capitalized alternatives
  have been renamed to `skill_cluster` and `skill_clusters`, and their
  capitalized versions.
* All instances of `category`, `categories` or capitalized alternatives have
  been renamed to `domain` and `domains`, and their capitalized versions.

### October 2022

* The `competency` and `score` fields in
  `PUT, PATCH /{entity}/{external_id}/skill_profile` in `competencies` format
  are now renamed to `competency_name` and `proficiency_level` respectively.

* The `score` fields in `PUT, PATCH /{entity}/{external_id}/skill_profile` in
  `skills` format is replaced by `has_skill` which is a boolean instead of
  number.

* The `competency` and `score` fields in
  `GET /{entity}/{external_id}/skill_profile` in `competencies` format are now
  renamed to `competency_name` and `proficiency_level` respectively.

### July 2022

* The `score` field in `GET /{entity}/{external_id}/skill_profile` in `list`
  format is now optional.

### June 2022

* Deprecated `GET /employees/{external_id}/recommended_courses` and added POST
  instead.
* Removed `POST /competencies/{external_id}/similar` and
  `POST /competencies/{external_id}/profile/related` endpoints.

### May 2022

* Removed `PUT /competencies/{external_id}/skill_profile` feedback endpoint.

### November 2021

* Removed Document Entity and all its functionalities.

### July 2021

* Similar Entity endpoints are now `POST` instead of `GET`.
* The response format of Similar Entity endpoints has changed from a list to
  an object containing two fields: the list of results and the total number of
  results available.

### June 2021

* Search endpoints now require weights in the body, in the same manner as
  matching endpoints.
* Search endpoints now support a `score_min_threshold` query parameter, and
  defaults to 0.5 for this value instead of the previously internal 0.0.

### April 2021

* The language query parameter has become required for the creation and update
  of an entity.

### March 2021

* The response format of matching results
  (`GET/POST /employees/{external_id}/matching_vacancies` ,
  `GET/POST /vacancies/{external_id}/matching_employees` ,
  `GET /employees/{external_id}/matching_companies` and
  `GET /companies/{external_id}/matching_employees`) has changed from a list
  to an object containing two fields: the list of results and the total number
  of results available.
* The response format of search results (`POST /employees/search` ,
  `POST /vacancies/search` and `POST /companies/search`) has changed from a
  list to an object containing two fields: the list of search results and the
  total number of results available from the free text search.
* The response format of list results (`GET /employees/`, `GET /vacancies/` ,
  `GET /companies/`, `GET /courses/`, `GET /competencies/`, `GET /documents/`
  and `GET /occupations/`) has changed from a list to an object containing two
  fields: the list of results and the total number of results available.

### February 2021

* Employee creation (`POST /employees`) and updates
  (`PATCH /employees/{external_id}`) no longer support uploading individual
  resumes (as `employee_resume`) in favour of accepting a list of multiple
  resumes (as `employee_documents`) with the same format.
* The list entity endpoints (`GET /employees`, `GET /vacancies`,
  `GET /courses` , `GET /occupations`, `GET /competencies` and
  `GET /documents`) no longer support the `response_format` query parameter.
  The response now corresponds to the former `objects` response format for all
  endpoints.

### January 2021

* The version endpoint now returns a body with a single field `version`,
  indicating the current version of your tenant. The version is returned as a
  date (ISO-8601, ex. 2021-01-19) and no longer as a number.