Core API Specification

Core API Specification#

You can find the OpenAPI YAML specification in the Swagger UI of your Yaku instance. The Swagger UI is available at /docs on your Yaku instance. For example, if your Yaku instance is available at https://yaku-ui.mycompany.com, you can access the Swagger UI at https://yaku-ui.mycompany.com/docs.

Warning

The API only supports file uploads with utf8 encoding.

An exception is the PATCH /api/v1/namespaces/{namespaceId}/configs/{configId}/config-from-excel endpoint, where the .xlsx file is expected to be a binary Excel file.

Namespaces#

GET /api/v1/namespaces#

Retrieve all namespaces, the current user has access to

Status Codes:
GET /api/v1/namespaces/{namespaceId}/users#

Retrieve users with access to the namespace

Parameters:

  • namespaceId (number)

Query Parameters:

  • page (integer) – The requested page of the list of existing resources

  • items (integer) – The amount of items on the page

  • sortOrder (string) – Sort order of the returned objects, must be one of ASC,DESC

  • sortBy (string) – Sort users in the namespace by the given property, allowed properties are displayName,username

  • search (string) – Only return those users that contain the characters in the search term

Status Codes:

Secrets#

GET /api/v1/namespaces/{namespaceId}/secrets#

Retrieve secrets known to the given namespace as paged data, contains only the metadata, not the secrets. The api does not allow to retrieve secret values at all.

Parameters:

  • namespaceId (number)

Query Parameters:

  • page (integer) – The requested page of the list of existing resources

  • items (integer) – The amount of items on the page

  • sortOrder (string) – Sort order of the returned objects, must be one of ASC,DESC

  • sortBy (string) – Sort secrets by the given property, allowed properties are name,creationTime,lastModificationTime

Status Codes:
POST /api/v1/namespaces/{namespaceId}/secrets#

Create a new secret in the namespace. The secret value will be stored in a vault and only retrieved for runs. The size of secret values is limited by a configurable value, default is 8kb.

Parameters:

  • namespaceId (number)

Status Codes:
PATCH /api/v1/namespaces/{namespaceId}/secrets/{name}#

Update a secret, i.e., change description and/or the secret value. The size of secret values is limited by a configurable value, default is 8kb. The name cannot be changed, replace this secret with a new one instead.

Parameters:

  • namespaceId (number)

  • name (string)

Status Codes:
DELETE /api/v1/namespaces/{namespaceId}/secrets/{name}#

Delete the given secret, this will remove the secret value from the vault as well.

Parameters:

  • namespaceId (number)

  • name (string)

Status Codes:

Run#

GET /api/v1/namespaces/{namespaceId}/runs#

Retrieve runs in the namespace, the list is paged and allows to filter for the config

Parameters:

  • namespaceId (number)

Query Parameters:

  • page (integer) – The requested page of the list of existing resources

  • items (integer) – The amount of items on the page

  • sortOrder (string) – Sort order of the returned objects, must be one of ASC,DESC

  • sortBy (string) – Sort runs by the given property, allowed properties are id,creationTime,completionTime,config

  • filter (string) – Multiple filter expressions to limit the returned entities for the given filter options, i.e., use multiple filter expressions in the url. Available for options “config” with a list of ids and “latestOnly” with a value “true”

Status Codes:
POST /api/v1/namespaces/{namespaceId}/runs#

Start a new qg run with the given config

Parameters:

  • namespaceId (number)

Status Codes:
POST /api/v1/namespaces/{namespaceId}/runs/synthetic#

Start a new synthetic qg run with the given config

Parameters:

  • namespaceId (number)

Query Parameters:

  • configId (number) – (Required)

Status Codes:
GET /api/v1/namespaces/{namespaceId}/runs/{runId}#

Get the requested run resource data

Parameters:

  • namespaceId (number)

  • runId (number)

Status Codes:
DELETE /api/v1/namespaces/{namespaceId}/runs/{runId}#

Delete the given run

Parameters:

  • namespaceId (number)

  • runId (number)

Status Codes:
GET /api/v1/namespaces/{namespaceId}/runs/{runId}/results#

Returns the results yaml file of a qg run.

