Account - REST API

Stenomatic REST API

Clients

Create a Client

Request:

curl https://api.stenomatic.ai/v1/clients \
   --request POST \
   --header 'Authorization: Bearer YOUR_DEVELOPER_API_KEY_HERE' \
   --header 'Content-Type: application/json' \
   --data '{"name": "ADD_CUSTOMER_NAME_HERE"}' 

Response:

{
   "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "name":"John Doe",
   "parent_customer_id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

List Clients

Request:

curl https://api.stenomatic.ai/v1/clients \
   --request GET \
   --header 'Authorization: Bearer YOUR_DEVELOPER_API_KEY_HERE' \
   --header 'Content-Type: application/json'

Response:

[
   {
       "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
       "name":"John Doe",
       "parent_customer_id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
   }
]

Rooms

Create, update, remove or retrieve rooms.

Create Room for given Client ID

The room id is an optional parameter that is only enabled for customers with sufficient privileges. Please refer to the upgrade section. The id must match the ^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$ regex pattern of words delimited with hyphens. If no id is provided, it will be automatically generated. The room id must be unique across all existing room id's.

Request:

curl https://api.stenomatic.ai/v1/clients/{client_id}/rooms \
   --request POST \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer YOUR_DEVELOPER_API_KEY_HERE' \
   --data '{
       "id":"xxx-xxxx-xxx",
       "title":"Test room",
       "description":"This is a test room",
       "to_languages":[
           "en-US",
           "de-DE",
           "fr-FR"
       ],
       "sponsorship_credit_title":"Sponsorship credit title",
       "sponsorship_title":"Sponsorship title",
       "sponsorship_description":"Sponsorship description",
       "sponsorship_info_url":"example.com",
       "passwords":{
           "speaker":"xxxxxxxx",
           "participant":"xxxxxxxx"
       },
       "allow_transcription_persistence": false,
       "custom_speech_recognition_model": "default",
       "enable_only_final_translate": false,
       "region": "default",
       "fast_tts_version": 1001,       
       "is_video_supported": false
   }' 
   
## Supported "custom_speech_recognition_model" values are "default" and "experimental".
## Supported "region" values are "default" and "southeastasia".
## Supported "fast_tts_version" values are 0, 1001 and 1002. 1001 is default, 0 is without TTS latency optimization, 1002 is stronger optimization

Response:

{
   "id":"xxx-xxxx-xxx",
   "conference_id":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "title":"Test room",
   "description":"This is a test room",
   "api_key":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "secret":"",
   "client_branch_id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "to_languages":[
      "en-US",
      "de-DE",
      "fr-FR"
   ],
   "start_date":"0001-01-01T00:00:00.000Z",
   "end_date":"0001-01-01T00:00:00.000Z",
   "create_date":"2023-04-13T13:41:35.137Z",
   "update_date":"2023-04-13T13:41:35.137Z",
   "main_image_url":"",
   "main_image_bucket_file_name":"",
   "sponsorship_image_bucket_file_name":"",
   "sponsorship_credit_title":"Sponsorship credit title",
   "sponsorship_title":"Sponsorship title",
   "sponsorship_description":"Sponsorship description",
   "sponsorship_info_url":"example.com",
   "sponsorship_image_url":"",
   "closed_captions_endpoint":"",
   "fast_tts_version": 1001,
   "allow_transcription_persistence": false,
   "custom_speech_recognition_model": "default",
   "usage_in_seconds":{
      "total":0,
      "twenty_four_hour":0
   },
   "is_video_supported": false,
   "enable_only_final_translate": false,
   "region": "default",
   "disable_logo": false,
   "history_threshold_date": "0001-01-01T00:00:00.000Z",
   "is_archived":false
}

Create room for your own client ID

Request:

curl https://api.stenomatic.ai/v1/clients/me/rooms \
   --request POST \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer YOUR_DEVELOPER_API_KEY_HERE' \
   --data '{
       "id":"xxx-xxxx-xxx",
       "title":"Test room",
       "description":"This is a test room",
       "to_languages":[
           "en-US",
           "de-DE",
           "fr-FR"
       ],
       "sponsorship_credit_title":"Sponsorship credit title",
       "sponsorship_title":"Sponsorship title",
       "sponsorship_description":"Sponsorship description",
       "sponsorship_info_url":"example.com",
       "passwords":{
           "speaker":"xxxxxxxx",
           "participant":"xxxxxxxx"
       },
       "allow_transcription_persistence": false,
       "custom_speech_recognition_model": "default",
       "enable_only_final_translate": false,
       "region": "default",
       "fast_tts_version": 1001,       
       "is_video_supported": false  
   }'

Response:

{
   "id":"xxx-xxxx-xxx",
   "conference_id":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "title":"Test room",
   "description":"This is a test room",
   "api_key":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "secret":"",
   "client_branch_id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "to_languages":[
      "de-DE",
      "fr-FR"
   ],
   "start_date":"0001-01-01T00:00:00.000Z",
   "end_date":"0001-01-01T00:00:00.000Z",
   "create_date":"2023-04-13T13:41:35.137Z",
   "update_date":"2023-04-13T13:41:35.137Z",
   "main_image_url":"",
   "main_image_bucket_file_name":"",
   "sponsorship_image_bucket_file_name":"",
   "sponsorship_credit_title":"Sponsorship credit title",
   "sponsorship_title":"Sponsorship title",
   "sponsorship_description":"Sponsorship description",
   "sponsorship_info_url":"example.com",
   "sponsorship_image_url":"",
   "closed_captions_endpoint":"",
   "fast_tts_version": 1001,
   "allow_transcription_persistence": false,
   "custom_speech_recognition_model": "default",
   "usage_in_seconds":{
      "total":0,
      "twenty_four_hour":0
   },
   "is_video_supported": false,
   "enable_only_final_translate": false,
   "region": "default",
   "disable_logo": false,
   "history_threshold_date": "0001-01-01T00:00:00.000Z",
   "is_archived":false
}

List rooms for given Client ID

Request:

curl https://api.stenomatic.ai/v1/clients/{client_id}/rooms \
   --request GET \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer YOUR_DEVELOPER_API_KEY_HERE' \

Response:

[ 
   {
      "id":"xxx-xxxx-xxx",
      "conference_id":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "title":"Test room",
      "description":"This is a test room",
      "api_key":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "secret":"xxxxxxxxxxx",
      "client_branch_id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "to_languages":[
         "en-US",
         "de-DE",
         "fr-FR"
      ],
      "start_date":"0001-01-01T00:00:00.000Z",
      "end_date":"0001-01-01T00:00:00.000Z",
      "create_date":"2023-04-13T13:41:35.137Z",
      "update_date":"2023-04-13T13:41:35.137Z",
      "main_image_url":"",
      "main_image_bucket_file_name":"",
      "sponsorship_image_bucket_file_name":"",
      "sponsorship_credit_title":"Sponsorship credit title",
      "sponsorship_title":"Sponsorship title",
      "sponsorship_description":"Sponsorship description",
      "sponsorship_info_url":"example.com",
      "sponsorship_image_url":"",
      "closed_captions_endpoint":"",
      "fast_tts_version": 1001,
      "allow_transcription_persistence": true,
      "custom_speech_recognition_model": "experimental",
      "usage_in_seconds":{
         "total":0,
         "twenty_four_hour":0
      },
      "is_video_supported": false,
      "enable_only_final_translate": false,
      "region": "default",
      "disable_logo": false,
      "history_threshold_date": "0001-01-01T00:00:00.000Z",
      "is_archived":false
   },]

List rooms for your own Client ID

Request

curl https://api.stenomatic.ai/v1/clients/me/rooms \
   --request GET \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer YOUR_DEVELOPER_API_KEY_HERE' \

Response:

