Instance Folders

The /instance_folders endpoint provides read-only access to the folder hierarchy used to organize instances within a project. Folders form a nested tree structure, and each folder has a computed path (e.g. /RAW_VAULT, /BUSINESS_VAULT/CRM).

See Also

• Authentication — Required for all API requests
• Instances — Web UI reference for instances
• Instances API — Instance metadata endpoint

GET /api/v1/instance_folders — Find Instance Folders

Retrieve a list of instance folders for a project, optionally filtered by pattern or name.

Endpoint

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

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.
name	string	No	Filter by folder name.
deleted	boolean	No	Filter by deletion status.

TIP

* Exactly one of project or project_id is required.

Response Schema

Returns an array of instance folder objects:

Field	Type	Description
id	integer	Unique folder ID.
project_id	integer	Project ID.
pattern_id	integer	Associated pattern ID.
parent_folder_id	integer	Parent folder ID (null for root folders).
name	string	Folder name.
path	string	Computed full path (e.g. /BUSINESS_VAULT).
deleted	boolean	Whether the folder is marked as deleted.
upload_disabled	boolean	Whether upload is disabled for instances in this folder.
insert_disabled	boolean	Whether insert is disabled for instances in this folder.
build_disabled	boolean	Whether build is disabled for instances in this folder.
edit_disabled	boolean	Whether editing is disabled for instances in this folder.

Examples

cURL

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

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

# Find by name
curl -X GET "https://app.metakraftwerk.com/api/v1/instance_folders?project_id=402&name=RAW_VAULT" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Find non-deleted folders
curl -X GET "https://app.metakraftwerk.com/api/v1/instance_folders?project_id=402&deleted=false" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

JavaScript (Fetch)

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

const folders = await response.json();

Response Example

[
  {
    "id": 903,
    "project_id": 402,
    "pattern_id": 808,
    "parent_folder_id": null,
    "name": "BUSINESS_VAULT",
    "path": "/BUSINESS_VAULT",
    "deleted": false,
    "upload_disabled": false,
    "insert_disabled": false,
    "build_disabled": false,
    "edit_disabled": false
  }
]

Error Responses

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

Retrieve a single instance folder by its ID, including the computed path.

Endpoint

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

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	The instance folder ID.

Examples

cURL

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

JavaScript (Fetch)

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

const folder = await response.json();

Error Responses

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

---

POST /api/v1/instance_folders — Create

Not implemented

PUT /api/v1/instance_folders — Update

Not implemented

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

Not implemented

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

Not implemented