Parameters:

  • namespaceId (number)

  • runId (number)

Status Codes:
GET /api/v1/namespaces/{namespaceId}/runs/{runId}/evidences#

Returns the work folder content of a qg run as a zipped file.

Parameters:

  • namespaceId (number)

  • runId (number)

Status Codes:

Configs#

GET /api/v1/namespaces/{namespaceId}/configs#

Retrieve config resources in the namespace

Parameters:

  • namespaceId (number)

Query Parameters:

  • page (integer) – The requested page of the list of existing resources

  • items (integer) – The amount of items on the page

  • sortOrder (string) – Sort order of the returned objects, must be one of ASC,DESC

  • sortBy (string) – Sort configs by the given property, allowed properties are id,name,creationTime,lastModificationTime

Status Codes:
POST /api/v1/namespaces/{namespaceId}/configs#

Create a new config resource in the namespace, no files associated initially

Parameters:

  • namespaceId (number)

Status Codes:
GET /api/v1/namespaces/{namespaceId}/configs/{configId}#

Get the requested config resource data

Parameters:

  • namespaceId (number)

  • configId (number)

Status Codes:
PATCH /api/v1/namespaces/{namespaceId}/configs/{configId}#

Update the given config resource

Parameters:

  • namespaceId (number)

  • configId (number)

Status Codes:
DELETE /api/v1/namespaces/{namespaceId}/configs/{configId}#

Delete the given config resource

Parameters:

  • namespaceId (number)

  • configId (number)

Status Codes:
PATCH /api/v1/namespaces/{namespaceId}/configs/{configId}/initial-config#

Create an initial qg-config file out of a basic questionnaire data format. If there is no prior qg-config file stored, the created file will be stored as qg-config in the config resource. It will not overwrite an existing qg-config file, instead it will store the created config as additional config file with a name qg-config-<x>.yaml.

Parameters:

  • namespaceId (number)

  • configId (number)

Status Codes:
PATCH /api/v1/namespaces/{namespaceId}/configs/{configId}/config-from-excel#

Create an initial qg-config file out of an excel sheet with rows of questions. If there is no prior qg-config file stored, the created file will be stored as qg-config in the config resource. It will not overwrite an existing qg-config file, instead it will store the created config as additional config file with a name qg-config-<x>.yaml.

Parameters:

  • namespaceId (number)

  • configId (number)

Status Codes:
POST /api/v1/namespaces/{namespaceId}/configs/{configId}/copy#

Create a copy of the given config resource

Parameters:

  • namespaceId (number)

  • configId (number)

Status Codes:
POST /api/v1/namespaces/{namespaceId}/configs/{configId}/files#

Add a new file to the given config resource. The special file qg-config is identified by filename

Parameters:

  • namespaceId (number)

  • configId (number)

Status Codes:
GET /api/v1/namespaces/{namespaceId}/configs/{configId}/files/{filename}#

Get the requested file content

Parameters:

  • namespaceId (number)

  • configId (number)

  • filename (string)

Status Codes:
PATCH /api/v1/namespaces/{namespaceId}/configs/{configId}/files/{filename}#

Update the file content of the referenced file

Parameters:

  • namespaceId (number)

  • configId (number)

  • filename (string)

Status Codes:
DELETE /api/v1/namespaces/{namespaceId}/configs/{configId}/files/{filename}#

Delete a file from the given config resource

Parameters:

  • namespaceId (number)

  • configId (number)

  • filename (string)

Status Codes:

Findings#

GET /api/v1/namespaces/{namespaceId}/findings#

Get all findings in a namespace

Parameters:

  • namespaceId (number)

Query Parameters:

  • page (integer) – The requested page of the list of existing resources

  • items (integer) – The amount of items on the page

  • sortOrder (string) – Sort order of the returned objects, must be one of ASC,DESC

  • sortBy (string) – Sort findings by the given property, allowed properties are id, configId, runId, runStatus, runCompletionTime, occurrenceCount, status, resolvedDate, resolver, createdAt, updatedAt

  • filter (string) – Multiple filter expressions to limit the returned entities for the given filter options, i.e., use multiple filter expressions in the url. Available for options “configId” with a list of ids

