Builds

The /builds endpoint allows you to list existing builds and trigger new build executions. A build generates executable process instances (e.g. Informatica mappings, DDL statements) from patterns and instance metadata.

See Also

• Authentication — Required for all API requests
• Build — Web UI reference for builds
• Start of a new build — Starting builds via the web interface
• Download of the build results — Downloading build artifacts
• Downloads API — Programmatic download of build result files
• Build Deployments API — Deploying build results

GET /api/v1/builds — Find Builds

Retrieve a list of builds matching the specified filter criteria.

Endpoint

GET https://app.metakraftwerk.com/api/v1/builds

Query Parameters

Parameter	Type	Required	Description
project	string	No	Filter by project name.
project_id	integer	No	Filter by project ID.
user	string	No	Filter by username who started the build.
user_id	integer	No	Filter by user ID who started the build.
pattern	string	No	Filter by pattern name.
pattern_id	integer	No	Filter by pattern ID.
releases	object	No	JSON object mapping release group names to release names (e.g. {"DWH_GROUP": "R1"}).

Response Schema

Returns an array of build objects:

Field	Type	Description
id	integer	Unique build ID.
customer_id	integer	Customer ID.
user_id	integer	User ID who started the build.
project_id	integer	Project ID.
progress	integer	Build progress percentage (0–100).
status	string	Build status: BUILDING, FINISHED, FAILED, CANCELED.
message	string	Current status message.
build_start	string	ISO 8601 timestamp of build start.
build_end	string	ISO 8601 timestamp of build completion.
created_at	string	ISO 8601 timestamp of build creation.
updated_at	string	ISO 8601 timestamp of last update.
history_commited	integer	Whether the history has been committed.
version	integer	Build version.
active	integer	Whether the build is active.
mts	integer	Internal timestamp.
name	string	Build name.
deliveries_calculated	integer	Whether deliveries have been calculated.
description	string	Build description.
commit_ind	integer	Commit indicator.
deleted	integer	Whether the build is deleted.
instances	integer	Number of instances in the build.
patterns	integer[]	Array of pattern IDs included in the build.
releases	integer[]	Array of release IDs included in the build.
downloads	object[]	Array of download objects (see Downloads).

Examples

cURL

curl -X GET "https://app.metakraftwerk.com/api/v1/builds?project=DEMO_PROJECT" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

JavaScript (Fetch)

const response = await fetch(
  'https://app.metakraftwerk.com/api/v1/builds?project=DEMO_PROJECT',
  { headers: { 'Authorization': `Bearer ${accessToken}` } }
);

const builds = await response.json();

Error Responses

Status	Condition	Example Message
401	Missing or invalid token	Not authenticated
403	User lacks project access	You don't have permissions to access this project!
404	Project not found	A project with the name 'X' does not exist!

---

GET /api/v1/builds/:id — Get Build

Retrieve a single build by its ID, including download links if the build has finished.

Endpoint

GET https://app.metakraftwerk.com/api/v1/builds/:id

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	The build ID.

Response Schema

Returns a single build object with the same schema as the find response. If the build has finished, the downloads array contains the generated files.

Examples

cURL

curl -X GET "https://app.metakraftwerk.com/api/v1/builds/5139" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

JavaScript (Fetch)

const response = await fetch(
  'https://app.metakraftwerk.com/api/v1/builds/5139',
  { headers: { 'Authorization': `Bearer ${accessToken}` } }
);

const build = await response.json();

Error Responses

Status	Condition	Example Message
401	Missing or invalid token	Not authenticated
404	Build not found	No record found for id 'X'

---

POST /api/v1/builds — Create Build

Start a new build for one or more instances.

Endpoint

POST https://app.metakraftwerk.com/api/v1/builds

Authentication

The authenticated user must have write_builds permission on the target project.

Request Headers

Header	Value
Content-Type	application/json
Authorization	Bearer <ACCESS_TOKEN>

Request Body

Field	Type	Required	Description
project	string	Yes*	Project name. Mutually exclusive with project_id.
project_id	integer	Yes*	Project ID. Mutually exclusive with project.
instances	object[]	Yes	Array of instance definitions to build.
releases	object	No	Object mapping release group names to release names (e.g. {"DWH_GROUP": "R1"}).
description	string	No	Description for the build.
wait	boolean	No	When true, the request blocks until the build completes and returns the full result with downloads. Defaults to false.
restore	boolean	No	When true, restores deleted instances before building. Defaults to false.

TIP

* Exactly one of project or project_id is required.

Instance Definition

Each entry in the instances array can be specified in two ways:

By ID:

Field	Type	Description
id	integer	Instance ID.

By name:

Field	Type	Description
pattern	string	Pattern name.
folder	string	Folder path (e.g. /BUSINESS_VAULT).
name	string	Instance name.

By name pattern (*):

You can pass the literal string "*" as name to dynamically resolve the build set instead of listing every instance by hand. The build service expands a * entry into one entry per matching instance by calling the find endpoint of the instances API internally. pattern and folder are still required on the entry — they constrain the lookup to one folder of one pattern. To match across several folders, add one * entry per folder.

In addition to pattern, folder and name, the entry can carry any of the filter fields below. They are forwarded to the instances find endpoint as query parameters. See the instance filter parameters for the full semantics of each.

Field	Type	Description
pattern	string	Required. Pattern name.
folder	string	Required. Folder path (e.g. /BUSINESS_VAULT).
name	string	Required. Must be "*" to enable expansion.
checked_out	boolean	Restrict to checked-out (true) or checked-in (false) instances.
checked_out_by_user_id	integer	Together with checked_out=true, restrict to instances locked by this user id.
checked_out_by_user	string	Together with checked_out=true, restrict to instances locked by this user name.
deleted	boolean	true matches soft-deleted instances; false matches non-deleted instances. Combine with the top-level restore: true to also build deleted instances.
labels	string[]	Match instances that carry at least one of the given label names.
upload_disabled	boolean	Filter by the upload-disabled flag.
insert_disabled	boolean	Filter by the insert-disabled flag.
edit_disabled	boolean	Filter by the edit-disabled flag.

