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.

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