Build Deployments

The /build_deployments endpoint allows you to list and trigger deployments for specific builds. A build deployment executes a deployment definition against the artifacts produced by a build, delivering results to a target environment.

See Also

• Authentication — Required for all API requests
• Builds API — Trigger and monitor builds
• Deployments API — Deployment definitions
• Deployment Guide — Guide to deployment types and workflows
• API Deployment — API-based deployment guide

GET /api/v1/build_deployments — Find Build Deployments

Retrieve a list of build deployments matching the specified filter criteria.

Endpoint

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

Query Parameters

Parameter	Type	Required	Description
build_id	integer	No	Filter by build ID.
pattern	string	No	Filter by pattern name.
pattern_id	integer	No	Filter by pattern ID.
deployment	string	No	Filter by deployment name.
deployment_id	integer	No	Filter by deployment ID.

Response Schema

Returns an array of build deployment objects:

Field	Type	Description
id	integer	Unique build deployment ID.
build_id	integer	Associated build ID.
pattern_id	integer	Associated pattern ID.
deployment_id	integer	Associated deployment definition ID.
upload_id	integer	Associated upload ID.
agent_id	integer	Agent ID assigned to execute the deployment.
agent_group_id	integer	Agent group ID assigned to execute the deployment.

Examples

cURL

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

JavaScript (Fetch)

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

const buildDeployments = await response.json();

Error Responses

Status	Condition	Example Message
401	Missing or invalid token	Not authenticated

---

GET /api/v1/build_deployments/:id — Get Build Deployment

Retrieve a single build deployment by its ID.

Endpoint

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

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	The build deployment ID.

Examples

cURL

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

JavaScript (Fetch)

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

const buildDeployment = await response.json();

Error Responses

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

---

POST /api/v1/build_deployments — Create Build Deployment

Trigger a deployment for a specific build. This executes a deployment definition against the build artifacts.

Endpoint

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

Request Headers

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

Request Body

Field	Type	Required	Description
build_id	integer	Yes	The build ID to deploy.
pattern	string	Yes*	Pattern name. Mutually exclusive with pattern_id.
pattern_id	integer	Yes*	Pattern ID. Mutually exclusive with pattern.
deployment	string	Yes†	Deployment name. Mutually exclusive with deployment_id.
deployment_id	integer	Yes†	Deployment ID. Mutually exclusive with deployment.
agent	string	No‡	Agent name to execute the deployment.
agent_id	integer	No‡	Agent ID to execute the deployment.
agent_group	string	No‡	Agent group name. Any available agent in the group will execute the deployment.
agent_group_id	integer	No‡	Agent group ID.

TIP

* Exactly one of pattern or pattern_id is required.

† Exactly one of deployment or deployment_id is required.

‡ Specify either a specific agent (agent/agent_id) or an agent group (agent_group/agent_group_id), or neither to use the default assignment.

Examples

cURL

curl -X POST "https://app.metakraftwerk.com/api/v1/build_deployments" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "build_id": 5139,
    "pattern": "CORE_DV_HLS",
    "deployment": "DEPLOY_TO_DEV",
    "agent_group": "DEV_AGENTS"
  }'

JavaScript (Fetch)

const response = await fetch('https://app.metakraftwerk.com/api/v1/build_deployments', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    build_id: 5139,
    pattern: 'CORE_DV_HLS',
    deployment: 'DEPLOY_TO_DEV',
    agent_group: 'DEV_AGENTS'
  })
});

const result = await response.json();

Error Responses

Status	Condition	Example Message
400	Missing required fields	A build_id is required!
401	Missing or invalid token	Not authenticated
404	Build not found	Build not found
404	Deployment not found	A deployment with the name 'X' does not exist!

---

PUT /api/v1/build_deployments — Update

Not implemented

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

Not implemented

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

Not implemented