Skip to main content
API docs by Redocly

Control Plane API (1.0.0)

The Control Plane API is a set of endpoints for managing the registration of Technology Adapters, generating descriptors from uploaded archives, and starting and monitoring template instantiations.

Base URL

The Witboost URL is the instance URL that you visit in the browser to access the Witboost UI. Therefore, the base URL of the API will depend on your deployment. Below, we are providing an example base URL, yours may differ.

Builder

Endpoints for managing the registration of Technology Adapters, generating descriptors from uploaded archives, and starting and monitoring template instantiations.

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

Create a Feature Request

Submits a new Feature Request against a System or a specific Component.

Requires the control-plane.feature-request.create RBAC permission scoped to the target System's URN. Accepts multipart/form-data to support binary file attachments (PDF, JPG, PNG; max 5 files, 10 MB each).

Both projectUrn and componentUrn (when provided) are validated:

  • Format: must be a valid Witboost URN (urn:dmb:<kind>:<domain>:<name>:<version>[:<component>[:<subcomponent>]]).
  • Existence: the referenced entity must exist in the Witboost catalog.
  • Hierarchy (componentUrn only): the component must belong to the system identified by projectUrn.
Request Body schema: multipart/form-data
required
summary
required
string <= 500 characters

Short title describing the request

description
required
string <= 10000 characters

Detailed description of the requested feature or improvement

priority
required
string
Enum: "LOW" "MEDIUM" "HIGH" "CRITICAL"

Caller-assigned priority level

projectUrn
required
string

URN of the target System. Must be a valid Witboost URN referencing an existing entity in the catalog. Format: urn:dmb:<kind>:<domain>:<name>:<version>

componentUrn
string

URN of the target Component (optional). When provided, must be a valid Witboost URN referencing an existing component that belongs to the system identified by projectUrn. Format: urn:dmb:cmp:<domain>:<name>:<version>:<component>

string or Array of strings

Binary file uploads. Only PDF, JPG, and PNG allowed. Max 5 files, 10 MB each.

Responses

Response samples

Content type
application/json
{
  • "id": "aaaaaaaa-0000-0000-0000-000000000001",
  • "summary": "Add export feature",
  • "description": "Allow users to export data as CSV",
  • "status": "SUBMITTED",
  • "priority": "MEDIUM",
  • "projectUrn": "urn:dmb:dp:finance:cashflow:0",
  • "componentUrn": null,
  • "requesterRef": "user:default/alice",
  • "createdAt": "2026-06-01T10:00:00.000Z",
  • "createdBy": "user:default/alice",
  • "updatedAt": "2026-06-01T10:00:00.000Z",
  • "updatedBy": "user:default/alice",
  • "attachments": [ ]
}

List Feature Requests for a System

Returns a paginated list of Feature Requests for the specified System.

The caller must be the Data Product Owner (or owner delegate) of the System, resolved via Team Roles. Service principals bypass the ownership check.

The projectUrn query parameter is required and must be a valid Witboost URN. Optional filters (componentUrn, status, priority) and pagination (offset, limit) are supported.

query Parameters
projectUrn
required
string
Example: projectUrn=urn:dmb:dp:finance:cashflow:0

URN of the System. Must be a valid Witboost URN. Format: urn:dmb:<kind>:<domain>:<name>:<version>

componentUrn
string
Example: componentUrn=urn:dmb:cmp:finance:cashflow:0:storage

Narrow results to requests targeting a specific Component. Must be a valid Witboost URN when provided. Format: urn:dmb:cmp:<domain>:<name>:<version>:<component>

status
string
Enum: "SUBMITTED" "APPROVED" "IN_PROGRESS" "IMPLEMENTED" "REJECTED"

Filter by status

priority
string
Enum: "LOW" "MEDIUM" "HIGH" "CRITICAL"

Filter by priority

offset
integer >= 0
Default: 0

Pagination offset (zero-based)