The lookup is always constrained to:

• the project the build is started in (taken from the top-level project / project_id),
• the releases you passed at the top level (so the asterisk only resolves instances that exist in those releases),
• invalid: false — instances with validation errors are never expanded into the build set,
• build_disabled: false — instances whose build is disabled are skipped (they could not be built anyway).

These four constraints are not user-overridable.

TIP

The * shortcut is purely a convenience. It is fully equivalent to first calling GET /api/v1/instances with the same filters, collecting the resulting (pattern, folder, name) triples, and passing them as explicit By name entries. Use it when the build set should be derived dynamically — for example "build every checked-out instance with the ready label".

Example: build every checked-out instance with a label

{
  "project": "DEMO_PROJECT",
  "releases": { "DWH_GROUP": "R1" },
  "instances": [
    {
      "pattern": "CORE_DV_HLS",
      "folder": "/BUSINESS_VAULT",
      "name": "*",
      "checked_out": true,
      "labels": ["ready"]
    }
  ]
}

Example: combine * with explicit entries

{
  "project": "DEMO_PROJECT",
  "releases": { "DWH_GROUP": "R1" },
  "instances": [
    { "id": 4711 },
    { "pattern": "FACT", "folder": "/STG", "name": "ORDERS" },
    { "pattern": "DIM",  "folder": "/LDG", "name": "*", "labels": ["ready"] }
  ]
}

Response Schema

Field	Type	Description
build	object	The created build object.
build.id	integer	Build ID.
build.status	string	Build status (BUILDING or FINISHED if wait=true).
build.progress	integer	Build progress (0–100).
build.downloads	object[]	Array of download objects (only populated when wait=true and status is FINISHED).
build.downloads[].id	integer	Download ID. Use with the Downloads API to retrieve the file.
build.downloads[].pattern	string	Pattern name.
build.downloads[].pattern_id	integer	Pattern ID.
build.downloads[].name	string	File name.
warnings	string[]	Array of warning messages (e.g. missing releases).

Examples

cURL

curl -X POST "https://app.metakraftwerk.com/api/v1/builds" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "DEMO_PROJECT",
    "releases": { "DWH_GROUP": "R1" },
    "instances": [
      { "pattern": "CORE_DV_HLS", "folder": "/BUSINESS_VAULT", "name": "AIRPLANE" }
    ],
    "description": "build via rest api",
    "wait": true,
    "restore": true
  }'

JavaScript (Fetch)

const response = await fetch('https://app.metakraftwerk.com/api/v1/builds', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    project: 'DEMO_PROJECT',
    releases: { DWH_GROUP: 'R1' },
    instances: [
      { pattern: 'CORE_DV_HLS', folder: '/BUSINESS_VAULT', name: 'AIRPLANE' }
    ],
    description: 'build via rest api',
    wait: true,
    restore: true
  })
});

const result = await response.json();

Response Example (wait: true)

{
  "build": {
    "id": 5139,
    "customer_id": 1,
    "user_id": 1,
    "project_id": 402,
    "progress": 100,
    "status": "FINISHED",
    "message": "calculating deliveries ...",
    "build_start": "2026-04-02T08:14:40.320Z",
    "build_end": "2026-04-02T08:14:58.898Z",
    "created_at": "2026-04-02T08:14:40.320Z",
    "updated_at": "2026-04-02T08:14:58.898Z",
    "history_commited": 1,
    "version": 10,
    "active": 1,
    "mts": 1775124880390,
    "name": null,
    "deliveries_calculated": 1,
    "description": "build via rest api",
    "commit_ind": 0,
    "deleted": 0,
    "instances": 1,
    "patterns": [808],
    "releases": [21],
    "downloads": [
      {
        "id": 5442,
        "pattern": "CORE_DV_HLS",
        "pattern_id": 808,
        "file_id": null,
        "name": "CORE_DV_HLS_2026-4-2_10_14.zip"
      }
    ]
  },
  "warnings": []
}

Response Example (wait: false)

When wait is false or omitted, the build starts asynchronously and the response returns immediately:

{
  "build": {
    "id": 5139,
    "status": "BUILDING"
  },
  "warnings": []
}

You can poll the build status using GET /api/v1/builds/:id until the status changes to FINISHED.

Error Responses

Status	Condition	Example Message
400	Missing required fields	A project id or name is required!
400	No instances specified	No instances specified!
401	Missing or invalid token	Not authenticated
403	User lacks project access	You don't have permissions to access this project!
403	User lacks build permission	You don't have permissions to start builds in this project!
404	Project not found	A project with the name 'X' does not exist!
404	Instance not found	Instance not found

Build Workflow

The typical workflow for creating a build and retrieving results is:

1. Start the build — POST /api/v1/builds with wait: true (synchronous) or wait: false (asynchronous).
2. Poll for completion (async only) — GET /api/v1/builds/:id until status is FINISHED.
3. List downloads — The downloads array in the build response contains the generated files.
4. Download files — Use GET /api/v1/downloads/:id to download each file.

WARNING

Long-running builds with wait: true may time out depending on your HTTP client configuration. For large builds, consider using wait: false and polling for status.

---

PUT /api/v1/builds — Update

Not implemented

PATCH /api/v1/builds/:id — Patch

Not implemented

DELETE /api/v1/builds/:id — Remove

Not implemented