# Authentication
Source: https://docs.vatis.tech/api-reference/authentication
Authenticate to Vatis Streams API
The Vatis Streams API offers the following authentication schemas:
* **Client credentials**: Authenticate using the `Client Id` and `Client Secret` provided by Vatis Tech Platform
* **Authorization token**: Authenticate using an `access_token` obtained by exchanging the client credentials
* **API Key**: Authenticate using an `api key` provided by Vatis Tech Platform
Get the `Client Id` and `Client Secret` from your [API Dashboard](https://vatis.tech/app/playground/transcribe)
There are two ways to set the client credentials on each request:
1. Set the `X-Client-Id` and `X-Client-Secret` headers
2. Set the `client_id` and `client_secret` query parameters
Send the credentials as query parameters with extra caution as they may get logged
Get the `Client Id` and `Client Secret` from your Vatis Tech Platform account
Request the access token as illustrated below:
```bash
curl --request POST \
--url https://auth.vatis.tech/realms/vatistech/protocol/openid-connect/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data 'client_id=string' \
--data 'client_secret=string' \
--data grant_type=client_credentials
```
[Try it out](https://docs.vatis.tech/api-reference/commons/authenticate)
In the response, you will get an `access_token` which you can use to authenticate your requests.
```json
{
"access_token": "eyJhb...",
"expires_in": 600,
"token_type": "Bearer",
...
}
```
It's recommended to obtain a new access token before each workflow execution
There are two ways to set the authorization token on each subsequent request:
1. Set the `Authorization` header with the `Bearer [token]` value
2. Set the `access_token` as a query parameter having the token as the value
It's recommended to set the token as a header
Get the `API key` from your [API Dashboard](https://vatis.tech/app/playground/transcribe)
There are two ways to set the API key on each subsequent request:
1. Set the `Authorization` header with the `Basic [api_key]` value
2. Set the `access_token` as a query parameter having the API key as the value
Send the API key as query parameter with extra caution as it may get logged
# Authenticate
Source: https://docs.vatis.tech/api-reference/commons/authenticate
POST /realms/vatistech/protocol/openid-connect/token
# Export
Source: https://docs.vatis.tech/api-reference/export/exports-a-stream-of-data-in-various-formats
get /export-service/api/v1/export/{exportFormat}
Exports results of one or more streams in various formats
# Upload
Source: https://docs.vatis.tech/api-reference/gateway/upload
post /http-gateway/api/v1/upload
Upload a stream of bytes to a new stream
Please note the body can be any binary data.
Use the [Swagger UI](https://http-gateway.vatis.tech/swagger-ui/index.html) to test this endpoint.
# Introduction
Source: https://docs.vatis.tech/api-reference/introduction
Vatis Streams API reference
Vatis Streams API is a RESTful API that aims to provide a simple and easy way to interact with the Vatis Streams platform.
The API is built using the OpenAPI specification and is available for public use.
## Examples
Explore our [GitHub samples repository](https://github.com/Vatis-Tech/vatis-streams-samples) to find examples for the programming languages and the use-case that fits you best.
## Swagger docs
Feel free to check out the Swagger documentation for each individual service in out infrastructure
# null
Source: https://docs.vatis.tech/api-reference/schemas/egress/diarization-response
# null
Source: https://docs.vatis.tech/api-reference/schemas/egress/llm-response
# null
Source: https://docs.vatis.tech/api-reference/schemas/egress/stream-sink-message
# null
Source: https://docs.vatis.tech/api-reference/schemas/egress/transcription-response
# null
Source: https://docs.vatis.tech/api-reference/schemas/error/error-response
# Internal error names
Source: https://docs.vatis.tech/api-reference/schemas/error/internal-error-name
# null
Source: https://docs.vatis.tech/api-reference/schemas/export/audio-intelligence-response
# null
Source: https://docs.vatis.tech/api-reference/schemas/http-gateway/stream-configuration
# null
Source: https://docs.vatis.tech/api-reference/schemas/webhook/event-payload/group-state-changed-event
# null
Source: https://docs.vatis.tech/api-reference/schemas/webhook/event-payload/group-stream-joined-event
# null
Source: https://docs.vatis.tech/api-reference/schemas/webhook/event-payload/stream-gateway-state-event
# null
Source: https://docs.vatis.tech/api-reference/schemas/webhook/event-payload/stream-processor-state-event
# null
Source: https://docs.vatis.tech/api-reference/schemas/webhook/event-payload/stream-state-event
# null
Source: https://docs.vatis.tech/api-reference/schemas/webhook/webhook-event
# null
Source: https://docs.vatis.tech/api-reference/schemas/websocket/configuration
# End of Stream
Source: https://docs.vatis.tech/api-reference/schemas/websocket/end-of-stream
Message type.
```json
{
"type": "END_OF_STREAM"
}
```
# null
Source: https://docs.vatis.tech/api-reference/schemas/websocket/error
# null
Source: https://docs.vatis.tech/api-reference/schemas/websocket/keep-alive
# null
Source: https://docs.vatis.tech/api-reference/schemas/websocket/response
# null
Source: https://docs.vatis.tech/api-reference/schemas/websocket/stream-metadata
# Find all
Source: https://docs.vatis.tech/api-reference/stream-configuration/processor-declaration-resource-impl/find-all
get /stream-configuration-service/api/v1/processor-declarations
Retrieves all the processor declarations the user can access in a paginated manner
# Find all
Source: https://docs.vatis.tech/api-reference/stream-configuration/stream-configuration-template-resource-impl/find-all
get /stream-configuration-service/api/v1/stream-configuration-templates
Retrieves all the stream configuration templates the user can access in a paginated manner
# Patch by id
Source: https://docs.vatis.tech/api-reference/stream-configuration/stream-configuration-template-resource-impl/patch-by-id
patch /stream-configuration-service/api/v1/stream-configuration-templates/{streamConfigurationTemplateId}
Retrieves the stream configuration template with patches applied.
# Cancel
Source: https://docs.vatis.tech/api-reference/streams/stream-resource-impl/cancel
put /stream-service/api/v1/streams/{streamId}/cancel
Cancels a stream. This operation can be performed by a gateway, on behalf of the user
# Find all
Source: https://docs.vatis.tech/api-reference/streams/stream-resource-impl/find-all
get /stream-service/api/v1/streams
Find all streams the current user has access to in a paginated manner
# Find by id
Source: https://docs.vatis.tech/api-reference/streams/stream-resource-impl/find-by-id
get /stream-service/api/v1/streams/{streamId}
Retrieves a stream by id
# Get components
Source: https://docs.vatis.tech/api-reference/streams/stream-resource-impl/get-components
get /stream-service/api/v1/streams/{streamId}/components
Get the components of a stream
# Stream usage
Source: https://docs.vatis.tech/api-reference/usage/stream-usage-resource-impl/stream-usage
get /usage-service/api/v1/usage/streams/{streamId}
Get the usage of all processors in a stream
# Usage report
Source: https://docs.vatis.tech/api-reference/usage/usage-report-resource-impl/usage-report
get /usage-service/api/v1/usage/report
Retrieve usage report for a given time interval
# Create/update
Source: https://docs.vatis.tech/api-reference/webhooks/webhook-endpoint-resource-impl/createupdate
put /notification-service/api/v1/webhook-endpoints
Creates or updates a webhook endpoint.
# Delete
Source: https://docs.vatis.tech/api-reference/webhooks/webhook-endpoint-resource-impl/delete
delete /notification-service/api/v1/webhook-endpoints/{id}
Deletes a webhook endpoint.
# Find all
Source: https://docs.vatis.tech/api-reference/webhooks/webhook-endpoint-resource-impl/find-all
get /notification-service/api/v1/webhook-endpoints
Finds all webhook endpoints of the current user.
# Find by ID
Source: https://docs.vatis.tech/api-reference/webhooks/webhook-endpoint-resource-impl/find-by-id
get /notification-service/api/v1/webhook-endpoints/{id}
Finds a webhook endpoint by id.
# Get available event type
Source: https://docs.vatis.tech/api-reference/webhooks/webhook-endpoint-resource-impl/get-available-event-type
get /notification-service/api/v1/webhook-endpoints/supported-events
Finds all supported events for webhook endpoints.
# Toggle endpoint
Source: https://docs.vatis.tech/api-reference/webhooks/webhook-endpoint-resource-impl/toggle-endpoint
patch /notification-service/api/v1/webhook-endpoints/{id}/enabled/{enabled}
Enables or disables a webhook endpoint. A disabled webhook won't be notified.
# Ask Anything
Source: https://docs.vatis.tech/audio-intelligence/ask-anything
Create custom prompts for your content
Configure your custom prompts using the following options:
Specifies the custom prompt content for one of the `ask0`, `ask1`, ..., `askN` ask anything slots.
When the content is specified, the prompt is considered activated. Otherwise, it is deactivated.
Specifies the custom system prompt for one of the `ask0System`, `ask1System`, ..., `askNSystem` ask anything slots.
Specifies the prompt id for one of the `ask0Id`, `ask1Id`, ..., `askNId` ask anything slots.
The role of the prompt id is to identify the prompt in the responses.
When unspecified, it will fallback on the index of the slot (e.g. `"0"`, `"1"`).
Specifies the prompt response [JSON Schema](https://json-schema.org/overview/what-is-jsonschema) encoded as a string for one of the `ask0Format`, `ask1Format`, ..., `askNFormat` ask anything slots.
When unspecified, the response not be structured in any particular way.
When specified, the response will be a JSON object encoded as a string.
## Usage
Currently, there are up to 3 ask anything slots available.
For using the ask anything slots, you can specify the prompts as query parameters in the request URL, or using a configuration message on the WebSocket connection.
Here we'll create to custom prompts about the processed phone call:
1. `What was the client intent?`
2. `Was the client issue solved?`
```bash
curl -X 'POST' \
'https://http-gateway.vatis.tech/http-gateway/api/v1/upload?streamConfigurationTemplateId=668115d123bca7e3509723d4&ask0=What%20was%20the%20client%20intent%3F&ask1=Was%20the%20client%20issue%20solved%3F&persist=true' \
-H 'accept: application/json' \
-H 'Authorization: Basic ' \
-H 'Content-Type: application/octet-stream' \
--data-binary '@test-phone-call.wav'
```
When the prompts exceed the URL length limit, the alternative is to transmit the prompts over a WebSocket connection using a configuration message.
```
wss://ws-gateway.vatis.tech/ws-gateway/api/v1?streamConfigurationTemplateId=668115d123bca7e3509723d4&persist=true&egress=false&configurationMessage=true
```
Send this message as the first message after the connection is established:
```json
{
"type": "CONFIGURATION",
"patches": {
"ask0": "What was the client intent?",
"ask1": "Was the client issue solved?"
}
}
```
## Response
```json
{
...
"askAnything": {
"0": {
"promptId": "0",
"content": "The client's intent was to sign up for a Wi-Fi service with ***, provide the necessary personal and address information, select a connection speed, and schedule an installation appointment."
},
"1": {
"promptId": "1",
"content": "Yes, the client's issue was solved. George Washington successfully signed up for the Wi-Fi service, provided the necessary information, and scheduled an installation appointment for a convenient date and time. The representative also explained the costs and payment process."
}
}
}
```
## System Prompt
Each ask-anything prompt can receive an optional system prompt alongside the custom prompt. The system prompt can be used to modify the LLM behavior or to provide additional context to the user prompt.
The system prompt can be specified using the `ask0System`, `ask1System`, etc. query parameters.
## Prompt Id
By default, each ask-anything prompt will be assigned with an ID corresponding to the prompt index.
To override this behavior, you can specify the prompt ID using the `ask0Id`, `ask1Id`, etc. query parameters.
For example, given the following prompt id values: `ask0Id=client_intent&ask1Id=issue_solved`
The response will be:
```json
{
...
"askAnything": {
"client_intent": {
"promptId": "client_intent",
"content": "The client's intent was to sign up for a Wi-Fi service with ***, provide the necessary personal and address information, select a connection speed, and schedule an installation appointment."
},
"issue_solved": {
"promptId": "issue_solved",
"content": "Yes, the client's issue was solved. George Washington successfully signed up for the Wi-Fi service, provided the necessary information, and scheduled an installation appointment for a convenient date and time. The representative also explained the costs and payment process."
}
}
}
```
## Response format
The generated response for each ask-anything prompt will have no particular structure. For the scenarios where the response should be structured in a predefined way, we can use the response format feature to specify a [JSON Schema](https://json-schema.org/overview/what-is-jsonschema) to parse the response against.
To activate the response format feature, we need to specify the `ask0Format`, `ask1Format`, etc. query parameters having the JSON Schema value encoded as string.
For example, we'll take the following prompt: `Extract the client identification details, the requested service and any relevant information to the requested service`
And the following JSON Schema:
```json
{
"$defs": {
"ClientIdentificationData": {
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"phone_number": {
"title": "Phone Number",
"type": "string"
},
"date_of_birth": {
"title": "Date Of Birth",
"type": "string"
}
},
"required": [
"name",
"phone_number",
"date_of_birth"
],
"title": "ClientIdentificationData",
"type": "object"
}
},
"properties": {
"client_identification": {
"$ref": "#/$defs/ClientIdentificationData"
},
"requested_service": {
"enum": [
"WiFi",
"GSM",
"Billing"
],
"title": "Requested Service",
"type": "string"
}
},
"required": [
"client_identification",
"requested_service"
],
"title": "ClientRequest",
"type": "object"
}
```
The response will be:
```json
{
...
"askAnything": {
"0": {
"promptId": "0",
"content": "{\"client_identification\":{\"name\":\"George Washington\",\"phone_number\":\"414-2**-****\",\"date_of_birth\":\"July *, 19**\"},\"requested_service\":\"WiFi\"}"
}
}
}
```
By parsing the JSON encoded inside the string response we can get
```json
{
"client_identification": {
"name": "George Washington",
"phone_number": "414-***-****",
"date_of_birth": "July **, 19**"
},
"requested_service": "WiFi"
}
```
The PII data will be explicitly displayed unless specified otherwise.
### Limitations
* No default values are supported.
* No arbitrary objects are allowed. All the required values must be specified.
# Sentiment Analysis
Source: https://docs.vatis.tech/audio-intelligence/sentiment-analysis
Perform sentiment analysis over your content
Enable sentiment analysis with the following configuration:
Perform sentiment analysis on the upstream content.
## Pre-recorded
### Usage
```bash
curl -X 'POST' \
'https://http-gateway.vatis.tech/http-gateway/api/v1/upload?streamConfigurationTemplateId=668115d123bca7e3509723d4&sentimentAnalysis=true&persist=true' \
-H 'accept: application/json' \
-H 'Authorization: Basic ' \
-H 'Content-Type: application/octet-stream' \
--data-binary '@test.wav'
```
### Mono audio
```json
{
...
"sentimentAnalysis": {
"segments": [
{
"text": " Good afternoon. My name is Aisha. Thank you for calling *** today. How may I be of assistance?",
"sentiment": "positive",
"startTime": 820,
"endTime": 6120,
"score": 0.9
},
{
"text": " Hi, Aisha. Well, I want to sign up for the Wi-Fi service.",
"sentiment": "positive",
"startTime": 7660,
"endTime": 13460,
"score": 0.5
},
...
],
"summary": {
"negativeCount": 2,
"positiveCount": 21,
"neutralCount": 31,
"averageScore": 0.24444444444444446,
"sentiment": "neutral"
}
}
}
```
### Stereo audio
```json
{
...
"sentimentAnalysis": {
"segments": [
{
"text": " Good afternoon. My name is Aisha. Thank you for calling *** today. How may I be of assistance?",
"sentiment": "positive",
"channel": 0,
"startTime": 1010,
"endTime": 6130,
"score": 0.9
},
{
"text": " Hi, Aisha. Well, I want to sign up for the Wi-Fi service.",
"sentiment": "positive",
"channel": 1,
"startTime": 7660,
"endTime": 24180,
"score": 0.5
},
...
],
"summary": {
"channels": [
{
"channel": 0,
"negativeCount": 0,
"positiveCount": 17,
"neutralCount": 11,
"averageScore": 0.3642857142857143,
"sentiment": "positive"
},
{
"channel": 1,
"negativeCount": 1,
"positiveCount": 10,
"neutralCount": 17,
"averageScore": 0.22142857142857145,
"sentiment": "neutral"
}
],
"negativeCount": 1,
"positiveCount": 27,
"neutralCount": 28,
"averageScore": 0.2928571428571428,
"sentiment": "neutral"
}
}
}
```
## Real-time
The sentiment analysis results can be consumed in real-time.
Each sentiment analysis message will contain either an `utterance sentiment analysis` or a `summary sentiment analysis`.
### Utterance sentiment analysis
The sentiment analysis will be performed for each utterance in the conversation.
```json
{
"promptId": "sentimentAnalysis",
"sequenceId": 0,
"sentimentAnalysis": [
{
"text": " Good afternoon. My name is Aisha. Thank you for calling Verizon today. How may I be of assistance?",
"sentiment": "positive",
"channel": 0,
"startTime": 0,
"endTime": 7679,
"score": 0.8
}
]
}
```
### Summary sentiment analysis
After all the utterances have been processed, a summary sentiment analysis will be provided.
```json
{
"promptId": "sentimentAnalysis",
"sequenceId": 9,
"sentimentAnalysisSummary": {
"channels": [
{
"channel": 1,
"negativeCount": 0,
"positiveCount": 1,
"neutralCount": 3,
"averageScore": 0.2,
"sentiment": "neutral"
},
{
"channel": 0,
"negativeCount": 0,
"positiveCount": 4,
"neutralCount": 1,
"averageScore": 0.52,
"sentiment": "positive"
}
],
"negativeCount": 0,
"positiveCount": 5,
"neutralCount": 4,
"averageScore": 0.3777777777777778,
"sentiment": "positive"
}
}
```
# Summarization
Source: https://docs.vatis.tech/audio-intelligence/summarization
Extract the essentials from your content
Configure the summary with the following options:
Create a summary based on the upstream content.
Summary length. Options are: `brief` or `detailed`.
Summary tone. Options are: `conversational` or `informative`.
Summary structure. Options are: `paragraphs` or `bullet_points`.
## Usage
```bash
curl -X 'POST' \
'https://http-gateway.vatis.tech/http-gateway/api/v1/upload?streamConfigurationTemplateId=668115d123bca7e3509723d4&summary=true&summaryTone=informative&persist=true' \
-H 'accept: application/json' \
-H 'Authorization: Basic ' \
-H 'Content-Type: application/octet-stream' \
--data-binary '@test.wav'
```
## Export Response
```json
{
...
"summary": {
"content": "A customer named George Washington contacted *** to sign up for Wi-Fi service. During the call, he provided his phone number..."
}
}
```
# Get API access
Source: https://docs.vatis.tech/get-started/get-api-access
Get the API key to gain access to the Vatis Streams API
Create an account on the Vatis Tech cloud platform. You can sign up [here](https://vatis.tech/app).
Once you have signed up, you can get the API key from the [API Dashboard](https://vatis.tech/app/playground/transcribe).
Try out our API using the [API Playground](https://vatis.tech/app/playground/transcribe).
# Configuration patches
Source: https://docs.vatis.tech/infrastructure/configuration-patches
Customizing stream execution with configuration patches
## Overview
Each stream is composed by a DAG of processors though which the data is processed.
Each processor has a set of properties that can be configured to customize its behavior.
Those properties are defined inside a stream configuration template, and it can look similar to this:
```json
{
"_id": "674c1f1ea3fc806ecb01df55",
"processors": [
{
"_id": "llm",
"propertiesSchema": "tech.vatis.schema.stream.processor.properties.llm.LlmPropertiesDto",
"properties": {
"summary": {
"enabled": true,
"flushInterval": "300",
"properties": {
"tone": "Conversational",
"length": "Brief",
"structure": "Paragraphs"
}
}
},
...
}
]
}
```
The system follows a **convention over configuration** approach, where the default values are defined in the processor implementation.
Generally, the default values are good enough for most of the cases, but sometimes you may need to customize the behavior of a processor.
For example, you may want to change the tone of the summary generated by the LLM processor from `Conversational` to `Formal`.
This can be done by creating a configuration patch that overrides the default value of the `tone` property.
## Configuration patches
A configuration patch is a JSON Patch that respects the [RFC 6902](https://tools.ietf.org/html/rfc6902) standard, with some imposed limitations.
The limitations are:
* the only supported operations are `add`, `replace`, and `remove`
* it can only apply to the `properties` object of a processor
* the added/replaced values can be either a primitive value or an array of primitive values
The accepted primitive values are:
* string
* number
* boolean
* null
For example, the configuration patch that changes the tone of the summary generated by the LLM processor from `Conversational` to `Formal` looks like this:
```json
[
{
"op": "replace",
"path": "/processors/0/properties/summary/properties/tone",
"value": "Formal"
}
]
```
The json paths can be also expressed using `.`.
For example, `properties.0.properties.tone`, `properties/0/properties/tone` and `/properties/0/properties/tone` are all equivalent paths.
## Specifying patches
The JSON Patch format proposed in the [RFC 6902](https://tools.ietf.org/html/rfc6902) standard is not always suitable for specifying configuration patches.
For this reason, the system allows specifying configuration patches as `query parameters` in the URL (all gateways) or using a configuration message (`WS Gateway` only).
### Query parameters
The query parameters are specified in the URL of the request, and they are used to specify the configuration patches that should be applied to the stream configuration template.
Every patch query parameter can be explicitly marked as a patch by using the `patches.` prefix. If the prefix is not specified, all undocumented query parameters are considered as patches.
For example, the equivalent of this JSON Patch:
```json
[
{
"op": "replace",
"path": "/processors/0/properties/summary/properties/tone",
"value": "Formal"
}
]
```
is the following query parameter:
```
https://gateway.vatis.tech/url?patches.processors.0.properties.summary.properties.tone=Formal
```
or even shorter:
```
https://gateway.vatis.tech/url?processors.0.properties.summary.properties.tone=Formal
```
#### Operation
By default, the operation is `replace`.
To use the `add` operation, prefix the patch value with `+`. For example, to add the `language` property with the value `en`, use the following query parameter:
```
https://gateway.vatis.tech/url?processors.0.properties.summary.properties.language=+en
```
The `replace` operation will behave as the `add` operation if the property does not exist.
So, the equivalent of the previous query parameter is:
```
https://gateway.vatis.tech/url?processors.0.properties.summary.properties.language=en
```
To use the `remove` operation, set the patch value to `-`. For example, to remove the `tone` property, use the following query parameter:
```
https://gateway.vatis.tech/url?processors.0.properties.summary.properties.tone=-
```
To escape the `+` and `-` characters, use the `\` character. For example, to set the `tone` property to `+Formal`, use the following query parameter:
```
https://gateway.vatis.tech/url?processors.0.properties.summary.properties.tone=\+Formal
```
In most of the cases, the `replace` operation is enough, and you don't need to specify it explicitly.
### Configuration message
The configuration message is a WebSocket message sent by the client as an initial message to the `WS Gateway`, with the following structure:
```json
{
"type": "CONFIGURATION",
"patches": {
"": ""
}
}
```
The rules of the configuration patches are the same as for the query parameters.
For example, the configuration message that changes the tone of the summary generated by the LLM processor from `Conversational` to `Formal` looks like this:
```json
{
"type": "CONFIGURATION",
"patches": {
"/processors/0/properties/summary/properties/tone": "Formal"
}
}
```
or using the `.` notation:
```json
{
"type": "CONFIGURATION",
"patches": {
"processors.0.properties.summary.properties.tone": "Formal"
}
}
```
A configuration message can contain as many patches as needed, and without any (reasonable) length limitation.The configuration message can be used alongside the query parameters, and the patches from the configuration message will overwrite the patches from the query parameters.Use the configuration message only when you need to specify a longer value that would not fit in the URL.
## Simplifying paths
### Processor index
Each patch path must contain the index of the processor to which the patch should be applied.
This may be problematic if the processors order is changed, and the indexes are not updated accordingly.
This can be avoided by using the processor ID instead of the index.
For example, the following patch:
```
https://gateway.vatis.tech/url?processors.0.properties.summary.properties.language=en
```
can be rewritten as:
```
https://gateway.vatis.tech/url?processors.llm.properties.summary.properties.language=en
```
### Path alias
Each processor can specify a path alias that can be used to simplify the patch path.
Given the following stream configuration template:
```json
{
"_id": "674c1f1ea3fc806ecb01df55",
"processors": [
{
"_id": "llm",
"propertiesSchema": "tech.vatis.schema.stream.processor.properties.llm.LlmPropertiesDto",
"properties": {
"summary": {
"enabled": true,
"flushInterval": "300",
"properties": {
"tone": "Conversational",
"length": "Brief",
"structure": "Paragraphs"
}
}
},
"patchAliases": {
"summary": "properties/summary/enabled",
"summary_tone": "properties/summary/properties/tone",
"summary_length": "properties/summary/properties/length",
"summary_structure": "properties/summary/properties/structure"
},
...
}
]
}
```
The following patch:
```
https://gateway.vatis.tech/url?processors.0.properties.summary.properties.tone=Formal
```
can be rewritten as:
```
https://gateway.vatis.tech/url?summary_tone=Formal
```
### The equivalence chain
To better understand, we'll take the following example, and we'll rewrite it from the most complex to the simplest form.
Given the following stream configuration template:
```json
{
"_id": "674c1f1ea3fc806ecb01df55",
"processors": [
{
"_id": "llm",
"propertiesSchema": "tech.vatis.schema.stream.processor.properties.llm.LlmPropertiesDto",
"properties": {
"summary": {
"enabled": true,
"flushInterval": "300",
"properties": {
"tone": "Conversational",
"length": "Brief",
"structure": "Paragraphs"
}
}
},
"patchAliases": {
"summary_tone": "properties/summary/properties/tone",
"summary_language": "properties/summary/properties/language"
},
...
}
]
}
```
And the following patch:
```json
[
{
"op": "replace",
"path": "/processors/0/properties/summary/properties/tone",
"value": "Formal"
},
{
"op": "add",
"path": "/processors/0/properties/summary/properties/language",
"value": "en"
}
]
```
The most complex form of the patch is:
```
https://gateway.vatis.tech/url?patches.processors.0.properties.summary.properties.tone=Formal&patches.processors.0.properties.summary.properties.language=+en
```
then we'll infer the redundant `patches.` prefix
```
https://gateway.vatis.tech/url?processors.0.properties.summary.properties.tone=Formal&processors.0.properties.summary.properties.language=+en
```
then we'll substitute the processor index with the processor ID
```
https://gateway.vatis.tech/url?processors.llm.properties.summary.properties.tone=Formal&processors.llm.properties.summary.properties.language=+en
```
then we'll replace the `add` operation for `language` with `replace`
```
https://gateway.vatis.tech/url?processors.llm.properties.summary.properties.tone=Formal&processors.llm.properties.summary.properties.language=en
```
then we'll use the path aliases for `tone` and `language`
```
https://gateway.vatis.tech/url?summary_tone=Formal&summary_language=en
```
## Examples
Given:
```json
{
"_id": "674c1f1ea3fc806ecb01df55",
"processors": [
{
"_id": "llm",
"propertiesSchema": "tech.vatis.schema.stream.processor.properties.llm.LlmPropertiesDto",
"properties": {
"summary": {
"enabled": false,
"flushInterval": "300",
"properties": {
"tone": "Conversational",
"length": "Brief",
"structure": "Paragraphs"
}
}
},
"patchAliases": {
"summary": "properties/summary/enabled"
},
...
}
]
}
```
To enable the summary, use the following query parameter:
```
https://gateway.vatis.tech/url?summary=true
```
Given:
```json
{
"_id": "674c1f1ea3fc806ecb01df55",
"processors": [
{
"_id": "llm",
"propertiesSchema": "tech.vatis.schema.stream.processor.properties.llm.LlmPropertiesDto",
"properties": {
"summary": {
"enabled": false,
"flushInterval": "300",
"properties": {
"tone": "Conversational",
"length": "Brief",
"structure": "Paragraphs"
}
}
},
"patchAliases": {
"summary_language": "properties/summary/properties/language"
},
...
}
]
}
```
To add the summary language, use the following query parameter:
```
https://gateway.vatis.tech/url?summary_language=en
```
Given:
```json
{
"_id": "674c1f1ea3fc806ecb01df55",
"processors": [
{
"_id": "llm",
"propertiesSchema": "tech.vatis.schema.stream.processor.properties.whispergpu.WhisperGpuProcessorPropertiesDto",
"properties": {
"allowedLanguages": null
},
"patchAliases": {
"allowed_languages": "properties/allowedLanguages"
},
...
}
]
}
```
To set the allowed languages to `["en", "fr"]`, use the following query parameter:
```
https://gateway.vatis.tech/url?allowed_languages=en&allowed_languages=fr
```
Given:
```json
{
"_id": "674c1f1ea3fc806ecb01df55",
"processors": [
{
"_id": "llm",
"propertiesSchema": "tech.vatis.schema.stream.processor.properties.llm.LlmPropertiesDto",
"properties": {
"summary": {
"enabled": false,
"flushInterval": "300",
"properties": {
"tone": "Conversational",
"length": "Brief",
"structure": "Paragraphs"
}
}
},
"patchAliases": {
"summary": "properties/summary/enabled",
"summary_tone": "properties/summary/properties/tone"
},
...
}
]
}
```
To enable the summary and set the tone to `Formal`, use the following configuration message:
```json
{
"type": "CONFIGURATION",
"patches": {
"summary": "true",
"summary_tone": "Formal"
}
}
```
# Data retention
Source: https://docs.vatis.tech/infrastructure/data-retention
Data retention policy of the Vatis Streams API
## Overview
The streams created using the Vatis Streams API falls under one of the following categories:
* **ephemeral**: Streams that are created with a retention period of 0 seconds. These stream results are not persisted and are deleted as soon as the last subscriber disconnects.
* **persistent**: Streams that retain the result for a limited period of time.
## Ephemeral streams
This is the default behavior of a stream. It's ideal for real-time usage and mitigates any data privacy concerns by removing all the data in the stream as soon as the last subscriber disconnects, or in up 60 seconds if the data is not consumed.
## Persistent streams
The persistent streams can be used for non-real-time use cases (e.g. file transcription) when the results must be exported all at once.
For this kind of stream, the data is persisted for about 3 hours before being deleted. This time may increase with up to 1 hour depending on the load on the system.
To configure a stream as persistent, use the `persist=true` flag at creation time. The API also provides the means to selectively persist only some of the results.
Please refer to the [OpenAPI specification](https://http-gateway.vatis.tech/swagger-ui/index.html) for more details.
# Export results
Source: https://docs.vatis.tech/infrastructure/diagrams/export-results
Overview of the possible methods to export results from a batch job
This section applies only to batch jobs
# Webhook notification
This is the recommended flow to export results as it does not require constant requests to check stream states, and assures the delivery using the exponential backoff retry mechanism.
This method requires an accessible server to receive the notifications.
```mermaid
sequenceDiagram
participant U as Client
participant NS as Notification Service
participant SS as Stream Service
participant G as Gateway
participant ES as Export Service
rect rgb(82, 82, 82)
note over U, NS: Webhook registration happens only once
U->>+NS: register webhook endpoint
NS->>-U: receive register confirmation
end
U->>G: upload data
G->>SS: create stream
SS->>NS: push event
loop Retry with backoff
NS->>+U: notify webhook
U-x-NS: return error status or fail to respond in time
end
NS->>+U: notify webhook
U->>-NS: return 200 status code
U->>+ES: export results
ES->>-U: return exported results
```
# Polling
Use this method for developing and testing, or when exposing an HTTP server is not possible.
```mermaid
sequenceDiagram
participant U as Client
participant SS as Stream Service
participant G as Gateway
participant ES as Export Service
U->>G: upload data
G->>SS: create stream
loop Poll stream status
U->>+SS: check stream status
SS-x-U: stream no ready
end
U->>+SS: check stream status
SS->>-U: stream completed
U->>+ES: export results
ES->>-U: return exported results
```
# System overview
Source: https://docs.vatis.tech/infrastructure/diagrams/system-overview
Overview of the main flows and components of the system
```mermaid
flowchart TB
gateway("HTTP Gateway")
streamService("Stream Service")
streamConfigurationService("Stream Configuration Service")
egressService("Egress Service")
exportService("Export Service")
sourceStreamingTopic(["Source streaming topic"])
destinationStreamingTopic(["Destination streaming topic"])
processor("Processor")
clientInput((("Input data")))
clientLiveOutput((("Live egress")))
clientExportOutput((("Export output")))
subgraph processingBlock["Processing block"]
direction RL
sourceStreamingTopic-->|4. consume|processor
processor-->|5. output results|destinationStreamingTopic
end
clientInput==>|1. send bytes|gateway
gateway-->|2. create stream|streamService
streamService-->|2.1. fetch stream configuration template|streamConfigurationService
streamConfigurationService-->|2.2. return stream configuration template|streamService
streamService-->|2.3. return stream configuration|gateway
gateway-->|3. publish bytes|sourceStreamingTopic
egressService-->|6.1. consume results|destinationStreamingTopic
clientLiveOutput-->|6.2. receive live results|egressService
exportService-->|7.1. retrieve results|egressService
clientExportOutput-->|7.2. export results|exportService
```
# Stream templates
Source: https://docs.vatis.tech/infrastructure/stream-templates
Overview of the stream configuration templates
## Introduction
In Vatis Streams engine, the first-class entity is a *stream*. A stream is a DAG of processors. This DAG of processors alongside with the configuration of each processor is stored in a **stream configuration template**.
Each stream created using the Vatis Streams API is based on a stream configuration template, that can be patched to modify processors configuration.
## Stream configuration template
A stream configuration template can be (optionally) patched and retrieved using the [**Patch by id endpoint**](/api-reference/stream-configuration/stream-configuration-template-resource-impl/patch-by-id)
An example of a stream configuration template is shown below:
```json
{
"id": "65f46430c6d8985974ff9c9d",
"name": "Ping",
"description": "Simple pipeline for testing stream latency",
"dataSourceSchema": "bytes",
"processors": [
{
"id": "echo",
"name": "echo",
"description": "Echo operation",
"processorDeclaration": {
"id": "echo",
"displayName": "Echo",
"description": "Echo processor. Returns the same message it receives.",
"clusterDomainNameTemplate": "echo-${REPLICA}.echo-headless.stream-processors.svc.cluster.local",
"podsDiscoveryClusterDomainName": "echo-headless.stream-processors.svc.cluster.local",
"revision": "2024-02-06",
"propertiesSchema": "tech.vatis.schema.stream.processor.properties.NoPropertiesDto",
"inputSchemas": [
"bytes"
],
"outputSchema": "bytes",
"features": {
"support": [],
"require": [],
"implement": [],
"requireSupport": []
},
"operationType": "NO_OPERATION"
},
"previousProcessorId": null,
"propertiesSchema": "tech.vatis.schema.stream.processor.properties.NoPropertiesDto",
"properties": {},
"destinationTopicMessageHeaders": {},
"destinationTopicHeaders": {
"X-Vat-Topic-Accept-Frame-Type": "final"
},
"sourceSubscriptionHeaders": {
"X-Vat-Sub-Accept-Frame-Type": "final"
},
"patchAliases": {},
"egress": {
"persist": false,
"sink": false,
"tags": []
}
}
],
"patchAliases": {}
}
```
This stream configuration template can produce a stream similar to the one shown below:
```json
{
"streamId": "20d36912-f746-4f45-8e68-d537fc1ff57f",
"name": "Stream jokidx",
"groupId": "20d36912-f746-4f45-8e68-d537fc1ff57f",
"configuration": {
"streamConfigurationTemplateId": "65f46430c6d8985974ff9c9d",
"dataSource": {
"topic": "persistent://vatis-streams/data-sources/4c43a454-32b4-4ef4-baa9-3442f5fecc90",
"messageSchema": "bytes",
"connectionOptions": {
"X-Vat-Topic-Conn-Close-On-Disconnect": "true"
},
"headers": {
"X-Vat-Topic-Accept-Frame-Type": "final"
},
"messageHeaders": {
"X-Vat-Stream-Frame-Type": "final",
"X-Vat-Stream-Processor-Id": "gateway"
},
"subscriptions": {
"echo": {
"subscription": "echo-ZlejK",
"topic": "persistent://vatis-streams/data-sources/4c43a454-32b4-4ef4-baa9-3442f5fecc90",
"messageSchema": "bytes",
"connectionOptions": {},
"headers": {
"X-Vat-Sub-Accept-Frame-Type": "final"
}
}
}
},
"dataSinks": {
"echo": {
"topic": "persistent://vatis-streams/persistent-data-sinks/f8eeb155-d496-4746-b949-94ae05426544",
"messageSchema": "bytes",
"connectionOptions": {},
"headers": {
"X-Vat-Topic-Accept-Frame-Type": "final"
},
"messageHeaders": {
"X-Vat-Stream-Egress-Tags": "echo,main",
"X-Vat-Stream-Id": "20d36912-f746-4f45-8e68-d537fc1ff57f",
"X-Vat-Stream-Group-Id": "20d36912-f746-4f45-8e68-d537fc1ff57f",
"X-Vat-Stream-Schema": "bytes",
"X-Vat-Stream-Processor-Id": "echo"
},
"subscriptions": {}
}
},
"processors": [
{
"id": "echo",
"source": {
"subscription": "echo-ZlejK",
"topic": "persistent://vatis-streams/data-sources/4c43a454-32b4-4ef4-baa9-3442f5fecc90",
"messageSchema": "bytes",
"connectionOptions": {},
"headers": {
"X-Vat-Sub-Accept-Frame-Type": "final"
}
},
"destination": {
"topic": "persistent://vatis-streams/persistent-data-sinks/f8eeb155-d496-4746-b949-94ae05426544",
"messageSchema": "bytes",
"connectionOptions": {},
"headers": {
"X-Vat-Topic-Accept-Frame-Type": "final"
},
"messageHeaders": {
"X-Vat-Stream-Egress-Tags": "echo,main",
"X-Vat-Stream-Id": "20d36912-f746-4f45-8e68-d537fc1ff57f",
"X-Vat-Stream-Group-Id": "20d36912-f746-4f45-8e68-d537fc1ff57f",
"X-Vat-Stream-Schema": "bytes",
"X-Vat-Stream-Processor-Id": "echo"
},
"subscriptions": {}
},
"clusterDomainName": "echo-0.echo-headless.stream-processors.svc.cluster.local",
"podsDiscoveryClusterDomainName": "echo-headless.stream-processors.svc.cluster.local",
"propertiesSchema": "tech.vatis.schema.stream.processor.properties.NoPropertiesDto",
"properties": {},
"egress": {
"persist": true,
"sink": true,
"tags": [
"main",
"echo"
]
}
}
]
},
"createdTimestamp": "2024-12-12T18:47:06.865Z",
"creatorId": "d710a067-daf3-460d-9e60-01d0bb8d10c4",
"groupCreatorId": "d710a067-daf3-460d-9e60-01d0bb8d10c4",
"state": "READY",
"stateDescription": null,
"finalizedTimestamp": null
}
```
The Vatis Streams API provides a set of pre-defined stream configuration templates that can be used out-of-the-box for use-cases like Speech-to-Text, Audio Intelligence, Real-time transcoding, etc.
## Streams
When a stream is created, it requires a stream configuration template id. This can be specified using the `streamConfigurationTemplateId` query parameter set in the connection URL.
# Inspect errors
Source: https://docs.vatis.tech/infrastructure/streams/inspect-errors
Debug a failed stream by inspecting its errors
## Overview
A stream error is a signal that something went wrong in the stream. It can occur in one of the following stream stages:
* during stream creation
* during stream processing
In this guide, you will learn how to inspect errors in a stream based on the stage it occurred.
## Stream creation errors
A stream creation error is an error that can be determined ahead of time, before the stream starts processing. It can occur due to various reasons, such as:
* invalid stream configuration
* maximum number of concurrent streams reached
* insufficient compute capacity
* authn or authz errors
The stream creation error may occur only in the upload phase, and it will result in a non-2xx HTTP status code.
The response body will be a standard [Error Response](/api-reference/schemas/error/error-response) JSON object, which can look like this:
```json
{
"statusCode": 400,
"title": "Invalid stream configuration",
"message": "Forbidden patch: /langs",
"internalErrorName": "STREAM_CONFIGURATION_BAD_PATCH",
"nestedErrors": []
}
```
## Stream processing errors
A stream processing error is an asynchronous error that occurs during the stream processing phase due to request data processing problems. It can occur due to various reasons, such as:
* invalid or missing request data
* unsupported payload type
* payload too large
An asynchronous error will cause the stream to enter in the `FAILED` state, and it can be identified either by regularly polling the [stream state](/api-reference/streams/stream-resource-impl/find-by-id) or receiving a `stream.failed` webhook notification.
The error details can be extracted from the [stream components state](/api-reference/streams/stream-resource-impl/get-components). The response can look like this:
```json
{
"streamId": "46df931a-3622-4c39-80fe-70d636e99ba5",
"groupId": "46df931a-3622-4c39-80fe-70d636e99ba5",
"state": "FAILED",
"stateDescription": null,
"stateChangedTimestamp": "2025-02-19T04:42:32.344Z",
"gateway": {
"state": "CLOSED",
"stateChangedTimestamp": "2025-02-19T04:42:28.037Z"
},
"processors": [
{
"processorId": "transcriber",
"state": "ERROR",
"stateChangedTimestamp": "2025-02-19T04:42:32.328Z",
"stateDescription": "External close signal received"
},
{
"processorId": "diarization",
"state": "ERROR",
"stateChangedTimestamp": "2025-02-19T04:42:32.298Z",
"stateDescription": "[InternalErrorName.GENERAL_INTERNAL_ERROR] JobFailedException: Job 5fb5614f-8959-409f-931f-3f9a4f233130-e1 failed with status FAILED: [Errno 1094995529] Invalid data found when processing input: ..."
},
{
"processorId": "llm",
"state": "COMPLETED",
"stateChangedTimestamp": "2025-02-19T04:42:28.027Z",
"stateDescription": "Stream has no prompt enabled"
}
]
}
```
Here we can see that the `transcriber` and `diarization` processors are in the `ERROR` state. The `stateDescription` field provides additional information about the error.
The `External close signal received` message indicates that the processor was closed by either a cancel action from the user or from an automatic cancel due to other processor failure in the same pipeline.
# Export
Source: https://docs.vatis.tech/integration/export
Export results from one or multiple streams in various formats
## Overview
The Vatis Streams API is designed to egress the results from one or multiple streams in real-time as JSON events or as bytes.
This means the client will receive the results in the fastest way possible, but it also means that the client needs to reconstruct the final results based on the received events.
In some scenarios, the client will not need the data in real-time, but rather in a more structured format.
For these cases, the Vatis Streams API provides an **export functionality** that handles this layer of complexity
and allows the client to export the results from one or multiple streams in various formats.
## Formats
Currently, the single format supported is `JSON`. The exact structure of the JSON response is determined by the aggregated event type from the stream(s).
Please refer to the [export OpenAPI specification](https://export-service.vatis.tech/swagger-ui/index.html) for more details.
## When to export?
Although the export functionality is available at any time after the stream was created, it is recommended to export the results only after the stream has finished.
This is because the export functionality will return the results in a single response, so the blocking connection may time out if it's long-running stream.
To find out when a stream is completed, either us the [webhook integration](/integration/webhooks) or stream status polling.
Perform the export before the stream expires, as describe in [data retention](/infrastructure/data-retention)
## Considerations
* only non-raw results can be used as part of the export functionality
* the export functionality works only with [persistent streams](/infrastructure/data-retention)
# Webhooks
Source: https://docs.vatis.tech/integration/webhooks
Listen to events on your resources with webhooks.
## Overview
When integrating the Vatis Streams API you may need to listen to events on your resources, so your application can react accordingly.
To do this, you can register a webhook endpoint containing the URL where you want to receive the events and the type of events the endpoint is listening to.
When an event is triggered, a `POST` request will be sent to all the registered endpoints with the event data.
## Setup
Manage your webhooks through the [API Dashboard](https://vatis.tech/app/playground/webhooks).
## Webhook structure
The webhook endpoint you can define will have the following structure:
```json
{
"id": "",
"url": "",
"events": [
""
],
"enabled": true,
"description": ""
}
```
| Property | Description |
| ------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `id` | The webhook endpoint identifier |
| `url` | The URL where the events will be sent. Accepted protocols: `HTTP`, `HTTPS` |
| `events` | The list of event types the endpoint is listening to. Check the avaiable event types [here](#event-types) |
| `enabled` | Indicates if the webhook is enabled. You can disable an endpoint to temporarily stop receiving requests to the endpoint |
| `description` | An optional description of the webhook |
Local IP addresses and loopback interfaces are not allowed in the `url`
## Event structure
The webhook event you'll receive will have the following structure:
```json
{
"id": "",
"type": "",
"webhookEndpointId": "",
"timestamp": "",
"payloadSchema": "",
"payload": "