[ 
   {
      "id":"xxx-xxxx-xxx",
      "conference_id":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "title":"Test room",
      "description":"This is a test room",
      "api_key":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "secret":"xxxxxxxxxxx",
      "client_branch_id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "to_languages":[
         "de-DE",
         "fr-FR"
      ],
      "start_date":"0001-01-01T00:00:00.000Z",
      "end_date":"0001-01-01T00:00:00.000Z",
      "create_date":"2023-04-13T13:41:35.137Z",
      "update_date":"2023-04-13T13:41:35.137Z",
      "main_image_url":"",
      "main_image_bucket_file_name":"",
      "sponsorship_image_bucket_file_name":"",
      "sponsorship_credit_title":"Sponsorship credit title",
      "sponsorship_title":"Sponsorship title",
      "sponsorship_description":"Sponsorship description",
      "sponsorship_info_url":"example.com",
      "sponsorship_image_url":"",
      "closed_captions_endpoint":"",
      "fast_tts_version": 1001,
      "allow_transcription_persistence": true,
      "custom_speech_recognition_model": "experimental",
      "usage_in_seconds":{
         "total":0,
         "twenty_four_hour":0
      },
      "is_video_supported": false,
      "enable_only_final_translate": false,
      "region": "default",
      "disable_logo": false,
      "history_threshold_date": "0001-01-01T00:00:00.000Z",
      "is_archived":false
   }
]

Retrieve Room

Request:

curl https://api.stenomatic.ai/v1/rooms/{room_id} \
   --request GET \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer YOUR_DEVELOPER_API_KEY_HERE' \

Response:

{
   "id":"xxx-xxxx-xxx",
   "conference_id":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "title":"Test room",
   "description":"This is a test room",
   "api_key":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "secret":"xxxxxxxxxxx",
   "client_branch_id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "to_languages":[
      "en-US",
      "de-DE",
      "fr-FR"
   ],
   "start_date":"0001-01-01T00:00:00.000Z",
   "end_date":"0001-01-01T00:00:00.000Z",
   "create_date":"2023-04-13T13:41:35.137Z",
   "update_date":"2023-04-13T13:41:35.137Z",
   "main_image_url":"",
   "main_image_bucket_file_name":"",
   "sponsorship_image_bucket_file_name":"",
   "sponsorship_credit_title":"Sponsorship credit title",
   "sponsorship_title":"Sponsorship title",
   "sponsorship_description":"Sponsorship description",
   "sponsorship_info_url":"example.com",
   "sponsorship_image_url":"",
   "closed_captions_endpoint":"",
   "fast_tts_version": 1001,
   "allow_transcription_persistence": true,
   "custom_speech_recognition_model": "experimental",      
   "usage_in_seconds":{
      "total":0,
      "twenty_four_hour":0
   },
   "is_video_supported": false,
   "enable_only_final_translate": false,
   "region": "default",
   "disable_logo": false,
   "history_threshold_date": "0001-01-01T00:00:00.000Z",
   "is_archived":false
}

Retrieve Passwords

Request:

curl https://api.stenomatic.ai/v1/rooms/{room_id}/passwords \
   --request GET \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer YOUR_DEVELOPER_API_KEY_HERE' \

Response:

{
   "speaker":"xxxxxxxx",
   "participant":"xxxxxxxx"
}

Retrieve RTMP Stream URL

Request:

curl https://api.stenomatic.ai/v1/rooms/{room_id}/stream_url \
   --request POST \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer YOUR_DEVELOPER_API_KEY_HERE' \
   --data '{
       "speaker_name": "John Doe",
       "language": "en-GB",
       "phrases": [
           "phrase 1",
           "phrase 2"
       ]
   }'

Response:

{
  "url": "rtmps://rtmp.stenomatic.com/z?lang=en-GB&name=John+Doe&phrases=phrase+1&phrases=phrase+2"},
  "stream_key": "xxxxxxxxxxx"
}

Update Room

Request:

