Operations related to data sources. A data source is a blob of text that can be made available to an agent's general info tools to provide more context to the agent when generating its responses. For more information, see [Console docs](https://docs.syllable.ai/Resources/DataSources).
openapi: 3.2.0
info:
title: SyllableSDK Data Sources 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: data_sources
description: Operations related to data sources. A data source is a blob of text that can be made available to an agent's general info tools to provide more context to the agent when generating its responses. For more information, see [Console docs](https://docs.syllable.ai/Resources/DataSources).
paths:
/api/v1/data_sources/:
get:
tags:
- data_sources
summary: List Data Sources
description: Fetch metadata about all data sources, not including their text.
operationId: data_sources_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/DataSourceProperties'
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/DataSourceProperties'
- 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/DataSourceProperties'
- 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_DataSourceMetadataResponse_'
'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.data_sources.list(page=0, limit=25, search_fields=[\n models.DataSourceProperties.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.dataSources.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:
- data_sources
summary: Create Data Source
description: Create a new data source.
operationId: data_sources_create
security:
- APIKeyHeader: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DataSourceCreateRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/DataSourceDetailResponse'
'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.data_sources.create(request={\n \"name\": \"Rain\",\n \"description\": \"Information about rain.\",\n \"labels\": [\n \"Weather Info\",\n ],\n \"chunk\": False,\n \"chunk_delimiter\": \"\",\n \"text\": \"The following are names and addresses of pizza shops.\\n\\nCool Pizza, 123 Main St.\\n\\nReally Good Pizza, 456 Water St.\\n\\nThe Best Pizza, 789 Circle Dr.\",\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.dataSources.create({\n name: \"Rain\",\n description: \"Information about rain.\",\n labels: [\n \"Weather Info\",\n ],\n chunk: false,\n chunkDelimiter: \"\",\n text: \"The following are names and addresses of pizza shops.\\n\\nCool Pizza, 123 Main St.\\n\\nReally Good Pizza, 456 Water St.\\n\\nThe Best Pizza, 789 Circle Dr.\",\n });\n\n console.log(result);\n}\n\nrun();"
put:
tags:
- data_sources
summary: Update Data Source
description: Update an existing data source.
operationId: data_sources_update
security:
- APIKeyHeader: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DataSourceUpdateRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/DataSourceDetailResponse'
'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.data_sources.update(request={\n \"name\": \"Rain\",\n \"description\": \"Information about rain.\",\n \"labels\": [\n \"Weather Info\",\n ],\n \"chunk\": False,\n \"chunk_delimiter\": \"\",\n \"id\": 1,\n \"edit_comments\": \"Added new info\",\n \"text\": \"The following are names and addresses of pizza shops.\\n\\nCool Pizza, 123 Main St.\\n\\nReally Good Pizza, 456 Water St.\\n\\nThe Best Pizza, 789 Circle Dr.\",\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.dataSources.update({\n name: \"Rain\",\n description: \"Information about rain.\",\n labels: [\n \"Weather Info\",\n ],\n chunk: false,\n chunkDelimiter: \"\",\n id: 1,\n editComments: \"Added new info\",\n text: \"The following are names and addresses of pizza shops.\\n\\nCool Pizza, 123 Main St.\\n\\nReally Good Pizza, 456 Water St.\\n\\nThe Best Pizza, 789 Circle Dr.\",\n });\n\n console.log(result);\n}\n\nrun();"
/api/v1/data_sources/{data_source_id}:
get:
tags:
- data_sources
summary: Get Data Source
description: Fetch a given data source, including its text.
operationId: data_sources_get_by_id
security:
- APIKeyHeader: []
parameters:
- name: data_source_id
in: path
required: true
schema:
type: integer
title: Data Source Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/DataSourceDetailResponse'
'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.data_sources.get_by_id(data_source_id=87219)\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.dataSources.getById({\n dataSourceId: 87219,\n });\n\n console.log(result);\n}\n\nrun();"
delete:
tags:
- data_sources
summary: Delete Data Source
description: Delete a given data source.
operationId: data_sources_delete
security:
- APIKeyHeader: []
parameters:
- name: data_source_id
in: path
required: true
schema:
type: integer
title: Data Source Id
- name: reason
in: query
required: true
schema:
type: string
title: Reason
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'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.data_sources.delete(data_source_id=509584, reason=\"<value>\")\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.dataSources.delete({\n dataSourceId: 509584,\n reason: \"<value>\",\n });\n\n console.log(result);\n}\n\nrun();"
components:
schemas:
OrderByDirection:
type: string
enum:
- asc
- desc
title: OrderByDirection
description: The direction in which to order list results, either ascending or descending.
ListResponse_DataSourceMetadataResponse_:
properties:
items:
items:
$ref: '#/components/schemas/DataSourceMetadataResponse'
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[DataSourceMetadataResponse]
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
DataSourceMetadataResponse:
properties:
name:
type: string
title: Name
description: The data source name. Must be unique within suborg. Cannot contain whitespace.
examples:
- Rain
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: The description of the data source.
examples:
- Information about rain.
labels:
items:
type: string
type: array
title: Labels
description: Searchable labels for the data source. Can be included in agent.prompt_tool_defaults for a given tool to give the agent access to data sources with those labels when calling that tool.
default: []
examples:
- - Weather Info
chunk:
type: boolean
title: Chunk
description: Whether the content should be split into smaller chunks. (This feature is coming in the future - currently this value will always be treated as False.)
examples:
- false
chunk_delimiter:
anyOf:
- type: string
- type: 'null'
title: Chunk Delimiter
description: String that should be treated as delimiter between intended chunks. (This feature is coming in the future - currently this value will always be treated as None.)
examples:
- ''
id:
type: integer
title: Id
description: The data source ID.
examples:
- 1
edit_comments:
anyOf:
- type: string
- type: 'null'
title: Edit Comments
description: The comments for the most recent edit to the data source
examples:
- Added new info
updated_at:
type: string
format: date-time
title: Updated At
description: Timestamp of most recent update
last_updated_by:
anyOf:
- type: string
- type: 'null'
title: Last Updated By
description: Email of the user who last updated the data source
examples:
- user@email.com
type: object
required:
- name
- chunk
- id
- updated_at
- last_updated_by
title: DataSourceMetadataResponse
description: 'Metadata about a data source, not including the text. A data source is a blob of text that
can be made available to an agent''s general info tools to provide more context to the agent when
generating its responses. For more information, see
[Console docs](https://docs.syllable.ai/Resources/DataSources).'
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
DataSourceCreateRequest:
properties:
name:
type: string
title: Name
description: The data source name. Must be unique within suborg. Cannot contain whitespace.
examples:
- Rain
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: The description of the data source.
examples:
- Information about rain.
labels:
items:
type: string
type: array
title: Labels
description: Searchable labels for the data source. Can be included in agent.prompt_tool_defaults for a given tool to give the agent access to data sources with those labels when calling that tool.
default: []
examples:
- - Weather Info
chunk:
type: boolean
title: Chunk
description: Whether the content should be split into smaller chunks. (This feature is coming in the future - currently this value will always be treated as False.)
examples:
- false
chunk_delimiter:
anyOf:
- type: string
- type: 'null'
title: Chunk Delimiter
description: String that should be treated as delimiter between intended chunks. (This feature is coming in the future - currently this value will always be treated as None.)
examples:
- ''
text:
type: string
title: Text
description: Information that the data source will provide to the agent accessing it. It is recommended to include a sentence at the beginning providing context to the LLM for the information in the data source.
examples:
- 'The following are names and addresses of pizza shops.
Cool Pizza, 123 Main St.
Really Good Pizza, 456 Water St.
The Best Pizza, 789 Circle Dr.'
type: object
required:
- name
- chunk
- text
title: DataSourceCreateRequest
description: Request model to create a data source.
DataSourceDetailResponse:
properties:
name:
type: string
title: Name
description: The data source name. Must be unique within suborg. Cannot contain whitespace.
examples:
- Rain
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: The description of the data source.
examples:
- Information about rain.
labels:
items:
type: string
type: array
title: Labels
description: Searchable labels for the data source. Can be included in agent.prompt_tool_defaults for a given tool to give the agent access to data sources with those labels when calling that tool.
default: []
examples:
- - Weather Info
chunk:
type: boolean
title: Chunk
description: Whether the content should be split into smaller chunks. (This feature is coming in the future - currently this value will always be treated as False.)
examples:
- false
chunk_delimiter:
anyOf:
- type: string
- type: 'null'
title: Chunk Delimiter
description: String that should be treated as delimiter between intended chunks. (This feature is coming in the future - currently this value will always be treated as None.)
examples:
- ''
id:
type: integer
title: Id
description: The data source ID.
examples:
- 1
edit_comments:
anyOf:
- type: string
- type: 'null'
title: Edit Comments
description: The comments for the most recent edit to the data source
examples:
- Added new info
updated_at:
type: string
format: date-time
title: Updated At
description: Timestamp of most recent update
last_updated_by:
anyOf:
- type: string
- type: 'null'
title: Last Updated By
description: Email of the user who last updated the data source
examples:
- user@email.com
text:
type: string
title: Text
description: Information that the data source will provide to the agent accessing it.
type: object
required:
- name
- chunk
- id
- updated_at
- last_updated_by
- text
title: DataSourceDetailResponse
description: 'Metadata about a data source, along with the text. A data source is a blob of text that
can be made available to an agent''s general info tools to provide more context to the agent when
generating its responses. For more information, see
[Console docs](https://docs.syllable.ai/Resources/DataSources).'
DataSourceProperties:
type: string
enum:
- name
- description
- labels
- chunk
- chunk_delimiter
- updated_at
- last_updated_by
title: DataSourceProperties
description: Names of data source fields supported for filtering/sorting on list endpoint.
DataSourceUpdateRequest:
properties:
name:
type: string
title: Name
description: The data source name. Must be unique within suborg. Cannot contain whitespace.
examples:
- Rain
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: The description of the data source.
examples:
- Information about rain.
labels:
items:
type: string
type: array
title: Labels
description: Searchable labels for the data source. Can be included in agent.prompt_tool_defaults for a given tool to give the agent access to data sources with those labels when calling that tool.
default: []
examples:
- - Weather Info
chunk:
type: boolean
title: Chunk
description: Whether the content should be split into smaller chunks. (This feature is coming in the future - currently this value will always be treated as False.)
examples:
- false
chunk_delimiter:
anyOf:
- type: string
- type: 'null'
title: Chunk Delimiter
description: String that should be treated as delimiter between intended chunks. (This feature is coming in the future - currently this value will always be treated as None.)
examples:
- ''
id:
type: integer
title: Id
description: The data source ID.
examples:
- 1
edit_comments:
anyOf:
- type: string
- type: 'null'
title: Edit Comments
description: The comments for the most recent edit to the data source
examples:
- Added new info
text:
type: string
title: Text
description: Information that the data source will provide to the agent accessing it. It is recommended to include a sentence at the beginning providing context to the LLM for the information in the data source.
examples:
- 'The following are names and addresses of pizza shops.
Cool Pizza, 123 Main St.
Really Good Pizza, 456 Water St.
The Best Pizza, 789 Circle Dr.'
type: object
required:
- name
- chunk
- id
- text
title: DataSourceUpdateRequest
description: Request model to update an existing data source.
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