Documentation

Workbench API Changelog

FossID Workbench 26.1

API extensions

API key expiration enforcement

A new fossid.conf parameter webapp_api_key_valability controls API key lifetime in days (default disabled). When enabled, expired API keys are rejected during authentication.

  • Impact: If an administrator sets webapp_api_key_valability (for example to 30), any API key older than that number of days is rejected on authenticated API calls. Previously, API keys did not expire.
  • New response field: api_key_expiry_date is returned only by users -> get_api_key and users -> renew_api_key. It is null when expiry is not configured in fossid.conf (see field description in the API reference).
  • Default behavior: The feature is disabled by default (webapp_api_key_valability unset or 0 means keys do not expire). There is no impact unless the setting is explicitly enabled.
; fossid.conf - disabled by default
; webapp_api_key_valability=30

Example response for users -> get_api_key when expiry is configured (api_key_expiry_date matches the API reference):

{
  "operation": "users_get_api_key",
  "status": "1",
  "data": {
    "api_key": "aaa",
    "api_key_expiry_date": "2025-12-31 23:59:59"
  }
}

Example response for users -> renew_api_key when expiry is configured:

{
  "operation": "users_renew_api_key",
  "status": "1",
  "data": {
    "api_key": "bbb",
    "api_key_expiry_date": "2025-12-31 23:59:59"
  }
}

When webapp_api_key_valability is not set in fossid.conf, api_key_expiry_date is null.

Optional field identification_on on scans -> remove_license_identifications

The request data object may include identification_on (optional):

  • Type: string
  • Values: FILE or SNIPPET
  • Behavior: If omitted, matching license identifications of both types are removed. If set, only identifications for that type are removed.

Example request:

{
  "group": "scans",
  "action": "remove_license_identifications",
  "data": {
    "username": "FOSSID_USERNAME",
    "key": "FOSSID_API_KEY",
    "scan_code": "scan_code",
    "path": "YWxnb3JpdGhtL2FsZ29yaXRobS5ocHA=",
    "license_identifier": "MIT",
    "identification_on": "FILE"
  }
}

Dependency analysis: is_direct_dependency and is_transitive_dependency in scans -> get_dependency_analysis_results

The data field in the response may be null or an array of dependency rows. Each object in the array may include two new integer flags:

  • Affected API action: scans -> get_dependency_analysis_results — use group scans and action get_dependency_analysis_results (same as path POST /scans/get_dependency_analysis_results in the API reference).
  • New response fields: is_direct_dependency (0 or 1), is_transitive_dependency (0 or 1)
  • A component can be both direct and transitive within the same analyzed project.

Example request:

{
  "group": "scans",
  "action": "get_dependency_analysis_results",
  "data": {
    "username": "FOSSID_USERNAME",
    "key": "FOSSID_API_KEY",
    "scan_code": "scan_code"
  }
}

Example response (excerpt):

{
  "operation": "scans_get_dependency_analysis_results",
  "status": "1",
  "data": [
    {
      "scan_id": 200,
      "component_id": 219,
      "package_id": "NPM::coffee-script:1.12.7",
      "projects_and_scopes": "{\"f49ac1310990fbeeb9def36950932940\":{\"project_id\":\"Yarn:json-diff:1.0.6:\",\"scope\":\"devDependencies\"}}",
      "detailed_dependency_info": "{\"f49ac1310990fbeeb9def36950932940\":{\"scope\":\"devDependencies\",\"project_id\":\"Yarn:json-diff:1.0.6:\",\"0\":\"NPM::jscoverage:0.6.0\",\"1\":\"NPM::coffee-script:1.12.7\"}}",
      "updated": "2023-11-13 15:26:10",
      "include_in_report": 1,
      "is_direct_dependency": 0,
      "is_transitive_dependency": 1,
      "name": "coffee-script",
      "version": "1.12.7",
      "license_identifier": "MIT",
      "license_category": "PERMISSIVE",
      "url": "http://coffeescript.org",
      "cpe": null,
      "license_id": 290,
      "concluded_license_name": null,
      "concluded_license_identifier": null,
      "concluded_license_category": null
    }
  ]
}

Optional type parameter on get_policy_warnings_info (scans and projects)

scans -> get_policy_warnings_info and projects -> get_policy_warnings_info accept an optional type parameter to limit policy warnings by source.

  • New optional request field: type — enum identifications, dependencies, or all; default identifications.
Value Description
identifications (default) Policy warnings from identifications
dependencies Policy warnings from dependency analysis
all Both identifications and dependencies

If type is omitted, it defaults to identifications (same behavior as before these values existed). The response shape is unchanged.

Example request (scan):

{
  "group": "scans",
  "action": "get_policy_warnings_info",
  "data": {
    "username": "FOSSID_USERNAME",
    "key": "FOSSID_API_KEY",
    "scan_code": "scan_code",
    "type": "all"
  }
}

Example request (project):

{
  "group": "projects",
  "action": "get_policy_warnings_info",
  "data": {
    "username": "FOSSID_USERNAME",
    "key": "FOSSID_API_KEY",
    "project_code": "project_code",
    "type": "identifications"
  }
}

New API actions

New API action users -> revoke_api_key

Administrators can revoke another user’s API key. You cannot revoke your own key.

  • API action: group: users, action: revoke_api_key

Example request:

{
  "group": "users",
  "action": "revoke_api_key",
  "data": {
    "username": "FOSSID_USERNAME",
    "key": "FOSSID_API_KEY",
    "searched_username": "example_username"
  }
}

Example response (success):

{
  "operation": "users_revoke_api_key",
  "status": "1",
  "data": {
    "success": true,
    "user_id": 2
  }
}

Example response (cannot revoke own key):

{
  "operation": "users_revoke_api_key",
  "status": "0",
  "data": null,
  "error": "Handler.Users.RevokeApiToken.cannot_revoke_own_api_key",
  "message": "You cannot revoke your own API key.",
  "message_parameters": []
}

Example response (user not found):

{
  "operation": "users_revoke_api_key",
  "status": "0",
  "data": null,
  "error": "User does not exist",
  "message": "User does not exist",
  "message_parameters": []
}

New API action components -> list_by_usage

Retrieves components with optional filtering and pagination. API action: group: components, action: list_by_usage

  • usage_equal_or_above (optional, integer): minimum usage count to include; for example 1 means components with at least one associated scan usage. See the Workbench API reference for full request fields and default behavior.
  • Other optional data fields include page, records_per_page, search_value, order_by, direction, and count_results (set to 1 to return only the total count).

Example request (components with at least one usage):

{
  "group": "components",
  "action": "list_by_usage",
  "data": {
    "username": "FOSSID_USERNAME",
    "key": "FOSSID_API_KEY",
    "page": 1,
    "records_per_page": 5,
    "search_value": "test_comp",
    "usage_equal_or_above": 1,
    "order_by": "name",
    "direction": "DESC",
    "count_results": 0
  }
}

Example response:

