1Generate AI Metadata

Overview

This API generates AI metadata for a semantic model, in one of two modes as specified by the parameter usecase.

Method: POST

Request URL: {kyvos-url}/rest/v2/semantic-models/{name-or-id}/generate-ai-metadata

Authorization

API Key: `sessionid`

This method authenticates requests using a session ID which acts like an API key.

BasicAuth: HTTP Authorization Scheme

This method authenticates requests using a username and password sent in the HTTP Authorization header.

Headers

Header	Required	Value	Description

Header	Required	Value	Description
Content-Type	Yes	`application/x-www-form-urlencoded`	Request body must be sent as URL-encoded form fields.
Accept	No	`application/json`	This API always returns `application/json`

Path Parameters

Name	Type	Required	Description

Name	Type	Required	Description
name-or-id	string	yes	The semantic model's name or id. How this value is interpreted is determined by the `by` query parameter.

Query Parameters

Name	Type	Default	Description

Name	Type	Default	Description
by	string	`name`	Whether `name-or-id` is a `name` or an `id`.

Form Parameters

Name	Type	Default	Required	Description

Name	Type	Default	Required	Description
folderName	string	—	no	Name of the folder in which the semantic model resides. Only used when resolving by name; ignored when resolving by id.
folderId	string	—	no	ID of the folder in which the semantic model resides. Only used when resolving by name.
usecase	string	`SM_BUSINESS_CONTEXT`	no	Specifies the AI metadata generation mode. Supported values (case-insensitive): `COLUMNS_METADATA`: Generates `businessContext` and `tags` for the model's eligible levels, attributes and measures. `SM_BUSINESS_CONTEXT`: Generates a single semantic-model-level business context. Note: Any other value returns error code `422`.
columns	string	`ALL`	no	Specifies which columns are considered for metadata generation when `usecase=COLUMNS_METADATA`. Supported values: `ALL`: Considers every eligible column `EMPTY_COLUMNS`: Restricts to columns whose existing `businessContext` and `tags` parameters are both blank. Note: Any other value returns error code `422`.
userPrompt	string	`""`	no	Free-text prompt to guide the AI generation.
action	string	`GENERATE_AND_SAVE`	no	Specifies whether to generate and save the result or generate it for preview without saving. The following values are supported: `GENERATE_AND_SAVE`: Generates and merges the result into the model's existing AI settings/metadata and saves. `GENERATE_ONLY`: Generates and returns the result without saving it (preview mode). Note: Any other value (case-insensitive) returns error code `422`.

Responses

The following responses are applicable when the usecase parameter is set to COLUMNS_METADATA and the action parameter is set to GENERATE_ONLY.

200 Success

{
  "columns": {
    "MEASURE_787792": {
      "name": "salary",
      "businessContext": "...",
      "type": "MEASURE",
      "tags": ["pay"]
    },
    "DIMENSION_ATTRIBUTE_448466": {
      "name": "country",
      "businessContext": "...",
      "type": "ATTRIBUTE",
      "tags": ["nation"]
    }
  },
  "failedColumns": {
    "DIMENSION_ATTRIBUTE_44864": {
      "name": "...",
      "businessContext": "",
      "type": "ATTRIBUTE",
      "tags": []
    }
  }
}

Status	Condition	Body shape

Status	Condition	Body shape
`412`	Neither the semantic model's name nor id could be resolved	`{ "message": "...", "code": -1 }`
`422`	`by` is not a recognized identifier type	`{ "message": "...", "code": -1 }`
`422`	`usecase` is neither `COLUMNS_METADATA` nor `SM_BUSINESS_CONTEXT`	`{ "message": "...", "code": -1 }`
`422`	`columns` is neither `ALL` nor `EMPTY_COLUMNS`	`{ "message": "...", "code": -1 }`
`422`	`action` is neither `GENERATE_AND_SAVE` nor `GENERATE_ONLY`	`{ "message": "...", "code": -1 }`
`422`	No eligible column to generate metadata for (`usecase=COLUMNS_METADATA` only)	`{ "message": "No eligible columns found for metadata generation.", "code": 422 }`
`422`	No eligible column to save (`usecase=COLUMNS_METADATA`, `action=GENERATE_AND_SAVE` only)	`{ "message": "No eligible columns found to save.", "code": 422 }`
`404`	Semantic model not found	`{ "message": "RECORD NOT FOUND", "code": -1 }`
`500`	Unexpected error, or an engine/`BaseException` error surfaced with its own error code/message	`{ "message": "...", "code": ... }`

Request Examples

Generate + save per-column metadata for all eligible columns (default action)

curl -X POST '{kyvos-url}/rest/v2/semantic-models/{name-or-id}/generate-ai-metadata?by=id' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic <token>' \
  --data-urlencode 'usecase=COLUMNS_METADATA' \
  --data-urlencode 'columns=ALL'

Preview per-column metadata for only the columns that don't have any yet, without saving

curl -X POST '{kyvos-url}/rest/v2/semantic-models/{name-or-id}/generate-ai-metadata?by=id' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic <token>' \
  --data-urlencode 'usecase=COLUMNS_METADATA' \
  --data-urlencode 'columns=EMPTY_COLUMNS' \
  --data-urlencode 'action=GENERATE_ONLY'

Generate and save a semantic-model-level business context, guided by a prompt

curl -X POST '{kyvos-url}/rest/v2/semantic-models/{name-or-id}/generate-ai-metadata?by=id' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic <token>' \
  --data-urlencode 'usecase=SM_BUSINESS_CONTEXT' \
  --data-urlencode 'userPrompt=Focus on retail sales terminology'

Bare defaults (still requires the form-urlencoded Content-Type header even with an empty body)

curl -X POST '{kyvos-url}/rest/v2/semantic-models/{name-or-id}/generate-ai-metadata?by=id' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic <token>'