Builder API

note

Read this page in wide view mode from here

• Builder
  • postRegister a Tech Adapter
  • getGet descriptor files info
  • postBuild descriptor from files archive
  • postInstantiate a template
  • getStream template instatiation events
  • getGet template instantiation status
  • patchUpdate the status of a hook

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

https://docs.witboost.com/api/builder/register

Request samples

• Payload

Content type

application/json

Example

Snowflake Output PortData Contract GuardianSnowflake Output Port

{

• "id": "urn:dmb:itm:snowflake-outputport-provisioner:0",
• "name": "Snowflake Output Port",
• "description": "Provisions a Snowflake Output Port",
• "version": "0",
• "url": "http://my-tech-adapter:8093/snowflake-outputport-provisioner",
• "environment": "production"

}

Response samples

• 200
• 500

Content type

application/json

"OK"

Get descriptor files info

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

Responses

https://docs.witboost.com/api/builder/v1/entities/descriptor/from-files/info

Response samples

• 200
• 500

Content type

application/json

{

• "files": [

  • "catalog-info.yaml",
  • "environments",
  • "parameters.yaml"

  ]

}

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

https://docs.witboost.com/api/builder/v1/entities/descriptor/from-files

Request samples

• Payload

Content type

multipart/form-data

{
  "environment": "development"
}

Response samples

• 200
• 400
• 500

Content type

application/json

{

• "descriptor": {

  • "projectKind": "system",
  • "dataProductOwner": "group:default/data-team",
  • "domain": "finance",
  • "kind": "System",
  • "metadata": {

    • "name": "my-data-product"

    }

  }

}

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

https://docs.witboost.com/api/builder/v1/templates/instantiation

Request samples

• Payload

Content type

application/json

Example

minimalwithEnvironmentParametersminimal

{

• "templateRef": "template:default/my-data-product-template",
• "values": {

  • "name": "my-data-product",
  • "owner": "group:default/data-team"

  }

}

Response samples

• 200
• 400
• 500

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

https://docs.witboost.com/api/builder/v1/templates/instantiation/{taskId}/stream

Response samples

• 200
• 500

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

https://docs.witboost.com/api/builder/v1/templates/instantiation/{taskId}/status

Response samples

• 200
• 500

Content type

application/json

Example

opencompletedopen

{

• "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

https://docs.witboost.com/api/actionHandler/hooks/{id}

Request samples

• Payload

Content type

application/json

Example

acceptrejectacceptWithTrackingaccept

{

• "status": "OK",
• "hookInfo": {

  • "message": "The request has been accepted on the external system"

  }

}

Response samples

• 200
• 404
• 409
• 500

Content type

application/json

Example

acceptedrejectedaccepted

{

• "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"

}