Status Codes:

  • 200 OK – Get all findings in a namespace, the list is paged and allows to filter for a config file

  • 429 Too Many Requests – The endpoint is temporarily blocked for the given namespace due to too many requests

GET /api/v1/namespaces/{namespaceId}/findings/{findingId}#

Get a finding

Parameters:

  • namespaceId (number) – Namespace ID

  • findingId (string) – Finding ID

Status Codes:

  • 200 OK – Get a finding by ID

PATCH /api/v1/namespaces/{namespaceId}/findings/{findingId}#

Update a finding

Parameters:

  • namespaceId (number) – Namespace ID

  • findingId (string) – Finding ID

Status Codes:
DELETE /api/v1/namespaces/{namespaceId}/findings/{findingId}#

Delete a finding

Parameters:

  • namespaceId (number) – Namespace ID

  • findingId (string) – Finding ID

Status Codes:

Metrics#

GET /api/v1/namespaces/{namespaceId}/metrics/findings#

Retrieve Findings metrics in the namespace, the list is paged and allows to filter by associated config

Parameters:

  • namespaceId (number)

Query Parameters:

  • page (integer) – The requested page of the list of existing resources

  • items (integer) – The amount of items on the page

  • sortOrder (string) – Sort order of the returned objects, must be one of ASC,DESC

  • sortBy (string) – Sort Findings metrics by the given property. Allowed properties: count,runId,configId,diff,datetime

  • configId (number) – Filter Findings metrics based on configId

Status Codes:
GET /api/v1/namespaces/{namespaceId}/metrics/findingsInRange#

Retrieve Findings metrics between specified range in the namespace, the list is paged and allows to filter by associated config

Parameters:

  • namespaceId (number)

Query Parameters:

  • page (integer) – The requested page of the list of existing resources

  • items (integer) – The amount of items on the page

  • sortOrder (string) – Sort order of the returned objects, must be one of ASC,DESC

  • sortBy (string) – Sort Findings metrics by the givent property, Allowed properties: count,runId,configId,diff,datetime

  • configId (number) – Filter Findings metrics based on configId

  • startRange (string) – Filter Findings metrics for runs starting with Timestamp (Required)

  • endRange (string) – Filter Findings metrics for runs ending before Timestamp (Required)

Status Codes:
GET /api/v1/namespaces/{namespaceId}/metrics/latestRunFindings#

Retrieve Findings metrics of the latest run in the namespace

Parameters:

  • namespaceId (number)

Query Parameters:

  • page (integer) – The requested page of the list of existing resources

  • items (integer) – The amount of items on the page

  • sortOrder (string) – Sort order of the returned objects, must be one of ASC,DESC

  • sortBy (string) – Sort Findings metrics by given property, Allowed properties: count,runId,configId,diff,datetime

Status Codes:
GET /api/v1/namespaces/{namespaceId}/metrics/latestRunFindingsInRange#

Retrieve Findings metrics of the latst run between specified range in the namespace

Parameters:

  • namespaceId (number)

Query Parameters:

  • page (integer) – The requested page of the list of existing resources

  • items (integer) – The amount of items on the page

  • sortOrder (string) – Sort order of the returned objects, must be one of ASC,DESC

  • sortBy (string) – Sort Findings metrics by given property, Allowed properties: count,runId,configId,diff,datetime

  • startRange (string) – Filter Findings metrics for runs starting with Timestamp (Required)

  • endRange (string) – Filter Findings metrics for runs ending before Timestamp (Required)

Status Codes:

Autopilot Explainer#

GET /api/v1/namespaces/{namespaceId}/explainer#

Get explanation for autopilot

Parameters:

  • namespaceId (number)

Query Parameters:

  • runId (number) – Id of the run. (Required)

  • chapter (string) – The selected chapter. (Required)

  • requirement (string) – The selected requirement. (Required)

  • check (string) – The selected check. (Required)

Status Codes:

Releases#

GET /api/v1/namespaces/{namespaceId}/releases#

Retrieve all releases

Parameters:

  • namespaceId (number)

Query Parameters:

  • page (integer) – The requested page of the list of existing resources

  • items (integer) – The amount of items on the page

  • sortOrder (string) – Sort order of the returned objects, must be one of ASC,DESC

  • filter (string) – Multiple filter expressions to limit the returned entities for the given filter options