curl https://api.stenomatic.ai/v1/rooms/{room_id} \
   --request PATCH \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer YOUR_DEVELOPER_API_KEY_HERE' \
   --data '{
     "title": "Board meeting updated",
     "description": "Updated description",
     "to_languages": ["en-US", "de-DE", "fr-FR"],
     "start_date": "2026-03-12T09:30:00Z",
     "end_date": "2026-03-12T11:30:00Z",
     "sponsorship_credit_title": "Sponsored by",
     "sponsorship_title": "Example Corp",
     "sponsorship_description": "Updated sponsor text",
     "sponsorship_info_url": "https://example.com/info",
     "closed_captions_endpoint": "-",
     "passwords": {
       "speaker": "new-speaker-pass",
       "participant": "new-participant-pass"
     },
     "is_archived": false,
     "fast_tts_version": 1002,
     "allow_transcription_persistence": true,
     "extras": {
       "boost": ["Stenomatic"],
       "block": {
         "en-US": ["wrongword"]
       },
       "replace": {
         "stm": "Stenomatic"
       }
     },
     "enable_only_final_translate": true,
     "region": "southeastasia",
     "custom_speech_recognition_model": "experimental",
     "disable_logo": true,
     "history_threshold_date": "2026-03-01T00:00:00Z",
     "update_date": "2026-03-12T08:00:00Z",
   }'

## all parameters, except update_date, are optional and only change when specified
## update_date is required and needs to be exactly the same as the one you get from the Retrieve Room API call.

Response:

{
   "id":"xxx-xxxx-xxx",
   "conference_id":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "title":"The room",
   "description":"This is a test room",
   "api_key":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "secret":"",
   "client_branch_id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "to_languages":[
      "en-US",
      "de-DE",
      "fr-FR"
   ],
   "start_date":"0001-01-01T00:00:00.000Z",
   "end_date":"0001-01-01T00:00:00.000Z",
   "create_date":"2023-04-13T13:41:35.137Z",
   "update_date":"2023-04-13T13:41:35.137Z",
   "main_image_url":"",
   "main_image_bucket_file_name":"",
   "sponsorship_image_bucket_file_name":"",
   "sponsorship_credit_title":"Sponsorship credit title",
   "sponsorship_title":"Sponsorship title",
   "sponsorship_description":"Sponsorship description",
   "sponsorship_info_url":"example.com",
   "sponsorship_image_url":"",
   "closed_captions_endpoint":"",
   "usage_in_seconds":{
      "total":0,
      "twenty_four_hour":0
   },
   "fast_tts_version": 1002,
   "allow_transcription_persistence": true,
   "extras": {
      "boost": ["Stenomatic"],
      "block": {
         "en-US": ["wrongword"]
      },
      "replace": {
         "stm": "Stenomatic"
      }
   },
   "enable_only_final_translate": true,
   "region": "southeastasia",
   "custom_speech_recognition_model": "experimental",
   "disable_logo": true,
   "is_archived": false
}

Usage

Retrieve all API usages for myself as a Customer

curl https://api.stenomatic.ai/v1/customers/me/api_usage?from={timestamp_in_milliseconds}&to={timestamp_in_milliseconds} \
   --request GET \
   --header 'Authorization: Bearer YOUR_DEVELOPER_API_KEY_HERE' \
   --header 'Content-Type: application/json'

Retrieve API usages for a Client created under my Customer

curl https://api.stenomatic.ai/v1/clients/{client_id}/api_usage?from={timestamp_in_milliseconds}&to={timestamp_in_milliseconds} \
   --request GET \
   --header 'Authorization: Bearer YOUR_DEVELOPER_API_KEY_HERE' \
   --header 'Content-Type: application/json'

Retrieve API usages for me as client

curl https://api.stenomatic.ai/v1/clients/me/api_usage?from={timestamp_in_milliseconds}&to={timestamp_in_milliseconds} \
   --request GET \
   --header 'Authorization: Bearer YOUR_DEVELOPER_API_KEY_HERE' \
   --header 'Content-Type: application/json'

Response

Returns API usages in nanoseconds (if they are greater than zero)

{
    "speech_recognition":56960000000,
    "voice_translate":32840000000 
}

Transcriptions

Retrieve Transcriptions

Request:

curl https://api.stenomatic.ai/v1/transcriptions?start_time={timestamp_in_milliseconds} \
   --request GET \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer YOUR_STREAM_API_KEY_HERE' \

Response:

Speaker name,Speaker language,Dialects for translation,Start time,End time,Start time in millis,End time in millis,Recognition,de-DE
John Doe,en-GB,de-DE,2024-10-15 10:56:06.277253 +0000 UTC,2024-10-15 10:56:08.927933 +0000 UTC,1728989766277,1728989768927,"Hello computer.","Hallo computer."