API Reference
API Reference

Update Insights Tool Configuration

Update an Insights tool.

PUT/api/v1/insights/tool-configurations/{tool_id}

Authentication

Syllable-API-Keyrequired

Send Syllable-API-Key in the header.

Need a credential? Create or manage an API token in the Syllable Console.

Parameters

Path parameters

tool_id integer path required

Request body

application/json

body InsightToolInput required
5 fields
namestringrequired

Human readable name of insight tool

descriptionstringrequired

Text description of insight tool configuration

versionintegerrequired

Version number of insight tool configuration

tool_argumentsunspecifiedrequired

Arguments for calling the insight tool

insight_tool_definition_idintegerrequired

Internal ID for the definition used by the insight tool configuration

Request example
{
  "name": "string",
  "description": "string",
  "version": 0,
  "tool_arguments": "string",
  "insight_tool_definition_id": 0
}

Responses

200Successful Response

application/json

response InsightToolResponse required
11 fields
namestringrequired

Human readable name of insight tool

descriptionstringrequired

Text description of insight tool configuration

versionintegerrequired

Version of insight tool

tool_argumentsunspecifiedrequired

Arguments for calling the insight tool

insight_tool_definition_idintegerrequired

Unique ID for insight tool definition used by this tool configuration

idintegerrequired

Unique ID for insight tool

insight_tool_definitionInsightToolDefinition | nulloptional

Insight Tool Definition

6 options
idintegerrequired

Unique ID for insight tool definition

namestringrequired

Human-readable name of insight tool definition

typestringrequired

Type of insight tool definition

descriptionstringrequired

Text description of insight tool definition

tool_parametersunspecifiedrequired

Parameters for tools that use this definition and their associated types

tool_result_setunspecifiedrequired

Result key/types for insight tool definition

created_atstring (date-time)optional

Timestamp of at which insight tool configuration was created

updated_atstring (date-time)optional

Timestamp at which insight tool configuration was last updated

last_updated_bystringrequired

Email of user who last updated insight tool configuration

validation_issuesValidationIssue[] | nulloptional

Non-blocking findings for the saved insight tool (e.g. a deprecated model warning). Warnings and infos are informational; errors block the save.

Item schema
itemsValidationIssuerequired

A single validation finding with severity, location, and description.

5 fields
idstringrequired

Stable machine-readable identifier (kebab-case)

severityenum<string>optional
Allowed values ["info","warning","error"]Default error
messagestringrequired

Human-readable description

pathstring | nulloptional

JSONPath-style location (e.g. $.context.task.steps[2])

valuestring | nulloptional

The offending value, when it adds clarity

Response example
{
  "name": "string",
  "description": "string",
  "version": 0,
  "tool_arguments": "string",
  "insight_tool_definition_id": 0,
  "id": 0,
  "insight_tool_definition": "string",
  "created_at": "string",
  "updated_at": "string",
  "last_updated_by": "string",
  "validation_issues": "string"
}
400Bad Request

No response body is declared.

404Not Found

No response body is declared.

412Precondition Failed

No response body is declared.

422Validation Error

application/json

response HTTPValidationError required
1 field
detailValidationError[]optional
Item schema
itemsValidationErrorrequired
3 fields
locstring | integer[]required
Item schema
itemsstring | integerrequired
2 options
Option 1stringrequired
Option 2integerrequired
msgstringrequired
typestringrequired
Response example
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
500Internal Server Error

No response body is declared.