Metadata

The /metadata endpoint allows you to execute arbitrary SQL statements against the MetaKraftwerk meta database. This provides programmatic access to query and manipulate instance metadata, views, and tables using the MetaKraftwerk SQL dialect.

See Also

• Authentication — Required for all API requests
• Meta Database — Meta database reference
• SQL Guide — Guide to SQL in MetaKraftwerk
• Information Schema — INSTANCES — Querying instance metadata

POST /api/v1/metadata — Execute Statement

Execute a SQL statement in the meta database within the context of a project.

Endpoint

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

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.
statement	string	Yes	The SQL statement to execute. Supports the MetaKraftwerk SQL dialect including @INSTANCES, @TABLES, and information schema views.

TIP

* Exactly one of project or project_id is required.

Response Schema

Field	Type	Description
id	string	Unique execution ID (UUID).
user_id	integer	User ID who executed the statement.
type	string	Statement type (e.g. select_statement, insert_statement).
sql	string	The SQL statement that was executed.
stmt_no	integer	Statement number (for multi-statement execution).
start_time	integer	Execution start timestamp (Unix milliseconds).
status	string	Execution status: FINISHED, ERROR.
rows	object[]	Array of result rows (for SELECT statements). Each object has keys matching the column names.
metadata	object[]	Array of column metadata describing the result set.
metadata[].name	string	Column name.
metadata[].type	string	Column data type (string, integer, etc.).
metadata[].pos_no	integer	Column position (0-based).
runtime	integer	Execution time in milliseconds.
error	string	Error message (only present when status is ERROR).

Examples

cURL

curl -X POST "https://app.metakraftwerk.com/api/v1/metadata" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "DEMO_PROJECT",
    "statement": "SELECT * FROM @INSTANCES.CORE_DV_HLS"
  }'

JavaScript (Fetch)

const response = await fetch('https://app.metakraftwerk.com/api/v1/metadata', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    project: 'DEMO_PROJECT',
    statement: 'SELECT * FROM @INSTANCES.CORE_DV_HLS'
  })
});

const result = await response.json();

Response Example

{
  "id": "0e9f7437-733f-4086-8f1e-d4fb048ce815",
  "user_id": 1,
  "type": "select_statement",
  "sql": "SELECT * FROM @INSTANCES.CORE_DV_HLS",
  "stmt_no": 0,
  "start_time": 1775117873027,
  "status": "FINISHED",
  "rows": [
    {
      "@PATTERN": "CORE_DV_HLS",
      "@FOLDER": "/BUSINESS_VAULT",
      "@INSTANCE": "AIRPLANE",
      "@RELEASE": "R1",
      "@POS_NO": 1,
      "@DELETED": 0,
      "FUNCTIONAL_ROLE": "SK",
      "NAME": "AIRPLANE_ID",
      "DATA_TYPE": "bigint",
      "PRECISION": 19,
      "SCALE": null,
      "NULLABLE": 0
    }
  ],
  "metadata": [
    { "name": "@PATTERN", "type": "string", "pos_no": 0 },
    { "name": "@FOLDER", "type": "string", "pos_no": 1 },
    { "name": "@INSTANCE", "type": "string", "pos_no": 2 },
    { "name": "@RELEASE", "type": "string", "pos_no": 3 },
    { "name": "@POS_NO", "type": "integer", "pos_no": 4 },
    { "name": "@DELETED", "type": "integer", "pos_no": 5 },
    { "name": "FUNCTIONAL_ROLE", "type": "string", "pos_no": 6 },
    { "name": "NAME", "type": "string", "pos_no": 7 },
    { "name": "DATA_TYPE", "type": "string", "pos_no": 8 },
    { "name": "PRECISION", "type": "integer", "pos_no": 9 },
    { "name": "SCALE", "type": "integer", "pos_no": 10 },
    { "name": "NULLABLE", "type": "integer", "pos_no": 11 }
  ],
  "runtime": 434
}

SQL Dialect

The MetaKraftwerk meta database supports a specialized SQL dialect. Key features include:

• @INSTANCES.<PATTERN> — Access instance metadata for a specific pattern as a virtual table.
• @TABLES.<TABLE> — Access custom metadata tables.
• System columns — Columns prefixed with @ (e.g. @PATTERN, @FOLDER, @INSTANCE, @RELEASE, @POS_NO, @DELETED) are system-managed.
• Information schema views — Query system views for metadata about instances, columns, commits, and more.

INFO

For the complete SQL reference, see the Meta Database documentation and the SQL Guide.

Error Responses

Status	Condition	Example Message
400	Missing required fields	A statement 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!

WARNING

SQL errors (e.g. syntax errors, unknown tables) are returned with a 200 status code but with status: "ERROR" and an error field in the response body. Always check the status field of the response.

---

GET /api/v1/metadata — Find

Not implemented

GET /api/v1/metadata/:id — Get

Not implemented

PUT /api/v1/metadata — Update

Not implemented

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

Not implemented

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

Not implemented