Status Codes:
POST /api/v1/namespaces/{namespaceId}/releases#

Add a new release

Parameters:

  • namespaceId (number)

Status Codes:
GET /api/v1/namespaces/{namespaceId}/releases/{releaseId}#

Retrieve a release

Parameters:

  • namespaceId (number)

  • releaseId (number)

Status Codes:
PATCH /api/v1/namespaces/{namespaceId}/releases/{releaseId}#

Update a release

Parameters:

  • namespaceId (number)

  • releaseId (number)

Status Codes:
DELETE /api/v1/namespaces/{namespaceId}/releases/{releaseId}#

Delete a release

Parameters:

  • namespaceId (number)

  • releaseId (number)

Status Codes:
GET /api/v1/namespaces/{namespaceId}/releases/{releaseId}/state#

Get aggregate approval state of the release

Parameters:

  • namespaceId (number)

  • releaseId (number)

Status Codes:
POST /api/v1/namespaces/{namespaceId}/releases/{releaseId}/close#

Close the release

The release cannot be modified anymore. Closing is not reversible

Parameters:

  • namespaceId (number)

  • releaseId (number)

Status Codes:
GET /api/v1/namespaces/{namespaceId}/releases/{releaseId}/history#

Get release history

Parameters:

  • namespaceId (number)

  • releaseId (number)

Query Parameters:

  • sortOrder (string) – The sort order for the history items based on the timestamp

  • filter (string) – The filter for the history types

  • items (number) – The amount of items on the page

Status Codes:
POST /api/v1/namespaces/{namespaceId}/releases/{releaseId}/approvers#

Add an approver to the release

Parameters:

  • namespaceId (number)

  • releaseId (number)

Status Codes:
GET /api/v1/namespaces/{namespaceId}/releases/{releaseId}/approvers#

Get approval state of all approvers

Parameters:

  • namespaceId (number)

  • releaseId (number)

Query Parameters:

  • page (integer) – The requested page of the list of existing resources

  • items (integer) – The amount of items on the page

  • sortOrder (string) – Sort order of the returned objects, must be one of ASC,DESC

Status Codes:
POST /api/v1/namespaces/{namespaceId}/releases/{releaseId}/approve#

Approve a release

Parameters:

  • namespaceId (number)

  • releaseId (number)

Status Codes:
POST /api/v1/namespaces/{namespaceId}/releases/{releaseId}/reset#

Reset your approval

Parameters:

  • namespaceId (number)

  • releaseId (number)

Status Codes:
GET /api/v1/namespaces/{namespaceId}/releases/{releaseId}/approvers/{approverId}#

Get an approver

Parameters:

  • namespaceId (number)

  • releaseId (number)

  • approverId (number)

Status Codes:
DELETE /api/v1/namespaces/{namespaceId}/releases/{releaseId}/approvers/{approverId}#

Remove an approver from the release

Parameters:

  • namespaceId (number)

  • releaseId (number)

  • approverId (number)

Status Codes:
GET /api/v1/namespaces/{namespaceId}/releases/{releaseId}/comments#

Get comments of the release

Parameters:

  • namespaceId (number)

  • releaseId (number)

Query Parameters:

  • page (integer) – The requested page of the list of existing resources

  • items (integer) – The amount of items on the page

  • sortOrder (string) – Sort order of the returned objects, must be one of ASC,DESC

  • sortBy (string) – Sort comments by the given property, allowed properties are id,creationTime,lastModificationTime

Status Codes:
POST /api/v1/namespaces/{namespaceId}/releases/{releaseId}/comments#

Add a comment to the release

Parameters:

  • namespaceId (number)

  • releaseId (number)

Status Codes:
GET /api/v1/namespaces/{namespaceId}/releases/{releaseId}/comments/{commentId}#

Get a comment of the release

Parameters:

  • namespaceId (number)

  • releaseId (number)

  • commentId (number)

Status Codes:
PATCH /api/v1/namespaces/{namespaceId}/releases/{releaseId}/comments/{commentId}#

Update a comment

