Ketryx Documentation
Book a DemoFAQTraining Videos
  • Introduction
  • ๐Ÿ“„Manuals
    • MAN-01 Ketryx Lifecycle Management
    • MAN-02 Software Release Process
    • MAN-03 Supply Chain Management: Software Dependencies
      • Threat Modeling
      • Vulnerability Management
      • Working with CycloneDX
      • Working with SPDX
    • MAN-04 Supply Chain Management: Cloud Dependencies
    • MAN-05 Milestones
    • MAN-06 Test Management
    • MAN-07 Traceability
    • MAN-08 Risk Management
    • MAN-09 Git-Based Configuration Items
    • MAN-10 Managing items in Ketryx
    • MAN-11 Approval Rules
    • MAN-12 Computational Controls
    • MAN-13 Data Export
  • ๐Ÿ› ๏ธWork Instructions
    • WI-01 Requirement
    • WI-02 Software Item Specification
    • WI-03 Task
    • WI-04 Test Case
    • WI-05 Test Execution
    • WI-06 Anomaly
    • WI-07 Complaint
    • WI-08 Change Request
    • WI-09 Corrective and Preventive Action (CAPA)
    • WI-10 Risk
    • WI-11 Document
  • ๐ŸŒIntegrations
    • Jira
    • Azure DevOps
    • TestRail
    • Jama
    • Polarion
    • Chrome extension
    • Source Code
      • Azure DevOps
      • Bitbucket
      • GitHub
      • GitLab
      • Code Change Reviews
    • Release documents
      • Google Workspace
    • Authentication
  • ๐Ÿ“šReference
    • Ketryx Query Language
    • Advanced Settings
    • Glob Pattern Matching Algorithm
    • Traceability Configuration
    • Document Templating
    • Project Settings
    • Custom Item Types
    • Assistant
    • Agents
    • Release Notes
  • ๐Ÿ”ƒAPI
    • Authentication
    • Build API
    • Project API
    • Item API
    • Webhooks
Powered by GitBook

Ketryx

  • ketryx.com
  • What is Ketryx?

Resources

  • FAQ
  • Training Videos

ยฉ 2025 Ketryx Corporation

On this page

Was this helpful?

Export as PDF
  1. API

Build API

API to report builds and test results to Ketryx

PreviousAuthenticationNextProject API

Last updated 1 month ago

Was this helpful?

Ketryx exposes an API to report builds and test results programmatically. There is also a formal defining this API, and a separate page about . You can also take a look at the implementation of the for how this API can be interacted with.

Builds

You should either pass in the version parameter to associate the build with a particular version, or set the commitSha parameter so the build will be associated with any version whose release ref pattern (as configured in the Ketryx project settings) resolves to that commit. The version parameter can be the Ketryx version ID (KXVSN...) or the full version name (e.g. App v1.0.0). Either way, automated tests need to be associated with a particular version (not the Current state), so they will not show up in Ketryx test management unless you create a version.

You can combine the reporting of test results with one or more checks (checkDependenciesStatus, checkReleaseStatus), or make separate requests. Typically, test results will be reported for all release candidate builds, while the final check for checkReleaseStatus would happen in the deployment script to production (before actually triggering the deployment).

Build artifacts

Configure required build documents

A particular set of uploaded build artifacts may be detected as required build documents to either block the release of a Ketryx version, or help gathering important build documents for a release in an automated way.

Examples

Reporting a Cucumber test result

Upload a Cucumber JSON build artifact to Ketryx:

POST https://app.ketryx.com/api/v1/build-artifacts?project=KXPRJ11T0R3MGR39WCVN0PEKP77HVP0
Content-Type: multipart/form-data
Authorization: Bearer KXTK_...

with an attached file (e.g., cucumber.json) as multipart form data. This returns a JSON response of the following form:

{
  "ok": true,
  "id": "KXUPF..."
}

Using the id from the response, make another request to report a build that produced this build artifact:

POST https://app.ketryx.com/api/v1/builds
Content-Type: application/json
Authorization: Bearer KXTK_...

{
  "project": "KXPRJ11T0R3MGR39WCVN0PEKP77HVP0",
  "version": "1.0",
  "artifacts": [
    {
      "id": "KXUPF...",
      "type": "cucumber-json"
    }
  ]
}

Reporting individual test results directly

As an alternative to uploading Cucumber JSON or JUnit XML files to Ketryx, you can report individual test results directly, using the tests property:

POST https://app.ketryx.com/api/v1/builds
Content-Type: application/json
Authorization: Bearer KXTK_...

{
  "project": "KXPRJ11T0R3MGR39WCVN0PEKP77HVP0",
  "version": "1.0",
  "tests": [
    {
      "testedItem": "SAMD-45",
      "result": "pass",
      "title": "My automated test",
      "log": "Log output from executing this test"
    }
  ]
}

Each test may optionally reference one or more artifacts as well.

Uploading an SPDX file

Upload an SPDX build artifact to Ketryx:

POST https://app.ketryx.com/api/v1/build-artifacts?project=KXPRJ11T0R3MGR39WCVN0PEKP77HVP0
Content-Type: multipart/form-data
Authorization: Bearer KXTK_...

with an attached file (e.g., spdx.json) as multipart form data. This returns a JSON response of the following form:

{
  "ok": true,
  "id": "KXUPF..."
}

Using the id from the response, make another request to report a build that produced this build artifact:

POST https://app.ketryx.com/api/v1/builds
Content-Type: application/json
Authorization: Bearer KXTK_...

{
  "project": "KXPRJ11T0R3MGR39WCVN0PEKP77HVP0",
  "version": "1.0",
  "artifacts": [
    {
      "id": "KXUPF...",
      "type": "spdx-json"
    }
  ]
}

Ketryx will parse the SPDX JSON file and create corresponding dependencies as defined within these files. It extracts crucial information about software packages, including version, license, and advisory information (introduced in SPDX version 2.3), which pertains to any vulnerabilities associated with the software packages.

Note: Uploading an additional SPDX JSON file will overwrite the previous SPDX JSON file upload if it is uploaded to the same project, version, and uses the same buildName. Providing a unique buildName when uploading multiple SPDX JSON build artifacts to the same project and version is recommended. This allows for incremental uploads of different SPDX JSON files for a specific project and version. To overwrite a build, reference the original buildName in the build artifact when reporting a subsequent build.

Previous example of reporting a build with a SPDX build artifact using buildName:

POST https://app.ketryx.com/api/v1/build-artifacts?project=KXPRJ11T0R3MGR39WCVN0PEKP77HVP0&buildName=SPDX_SBOM_Upload
Content-Type: multipart/form-data
Authorization: Bearer KXTK_...
POST https://app.ketryx.com/api/v1/builds
Content-Type: application/json
Authorization: Bearer KXTK_...

{
  "project": "KXPRJ11T0R3MGR39WCVN0PEKP77HVP0",
  "version": "1.0",
  "buildName": "SPDX_SBOM_Upload",
  "artifacts": [
    {
      "id": "KXUPF...",
      "type": "spdx-json"
    }
  ]
}

Uploading a CycloneDX file

Upload a CycloneDX build artifact to Ketryx:

POST https://app.ketryx.com/api/v1/build-artifacts?project=KXPRJ11T0R3MGR39WCVN0PEKP77HVP0
Content-Type: multipart/form-data
Authorization: Bearer KXTK_...

with an attached file (e.g., cyclonedx.json) as multipart form data. This returns a JSON response of the following form:

{
  "ok": true,
  "id": "KXUPF..."
}

Using the id from the response, make another request to report a build that produced this build artifact:

POST https://app.ketryx.com/api/v1/builds
Content-Type: application/json
Authorization: Bearer KXTK_...

{
  "project": "KXPRJ11T0R3MGR39WCVN0PEKP77HVP0",
  "version": "1.0",
  "artifacts": [
    {
      "id": "KXUPF...",
      "type": "cyclonedx-json"
    }
  ]
}

