Syllable Insights.tools API
Operations related to insights tool configurationss. An insight is a tool that processes conversation data to extract information and generate reports.
OpenAPI Specification
openapi: 3.2.0
info:
title: SyllableSDK Insights.tools API
description: "\n# Syllable Platform SDK\n\nSyllable SDK gives you the power of awesome AI agentry. \U0001F680\n\n## Overview\n\nThe Syllable SDK provides a comprehensive set of tools and APIs to integrate powerful AI\ncapabilities into your communication applications. Whether you're building phone agents, chatbots,\nvirtual assistants, or any other AI-driven solutions, Syllable SDK has got you covered.\n\n## Features\n\n- **Agent Configuration**: Create and manage agents that can interact with users across various \nchannels.\n- **Channel Management**: Configure channels like SMS, web chat, and more to connect agents with \nusers.\n- **Custom Messages**: Set up custom messages that agents can deliver as greetings or responses.\n- **Conversations**: Track and manage conversations between users and agents, including session \nmanagement.\n- **Tools and Workflows**: Leverage tools and workflows to enhance agent capabilities, such as data \nprocessing and API calls.\n- **Data Sources**: Integrate data sources to provide agents with additional context and \ninformation.\n- **Insights and Analytics**: Analyze conversations and sessions to gain insights into user \ninteractions.\n- **Permissions and Security**: Manage permissions to control access to various features and \nfunctionalities.\n- **Language Support**: Define language groups to enable multilingual support for agents.\n- **Outbound Campaigns**: Create and manage outbound communication campaigns to reach users \neffectively.\n- **Session Labels**: Label sessions with evaluations of quality and descriptions of issues \nencountered.\n- **Incident Management**: Track and manage incidents related to agent interactions.\n"
version: 0.0.3
servers:
- url: https://api.syllable.cloud
description: API server
tags:
- name: insights.tools
description: Operations related to insights tool configurationss. An insight is a tool that processes conversation data to extract information and generate reports.
paths:
/api/v1/insights/tool-configurations:
get:
tags:
- insights.tools
summary: List Insight Tool Configurations
description: List the existing insight_tools
operationId: insight_tool_list
security:
- APIKeyHeader: []
parameters:
- name: page
in: query
required: false
schema:
anyOf:
- type: integer
minimum: 0
- type: 'null'
description: The page number from which to start (0-based)
examples:
- 0
default: 0
title: Page
description: The page number from which to start (0-based)
- name: limit
in: query
required: false
schema:
type: integer
minimum: 0
description: The maximum number of items to return
examples:
- 25
default: 25
title: Limit
description: The maximum number of items to return
- name: search_fields
in: query
required: false
schema:
type: array
items:
$ref: '#/components/schemas/InsightToolProperties'
description: String names of fields to search. Correspond by index to search field values
examples:
- name
default: []
title: Search Fields
description: String names of fields to search. Correspond by index to search field values
- name: search_field_values
in: query
required: false
schema:
type: array
items:
type: string
description: Values of fields to search. Correspond by index to search fields. Unless field name contains "list", an individual search field value cannot be a list
examples:
- Some Object Name
default: []
title: Search Field Values
description: Values of fields to search. Correspond by index to search fields. Unless field name contains "list", an individual search field value cannot be a list
- name: order_by
in: query
required: false
schema:
anyOf:
- $ref: '#/components/schemas/InsightToolProperties'
- type: 'null'
description: The field whose value should be used to order the results
examples:
- name
title: Order By
description: The field whose value should be used to order the results
- name: order_by_direction
in: query
required: false
schema:
anyOf:
- $ref: '#/components/schemas/OrderByDirection'
- type: 'null'
description: The direction in which to order the results
title: Order By Direction
description: The direction in which to order the results
- name: fields
in: query
required: false
schema:
anyOf:
- type: array
items:
$ref: '#/components/schemas/InsightToolProperties'
- type: 'null'
description: The fields to include in the response
default: []
title: Fields
description: The fields to include in the response
- name: start_datetime
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: The start datetime for filtering results
examples:
- '2023-01-01T00:00:00Z'
title: Start Datetime
description: The start datetime for filtering results
- name: end_datetime
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: The end datetime for filtering results
examples:
- '2024-01-01T00:00:00Z'
title: End Datetime
description: The end datetime for filtering results
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ListResponse_InsightToolOutput_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
x-codeSamples:
- lang: python
label: Python (SDK)
source: "import os\nfrom syllable_sdk import SyllableSDK, models\n\n\nwith SyllableSDK(\n api_key_header=os.getenv(\"SYLLABLESDK_API_KEY_HEADER\", \"\"),\n) as ss_client:\n\n res = ss_client.insights.tools.list(page=0, limit=25, search_fields=[\n models.InsightToolProperties.NAME,\n ], search_field_values=[\n \"Some Object Name\",\n ], start_datetime=\"2023-01-01T00:00:00Z\", end_datetime=\"2024-01-01T00:00:00Z\")\n\n # Handle response\n print(res)"
- lang: typescript
label: Typescript (SDK)
source: "import { SyllableSDK } from \"syllable-sdk\";\n\nconst syllableSDK = new SyllableSDK({\n apiKeyHeader: process.env[\"SYLLABLESDK_API_KEY_HEADER\"] ?? \"\",\n});\n\nasync function run() {\n const result = await syllableSDK.insights.tools.list({\n page: 0,\n searchFields: [\n \"name\",\n ],\n searchFieldValues: [\n \"Some Object Name\",\n ],\n startDatetime: \"2023-01-01T00:00:00Z\",\n endDatetime: \"2024-01-01T00:00:00Z\",\n });\n\n console.log(result);\n}\n\nrun();"
post:
tags:
- insights.tools
summary: Create Insight Tool Configuration
description: Create a new insight tool.
operationId: insights_tool_create
security:
- APIKeyHeader: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InsightToolInput'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/InsightToolOutput'
'400':
description: Bad Request
'500':
description: Internal Server Error
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
x-codeSamples:
- lang: python
label: Python (SDK)
source: "import os\nfrom syllable_sdk import SyllableSDK\n\n\nwith SyllableSDK(\n api_key_header=os.getenv(\"SYLLABLESDK_API_KEY_HEADER\", \"\"),\n) as ss_client:\n\n res = ss_client.insights.tools.create(request={\n \"name\": \"summary-tool\",\n \"description\": \"This tool uses GPT4.1 to generate a summary of the call\",\n \"version\": 1,\n \"tool_arguments\": {\n \"prompt\": \"Provide a concise, accurate summary of the conversation's key points, focusing on the user's goal and how the agent responded\",\n },\n \"insight_tool_definition_id\": 1,\n })\n\n # Handle response\n print(res)"
- lang: typescript
label: Typescript (SDK)
source: "import { SyllableSDK } from \"syllable-sdk\";\n\nconst syllableSDK = new SyllableSDK({\n apiKeyHeader: process.env[\"SYLLABLESDK_API_KEY_HEADER\"] ?? \"\",\n});\n\nasync function run() {\n const result = await syllableSDK.insights.tools.create({\n name: \"summary-tool\",\n description: \"This tool uses GPT4.1 to generate a summary of the call\",\n version: 1,\n toolArguments: {\n \"prompt\": \"Provide a concise, accurate summary of the conversation's key points, focusing on the user's goal and how the agent responded\",\n },\n insightToolDefinitionId: 1,\n });\n\n console.log(result);\n}\n\nrun();"
/api/v1/insights/tool-configurations/{tool_id}:
get:
tags:
- insights.tools
summary: Get Insight Tool Config By Id
description: Get a InsightTool by Name.
operationId: insight_tool_get_by_id
security:
- APIKeyHeader: []
parameters:
- name: tool_id
in: path
required: true
schema:
type: string
title: Tool Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/InsightToolOutput'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
x-codeSamples:
- lang: python
label: Python (SDK)
source: "import os\nfrom syllable_sdk import SyllableSDK\n\n\nwith SyllableSDK(\n api_key_header=os.getenv(\"SYLLABLESDK_API_KEY_HEADER\", \"\"),\n) as ss_client:\n\n res = ss_client.insights.tools.get_by_id(tool_id=\"<id>\")\n\n # Handle response\n print(res)"
- lang: typescript
label: Typescript (SDK)
source: "import { SyllableSDK } from \"syllable-sdk\";\n\nconst syllableSDK = new SyllableSDK({\n apiKeyHeader: process.env[\"SYLLABLESDK_API_KEY_HEADER\"] ?? \"\",\n});\n\nasync function run() {\n const result = await syllableSDK.insights.tools.getById({\n toolId: \"<id>\",\n });\n\n console.log(result);\n}\n\nrun();"
delete:
tags:
- insights.tools
summary: Delete Insight Tool Configuration
description: Delete an Insights tool configuration.
operationId: insights_tool_delete
security:
- APIKeyHeader: []
parameters:
- name: tool_id
in: path
required: true
schema:
type: integer
title: Tool Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'400':
description: Bad Request
'404':
description: Not Found
'412':
description: Precondition Failed
'500':
description: Internal Server Error
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
x-codeSamples:
- lang: python
label: Python (SDK)
source: "import os\nfrom syllable_sdk import SyllableSDK\n\n\nwith SyllableSDK(\n api_key_header=os.getenv(\"SYLLABLESDK_API_KEY_HEADER\", \"\"),\n) as ss_client:\n\n res = ss_client.insights.tools.delete(tool_id=770449)\n\n # Handle response\n print(res)"
- lang: typescript
label: Typescript (SDK)
source: "import { SyllableSDK } from \"syllable-sdk\";\n\nconst syllableSDK = new SyllableSDK({\n apiKeyHeader: process.env[\"SYLLABLESDK_API_KEY_HEADER\"] ?? \"\",\n});\n\nasync function run() {\n const result = await syllableSDK.insights.tools.delete({\n toolId: 770449,\n });\n\n console.log(result);\n}\n\nrun();"
put:
tags:
- insights.tools
summary: Update Insights Tool Configuration
description: Update an Insights tool.
operationId: insights_tool_update
security:
- APIKeyHeader: []
parameters:
- name: tool_id
in: path
required: true
schema:
type: integer
title: Tool Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InsightToolInput'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/InsightToolOutput'
'400':
description: Bad Request
'404':
description: Not Found
'412':
description: Precondition Failed
'500':
description: Internal Server Error
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
x-codeSamples:
- lang: python
label: Python (SDK)
source: "import os\nfrom syllable_sdk import SyllableSDK\n\n\nwith SyllableSDK(\n api_key_header=os.getenv(\"SYLLABLESDK_API_KEY_HEADER\", \"\"),\n) as ss_client:\n\n res = ss_client.insights.tools.update(tool_id=368362, insight_tool_input={\n \"name\": \"summary-tool\",\n \"description\": \"This tool uses GPT4.1 to generate a summary of the call\",\n \"version\": 1,\n \"tool_arguments\": {\n \"prompt\": \"Provide a concise, accurate summary of the conversation's key points, focusing on the user's goal and how the agent responded\",\n },\n \"insight_tool_definition_id\": 1,\n })\n\n # Handle response\n print(res)"
- lang: typescript
label: Typescript (SDK)
source: "import { SyllableSDK } from \"syllable-sdk\";\n\nconst syllableSDK = new SyllableSDK({\n apiKeyHeader: process.env[\"SYLLABLESDK_API_KEY_HEADER\"] ?? \"\",\n});\n\nasync function run() {\n const result = await syllableSDK.insights.tools.update({\n toolId: 368362,\n insightToolInput: {\n name: \"summary-tool\",\n description: \"This tool uses GPT4.1 to generate a summary of the call\",\n version: 1,\n toolArguments: {\n \"prompt\": \"Provide a concise, accurate summary of the conversation's key points, focusing on the user's goal and how the agent responded\",\n },\n insightToolDefinitionId: 1,\n },\n });\n\n console.log(result);\n}\n\nrun();"
/api/v1/insights/tools-test:
post:
tags:
- insights.tools
summary: Test Insights Tool
description: Manually run the given insight tool against a session and return the response.
operationId: insights_tool_test
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InsightToolTestInput'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'400':
description: Bad Request
'404':
description: Not Found
'500':
description: Internal Server Error
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
x-codeSamples:
- lang: python
label: Python (SDK)
source: "import os\nfrom syllable_sdk import SyllableSDK\n\n\nwith SyllableSDK(\n api_key_header=os.getenv(\"SYLLABLESDK_API_KEY_HEADER\", \"\"),\n) as ss_client:\n\n res = ss_client.insights.tools.insights_tool_test(request={\n \"tool_name\": \"summary-tool\",\n })\n\n # Handle response\n print(res)"
- lang: typescript
label: Typescript (SDK)
source: "import { SyllableSDK } from \"syllable-sdk\";\n\nconst syllableSDK = new SyllableSDK({\n apiKeyHeader: process.env[\"SYLLABLESDK_API_KEY_HEADER\"] ?? \"\",\n});\n\nasync function run() {\n const result = await syllableSDK.insights.tools.insightsToolTest({\n toolName: \"summary-tool\",\n });\n\n console.log(result);\n}\n\nrun();"
/api/v1/insights/tool-definitions:
get:
tags:
- insights.tools
summary: Get Insight Tool Definitions
description: Get a InsightTool by Name.
operationId: insight_tool_get_definitions
responses:
'200':
description: Successful Response
content:
application/json:
schema:
items:
$ref: '#/components/schemas/InsightToolDefinition'
type: array
title: Response Insight Tool Get Definitions
security:
- APIKeyHeader: []
x-codeSamples:
- lang: python
label: Python (SDK)
source: "import os\nfrom syllable_sdk import SyllableSDK\n\n\nwith SyllableSDK(\n api_key_header=os.getenv(\"SYLLABLESDK_API_KEY_HEADER\", \"\"),\n) as ss_client:\n\n res = ss_client.insights.tools.insight_tool_get_definitions()\n\n # Handle response\n print(res)"
- lang: typescript
label: Typescript (SDK)
source: "import { SyllableSDK } from \"syllable-sdk\";\n\nconst syllableSDK = new SyllableSDK({\n apiKeyHeader: process.env[\"SYLLABLESDK_API_KEY_HEADER\"] ?? \"\",\n});\n\nasync function run() {\n const result = await syllableSDK.insights.tools.insightToolGetDefinitions();\n\n console.log(result);\n}\n\nrun();"
components:
schemas:
InsightToolTestInput:
properties:
tool_name:
type: string
title: Tool Name
description: Human readable name of insight tool configuration
examples:
- summary-tool
session_id:
anyOf:
- type: integer
- type: 'null'
title: Session Id
description: The session ID of the session against which to run the tool
examples:
- '283467'
upload_file_id:
anyOf:
- type: integer
- type: 'null'
title: Upload File Id
description: The file ID of the uploaded file against which to run the tool
examples:
- '283467'
type: object
required:
- tool_name
title: InsightToolTestInput
description: Request model to test an insight tool.
OrderByDirection:
type: string
enum:
- asc
- desc
title: OrderByDirection
description: The direction in which to order list results, either ascending or descending.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
ListResponse_InsightToolOutput_:
properties:
items:
items:
$ref: '#/components/schemas/InsightToolOutput'
type: array
title: Items
description: List of items returned from the query
examples: []
page:
type: integer
title: Page
description: The page number of the results (0-based)
examples:
- 0
page_size:
type: integer
title: Page Size
description: The number of items returned per page
examples:
- 25
total_pages:
anyOf:
- type: integer
- type: 'null'
title: Total Pages
description: The total number of pages of results given the indicated page size
examples:
- 4
total_count:
anyOf:
- type: integer
- type: 'null'
title: Total Count
description: The total number of items returned from the query
examples:
- 100
type: object
required:
- items
- page
- page_size
title: ListResponse[InsightToolOutput]
InsightToolOutput:
properties:
name:
type: string
title: Name
description: Human readable name of insight tool
examples:
- summary-tool
description:
type: string
title: Description
description: Text description of insight tool configuration
examples:
- This tool uses GPT4.1 to generate a summary of the call
version:
type: integer
title: Version
description: Version of insight tool
examples:
- 1
tool_arguments:
title: Tool Arguments
description: Arguments for calling the insight tool
examples:
- prompt: Provide a concise, accurate summary of the conversation's key points, focusing on the user's goal and how the agent responded
insight_tool_definition_id:
type: integer
title: Insight Tool Definition Id
description: Unique ID for insight tool definition used by this tool configuration
examples:
- 1
id:
type: integer
title: Id
description: Unique ID for insight tool
examples:
- 1
insight_tool_definition:
anyOf:
- $ref: '#/components/schemas/InsightToolDefinition'
- type: 'null'
description: Insight Tool Definition
created_at:
type: string
format: date-time
title: Created At
description: Timestamp of at which insight tool configuration was created
examples:
- '2026-08-04T00:00:00Z'
updated_at:
type: string
format: date-time
title: Updated At
description: Timestamp at which insight tool configuration was last updated
examples:
- '2026-08-05T00:00:00Z'
last_updated_by:
type: string
title: Last Updated By
description: Email of user who last updated insight tool configuration
examples:
- user@email.com
type: object
required:
- name
- description
- version
- tool_arguments
- insight_tool_definition_id
- id
- last_updated_by
title: InsightToolOutput
description: Response model for an insight tool configuration.
InsightToolInput:
properties:
name:
type: string
title: Name
description: Human readable name of insight tool
examples:
- summary-tool
description:
type: string
title: Description
description: Text description of insight tool configuration
examples:
- This tool uses GPT4.1 to generate a summary of the call
version:
type: integer
title: Version
description: Version number of insight tool configuration
examples:
- 1
tool_arguments:
title: Tool Arguments
description: Arguments for calling the insight tool
examples:
- prompt: Provide a concise, accurate summary of the conversation's key points, focusing on the user's goal and how the agent responded
insight_tool_definition_id:
type: integer
title: Insight Tool Definition Id
description: Internal ID for the definition used by the insight tool configuration
examples:
- 1
type: object
required:
- name
- description
- version
- tool_arguments
- insight_tool_definition_id
title: InsightToolInput
description: Request model to create/update an insight tool configuration.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
InsightToolProperties:
type: string
enum:
- id
- name
- name_exact
- description
- tool_arguments
- insight_tool_definition_id
- updated_at
title: InsightToolProperties
InsightToolDefinition:
properties:
id:
type: integer
title: Id
description: Unique ID for insight tool definition
examples:
- 1
name:
type: string
title: Name
description: Human-readable name of insight tool definition
examples:
- llm_tool
type:
type: string
title: Type
description: Type of insight tool definition
description:
type: string
title: Description
description: Text description of insight tool definition
examples:
- An LLM tool evaluates a transcript with a given prompt
tool_parameters:
title: Tool Parameters
description: Parameters for tools that use this definition and their associated types
examples:
- prompt: string
tool_result_set:
title: Tool Result Set
description: Result key/types for insight tool definition
examples:
- summary: string
type: object
required:
- id
- name
- type
- description
- tool_parameters
- tool_result_set
title: InsightToolDefinition
description: 'Model for an insight tool definition. This is a template that can be used by multiple insight
tool configurations, each providing their own parameter values.'
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: Syllable-API-Key
x-speakeasy-name-override:
- operationId: .*_list$
methodNameOverride: list
- operationId: .*_create$
methodNameOverride: create
- operationId: .*_update$
methodNameOverride: update
- operationId: .*_upload$
methodNameOverride: upload
- operationId: .*_delete$
methodNameOverride: delete
- operationId: .*_get_by_id$
methodNameOverride: get_by_id
- operationId: .*_get_by_name$
methodNameOverride: get_by_name
- operationId: .*_add$
methodNameOverride: add
- operationId: .*_remove$
methodNameOverride: remove
- operationId: .*_results$
methodNameOverride: results
- operationId: .*_queue_work$
methodNameOverride: queue_work
- operationId: .*_activate$
methodNameOverride: activate
- operationId: .*_inactivate$
methodNameOverride: inactivate
- operationId: .*_list_files$
methodNameOverride: list_files
- operationId: .*_move_files$
methodNameOverride: move_files
- operationId: .*_upload_file$
methodNameOverride: upload_file