Instances

The /instances endpoint allows you to list, retrieve, and upload instance metadata. Instances represent sets of metadata for specific data objects or processes within a project, organized by pattern and folder.

See Also

• Authentication — Required for all API requests
• Instances — Web UI reference for instances
• Upload of Instance Data — Uploading instance data via the web interface
• Download of Instance Data — Downloading instance data
• Instance Metadata — Guide to instance metadata concepts
• Filtering of Instances — Filtering instances in the web UI

GET /api/v1/instances — Find Instances

Retrieve a list of instances matching the specified filter criteria.

Endpoint

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

Query Parameters

Parameter	Type	Required	Description
project	string	Yes*	Project name. Mutually exclusive with project_id.
project_id	integer	Yes*	Project ID. Mutually exclusive with project.
pattern	string	No	Filter by pattern name.
pattern_id	integer	No	Filter by pattern ID.
folder	string	No	Filter by folder path (e.g. /RAW_VAULT).
name	string	No	Filter by instance name.
releases	object	No	JSON object mapping release group names to release names (e.g. {"DWH_GROUP": "R1"}).
checked_out	boolean	No	Filter by checkout status.
checked_out_by_user_id	integer	No	Filter by the user ID who checked out the instance.
checked_out_by_user	string	No	Filter by the username who checked out the instance.
deleted	boolean	No	Filter by deletion status.
upload_disabled	boolean	No	Filter by upload-disabled flag.
insert_disabled	boolean	No	Filter by insert-disabled flag.
build_disabled	boolean	No	Filter by build-disabled flag.
edit_disabled	boolean	No	Filter by edit-disabled flag.
invalid	boolean	No	Filter by validation status.

TIP

* Exactly one of project or project_id is required.

Response Schema

Field	Type	Description
id	integer	Unique instance ID.
customer_id	integer	Customer ID.
name	string	Instance name.
project_id	integer	Project ID.
pattern_id	integer	Pattern ID.
errors	integer	Number of validation errors.
instance_folder_id	integer	Folder ID.
version	integer	Current version number.
description	string	Instance description.
release_id	integer	Release ID.
identity_id	integer	Identity ID for version tracking.
user_id	integer	Owner user ID.
latest_commit_id	integer	ID of the latest commit.
labels	string[]	Array of label names attached to the instance.
checked_out	boolean	Whether the instance is checked out.
deleted	boolean	Whether the instance is marked as deleted.
upload_disabled	boolean	Whether upload is disabled.
insert_disabled	boolean	Whether insert is disabled.
build_disabled	boolean	Whether build is disabled.
edit_disabled	boolean	Whether editing is disabled.
invalid	boolean	Whether the instance has validation errors.
folder	string	Computed folder path (e.g. /RAW_VAULT).

Examples

cURL

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

JavaScript (Fetch)

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

const instances = await response.json();

Response Example

[
  {
    "id": 5567,
    "customer_id": 1,
    "name": "AIRLINE",
    "project_id": 402,
    "pattern_id": 808,
    "errors": 0,
    "instance_folder_id": 902,
    "version": 9,
    "description": null,
    "release_id": 21,
    "identity_id": 3326,
    "user_id": 1,
    "latest_commit_id": 15720,
    "labels": [
      "DEPRECATED"
    ],
    "checked_out": false,
    "deleted": false,
    "upload_disabled": false,
    "insert_disabled": false,
    "build_disabled": false,
    "edit_disabled": false,
    "invalid": false,
    "folder": "/RAW_VAULT"
  }
]

Error Responses

Status	Condition	Example Message
400	Missing project parameter	A project id or name is required!
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/instances/:id — Get Instance

Retrieve a single instance by its ID. Supports JSON and Excel export formats.

Endpoint

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

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	The instance ID.

Content Negotiation

The response format depends on the Accept header:

Accept Header	Response Format
application/json (default)	JSON object with instance metadata including header and field details.
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet	Excel workbook (.xlsx) file download.

Response Schema (JSON)

Field	Type	Description
instance_id	integer	Instance ID.
instance_name	string	Instance name.
project_name	string	Project name.
pattern_name	string	Pattern name.
folder	string	Folder path.
header	string[]	Array of column names for the field details.
field_details	object[]	Array of metadata rows with properties and functional roles.

Examples

cURL (JSON)

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

cURL (Excel Download)

curl -X GET "https://app.metakraftwerk.com/api/v1/instances/5567" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" \
  -OJ

JavaScript (Fetch)

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