Ketryx will parse the CycloneDX JSON file and create corresponding dependencies as defined within these files. It extracts crucial information about software packages, including version, license, and vulnerability information, which pertains to any vulnerabilities associated with the software packages.

Note: Uploading an additional CycloneDX JSON file will overwrite the previous CycloneDX JSON file upload if it is uploaded to the same project, version, and buildName. Providing a unique buildName when uploading multiple CycloneDX JSON build artifacts to the same project and version is recommended. This allows for incremental uploads of different CycloneDX files for a specific project and version. To overwrite a build, reference the original buildName in the build artifact when reporting a subsequent build.

Previous example of reporting a build with a CycloneDX build artifact using buildName:

POST https://app.ketryx.com/api/v1/build-artifacts?project=KXPRJ11T0R3MGR39WCVN0PEKP77HVP0&buildName=CDX_SBOM_Upload
Content-Type: multipart/form-data
Authorization: Bearer KXTK_...
POST https://app.ketryx.com/api/v1/builds
Content-Type: application/json
Authorization: Bearer KXTK_...

{
  "project": "KXPRJ11T0R3MGR39WCVN0PEKP77HVP0",
  "version": "1.0",
  "buildName": "CDX_SBOM_Upload",
  "artifacts": [
    {
      "id": "KXUPF...",
      "type": "cyclonedx-json"
    }
  ]
}

Check the approval status of dependencies

To check whether all SOUP dependencies in a particular version of a project are controlled:

POST https://app.ketryx.com/api/v1/builds
Content-Type: application/json
Authorization: Bearer KXTK_...

{
  "project": "KXPRJ11T0R3MGR39WCVN0PEKP77HVP0",
  "version": "1.0",
  "checkDependenciesStatus": true
}

This returns a JSON response containing an ok property which will be true if all dependencies are accepted and fully approved, or false otherwise. If ok is false, the error property provides more details about what is missing.

Check the release status of a version

To check whether a version has been released in Ketryx (e.g., to block the deployment of an unreleased version to production):

POST https://app.ketryx.com/api/v1/builds
Content-Type: application/json
Authorization: Bearer KXTK_...

{
  "project": "KXPRJ11T0R3MGR39WCVN0PEKP77HVP0",
  "version": "1.0",
  "checkReleaseStatus": true
}

This returns a JSON response containing an ok property which will be true if the version has been fully released in Ketryx, or false otherwise.

To enable tracking for required build documents on the release / Git commit level, please refer to the for more details.

Ketryx will parse the Cucumber JSON file and create corresponding automatic test executions, based on annotations in the test file as described in .

๐Ÿ”ƒ
MAN-06 Test Management
OpenAPI specification
authentication and API keys
Ketryx GitHub Action
  • Builds
  • POSTReport a build to Ketryx
  • Build artifacts
  • POSTUpload a build artifact file to Ketryx
  • Configure required build documents
  • Examples
  • Reporting a Cucumber test result
  • Reporting individual test results directly
  • Uploading an SPDX file
  • Uploading a CycloneDX file
  • Check the approval status of dependencies
  • Check the release status of a version

Report a build to Ketryx

post

Reports a build to Ketryx, potentially including test results. Additionally, certain checks can be performed, namely whether all software dependencies are accepted and controlled, and/or whether the given version(s) are fully released in Ketryx.

The reported build can be associated with a particular version directly (via version), or with any versions given a particular commit (via commitSha), based on the release ref pattern configured in the Ketryx project.

Authorizations
Body
projectstringOptional

Ketryx project ID

Example: KXPRJ49GQYFQ5RR9KRTPWTRTC39YZ9W
versionstringOptional

Ketryx version ID or the full version name. Either this or the commitSha must be set.

Example: {"value":"KXVSN352CZED7078FC8DN23YYZVM59D","summary":"Ketryx version ID"}
commitShastringOptional