limit
integer [ 1 .. 100 ]
Default: 20

Page size (1–100)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 1,
  • "offset": 0,
  • "limit": 20
}

List Feature Requests submitted by the authenticated caller

Returns a paginated list of Feature Requests submitted by the currently authenticated user.

Results are implicitly scoped to the caller's identity — no additional authorization is required beyond a valid session. Optional filters (projectUrn, status, priority) and pagination (offset, limit) are supported.

query Parameters
projectUrn
string
Example: projectUrn=urn:dmb:dp:finance:cashflow:0

Filter by System URN

status
string
Enum: "SUBMITTED" "APPROVED" "IN_PROGRESS" "IMPLEMENTED" "REJECTED"

Filter by status

priority
string
Enum: "LOW" "MEDIUM" "HIGH" "CRITICAL"

Filter by priority

offset
integer >= 0
Default: 0

Pagination offset (zero-based)

limit
integer [ 1 .. 100 ]
Default: 20

Page size (1–100)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "offset": 0,
  • "limit": 0
}

Retrieve full Feature Request details

Returns the full details of a Feature Request including its description and attachment metadata (without binary content).

Accessible to:

  • The Data Product Owner (or owner delegate) of the associated System
  • The original requester who submitted the Feature Request
  • Service principals
path Parameters
id
required
string <uuid>

Feature Request ID

Responses

Response samples

Content type
application/json
{
  • "id": "aaaaaaaa-0000-0000-0000-000000000001",
  • "summary": "Add export feature",
  • "description": "Allow users to export data as CSV",
  • "status": "SUBMITTED",
  • "priority": "MEDIUM",
  • "projectUrn": "urn:dmb:dp:finance:cashflow:0",
  • "componentUrn": null,
  • "requesterRef": "user:default/alice",
  • "createdAt": "2026-06-01T10:00:00.000Z",
  • "createdBy": "user:default/alice",
  • "updatedAt": "2026-06-01T10:00:00.000Z",
  • "updatedBy": "user:default/alice",
  • "attachments": [
    ]
}

Delete a Feature Request

Permanently deletes a Feature Request and all its associated attachments.

Restricted to the original requester who submitted the Feature Request. Service principals bypass the ownership check.

path Parameters
id
required
string <uuid>

Feature Request ID

Responses

Response samples

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

Update the status of a Feature Request

Updates the status of a Feature Request to any valid value. No transition restrictions are enforced — any status can be set regardless of the current status.

Restricted to:

  • The Data Product Owner (or owner delegate) of the associated System
  • Service principals
path Parameters
id
required
string <uuid>

Feature Request ID

Request Body schema: application/json
required
status
required
string
Enum: "SUBMITTED" "APPROVED" "IN_PROGRESS" "IMPLEMENTED" "REJECTED"

The new status to set

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "aaaaaaaa-0000-0000-0000-000000000001",
  • "summary": "Add export feature",
  • "status": "APPROVED",
  • "priority": "MEDIUM",
  • "projectUrn": "urn:dmb:dp:finance:cashflow:0",
  • "componentUrn": null,
  • "requesterRef": "user:default/alice",
  • "createdAt": "2026-06-01T10:00:00.000Z",
  • "createdBy": "user:default/alice",
  • "updatedAt": "2026-06-03T14:30:00.000Z",
  • "updatedBy": "user:default/owner"
}

Download a Feature Request attachment

Returns the binary content of a single attachment with the correct Content-Type and Content-Disposition headers set for browser download.

Accessible to:

  • The Data Product Owner (or owner delegate) of the associated System
  • The original requester who submitted the Feature Request
  • Service principals
path Parameters
id
required
string <uuid>

Feature Request ID

attachmentId
required
string <uuid>

Attachment ID (from the attachments array in the Feature Request detail)

Responses

Response samples

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

Hooks

Endpoint for updating the status of a hook, which is used to model third-party approval workflows in Witboost, such as Access Control requests.

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