Labels

The /labels endpoint provides read-only access to label definitions. Labels are used to categorize and tag instances. They can be defined at three levels: global (no project or pattern scope), project-level, or pattern-level.

See Also

• Authentication — Required for all API requests
• Definition of Labels — Administering labels
• Labels (Patterns) — Pattern-level label configuration
• Project level labels — Project-level label configuration
• Instances API — Instance metadata with labels

GET /api/v1/labels — Find Labels

Retrieve a list of labels, optionally filtered by project, pattern, name, or color.

Endpoint

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

Query Parameters

Parameter	Type	Required	Description
project	string	No	Filter by project name.
project_id	integer	No	Filter by project ID.
pattern	string	No	Filter by pattern name.
pattern_id	integer	No	Filter by pattern ID.
name	string	No	Filter by label name.
color	string	No	Filter by label color (e.g. red, blue, green).

Response Schema

Returns an array of label objects:

Field	Type	Description
id	integer	Unique label ID.
project_id	integer	Project ID (null for global labels).
pattern_id	integer	Pattern ID (null for project-level or global labels).
name	string	Label name.
color	string	Label color.

Label Scopes

Labels are hierarchical and can be defined at different scopes:

Scope	project_id	pattern_id	Description
Global	null	null	Available across all projects and patterns.
Project	set	null	Available for all patterns within a specific project.
Pattern	set	set	Available only for instances of a specific pattern in a project.

Examples

cURL

# List all labels
curl -X GET "https://app.metakraftwerk.com/api/v1/labels" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

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

# Find by pattern
curl -X GET "https://app.metakraftwerk.com/api/v1/labels?pattern=CORE_DV_HLS" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Find by name
curl -X GET "https://app.metakraftwerk.com/api/v1/labels?name=NEEDS_FIX" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Find by color
curl -X GET "https://app.metakraftwerk.com/api/v1/labels?color=red" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

JavaScript (Fetch)

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

const labels = await response.json();

Response Example

[
  {
    "id": 64,
    "project_id": 402,
    "pattern_id": null,
    "name": "NEEDS_FIX",
    "color": "red"
  }
]

Error Responses

Status	Condition	Example Message
401	Missing or invalid token	Not authenticated
404	Project not found	A project with the name 'X' does not exist!
404	Pattern not found	A pattern with the name 'X' does not exist!

---

GET /api/v1/labels/:id — Get Label

Retrieve a single label by its ID.

Endpoint

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

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	The label ID.

Examples

cURL

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

JavaScript (Fetch)

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

const label = await response.json();

Error Responses

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

---

POST /api/v1/labels — Create

Not implemented

PUT /api/v1/labels — Update

Not implemented

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

Not implemented

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

Not implemented