{
  "operation": "components_list_by_usage",
  "status": "1",
  "data": {
    "total_count": 1,
    "page": 1,
    "next_page": false,
    "previous_page": false,
    "list": [
      {
        "id": 14,
        "version": "1.0",
        "name": "test-comp",
        "cpe": null,
        "license_name": "BSD Zero Clause License",
        "license_identifier": "0BSD",
        "license_category": "PERMISSIVE",
        "intake_status": null,
        "created": "2026-03-03 10:38:21",
        "updated": "2026-03-03 10:38:21",
        "created_by": 1,
        "supplier_name": "",
        "critical_vulnerability_count": 0,
        "high_vulnerability_count": 0,
        "medium_vulnerability_count": 0,
        "low_vulnerability_count": 0,
        "concluded_license_identifier": "0BSD",
        "concluded_license_category": "PERMISSIVE",
        "component_origin": "identification_component"
      }
    ]
  }
}

Supports count_results: 1 to return only the total count.

FossID Workbench 25.2

Behaviour after unique key for components changed from ‘name+version’ to ‘name+version+supplier’

For API calls that try to get/search ONE component by name + version, the field ‘supplier_name’ will not be mandatory in order to avoid backward compatibility issues. If ‘supplier_name’ isn’t specified the behaviour will be this one:

  • If the app finds the list of components - use the first one as the correct one.
  • If the app finds only one component, just use it.

Description how ‘Automatically resolve pending identifications’ or SBOM import will work from perspective of reusing existing component or creating a new one:

  • search in components table by ‘name+version+supplier_name’, if a local component with all 3 fields is found use it
  • If no components is found search in components table only by ‘name+version’
    • If there is just one component use it, and if the component found in local Database has empty supplier it will be updated with the one from match.
    • If there is more than one component in local Database with same name+version, do not use any of them, instead create a new component.

Additional field “cpe” in API response for action “scans->get_scan_file_info”.

FossID Workbench 25.1.1

New APIs for manipulating file comments: “files_and_folders->get_file_comments”, “files_and_folders->edit_file_comment”, “files_and_folders->delete_file_comment”

Removed fields from API users->get_information which were always returned as empty: password_history, password_updated, invalid_logins together with fields created, updated.

Also, only requests from users with permission “USERS_EDIT_ANY” will include fields: email, language, phone, mobile, is_deleted.

Changed values from null to “0” for fields “warnings” and “policy_rules” in response for API projects->list_projects

FossID Workbench 25.1

New API “components->get_usage”

Added new API “components->get_usage” which returns a list of scans where a component is used as identification or dependency.

Get the list of users assigned a specific role or permission

Added the possibility to get the list of users assigned a specific role or permission by using existing API action “users->get_all_users” with new optional parameters “role_id” or “permission_code”. Please note that permission USERS_ASSIGN_PERMISSIONS is required.

List permissions and roles for each user

Added the possibility to list permissions and roles for each user by sending “searched_username” optional parameter to APIs: “users->get_user_roles_list” and “users->get_user_permissions_list”.

Vulnerabilities count in API response “components->list_components”

Include information about component vulnerabilities count in API response “components->list_components” by adding 4 new fields: critical_vulnerability_count, high_vulnerability_count, medium_vulnerability_count, low_vulnerability_count.

Added new “type” value in API “users->check_status”: “EXTRACT_ARCHIVES”.

Added new API actions: “logs->get_list”, “logs->get_actions_list”.

Changed error response in order to support multiple fields errors in API “licenses->create” and “licenses->update”. Example of the new response:

{
  "operation": "licenses_create",
  "status": "0",
  "data": [
    {
      "code": "Legacy.controller.licenses.name_already_exists",
      "message": "License already exists with that name.",
      "message_parameters": {
        "fieldname": "license_name",
        "value": "MIT License"
      }
    },
    {
      "code": "Legacy.controller.licenses.identifier_already_exists",
      "message": "License already exists with that identifier.",
      "message_parameters": {
        "fieldname": "license_identifier",
        "value": "MIT"
      }
    }
  ],
  "error": "Legacy.controller.licenses.identifier_already_exists",
  "message": "License already exists with that identifier.",
  "message_parameters": []
}

Fixed bug: API “scans → get_identified_files” does not include license text when “exclude_file_license_text=0” and “new_output_format=1”

Fixed bug: API “files_and_folders->get_fossid_results” returns scan_id value “0” always.

Fixed bug: API “scans->get_scan_comments” returns only records marked “only_include_in_report”

Added new option “include_dep_det_info” only for Excel reports, to the scans/projects -> generate_report action

"include_dep_det_info: "Optional, only for Excel reports, default false if not set.
        Specify if dependency tab has to contain detailed information string, 
        example: Scope: devDependencies  Project: NPM:json-diff:0.5.5 => NPM::mocha:1.7.4 =>"
        