const instance = await response.json();

Error Responses

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

---

POST /api/v1/instances — Upload Instances

Upload an Excel file to bulk-create or update instances for a given pattern.

Endpoint

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

Authentication

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

Request

The request must be sent as multipart/form-data with exactly one file upload and the form fields described below.

Form Fields

Field	Type	Required	Description
file	File	Yes	An .xlsx Excel workbook containing the instance data to import. Each row must have at minimum an INSTANCE column.
project	string	Yes*	Name of the target project. Mutually exclusive with project_id.
project_id	integer	Yes*	ID of the target project. Mutually exclusive with project.
pattern	string	No	Pattern name to apply to all rows. Overrides any PATTERN column in the spreadsheet.
folder	string	No	Folder path to apply to all rows (e.g. /BUSINESS_VAULT). Overrides any FOLDER column in the spreadsheet.
release	string	No	Release identifier to assign to every imported instance (e.g. R1).
overwrite	boolean	No	When true, existing instances that match by key are overwritten. Defaults to false.
sheets[]	string[]	No	Array of sheet names to import. When omitted, all sheets in the workbook are processed.

TIP

* Exactly one of project or project_id is required. If project is provided, the API resolves the project ID by name.

Excel Workbook Format

Each sheet that is processed must contain rows with the following column conventions:

Column	Required	Description
INSTANCE	Yes	Instance identifier. Rows without this column value are skipped.
PATTERN	Conditional	Pattern name for the row. Required per-row unless the pattern form field is set.
PROJECT	No	Populated automatically when the project form field is set.
FOLDER	No	Folder path. Can be set globally via the folder form field.
POS_NO	No	Position number (integer). Defaults to 0 if missing or non-numeric.
<property columns>	No	Any additional columns whose names match instance property names defined on the pattern.

Response Schema

Field	Type	Description
instances	object[]	Array of successfully created or updated instance records.
instances[].id	integer	The ID of the created/updated instance.
instances[].name	string	Instance name.
instances[].folder	string	Folder path.
instances[].pattern	string	Pattern name.
instances[].release	string	Release name.
instances[].status	string	Processing status (e.g. INSERTED).
errors	string[]	Present only when one or more patterns failed to import.

Examples

cURL

FILE_PATH="/path/to/CORE_DV_HLS_AIRPLANE.xlsx"

curl -X POST "https://app.metakraftwerk.com/api/v1/instances" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "project=DEMO_PROJECT" \
  -F "pattern=CORE_DV_HLS" \
  -F "folder=/BUSINESS_VAULT" \
  -F "release=R1" \
  -F "sheets[]=FIELD_DETAILS" \
  -F "file=@${FILE_PATH}"

JavaScript (Fetch)

const form = new FormData();
form.append('file', fileInput.files[0]);
form.append('project', 'DEMO_PROJECT');
form.append('pattern', 'CORE_DV_HLS');
form.append('folder', '/BUSINESS_VAULT');
form.append('release', 'R1');
form.append('sheets[]', 'FIELD_DETAILS');

const response = await fetch('https://app.metakraftwerk.com/api/v1/instances', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${accessToken}` },
  body: form
});

const result = await response.json();

Response Example

{
  "instances": [
    {
      "id": 3334,
      "name": "AIRPLANE",
      "folder": "/BUSINESS_VAULT",
      "pattern": "CORE_DV_HLS",
      "release": "R1",
      "status": "INSERTED"
    }
  ]
}

Partial Success

When importing rows across multiple patterns, each pattern is processed independently. A failure in one pattern does not roll back successfully imported patterns:

{
  "instances": [ ... ],
  "errors": [
    "Error importing pattern X: ..."
  ]
}

Error Responses

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

Processing Details

The import follows this sequence for each distinct pattern found in the data:

1. Instance properties for the pattern are resolved from the database.
2. A temporary table is created with columns matching FOLDER, RELEASE, INSTANCE, POS_NO, and all pattern-specific instance properties.
3. The spreadsheet rows are loaded into the temporary table.
4. An INSERT INTO @INSTANCES.<PATTERN> statement is executed. If overwrite is true, the OVERWRITE modifier is appended.
5. The temporary table is dropped.
6. Results are collected and returned.

WARNING

When importing rows across multiple patterns (either via the PATTERN column in the spreadsheet or multiple sheets), each pattern is processed independently. A failure in one pattern does not roll back successfully imported patterns.

---

PUT /api/v1/instances — Update

Not implemented

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

Not implemented

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

Not implemented