Parameters:

  • namespaceId (number)

  • releaseId (number)

  • commentId (number)

Status Codes:
DELETE /api/v1/namespaces/{namespaceId}/releases/{releaseId}/comments/{commentId}#

Remove a comment from the release

Parameters:

  • namespaceId (number)

  • releaseId (number)

  • commentId (number)

Status Codes:
POST /api/v1/namespaces/{namespaceId}/releases/{releaseId}/comments/get-by-reference#

Get comments by reference

Parameters:

  • namespaceId (number)

  • releaseId (number)

Query Parameters:

  • sortOrder (string) – Sort top level comments in the given order, allowed values are ‘ASC’ and ‘DESC’

Status Codes:
POST /api/v1/namespaces/{namespaceId}/releases/{releaseId}/comments/{commentId}/resolve#

Resolve a comment

Parameters:

  • namespaceId (number)

  • releaseId (number)

  • commentId (number)

Status Codes:
POST /api/v1/namespaces/{namespaceId}/releases/{releaseId}/comments/{commentId}/reset#

Reset a comment

Parameters:

  • namespaceId (number)

  • releaseId (number)

  • commentId (number)

Status Codes:
POST /api/v1/namespaces/{namespaceId}/releases/{releaseId}/overrides#

Override a check’s status color for this release

Parameters:

  • namespaceId (number)

  • releaseId (number)

Status Codes:
GET /api/v1/namespaces/{namespaceId}/releases/{releaseId}/overrides#

Returns all check status color overrides for a release

Parameters:

  • namespaceId (number)

  • releaseId (number)

Status Codes:
PATCH /api/v1/namespaces/{namespaceId}/releases/{releaseId}/overrides/{overrideId}#

Update an override for a check’s status color

Parameters:

  • namespaceId (number)

  • releaseId (number)

  • overrideId (number)

Status Codes:
DELETE /api/v1/namespaces/{namespaceId}/releases/{releaseId}/overrides/{overrideId}#

Delete an override for a check’s status color

Parameters:

  • namespaceId (number)

  • releaseId (number)

  • overrideId (number)

Status Codes:
POST /api/v1/namespaces/{namespaceId}/releases/{releaseId}/resultOverrides#

Override a check results fulfilled property for this release

Parameters:

  • namespaceId (number)

  • releaseId (number)

Status Codes:
GET /api/v1/namespaces/{namespaceId}/releases/{releaseId}/resultOverrides#

Returns all check result overrides for a release

Parameters:

  • namespaceId (number)

  • releaseId (number)

Status Codes:
PATCH /api/v1/namespaces/{namespaceId}/releases/{releaseId}/resultOverrides/{overrideId}#

Update an override for a check results fulfilled property

Parameters:

  • namespaceId (number)

  • releaseId (number)

  • overrideId (number)

Status Codes:
DELETE /api/v1/namespaces/{namespaceId}/releases/{releaseId}/resultOverrides/{overrideId}#

Delete an override for a check results fulfilled property

Parameters:

  • namespaceId (number)

  • releaseId (number)

  • overrideId (number)

Status Codes:
GET /api/v1/namespaces/{namespaceId}/releases/{releaseId}/tasks#

Get all tasks for a release

Get all tasks for a release

Parameters:

  • namespaceId (number)

  • releaseId (number)

Query Parameters:

  • page (integer) – The requested page of the list of existing resources

  • items (integer) – The amount of items on the page

  • sortOrder (string) – Sorting order

  • sortBy (string) – Sorting by the given field

  • state (string) – Filtering by task states

  • assignees (array) – Filtering by assignees

Status Codes:
POST /api/v1/namespaces/{namespaceId}/releases/{releaseId}/tasks#

Add a task

Add a task

Parameters:

  • namespaceId (number)

  • releaseId (number)

Status Codes:
GET /api/v1/namespaces/{namespaceId}/releases/{releaseId}/tasks/{taskId}#

Get a task

Get a task

Parameters:

  • namespaceId (number)

  • releaseId (number)

  • taskId (number)

Status Codes:
PATCH /api/v1/namespaces/{namespaceId}/releases/{releaseId}/tasks/{taskId}#

Update a task

Update a task

