Skip to main content
API docs by Redocly

Builder API (1.0.0)

APIs for registering Technology Adapters, generating descriptors from uploaded archives, and starting and monitoring template instantiations.

Builder

Register a Tech Adapter

This endpoint is used to register the Technology Adapter's URL and link it to the infrastructureTemplateId.

After deploying a new Technology Adapter into the infrastructure, all the components with a your chosen infrastructureTemplateId should invoke said microservice.

To do so, we need to link the infrastructureTemplateId with the Technology Adapter's URL where the microservice is located. Make sure the URL is reachable by the Witboost platform.

Request Body schema: application/json
required
id
required
string

Unique identifier of the Technology Adapter, in the form of a Witboost's URN, like "urn:dmb:itm:snowflake-outputport-provisioner:0"

name
required
string

Name of the Technology Adapter, like "Snowflake Output Port"

description
required
string

A description that explains the purpose of the Technology Adapter

version
required
string

The Technology Adapter's version, like "0". This version must be ALWAYS equal to the version defined in the URN identifier (the last section of the URN identifier after the last ":")

url
required
string

The URL of the Technology Adapter, like "http://my-tech-adapter:8093/snowflake-outputport-provisioner". This URL must be reachable from the provisioning coordinator (from a pod in the Kubernetes cluster where the provisioning coordinator is running)

environment
required
string

The environment where the Technology Adapter is running, like "production". The environment here must be one of the environments configured for the Builder module of Witboost.

object (InfraTemplateProperties)

Additional infrastructure template properties

Responses

Request samples

Content type
application/json
Example
{}

Response samples

Content type
application/json
"OK"

Get descriptor files info

Returns the list of files/folders expected by the descriptor generation flow.

Responses

Response samples

Content type
application/json
{
  • "files": [
    ]
}

Build descriptor from files archive

Builds a single descriptor by processing an uploaded archive containing one or more entity directories.

The archive must be in .tar.gz or .tgz format. Each top-level directory in the archive represents one entity and must include a catalog-info.yaml file. It can also optionally include:

  • parameters.yaml
  • environments/<environment>/configurations.yaml

The processing flow unpacks all directories, resolves each entity's descriptor from its catalog-info.yaml, distinguishes between system and component descriptors, then merges all component descriptors into the system descriptor, which acts as the root.

Note: The archive is expected to contain exactly one system directory. If multiple system directories are present, only the first one will be used and the others will be ignored.

Request Body schema: multipart/form-data
required
archive
required
string <binary>

Archive file containing descriptor source files (.tar.gz or .tgz)

environment
required
string

Target environment used to resolve environment-specific configurations

Responses

Request samples

Content type
multipart/form-data
{
  "environment": "development"
}

Response samples

Content type
application/json
{
  • "descriptor": {
    }
}

Instantiate a template

Starts a new template instantiation asynchronously. The endpoint returns the created task identifier.

See the Template page for a step-by-step guide.

Request Body schema: application/json
required
templateRef
required
string

Entity reference of the template to instantiate

required
object

Input values for template parameters

object

Optional environment-scoped parameter overrides

Responses

Request samples

Content type
application/json
Example
{
  • "templateRef": "template:default/my-data-product-template",
  • "values": {
    }
}

Response samples

Content type
application/json
{
  • "id": "2f4b7a6f-6d2e-4a22-a912-cce8f90b3843"
}

Stream template instatiation events

Opens a Server-Sent Events (SSE) stream for a template instantiation task.

Events are emitted as event: <type> and data: <json> records. Supported event types include log, recovered, cancelled, and completion.

See the Template page for a step-by-step guide.

path Parameters
taskId
required
string

The template instantiation task identifier

Responses

Response samples

Content type
text/event-stream
event: log
data: {"message":"Starting template execution","createdAt":"2026-01-01T10:00:00.000Z"}

event: completion
data: {"message":"Task completed","createdAt":"2026-01-01T10:00:10.000Z"}

Get template instantiation status

Returns the latest status for a template instantiation task.

See the Template page for a step-by-step guide.

path Parameters
taskId
required
string

The template instantiation task identifier

Responses

Response samples

Content type
application/json
Example
{
  • "status": "open"
}

Update the status of a hook

Witboost Hooks model third-party approval workflows.

Hooks are used, for instance, to model the Access Control workflow, where an Data Consumer asks access to a Data Owner. In case an Access Control request is forwarded to third-party ticketing systems, this endpoint helps Witboost understand whether the request is still pending, completed or rejected/failed.

In general, outside of the Access Control workflow, this endpoint is used to update the status of a hook, so that the Witboost platform knows how to proceed with a pending request.

path Parameters
id
required
string

Request ID as provided by the Witboost platform in the respondToUrl field.

Request Body schema: application/json
required

A resource to be evaluated

One of
status
required
string (RequestedHookState)
Enum: "KO" "OK"

Represents the desired state of the hook. OK means the third-party interaction has been completed with a positive result, KO on the other hand can be used to represent a negative result. If the hook is attached to an action, signaling KO could prevent the action's callback to be invoked

hookInfo
object

A free-form object that will be stored as the hook's response data

Responses

Request samples

Content type
application/json
Example
{
  • "status": "OK",
  • "hookInfo": {
    }
}

Response samples

Content type
application/json
Example
{
  • "hookId": "34797dd1-1f25-48b0-89c7-14d2ce04a78b",
  • "hookName": "RemoteRequestHook",
  • "actionId": "0298b78f-4d77-45f7-a7a4-f16278144141",
  • "actionName": "AccessControlAction",
  • "creationAt": "2021-09-01T12:00:00Z",
  • "updateAt": "2021-09-01T12:00:00Z",
  • "status": "OK"
}