Save AI Tools

Content-Type (Required)

String

Specifies the media type of the request body.

application/x-www-form-urlencoded

sessionid

String

The session ID is the token received from the login API.

Note: Session ID is required for token-based authentication.

–

name-or-id (Required)

String

Represents the name or ID of the AI Space for which AI tool configurations are to be added or updated.

Note: If the AI Space name is provided, then either folderName or folderId must also be provided.

–

by

String

Specifies whether the name-or-id parameter should be interpreted as an AI Space name or an AI Space ID.

If by=name, provide the AI Space name in the name-or-id parameter.

If by=id, provide the AI Space ID in the name-or-id parameter.

The default value is name.

–

folderName

String

Name of the folder containing the AI Space. If the AI Space is present in the root directory, specify [Root].

Note: If neither folderName nor folderId is provided, the AI Space is treated as a root-level entity by default.

–

folderId

String

ID of the folder containing the AI Space.

–

aiToolsJson (Required)

String

JSON object containing AI tool configuration details for the specified AI Space.

Note: An example JSON is provided under the Resources section.

–

401

Authorization information is missing or invalid.

404

No matching record found.

412

Precondition failed. Required parameter missing.

500

Internal Server Error

Field

Type

Description

Possible Values

Example

aiSpaceId

String

The unique identifier of the AI Space for which tools are being saved. Required.

Any valid GUID string

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

aiSpaceName

String

The display name of the AI Space. Required.

Any valid string

"Sales Analytics Space"

tools[]

Array of Objects

List of tool instances configured for the AI Space. Each entry represents one instance of a tool. Required. At least one enabled tool must be present for a valid configuration.

Array of tool objects

See tools[] fields below

tool

JSON Object

A single tool instance entry.

—

{ "toolId": "lookupKB", "instanceId": "...", "enabled": true, "toolType": "lookupKB", "config": {...} }

tools[].toolId

String

The canonical identifier of the tool. For standard tools, matches toolType. Used to map this tool instance back to its manifest definition. Required

"generateAndExecuteSQL", "lookupKB", "webSearch", "codeGenAndExecutor"

"lookupKB"

tools[].instanceId

String

Unique identifier for this tool configuration within the AI Space. Required. Used to differentiate multiple instances of the same tool type (e.g., multiple lookupKB instances).

Any valid GUID string

"f1a2b3c4-d5e6-7890-abcd-ef1234567890"

tools[].enabled

Boolean

Indicates whether this tool instance is active and should be used during AI Space conversations. Required.

true, false

TRUE

tools[].toolType

String

The functional type of the tool that determines its behavior and the applicable config sub-fields. Required

"generateAndExecuteSQL", "lookupKB", "webSearch", "codeGenAndExecutor"

"generateAndExecuteSQL"

tools[].config

JSON Object

Configuration block containing tool-specific settings. Required.

—

See tools[].config fields below

tools[].config.displayName

String

Display name of the tool shown in the AI Space. Required when the tool is enabled. Must be unique among enabled tools.

Any valid string

"SQL Generator and Executor"

tools[].config.purpose

String

Description of the purpose of this tool instance — helps the AI understand when and why to invoke it. Required when tools[].enabled is true and toolType is "lookupKB", "webSearch", or "codeGenAndExecutor". Optional for "generateAndExecuteSQL".

Any valid string

"Use this tool to generate and execute SQL queries against semantic models"

tools[].config.instructions

String

Additional instructions provided to the AI for how to use this tool. Optional.

Any valid string

"Always prefer aggregated results. Avoid full table scans."

tools[].config.prerequisiteTools

Array of Strings

List of instanceId values of other tool instances that must be invoked before this tool. Optional

Array of valid instanceId strings

["f1a2b3c4-d5e6-7890-abcd-ef1234567890"]

tools[].config.applicableUsecases

Array of Strings

Specifies where this tool can be used, such as Kyvos Dialogs or MCP integrations. Optional.

lookupKB → ["KYVOS_DIALOGS", "MCP"]
webSearch → ["KYVOS_DIALOGS"]
codeGenAndExecutor → ["KYVOS_DIALOGS"]
generateAndExecuteSQL → not serialized at all (field not added for this toolType)

["KYVOS_DIALOGS", "MCP"]

tools[].config.content

String

The knowledge base identifier or content reference that this lookupKB tool instance should query. Required when tools[].enabled is true and toolType is "lookupKB".

Any valid string

"Our product pricing follows a tiered model based on usage."

tools[].config.enableSummarization

Boolean

Whether the retrieved knowledge base results should be summarized before being returned. Applicable only when toolType is "lookupKB". Defaults to false.

true, false

FALSE

tools[].config.summarizationPromptContext

String

Additional context prompt used to guide the summarization when enableSummarization is true. Applicable only when toolType is "lookupKB". Optional.

Any valid string

"Summarize in the context of sales performance."

tools[].config.topK

Integer

The maximum number of Knowledge Base chunks to retrieve. Applicable only when toolType is "lookupKB". If not provided, the system uses a default value of 5. Must be between 1 and 50 (inclusive).

Integer between 1 and 50

5

tools[].config.thresholdScore

Number

Minimum similarity score required for a Knowledge Base result to be included. Applicable only when toolType is "lookupKB". If not provided, the default value is 0.7. Must be between -1 and 1 (inclusive). Set the value to null to disable threshold filtering.

Decimal between -1 and 1, or null

0.7

tools[].config.allowedDomains

Array of Strings

List of domain names the web search tool is allowed to search. Applicable only when toolType is "webSearch". Optional. An empty list allows searching any website.

Array of domain strings

["kyvos.io", "docs.microsoft.com"]

tools[].config.searchContextSize

String

Controls the depth/breadth of the web search context. Applicable only when toolType is "webSearch". If not provided system uses a default value is "medium"

"low", "medium", "high"

"medium"

tools[].config.userLocation

JSON Object

Geographic location information used to personalize web search results. Applicable only when toolType is "webSearch". Optional. Omitted from the payload when no location is configured. Contains either a timezone or geographic fields (country, region, city), but never both.

—

{ "timezone": "America/New_York" } or { "country": "US", "region": "NY", "city": "New York" }

tools[].config.userLocation.timezone

String

IANA timezone identifier used when location mode is TIMEZONE. Conditionally included when timezone value is set.

Any valid IANA timezone string

"America/New_York"

tools[].config.userLocation.country

String

Country name or code for manual location mode. Conditionally included when the value is non-blank.

Any valid string

"US"

tools[].config.userLocation.region

String

Region or state for manual location mode. Conditionally included when the value is non-blank.

Any valid string

"California"

tools[].config.userLocation.city

String

City for manual location mode. Conditionally included when the value is non-blank.

Any valid string

"San Francisco"

plannerConfig

JSON Object

Configuration for the AI planner/orchestrator that decides which tools to invoke and in what order. Optional.

—

See plannerConfig fields below

plannerConfig.instructions

String

System-level instructions provided to the planner governing how it should orchestrate tool calls and respond to user queries. Optional.

Any valid string

"Always verify SQL output before presenting results. Prefer knowledge base lookups for policy questions."