#### New notice file: aggregate level.
There is a new "type" optional parameter in actions "scans->notice_extract_run", "scans->notice_extract_view_status" and "scans->notice_extract_download"
Default value is **NOTICE_EXTRACT_FILE** in order to maintain backward compatibility.
```plaintext
{
  "group": "scans",
  "action": "notice_extract_run",
  "data": {
    "username": "username",
    "key": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "scan_code": "scan_code",
    "type": "NOTICE_EXTRACT_COMPONENT or NOTICE_EXTRACT_FILE or NOTICE_EXTRACT_AGGREGATE"
  }
}

Improved error message clarity for API action “scans->get_scan_comments” when handling absence of scan_code values.

Old response example

{
  "operation": "scans_get_scan_comments",
  "status": "0",
  "data": null,
  "error": "Scan code is required.",
  "message": "Scan code is required.",
  "message_parameters": []
}

New response example

{
  "operation": "scans_get_scan_comments",
  "status": "0",
  "data": [
    {
      "code": "RequestData.Base.mandatory_field_missing",
      "message": "The mandatory field scan_code is missing; string is required",
      "message_parameters": {
        "fieldname": "scan_code"
      }
    }
  ],
  "error": "RequestData.Base.issues_while_parsing_request",
  "message": "These issues were found while parsing the request:",
  "message_parameters": []

New option were added to the request in API action “scans->get_scan_comments”

Old request example

{
  "group": "scans",
  "action": "get_scan_comments",
  "data": {
    "username": "username",
    "key": "user key",
    "scan_code": "scan_code",
    "only_include_in_report": "Optional, Default: true",
    "only_important": "Optional, Default: false"
  }
}

New request example

{
  "group": "scans",
  "action": "get_scan_comments",
  "data": {
    "username": "username",
    "key": "user key",
    "scan_code": "scan_code",
    "only_include_in_report": "Optional, Default: true",
    "only_important": "Optional, Default: false",
    "include_scan_component_comment": "Optional, Default: true"     
  }
}

New fields were added to response in API action “components->list_components”

Old response example

{
  "operation": "components_list_components",
  "status": "1",
  "data": [
     {
        "id": 3,
        "version": "1.1",
        "name": "ofp",
        "cpe": "cpe:2.3:a:ansi-regex_project:ansi-regex:1.1.1:*:*:*:*:node.js:*:*",
      }
    ]
  }
}

New response example

{
  "operation": "components_list_components",
  "status": "1",
  "data": [
     {
        "id": 3,
        "version": "1.1",
        "name": "ofp",
        "cpe": "cpe:2.3:a:ansi-regex_project:ansi-regex:1.1.1:*:*:*:*:node.js:*:*",
        "license_name": "BSD 3-Clause \"New\" or \"Revised\" License",
        "license_identifier": "BSD-3-Clause",
        "license_category": "UNCATEGORIZED",
        "intake_status": "pending",
        "critical_vulnerability_count": 0,
        "high_vulnerability_count": 3,
        "medium_vulnerability_count": 0,
        "low_vulnerability_count": 0,
        "created": "2024-11-21 00:39:46",
        "updated": "2024-11-21 00:39:46"
      }
    ]
  }
}

FossID Workbench 24.3

License category identifier “NON_COMMERCIAL” was replaced with “SOURCE_AVAILABLE_NC” in order to align with the label used in UI.

Improved error message clarity for API action “scans->run” when handling invalid specific_code values.

Old response example

{
  "operation": "scans_run",
  "status": "0",
  "data": [
    {
      "code": "RequestData.RunRequest.specific_code_is_not_a_valid_scan_code",
      "message": "null is not a valid scan code",
      "message_parameters": {
        "specific_code": "null"
      }
    }
  ],
  "error": "RequestData.Base.issues_while_parsing_request",
  "message": "These issues were found while parsing the request:",
  "message_parameters": []
}

New response example

{
  "operation": "scans_run",
  "status": "0",
  "data": [
    {
      "code": "RequestData.RunRequest.specific_code_is_not_a_valid_scan_code",
      "message": "not_existing is not a valid scan code",
      "message_parameters": {
        "specific_code": "not_existing"
      }
    }
  ],
  "error": "RequestData.Base.issues_while_parsing_request",
  "message": "These issues were found while parsing the request:",
  "message_parameters": []
}

Changed response: removed values with numeric keys for API action “component_approval->list_scans_with_component”

Old response example

{
  "operation": "component_approval_list_scans_with_component",
  "status": "1",
  "data": [
    {
      "0": "11",
      "1": "Scan Name",
      "2": "api_test_component_approval_2",
      "3": "2024-10-10",
      "4": "test_project_component_approval_2",
      "5": "test_project_component_approval_2",
      "scan_id": "11",
      "name": "Scan Name",
      "code": "api_test_component_approval_2",
      "scan_created": "2024-10-10",
      "project_name": "test_project_component_approval_2",
      "project_code": "test_project_component_approval_2"
    }
  ]
}

New response example

{
  "operation": "component_approval_list_scans_with_component",
  "status": "1",
  "data": [
    {
      "scan_id": "11",
      "name": "Scan Name",
      "code": "api_test_component_approval_2",
      "scan_created": "2024-10-10",
      "project_name": "test_project_component_approval_2",
      "project_code": "test_project_component_approval_2"
    }
  ]
}

Improvements in error messages

For example now when status is 0 the data field may contain an array of errors. Before:

{
  "operation": "policy_management_create_policy_rule",
  "status": "0",
  "data": {
    "type": "license_category",
    "condition": "UNCATEGORIZED"
  },
  "error": "Handler.project.policy_management.rule_already_exist",
  "message": "This policy rule already exists in this project\nlicense_category\nUNCATEGORIZED",
  "message_parameters": []
}

Now:

{
  "operation": "policy_management_create_policy_rule",
  "status": "0",
  "data": [
    {
      "code": "Handler.project.policy_management.rule_already_exist",
      "message": "This policy rule already exists in this project",
      "message_parameters": {
        "fieldname": "license_category",
        "value": "UNCATEGORIZED"
      }
    }
  ],
  "error": "Handler.project.policy_management.rule_already_exist",
  "message": "This policy rule already exists in this project",
  "message_parameters": []
}

New notice file: component level.

There is a new “type” optional parameter in actions “scans->notice_extract_run”, “scans->notice_extract_view_status” and “scans->notice_extract_download” Default value is NOTICE_EXTRACT_FILE in order to maintain backward compatibility.

{
  "group": "scans",
  "action": "notice_extract_run",
  "data": {
    "username": "username",
    "key": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "scan_code": "scan_code",
    "type": "NOTICE_EXTRACT_COMPONENT or NOTICE_EXTRACT_FILE"
  }
}

Pagination added to action scans->get_marked_as_identified_files

Optional parameters were added to help with pagination:

count_results:    Return number of components. Boolean (0 default, 1)
records_per_page: Number of records per page. If empty components will not be paginated
page:             Current page, if empty assume the first page

Pagination added to action scans->get_identified_files

Optional parameters were added to help with pagination:

count_results:    Return number of components. Boolean (0 default, 1)
records_per_page: Number of records per page. If empty components will not be paginated
page:             Current page, if empty assume the first page

Added new API to download local / matched remote scan files

Request for local scan file

{
    "group": "download",
    "action": "download_scan_local_file",
    "data": {
        "username": "fossid",
        "key": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "file_path": "Rm9zc0lELnBocA==",
        "scan_id": "19"
    }
}

Request for matched remote file

{
    "group": "download",
    "action": "download_scan_remote_file",
    "data": {
        "username": "fossid",
        "key": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "match_file_id": "ZWU2MGI0YTVkNGNmMGRmYzI1MjVkMzA0MDAwMDAwMDA=",
        "scan_id": "19"
    }
}

Vulnerabilities

New UI page for Vulnerabilities was added together with equivalent API actions. Please check API docs for detailed information.

Vulnerabilities API Docs

New API action to retrieve project component comments: projects->get_project_component_comment

Request

{
  "group": "projects",
  "action": "get_project_component_comment",
  "data": {
    "username": "username",
    "key": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "project_id": "project id ",
    "component_id": "component id"
  }
}

Experimental upper case “Components” API group which was visible only in API test but not in documentation was removed as announced in “Future Release Advisory” section of the release 24.1 and calling now API with group “Components” or “components” is the same.

FossID Workbench 24.2

Added new optional fields ‘match_filtering_threshold’ and ‘advanced_match_scoring‘ to API group ‘scans’, action ‘run’.

Both fields are enabled by default.

New request
{
    "group": "scans"
    "action": "run"
    "data": {
        "username": "username"
        "key": "user key"
        "scan_code": "Code of the scan"
        "limit": "Limit on number of FossID results. Default/Recommended: 10"
        "sensitivity": "Sensitivity of the scan. Default/Recommended: 10. A value lower than 6 (0-5) will result in only full file matches being returned"
        "replace_existing_identifications": "Replace existing identifications. Boolean (0 default,1)"
        "reuse_identification": "If exists, try to use an existing identification depending on parameter ‘identification_reuse_type’. Boolean (0 default,1)"
        "identification_reuse_type": "Last identification found will be used for files with the same hash. Values: any, only_me, specific_project, specific_scan"
        "specific_code": "Optional, only when ‘identification_reuse_type’ is ‘specific_project’ or ‘specific_scan’"
        "auto_identification_detect_declaration": "Automatically detect license declaration inside files. Boolean (0 default,1)"
        "auto_identification_detect_copyright": "Automatically detect copyright statements inside files. Boolean (0 default,1)"
        "auto_identification_resolve_pending_ids": "Automatically resolve pending identifications. Boolean (0 default,1)"
        "scan_failed_only": "If true, this will only scan files that have failed in the previous scan. Boolean (0 default,1)"
        "delta_only": "Only newly added files or modified files will be scanned. Boolean (0,1 default)"
        "full_file_only": "Will result in only full file matches being returned regardless of sensitivity setting. Boolean (0 default,1)"
        "match_filtering_threshold": "Minimum length (in characters) of snippet to be considered valid after applying intelligent match filtering. Set to 0 to disable intelligent match filtering for current scan. If parameter is not sent it defaults to value of ‘webapp_match_filtering_threshold‘ from fossid.conf. If there is no value in fossid.conf the default is 300 characters."
        "advanced_match_scoring": "If true, scan will run with advanced match scoring. When no value is provided, the default behaviour is enabled. Boolean (0,1 default)"
    }
}

Changed response for API call group: quick_scan, action: scan_one_file (renamed classification field into noise)

Old response example

{
    "operation": "quick_scan_scan_one_file",
    "status": "1",
    "data": [{
        "component": {},
        "classification": [], ...
    }]
}

New response example

{
    "operation": "quick_scan_scan_one_file",
    "status": "1",
    "data": [{
        "component": {},
        "noise": {}, ...
    }]
}

Changed response for API endpoints:

group: files_and_folders, action: get_fossid_results

group: scans, action: get_scan_file_info

Old response example

{
    "operation": "files_and_folders_get_fossid_results",
    "status": "1",
    "data": {
        "99": {
            "id": 99,
            "classification": "[]" ...
        }
    }
}

New response example

{
    "operation": "files_and_folders_get_fossid_results",
    "status": "1",
    "data": {
         "99": {
            "id": 99,
            "classification": "{}", ...
         }
    }
}

Old response example

{
    "operation": "scans_get_scan_file_info",
    "status": "1",
    "data": {
        "fossid_results": {
            "99": {
                "id": 99,
                "classification": "[]" ...
            }
        }
    }
}

New response example

{
    "operation": "scans_get_scan_file_info",
    "status": "1",
    "data": {
        "fossid_results": {
            "99": {
                "id": 99,
                "classification": "{}" ...
            }
        }
    }
}

Changed API call group: components, action: search_cpe

old request:
{
    "group": "components",
    "action": "search_cpe",
    "data": {
        "username": "username",
        "key": "user key",
        "product": "%android"
    }
}
new request:
{
    "group": "components",
    "action": "search_cpe",
    "data": {
        "username": "username",
        "key": "user key",
        "product": "Required, example: 'node' ",
        "version": "Optional, component version, example: '4.5.0' ",
        "limit": "Optional, limit of the search results, Default 30"
    }
}

Changed response, removed values with numeric keys, for API endpoints:

group: files_and_folders, action: get_identification
group: files_and_folders, action: get_folder_content_metrics
group: licenses, action: get_information
group: projects, action: get_all_scans
group: scans, action: get_folder_metrics
group: scans, action: get_scan_identified_components

Old response example

{
  "operation": "files_and_folders_get_folder_content_metrics",
  "status": "1",
  "data": {
    "0": "0",
    "1": "0",
    "2": "0",
    "3": "0",
    "total": "0",
    "pending_identification": "0",
    "identified_files": "0",
    "without_matches": "0"
  },
  "message": "Success"
}

New response example

{
  "operation": "files_and_folders_get_folder_content_metrics",
  "status": "1",
  "data": {
    "total": "0",
    "pending_identification": "0",
    "identified_files": "0",
    "without_matches": "0"
  },
  "message": "Success"
}

Changes in API call group ‘scans’ action ‘download_content_from_git’

In 24.1 API docs 2 fields were added by mistake to download_content_from_git. This is fixed in 24.2, the information regarding git branch and repo is saved during scans->create action

FossID Workbench 24.1

Added new option field ‘remove_dependency_request’ to API group ‘component_approval’ action ‘delete_requests_for_unidentified’

Old request

{
  "group": "component_approval",
  "action": "delete_requests_for_unidentified",
  "data": {
    "username": "username",
    "key": "user key",
    "project_code": "My project code"
  }
}

New request

{
  "group": "component_approval",
  "action": "delete_requests_for_unidentified",
  "data": {
    "username": "username",
    "key": "user key",
    "project_code": "My project code",
    "remove_dependency_request": "Optional. Deletes dependency components approval requests. Boolean (0 default, 1)"
  }
}

Added new options to API group ‘projects’ action ‘get_project_components’

Old request

{
    "group": "projects",
    "action": "get_project_components",
    "data": {
        "username": "username",
        "key": "user key",
        "project_code": "My project code"
    }
}

New request

{
    "group": "projects",
    "action": "get_project_components",
    "data": {
        "username": "username",
        "key": "user key",
        "project_code": "My project code",
        "count_results":"Return number of components. Boolean (0 default, 1)"
        "records_per_page":"Number of records per page. If empty components will not be paginated"
        "page":"Current page, if empty assume the first page"
    }
}
If option “count_results” is “1”
{
  "operation": "projects_get_project_components",
  "status": "1",
  "data": {
    "count_results": 18
  }
}

Changed response for API endpoint to get list of project components.

Old response: list of components contains only components that were use as identifications in the project scans.
New response: list of components includes components from identification plus components from dependencies.
New field ‘Origin’ was added to the response to differentiate components. The value could be: dependency or identified
{
  "operation": "projects_get_project_components",
  "status": "1",
  "data": {
    "2": {
      "id": 2,
      "created_by": 1,
      "cpe": null,
      "name": "coffee-script",
      "version": "1.12.7",
      "purl": "pkg:npm/coffee-script@1.12.7",
      "purl_type": "npm",
      "purl_namespace": null,
      "purl_name": "coffee-script",
      "purl_version": "1.12.7",
      "url": "http://coffeescript.org",
      "release_date": null,
      "built_date": null,
      "supplier_name": null,
      "supplier_url": "",
      "community_url": "",
      "download_url": "https://registry.npmjs.org/coffee-script/-/coffee-script-1.12.7.tgz",
      "download_url_binary": null,
      "md5": null,
      "sha1": "c05dae0cb79591d05b3070a8433a98c9a89ccc53",
      "sha256": null,
      "binary_md5": null,
      "binary_sha1": null,
      "binary_sha256": null,
      "license_id": 583,
      "comment": "Component created by WebApp from dependency analysis results.",
      "description": "Unfancy JavaScript",
      "package_size": null,
      "package_size_binary": null,
      "platform": null,
      "image_id": null,
      "repository_download_path_binary": null,
      "programming_language": null,
      "commits_nro": null,
      "contributors_nro": null,
      "releases_nro": null,
      "bugs_nro": null,
      "fixed_bugs_nro": null,
      "community_status": null,
      "community_size": null,
      "copyright": null,
      "attribution_acknowledgement": null,
      "warranty_liability_exclusions": null,
      "known_bugs": null,
      "known_vulnerabilities": null,
      "change_log": null,
      "kb_origin": 0,
      "created": "2024-01-09 13:42:03",
      "updated": "2024-01-09 13:42:03",
      "license_identifier": "MIT",
      "license_name": "MIT License",
      "origin": "dependency",
      "project_comment": "some comment about project"
    }
  }
}

Added new actions to components group of API endpoints

action: update_cpe_list:
{
    "group": "components",
    "action": "update_cpe_list",
    "data": {
        "username": "username",
        "key": "user key",
        "url": "Optional (one of url or base64file must be included): Url from where to download the CPE dictionary, eg https:\/\/nvd.nist.gov\/feeds\/xml\/cpe\/dictionary\/official-cpe-dictionary_v2.3.xml.gz",
        "base64file": "Optional (one of url or base64file must be included): base64 encoded gzipped CPE dictionary in xml format (cat official-cpe-dictionary_v2.3.xml | gzip | base64 w0). This may be useful for offline installations"
    }
}
action: search_cpe:
{
    "group": "components",
    "action": "search_cpe",
    "data": {
        "username": "username",
        "key": "user key",
        "product": "Required: Mysql pattern. See https:\/\/dev.mysql.com\/doc\/refman\/8.0\/en\/pattern-matching.html",
        "version": "Optional: Mysql pattern. See https:\/\/dev.mysql.com\/doc\/refman\/8.0\/en\/pattern-matching.html"
    }
}

Changed API endpoint to create a component: added possibility to insert all existing fields

Old request:
{
    "group": "components",
    "action": "create",
    "data": {
        "username": "username",
        "key": "user key",
        "name": "Component Name",
        "version": "Component Version",
        "purl": "Package URL",
        "url": "Component URL",
        "license_identifier": "Component license Identifier",
        "sup_com_name": "Name for the supplier or community of the component.",
        "supplier_url": "URL for the supplier of the component.",
        "community_url": "URL for the community of the component.",
        "download_url": "Download URL of the component.",
        "package_md5": "MD5 for the component package.",
        "package_sha1": "SHA1 for the component package.",
        "comment": "Desired comment for the component."
    }
}
New request with all fields:
{
    "group": "components",
    "action": "create",
    "data": {
        "username": "username",
        "key": "user key",
        "name": "Required: Exact name of the component.",
        "version": "Required: Exact version of the component.",
        "license_identifier": "Required: Valid SPDX identifier, see license group",
        "purl": "Optional. Package URL",
        "url": "Optional. Component URL",
        "cpe": "Optional. CPE 2.3 identifier",
        "package_size": "Optional",
        "package_size_binary": "Optional",
        "commits_nro": "Optional",
        "contributors_nro": "Optional",
        "releases_nro": "Optional",
        "bugs_nro": "Optional",
        "fixed_bugs_nro": "Optional",
        "community_size": "Optional",
        "sup_com_name": "Optional. Name for the supplier or community of the component.",
        "supplier_url": "Optional. URL for the supplier of the component.",
        "community_url": "Optional. URL for the community of the component.",
        "download_url": "Optional. Download URL of the component.",
        "download_url_binary": "Optional",
        "comment": "Optional. Desired comment for the component.",
        "description": "Optional",
        "repository_download_path_binary": "Optional",
        "copyright": "Optional",
        "attribution_acknowledgement": "Optional",
        "warranty_liability_exclusions": "Optional",
        "known_bugs": "Optional",
        "known_vulnerabilities": "Optional",
        "change_log": "Optional",
        "platform": "Optional",
        "programming_language": "Optional",
        "package_md5": "Optional. MD5 for the component package.",
        "binary_md5": "Optional",
        "package_sha1": "Optional. SHA1 for the component package.",
        "binary_sha1": "Optional",
        "sha256": "Optional",
        "binary_sha256": "Optional",
        "release_date": "Optional",
        "community_status": "Optional"
    }
}

Changed API endpoint to update a component: added possibility to edit all existing fields

Old request:
{
    "group": "components",
    "action": "update",
    "data": {
        "username": "username",
        "key": "user key",
        "name": "Component Name",
        "version": "Component Version",
        "purl": "Package URL",
        "url": "Component URL",
        "license_identifier": "Component license Identifier",
        "sup_com_name": "Name for the supplier or community of the component.",
        "supplier_url": "URL for the supplier of the component.",
        "community_url": "URL for the community of the component.",
        "download_url": "Download URL of the component.",
        "package_md5": "MD5 for the component package.",
        "package_sha1": "SHA1 for the component package.",
        "comment": "Desired comment for the component."
    }
}
New request with all fields:
{
    "group": "components",
    "action": "update",
    "data": {
        "username": "username",
        "key": "user key",
        "name": "Required: Exact name of the component.",
        "version": "Required: Exact version of the component.",
        "new_name": "Optional",
        "new_version": "Optional",
        "license_identifier": "Required: Valid SPDX identifier, see license group",
        "purl": "Optional. Package URL",
        "url": "Optional. Component URL",
        "cpe": "Optional. CPE 2.3 identifier",
        "package_size": "Optional",
        "package_size_binary": "Optional",
        "commits_nro": "Optional",
        "contributors_nro": "Optional",
        "releases_nro": "Optional",
        "bugs_nro": "Optional",
        "fixed_bugs_nro": "Optional",
        "community_size": "Optional",
        "sup_com_name": "Optional. Name for the supplier or community of the component.",
        "supplier_url": "Optional. URL for the supplier of the component.",
        "community_url": "Optional. URL for the community of the component.",
        "download_url": "Optional. Download URL of the component.",
        "download_url_binary": "Optional",
        "comment": "Optional. Desired comment for the component.",
        "description": "Optional",
        "repository_download_path_binary": "Optional",
        "copyright": "Optional",
        "attribution_acknowledgement": "Optional",
        "warranty_liability_exclusions": "Optional",
        "known_bugs": "Optional",
        "known_vulnerabilities": "Optional",
        "change_log": "Optional",
        "platform": "Optional",
        "programming_language": "Optional",
        "package_md5": "Optional. MD5 for the component package.",
        "binary_md5": "Optional",
        "package_sha1": "Optional. SHA1 for the component package.",
        "binary_sha1": "Optional",
        "sha256": "Optional",
        "binary_sha256": "Optional",
        "release_date": "Optional",
        "community_status": "Optional"
    }
}

Changed response for API endpoint to get list of components

Old response:
{
  "operation": "components_list_components",
  "status": "1",
  "data": {
    "1": {
      "id": "1",
      "name": "antlr/antlr",
      "version": "2.7.7"
    },
    "2": {
      "id": "2",
      "name": "com.github.ben-manes.caffeine/caffeine",
      "version": "2.8.8"
    },
    ...
}
New response:
{
  "operation": "components_list_components",
  "status": "1",
  "data": [
    {
      "id": 1316,
      "name": "@types/babel-types",
      "version": "7.0.15",
      "cpe": null
    },
    {
      "id": 1317,
      "name": "@types/babylon",
      "version": "6.16.9",
      "cpe": null
    },
    ...
}

Changed response for API endpoint to get component information, removed values with numeric keys

Old response example:
{
  "operation": "components_get_information",
  "status": "1",
  "data": {
    "0": "451",
    "1": "2022-09-12 20:11:17",
    "2": "2022-09-12 20:11:17",
    "3": "1",
    "4": null,
    "5": "abbrev",
    "6": "1.1.1",
    "7": null,
    "8": null,
    "9": null,
    "10": null,
    "11": null,
    "12": "https://github.com/isaacs/abbrev-js#readme",
    "13": null,
    "14": "",
    "15": "",
    "16": "",
    "17": "https://registry.npmjs.org/abbrev/-/abbrev-1.1.1.tgz",
    "18": null,
    "19": null,
    "20": "f8f2c887ad10bf67f634f005b6987fed3179aac8",
    "21": null,
    "22": null,
    "23": null,
    "24": null,
    "25": "483",
    "26": "Component created by WebApp from dependency analysis results.",
    "27": "Like ruby's abbrev module, but in js",
    "28": null,
    "29": null,
    "30": null,
    "31": null,
    "32": null,
    "33": null,
    "34": null,
    "35": null,
    "36": null,
    "37": null,
    "38": null,
    "39": null,
    "40": null,
    "41": null,
    "42": null,
    "43": null,
    "44": null,
    "45": null,
    "46": null,
    "47": "0",
    "48": "2022-09-12",
    "49": null,
    "50": "483",
    "51": "ISC License",
    "52": "ISC",
    "53": "fossid",
    "id": "451",
    "created": "2022-09-12 20:11:17",
    "updated": "2022-09-12 20:11:17",
    "created_by": "1",
    "cpe": null,
    "name": "abbrev",
    "version": "1.1.1",
    "purl": null,
    "purl_type": null,
    "purl_namespace": null,
    "purl_name": null,
    "purl_version": null,
    "url": "https://github.com/isaacs/abbrev-js#readme",
    "release_date": null,
    "supplier_name": "",
    "supplier_url": "",
    "community_url": "",
    "download_url": "https://registry.npmjs.org/abbrev/-/abbrev-1.1.1.tgz",
    "download_url_binary": null,
    "md5": null,
    "sha1": "f8f2c887ad10bf67f634f005b6987fed3179aac8",
    "sha256": null,
    "binary_md5": null,
    "binary_sha1": null,
    "binary_sha256": null,
    "license_id": "483",
    "comment": "Component created by WebApp from dependency analysis results.",
    "description": "Like ruby's abbrev module, but in js",
    "package_size": null,
    "package_size_binary": null,
    "platform": null,
    "image_id": null,
    "repository_download_path_binary": null,
    "programming_language": null,
    "commits_nro": null,
    "contributors_nro": null,
    "releases_nro": null,
    "bugs_nro": null,
    "fixed_bugs_nro": null,
    "community_status": null,
    "community_size": null,
    "copyright": null,
    "attribution_acknowledgement": null,
    "warranty_liability_exclusions": null,
    "known_bugs": null,
    "known_vulnerabilities": null,
    "change_log": null,
    "kb_origin": "0",
    "created_date": "2022-09-12",
    "component_release_date": null,
    "license_name": "ISC License",
    "license_identifier": "ISC",
    "user_username": "fossid"
  }
}
New response example:
{
  "operation": "components_get_information",
  "status": "1",
  "data": {
    "id": 394,
    "created_by": 1,
    "cpe": null,
    "name": "abbrev",
    "version": "1.1.1",
    "purl": "pkg:npm/abbrev@1.1.1",
    "purl_type": null,
    "purl_namespace": null,
    "purl_name": null,
    "purl_version": null,
    "url": "",
    "release_date": null,
    "supplier_name": "",
    "supplier_url": "",
    "community_url": "",
    "download_url": "",
    "download_url_binary": "",
    "md5": null,
    "sha1": "f8f2c887ad10bf67f634f005b6987fed3179aac8",
    "sha256": null,
    "binary_md5": "",
    "binary_sha1": "",
    "binary_sha256": "",
    "license_id": 541,
    "comment": "",
    "description": "Like ruby's abbrev module, but in js",
    "package_size": null,
    "package_size_binary": null,
    "platform": "",
    "image_id": null,
    "repository_download_path_binary": "",
    "programming_language": "",
    "commits_nro": null,
    "contributors_nro": null,
    "releases_nro": null,
    "bugs_nro": null,
    "fixed_bugs_nro": null,
    "community_status": "",
    "community_size": null,
    "copyright": null,
    "attribution_acknowledgement": "",
    "warranty_liability_exclusions": "",
    "known_bugs": "",
    "known_vulnerabilities": "",
    "change_log": "",
    "kb_origin": null,
    "created": "2024-01-09 14:22:07",
    "updated": "2024-01-09 14:22:07",
    "user_username": "fossid",
    "license_identifier": "ISC",
    "license_name": "ISC License",
    "license_category": "PERMISSIVE",
    "created_date": "2024-01-09",
    "component_release_date": null
  }
}

Removed duplicate information in responses for the next API endpoints:

group: users, action: assign_permission
group: users, action: assign_role
group: scans, action: archive_scan
group: scans, action: ignore_rules_add
group: scans, action: ignore_rules_show
group: scans, action: ignore_rules_delete
group: scans, action: add_scan_specific_component_comment
group: scans, action: remove_scan_specific_component_comment
group: scans, action: string_match_rules_add
group: scans, action: refresh_files
group: component_approval, action: delete_requests_for_unidentified
group: component_approval, action: reset_request_by_component
Old response:
{
    "operation": "operation name",
    "status": "1",
    "data": {
        "operation": "operation name",
        "status": "1",
        "data": null,
        "message": "Response message"
    },
    "message": "Response message"
}
New response:
{
    {
      "operation": "operation name",
      "status": "1",
      "data": null,
      "message": "Response message"
    }
}

Since 23.3 the validation for scans -> create/update actions, field jar_file_extraction, is strict and does not allow empty string.

Only valid options or explicit null will pass the validation, accepted values: always, never, if_no_fullmatch.

FossID Workbench 23.3

New API endpoints to create project management policy rule

{
    "group": "policy_management",
    "action": "create_policy_rule",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "My project code",
        "type": "policy rule type,(license, license_category)",
        "condition": "policy rule condition(existing license id or existing license category)",
        "description": "Optional",
        "action": "policy rule type,(generate_warning)"
    }
}

New API endpoints to update project management policy rule

{
    "group": "policy_management",
    "action": "update_policy_rule",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "My project code",
        "rule_id": "project policy management rule id",
        "type": "policy rule type,(license, license_category)",
        "condition": "policy rule condition(existing license id or existing license category)",
        "description": "Optional",
        "action": "policy rule type,(generate_warning)"
    }
}

New API endpoints to delete project management policy rule

{
    "group": "policy_management",
    "action": "delete_policy_rule",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "My project code",
        "rule_id": "project policy management rule id"
    }
}

New API endpoints to get project policy management rule

{
    "group": "policy_management",
    "action": "get_policy_rule",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "My project code",
        "rule_id": "project policy management rule id"
    }
}

New API endpoints to get project policy management rule by condition

{
    "group": "policy_management",
    "action": "get_policy_rule_by_condition",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "My project code",
        "type": "policy rule type,(license, license_category)",
        "condition": "policy rule condition(existing license id or existing license category)"
    }
}

New API endpoints to delete all project policy management rules

{
    "group": "policy_management",
    "action": "delete_all_policy_rules",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "My project code"
    }
}

New API endpoints to get list of all project policy management rules

{
    "group": "policy_management",
    "action": "get_policy_rules_list",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "My project code"
    }
}

New API endpoints to get project policy management warnings info

{
    "group": "projects",
    "action": "get_policy_warnings_info",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "My project code"
    }
}

New API endpoints to get policy management warnings counter by folder or file path

{
    "group": "scans",
    "action": "get_policy_warnings_by_path",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "scan_code": "My scan code",
        "path": "Path to the folder or file in base64"
    }
}

New API endpoints to get quantity scan project policy warnings

{
    "group": "scans",
    "action": "get_policy_warnings_counter",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "scan_code": "My scan code"
    }
}

New API endpoints to get policy management warnings information for given scan

{
    "group": "scans",
    "action": "get_policy_warnings_info",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "scan_code": "My scan code"
    }
}

Added fields to response from ‘projects’ -> ‘list_projects’

API call:
{
    "group": "projects",
    "action": "list_projects",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
}
Old response:
{
    "operation": "projects_list_projects",
    "status": "1",
    "data": [
        {
            "id": 1,
            "project_code": "test_1",
            "project_name": "test"
        }
    ]
}
New response:
{
    "operation": "projects_list_projects",
    "status": "1",
    "data": [
        {
          "id": 1,      
          "creator": 1,
          "project_code": "test_1",
          "project_name": "test",
          "limit_date": null,
          "product_code": "",
          "product_name": "",
          "description": "",
          "comment": "",
          "is_archived": false,
          "jira_project_key": "",
          "created": "2023-08-16 11:45:18",
          "updated": null,
          "scans": "int, number of the project scans",
          "policy_rules": "int, number of the project rules",
          "warnings": "int, number of the warnings",
        }
    ]
}

FossID Workbench 23.2

Backward incompatible changes

Stricter permissions for assigning a scan to a project

A user needs to be a project member or to have PROJECT_UPDATE_ANY permission in order to be able to assign a scan to a project when using actions scans -> create or scans -> update.

New API endpoints to retrieve and generate and set API keys for users

This API action retrieves the API keys of the user with the username searched_username.

{
    "group": "users",
    "action": "get_api_key",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "searched_username": "Username for the user being searched."
    }

This API action generates a new API keys and assigns it to the user with the username searched_username.

{
    "group": "users",
    "action": "renew_api_key",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "searched_username": "Username for the user being searched."
    }
}

New API endpoints to create/update/delete component approval comments

{
    "group": "component_approval",
    "action": "list_comments",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "My project code",
        "component_id": "Component id"
    }
}

{
    "group": "component_approval",
    "action": "create_comment",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "My project code",
        "component_id": "Legacy.view.apipusher.comment_id",
        "comment_text": "Comment content."
    }
}

{
    "group": "component_approval",
    "action": "update_comment",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "My project code",
        "comment_id": "Legacy.view.apipusher.comment_id",
        "comment_text": "Comment content."
    }
}

{
    "group": "component_approval",
    "action": "delete_comment",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "My project code",
        "comment_id": "Legacy.view.apipusher.comment_id"
    }
}

FossID Workbench 23.1

Backward incompatible changes

The API endpoint to download scan reports was removed. The new API group “download” was added to download reports

{
  {
    "group": "download",
    "action": "download_report",
    "data": {
        "username": "username",
        "key": "user_key",
        "report_entity" : "`scans` or `projects`"
        "process_id": "process_id",
    }
  }
}

New API endpoints regarding new feature: Project level reports

1. The new API endpoint to create project level reports

{
    "group": "projects",
    "action": "generate_report",
    "data": {
        "username": "username",
        "key": "user_key",
        "project_code": "My project code",
        "report_type": "xlsx or spdx or dynamic",
        "selection_type": "include_foss",
        "selection_view" :"",
        "async" : "0 or 1",
        "report_content_type" :"default or abbreviated"
    }
}

2. The new API endpoint to check the status of generating project level reports process

{
    "group": "projects",
    "action": "check_status",
    "data": {
        "username": "username",
        "key": "user_key",
        "type": "Type of the process - `REPORT_GENERATION`"
        "process_id": "Id of the process"
    }
}

Trigger async reports generation from API

The scans report type ‘basic’ was added to the list of reports that could be generated asynchronously using action “scans” -> “generate_report”.

New field purl in components -> create and components -> update

New field purl was added to store Package URL information associated with a component. You can read more about PackageURL specification here: https://github.com/package-url/purl-spec

Example creating a component:

{
    "group": "components",
    "action": "create",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "name": "aaaa",
        "version": "2",
        "license_identifier": "MIT",
        "purl": "pkg:npm/ansi-regex@5.0.1"
    }
}

Inside components table the value from purl field is parsed and also stored in individual columns, so in the output from components -> get_information several other fields can be seen alongside with purl:

{
  "operation": "components_get_information",
  "status": "1",
  "data": {
    ....
    "id": 1,
    "created": "2023-01-15 03:36:19",
    "updated": "2023-01-15 03:36:19",
    "created_by": 1,
    "cpe": null,
    "name": "json-diff",
    "version": "1.0.0",
    "purl": "pkg:github/andreyvit/json-diff@1.0.0",
    "purl_type": "github",
    "purl_namespace": "andreyvit",
    "purl_name": "json-diff",
    "purl_version": "1.0.0",
    "url": "https://github.com/andreyvit/json-diff/archive/v1.0.0.tar.gz",
   ...
  }
}

New API endpoints for updating dependencies scans -> update_dependency_analysis_results

Also existing API endpoint “add_dependency_analysis_result” received an optional field “include_in_report”. Default value being 1.

{
    "group": "scans",
    "action": "update_dependency_analysis_results",
    "data": {
        "username": "username",
        "key": "user_key",
        "scan_code": "My scan code",
        "component_name": "My component name",
        "component_version": "Component Version",
        "package_id": "Purl string",
        "projects_and_scopes": "Optional JSON object",
        "detailed_dependency_info": "Optional JSON object",
        "include_in_report": "Possible value 1 or 0"
    }
}

FossID Workbench 22.2

Boolean values returned in fields from scans -> get_information

The fields listed below which returned in the past: null, 0 or 1 will return from now on null, false or true:

is_archived

is_blind_audit

is_from_report

has_file_extension

{
    "group": "scans",
    "action": "get_information",
    "data": {
        "username": "test_user",
        "key": "test_user_key",
        "scan_code": "test_scan"
    }
}

{
  "operation": "scans_get_information",
  "status": "1",
  "data": {
    "id": 1950,
    "scanlimit": 10,
    "last_run": null,
    "code": "test_scan_code",
     ...
    "is_from_report": false,      <==
    "has_file_extension": true,   <==
     ...
    "user_id": 1,
    "project_id": 1
  }
}

API endpoints to add and remove dependencies to scans

Two new actions under “scans” group allows adding and removing dependencies:


{
    "group": "scans",
    "action": "add_dependency_analysis_results",
    "data": {
        "username": "username",
        "key": "user_key",
        "scan_code": "My scan code",
        "component_name": "My component name",
        "component_version": "Component Version",
        "package_id": "Purl string",
        "projects_and_scopes": "Optional JSON object",
        "detailed_dependency_info": "Optional JSON object",
        "include_in_report": "Possible value 1 or 0"
    }
}



{
    "group": "scans",
    "action": "remove_dependency_analysis_results",
    "data": {
        "username": "username",
        "key": "user_key",
        "scan_code": "My scan code",
        "component_name": "My component name",
        "component_version": "Legacy.view.apipusher.my_component_version"
    }
}

Improvement: Using wrong username or key when calling API is not returning meaningful error message

In the past a generic error would be displayed if wrong username or key was used:

{
    "group": "Components",
    "action": "update",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "name": "new_empty_comp",
        "version": "1",
        "new_name": "",
        "new_version": ""
    }
}

{
  "operation": "Components_update",
  "status": "0",
  "data": null,
  "error": "An error occurred. Please check WebApp logs.",
  "message": "An error occurred. Please check WebApp logs.",
  "message_parameters": []
}

The new message helps identify the issue:


{
  "operation": "Components_update",
  "status": "0",
  "data": [],
  "error": "Classes.FossID.user_not_found_or_api_key_is_not_correct",
  "message": "User is not found or API key is incorrect",
  "message_parameters": []
}

New optional field ‘new_project_owner’ in action ‘projects’ -> ‘update’

The ‘project creator’ concept proved to not be flexible enough to handle all situations, for this reason in 22.2 it is replaced with ‘project owner’. The owner can be changed by admin (user with permission PROJECT_UPDATE_ANY) while with the creator this was not possible. For backward compatibility reasons the ‘creator’ field will be kept when creating a project. While for update there is a new optional field ‘new_project_owner’ which allows changing the owner of a project with a different user.

{
    "group": "projects",
    "action": "update",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "project_some_code",
        "project_name": "project_some_name",
        ....
        "new_project_owner": "username of new owner"
    }
}

Trigger async reports generation from API

Until now reports generation using action “scans” -> “generate_report” was a synchronous operation. In WebApp 22.2 was introduced a method of asynchronously generating reports from API. This is a 3 steps action:

  1. Call action “scans” -> “generate_report” with new parameter async=1. This request will return a “process_id” value to used in next step
  2. Call action “scans” -> “check_status” passing process_id value and also setying type “REPORT_GENERATION”
  3. When the check_status indicates status FINISHED call newly added action “scans” -> “download_report” passing scan_id and process_id.

Changed errors and messages

Due to code refactoring or just to improve the information some errors and messages were changed:

1. projects -> delete

API call:
{
    "group": "projects",
    "action": "delete",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "pr_code"

    }
}

Old response

{
  "operation": "projects_delete",
  "status": "1",
  "data": {
    "operation": "delete",
    "status": "1",
    "data": null,
    "message": "Project has been deleted successfully",
    "error": ""
  },
  "message": "Project has been deleted successfully"
}

New response

{
  "operation": "projects_delete",
  "status": "1",
  "data": null,
  "message": "Project has been deleted successfully"
}

2. projects -> delete with missing field ‘project_code’

API call:
{
    "group": "projects",
    "action": "delete",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "pr_code"
    }
}

Old response

{
  "operation": "projects_delete",
  "status": "0",
  "data": null,
  "error": "Field 'project_code': the provided value  does not meet number of characters requirements.",
  "message": "Field 'project_code': the provided value  does not meet number of characters requirements.",
  "message_parameters": []
}

New response


{
  "operation": "projects_delete",
  "status": "0",  
  "data": [
    {
      "code": "RequestData.Base.invalid_field_length",
      "message": "Field 'project_code': the provided value  does not meet number of characters requirements.",
      "message_parameters": {
        "fieldname": "project_code"
      }
    }
  ],
  "error": "RequestData.Base.issues_while_parsing_request",
  "message": "These issues were found while parsing the request:",
  "message_parameters": []
}

3. projects -> create or update with missing field ‘project_code’ or “project_name”

API call:
{
    "group": "projects",
    "action": "create",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_name": "pr_code",
        ....

    }
}

Old response

{
   "operation":"projects_create",
   "status":"0",
   "data":null,
   "error":"Project code is required.",
   "message":"Project code is required.",
   "message_parameters":[
      
   ]
}

New response

{
  "operation": "projects_create",
  "status": "0",
  "data": [
    {
      "code": "RequestData.Base.mandatory_field_missing",
      "message": "The mandatory field project_code is missing; string is required",
      "message_parameters": {
        "fieldname": "project_code"
      }
    }
  ],
  "error": "RequestData.Base.issues_while_parsing_request",
  "message": "These issues were found while parsing the request:",
  "message_parameters": []
}

4. projects -> assign member

API call:
{
    "group": "projects",
    "action": "assign_member",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "pr_code",
        "assign_member": "fossid"
    }
}

Old response

{
    "operation": "projects_assign_member",
    "status": "1",
    "data": {
        "operation": "assign_member",
        "status": "1",
        "data": null,
        "message": "User fossid has been assigned to project pr_code"
    },
    "message": "User fossid has been assigned to project pr_code"
}

New response

{
    "operation": "projects_assign_member",
    "status": "1",
    "data": null,
    "message": "User fossid has been assigned to project pr_code"
}

5. projects -> remove member

API call:
{
    "group": "projects",
    "action": "remove_member",
    "data": {
        "username": "fossid",
        "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "project_code": "pr_code",
        "assign_member": "fossid"
    }
}

Old response

{
    "operation": "projects_remove_member",
    "status": "1",
    "data": {
        "operation": "remove_member",
        "status": "1",
        "data": null,
        "message": "User fossid has been removed from project pr_code"
    },
    "message": "User fossid has been removed from project pr_code"
}

New response

{
    "operation": "projects_remove_member",
    "status": "1",
    "data": null,
    "message": "User fossid has been removed from project pr_code"
}

6. scans -> delete

Scan delete process is background since 23.1 The Action adds a background job and returns a process_id number. When the background job execution is finished the scan is considered deleted.

Old response

{
   {
      "operation": "scans_delete",
      "status": "1",
      "data": "id of the deleted scan",
      "message": "Scan name: 4285 has been deleted."
   }
}

New response

{
  "operation": "scans_delete",
  "status": "1",
  "data": {
    "process_id": integer
  },
  "message": "Scan: scan_name was added in the queue to delete"
}

Use action check_status with the type DELETE_SCAN and process_id to check if the scan has been deleted.

API call:
{
    "group": "scans",
    "action": "check_status",
    "data": {
        "username": "username",
        "key": "user_key",
        "scan_code": "Must be empty if type is `DELETE_SCAN`",
        "type": "DELETE_SCAN",
        "delay_response": "Optional: Amount of seconds to wait before response. Max 10.",
        "process_id": "Id of the process"
    }
}

Response example if the process is running

{
  "operation": "scans_check_status",
  "status": "1",
  "data": {
    "process_id": "Id of the process - integer",
    "progress_state": "RUNNING",
    "process_requested": "2023-04-03 13:28:34",
    "process_started": "2023-04-03 13:28:40",
    "process_exited": null
  },
  "message": "Delete scan process is RUNNING"
}

Response example if the process is FINISHED

{
  "operation": "scans_check_status",
  "status": "1",
  "data": true,
  "message": "Scan was deleted successfully"
}
FossID Workbench Help, version 2026.1.0