Commit SHA associated with this build. Either this or the version must be set. If the given commit is associated with multiple versions in Ketryx (via the release ref pattern configured for the Ketryx project), the status of all those matching versions will be considered.

Example: ad4db8ac1e70bd41aa8bcee6f00a3a1e36bb0e01
buildNamestringOptional

Build name. For each unique name, the latest build is part of the set of effective builds for a project. Empty by default.

Example: ci-e2e-batch1
logstringOptional

Log output to store for this build

sourceUrlstringOptional

Source URL associated with this build. This is used for documentation purposes and to link back to the build from the Ketryx interface.

Example: https://github.com/Ketryx/ketryx/actions/runs/4991785273
repositoryUrlsstring[]Optional

This is important to find the relevant commits for a given version, and to trigger updates of the repositories before checking the build status. The URLs should match the repository URLs as configured in the Ketryx project settings.

Example: ["https://github.com/Ketryx/ketryx"]
syncRepositoryUpdatebooleanOptional

Whether to update the associated repositories (specified in repositoryUrls) synchronously before returning from this API. This is useful when checking for the status of dependencies (using checkDependenciesStatus), to ensure that Ketryx has up-to-date data from the repository before performing the check.

checkDependenciesStatusbooleanOptional

Whether to perform a check of dependencies in the associated commit(s). If not all dependencies are accepted and in a controlled state

checkReleaseStatusbooleanOptional

Whether to perform a check of the overall release of the associated version(s).

Responses
200
OK
application/json
400
The request is not valid.
application/json
401
The requester is not authenticated.
application/json
403
The requester is unauthorized.
application/json
404
The resource was not found.
application/json
post
POST /api/v1/builds HTTP/1.1
Host: app.ketryx.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 577

{
  "project": "KXPRJ49GQYFQ5RR9KRTPWTRTC39YZ9W",
  "version": "text",
  "commitSha": "ad4db8ac1e70bd41aa8bcee6f00a3a1e36bb0e01",
  "buildName": "ci-e2e-batch1",
  "log": "text",
  "sourceUrl": "https://github.com/Ketryx/ketryx/actions/runs/4991785273",
  "repositoryUrls": [
    "https://github.com/Ketryx/ketryx"
  ],
  "syncRepositoryUpdate": true,
  "tests": [
    {
      "testedItem": "text",
      "result": "PASS",
      "title": "text",
      "log": "text",
      "artifacts": [
        {
          "id": "KXUPF1GGK0R03458B8VK6R8S7SKCQSV"
        }
      ]
    }
  ],
  "artifacts": [
    {
      "id": "KXUPF4VNVT28EFA8PJBT5642XDPEFR1",
      "type": "cucumber-json"
    }
  ],
  "checkDependenciesStatus": true,
  "checkReleaseStatus": true
}
{
  "ok": true,
  "error": "text",
  "buildId": "text",
  "projectId": "text",
  "repositoryIds": [
    "text"
  ],
  "versionIds": [
    "text"
  ],
  "commitShas": [
    "text"
  ],
  "dependenciesAccepted": true,
  "dependenciesControlled": true
}

Upload a build artifact file to Ketryx

post

Uploads a build artifact to Ketryx, which can then be included in a build using the /builds API. The file is encoded in a request of type multipart/form-data.

Authorizations
Query parameters
projectstringOptional

Ketryx ID of the project to upload the file to

Example: KXPRJ49GQYFQ5RR9KRTPWTRTC39YZ9W
Body
contentstring ยท binaryOptional
Responses
200
OK
application/json
400
The request is not valid.
application/json
401
The requester is not authenticated.
application/json
403
The requester is unauthorized.
application/json
404
The resource was not found.
application/json
post
POST /api/v1/build-artifacts HTTP/1.1
Host: app.ketryx.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: multipart/form-data
Accept: */*
Content-Length: 20

{
  "content": "binary"
}
{
  "ok": true,
  "id": "text"
}
relevant Advanced settings section