Parameters:

  • namespaceId (number)

  • releaseId (number)

  • taskId (number)

Status Codes:
DELETE /api/v1/namespaces/{namespaceId}/releases/{releaseId}/tasks/{taskId}#

Delete a task

Delete a task

Parameters:

  • namespaceId (number)

  • releaseId (number)

  • taskId (number)

Status Codes:
POST /api/v1/namespaces/{namespaceId}/releases/{releaseId}/tasks/referenceTask#

Add a task mapped to a configuration reference

Add a task mapped to a configuration reference

Parameters:

  • namespaceId (number)

  • releaseId (number)

Status Codes:
POST /api/v1/namespaces/{namespaceId}/releases/{releaseId}/tasks/{taskId}/close#

Close a task

Close a task

Parameters:

  • namespaceId (number)

  • releaseId (number)

  • taskId (number)

Status Codes:
POST /api/v1/namespaces/{namespaceId}/releases/{releaseId}/tasks/{taskId}/reopen#

Reopen a task

Reopen a task

Parameters:

  • namespaceId (number)

  • releaseId (number)

  • taskId (number)

Status Codes:
POST /api/v1/namespaces/{namespaceId}/releases/{releaseId}/tasks/{taskId}/assignees#

Assign users to a task

Assign users to a task

Parameters:

  • namespaceId (number)

  • releaseId (number)

  • taskId (number)

Status Codes:
DELETE /api/v1/namespaces/{namespaceId}/releases/{releaseId}/tasks/{taskId}/assignees#

Remove assignees from a task

Remove assignees from a task

Parameters:

  • namespaceId (number)

  • releaseId (number)

  • taskId (number)

Status Codes:

User Profile#

GET /api/v1/user-profile#

Retrieve user profile

Status Codes:
PATCH /api/v1/user-profile#

Update the user’s profile

Status Codes:

Subscriptions#

POST /api/v1/subscriptions/manage#

Subscribe or unsubscribe to a release by creating or deleting a subscription resource.

Status Codes:
GET /api/v1/subscriptions/status/{userId}/{releaseId}#
Parameters:

  • userId (string) – userId of the user subscribed

  • releaseId (number) – releaseId

Status Codes:

Status#

GET /api/v1/service/info#

Retrieve information on current versions used to operate the service. It returns the version of the service, of the surrounding docker container and the versions of the workflow image used to execute runs.

Status Codes:

  • 200 OK – The version information from the operated service

GET /api/v1/service/oss/sources#

Returns a list of oss components for which the licenses requires source code to be distributed

Status Codes:

  • 200 OK – A list of oss component names for which source code is available

GET /api/v1/service/oss/sources/{name}#

Return the source code of the requested oss component as zip file

Parameters:

  • name (string)

Status Codes:

  • 200 OK – The sources as zipped stream

  • 404 Not Found – The component requested with the given name is not found, perhaps no source code needs to be distributed or the component is not used at all

GET /api/v1/service/oss/sbom#

Returns an sbom referencing all oss components used in the service with the necessary attribution data

Status Codes:

  • 200 OK – CycloneDX SBOM as application/octet-stream

Info about authentication and authorization configuration#

GET /api/v1/service/authinfo#

Retrieve the .well-known configuration URL of the OpenID Connect endpoints

Status Codes:

  • 200 OK – The .well-known configuration URL of the OpenID Connect endpoints

Tokens#

GET /api/v1/long-running-tokens#

Retrieve meta data about all the tokens of the calling user

The response does not contain the token values as the service does not know the values.

Query Parameters:

  • page (integer) – The requested page of the list of existing resources

  • items (integer) – The amount of items on the page

  • sortOrder (string) – Sort order of the returned objects, must be one of ASC,DESC

Status Codes:
POST /api/v1/long-running-tokens#

Create a new token

The new token is active.

Status Codes:
GET /api/v1/long-running-tokens/{id}#

Retrieve meta data about a token

The response does not contain the token value as the service does not know the value.

Parameters:

  • id (number)

Status Codes:
POST /api/v1/long-running-tokens/{id}/revoke#

Revoke an existing token

The token is revoked and can never be used again.

Parameters:

  • id (number)

Status Codes: