> For the complete documentation index, see [llms.txt](https://helm.docs.medcrypt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://helm.docs.medcrypt.com/~/changes/KjixZskptrAaNWiTYnvj/api-sdk-and-docs/api-sdk-documentation.md). # API SDK documentation {% hint style="info" %} [Contact us](mailto:helm.support@medcrypt.co) if you would like access to our Helm API. {% endhint %} You can use the Helm API SDK to perform a variety of functions, including uploading one or multiple SBOMs, returning all unmatched SBOM entries, returning all vulnerabilities or just CISA KEV vulnerabilities, and generating FDA SBOM or CycloneDX reports. ## Download Helm API SDK The Helm API is currently available as a Python SDK. It is in protobuf, with the API SDK providing Python bindings as well as helper bash scripts with which to call the SDK. * SDK Version: `2.74.2` * Download the API SDK file below, then verify that the MD5 checksum is **\`b65e44c7c6c11b740237a146b044f91e** . Note that our API documentation is hosted on Gitbook, thus you will see an interim page that Gitbook is verifying the safety of this file -- *this page unfortunately does not go away, but your file will complete downloading successfully*. {% file src="/files/751nB8gIqoGJl9ZSGsXC" %} Helm API Python SDK {% endfile %} {% hint style="warning" %} **Need C#?** Our C# SDK is currently in feature preview. If you'd like to use this instead of our Python SDK, [contact us](mailto:helm.support@medcrypt.co). {% endhint %} ## Start using the Helm API Once you have been granted access to our Helm API, you'll need to download our API SDK, then generate your API key to make calls to the API. To do so: 1. Click the **Developers** option on the sidebar. This will display the **Developers** page. 2. If you haven't followed the download instructions in the section above yet, do so now. If you're in the UI, you can also click the **Get API SDK** button (which will take you to this page). 3. Click the attached file in the section above to download it. Note that the Gitbook file security verification page does not go away, but the file does download successfully. 4. Verify that the SDK MD5 checksum is `550bee6dd3d7a5d80e5fb72bcebf16bc` 5. After uncompressing this file, you will find a `readme.txt` document that contains the rest of the steps to execute the API. 6. Make sure that you have the Python libraries that are in the `requirements.txt` file installed before continuing. 7. In the Helm UI, you'll see your **API user name** which is also the Helm email address that you have API access for. This will be your `client_id` that you will update in the scripts in the next steps. 8. In the Helm UI, click **Generate API key**. This will be your `client_secret` that you will update in the scripts in the next steps. 9. We'll now switch over to the command line. From the command line, `cd` to the directory `api/run`. You'll need to update `client_id`, `client_secret,` and other parameters in four scripts: `run_upload_sbom.sh`, `run_unmatched_sbom_entries.sh`, `run_vuln_list.sh`, and `run_product_version_report.sh`. 10. In the `run_upload_sbom.sh` script, update your `client_id` and `client_secret`. 11. Specify any other necessary [parameters](#command-line-parameters) in this file. Refer to each script for specific parameters to update. 12. Run `./run_upload_sbom`. 13. Repeat steps 10-12 for the `run_unmatched_sbom_entries.sh` and `run_vuln_list.sh` scripts. ### API methods These are the API methods and definitions available in this API. * **listorganizations:** Lists the organizations that the user has access to. * **listorganizationproducts:** Lists the products a given organization has. * **listorganizationproductversions:** Lists the product versions of a particular product for that organization. * **createorganizationproduct:** Creates a new product under that organization with the provided product name. The user will have access to this product. * **createorganizationproductversions:** Creates a new product version under a selected product with the provided version name. * **submitsbom:** * Uploads an SBOM provided in the `--sbom_files` parameter. * Allows the user to upload an SBOM under an existing product and product version. * Users can create a new product, product version, and upload an SBOM under this new version. * **listunmatchedsbomentries:** This lists all of your unmatched SBOM entries for a given SBOM product and version. * **listvulnerabilities:** This lists all vulnerabilities for a given SBOM product and version. You can also filter this down via `--exploit_source` to CISA KEV vulnerabilities only, as detailed below. * **requestreport:** This issues a request to generate a product version report. The report generation process is asynchronous, so this may take a moment. * **getreportrequeststate:** This checks on the status of a requested report. * **getreportfile:** Once a report request is completed (report\_request\_state=4), the report file will be available for download. ## Scripts and command line parameters There are four scripts for the Helm API: * `run_upload_sbom.sh` * `run_unmatched_sbom_entries.sh` * `run_vuln_list.sh` * `run_product_version_report.sh` ### Upload one or multiple SBOMs You can upload one or multiple SBOMs using the `run_upload_sbom.sh` script. The following command-line parameters are available: * `--client_id`: This is your API account username. In the Helm UI, this is the **API user name**. * `--client_secret`: This is your API key that you will generate from the Helm UI. * `--sbom_files`: This is the path to the SBOM file on your system. * `--product_name`: This is the name of the product that you want to create a version for. * `--version:` This is the product version that you want to create and upload an SBOM for. * `--createProdVers`: If your product version doesn't already exist, you can create a new product version for a given SBOM product. * `--api_url`: This is the API URL provided by Medcrypt. * `--file_type`: This is the file type you'll be uploading. It only needs to be set if you are uploading a SPDX SBOM. If so, set to `SPDX`. When you've set your parameters, run `./run_upload_sbom.sh`. ### Get all unmatched SBOM entries for product version: You can return all unmatched SBOM entries for a given product and version using the `run_unmatched_sbom_entries.sh` script. The following command-line parameters are available: * `--client_id`: This is your API account username. In the Helm UI, this is the **API user name**. * `--client_secret`: This is your API key that you will generate from the Helm UI. * `--product_name`: This is the name of the product that you want to create a version for. * `--version:` This is the product version that you want to create and upload an SBOM for. * `--api-url`: This is the API URL provided by Medcrypt. When you've set your parameters, run `./run_unmatched_sbom_entries.sh`. ### Get all vulnerabilities or just CISA KEV vulnerabilities for product version You can return all vulnerabilities or just CISA KEV vulnerabilities for a given product and version using the `run_vuln_list.sh` script. The following command-line parameters are available: * `--client_id`: This is your API account username. In the Helm UI, this is the **API user name**. * `--client_secret`: This is your API key that you will generate from the Helm UI. * `--product_name`: This is the name of the product that you want to create a version for. * `--version:` This is the product version that you want to create and upload an SBOM for. * `--api-url`: This is the API URL provided by Medcrypt. * `--start_date`: This is the start date at which to begin filtering vulnerabilities. * `--end_date`: This is the end date at which to begin filtering vulnerabilities. * `--exploit_source`: You can specify `CISA_KEV` to get just vulnerabilities on the CISA KEV list. If you don't specify this, you will get all of your vulnerabilities. The default value is UNDEFINED. When you've set your parameters, run `./run_vuln_list.sh`. ### Run run\_product\_version\_report.sh script: You can create and download an FDA SBOM or CycloneDX VEX report for a given product and version using the `run_product_version_report.sh` script. The following command-line parameters are available: * `--client_id`: This is your API account username. In the Helm UI, this is the **API user name**. * `--client_secret`: This is your API key that you will generate from the Helm UI. * `--product_name`: This is the name of the product that you want to create a version for. * `--version:` This is the product version that you want to create and upload an SBOM for. * `--api-url`: This is the API URL provided by Medcrypt. * `--file_path`: This is the path where you would like a generated report to be saved to. * `--report_type`: Specify either `FDA_EXCEL` or `CDX_VEX` to generate your FDA SBOM in Excel format or CycloneDX VEX report. When you've set your parameters, run `./run_product_version_report.sh`. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://helm.docs.medcrypt.com/~/changes/KjixZskptrAaNWiTYnvj/api-sdk-and-docs/api-sdk-documentation.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.