NAV
shell javascript

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "https://www.happyscribe.com/api/v1/transcriptions" \
  -H "Authorization: Bearer **your_api_key_here**"

fetch('https://www.happyscribe.com/api/v1/transcriptions', {
  headers: {
    authorization: 'Bearer **your_api_key_here**'
  }
})

Make sure to replace **your_api_key_here** with your API key.

Happy Scribe uses a different API key to allow access to each different API. You can get your Product API key by logging in and going to your "Account" page.

HappyScribe expects the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer **your_api_key_here**"

Uploads

When creating a transcription, a media file URL (accessible to our servers) must be provided.
This can be a publicly accessible URL hosted by you or a third party. We also support public links from services like YouTube and Vimeo. Alternatively, you can upload files directly to our storage system (AWS S3 bucket) and create the transcription using the returned URL.

To upload files to our AWS S3 bucket, you must first request a signed URL using the endpoints below.

1. Get a Signed Url

curl "https://www.happyscribe.com/api/v1/uploads/new?filename=my_media.mp3" \
  -H "Authorization: Bearer **your_api_key_here**"


fetch('https://www.happyscribe.com/api/v1/uploads/new?filename=my_media.mp3', {
  headers: {
    authorization: 'Bearer **your_api_key_here**',
  }
})

The above command returns JSON structured like this:

{
  "signedUrl": "https://happy-scribe-domain.s3.eu-west-1.amazonaws.com/xxxxxx?x-amx-signature=xxxxx..."
}

This endpoint returns a signed URL which can be used to make PUT requests to our S3 bucket. More information here: docs.aws.amazon.com

Once the file is uploaded, this same URL should be used as the tmp_url when creating the associated transcription.

HTTP Request

GET https://www.happyscribe.com/api/v1/uploads/new

Parameters

Parameter Description
filename (required) The filename and extension of the media file (e.g. my_media.mp3)

2. Upload your file with the Signed Url

curl -X PUT -T my_media.mp3 -L https://signed-url...

fetch('https://signed-url...', {
    method: 'PUT',
    body: my_media_data // This should be a Blob or File object representing my_media.mp3
})

Simple upload to an AWS S3 Bucket

Once you have a signed URL, you have to upload the file there, and you do it as you would with any AWS S3 bucket.

To upload a file to the signed URL you may use cURL like the example on the right.

Here you have more information about how to deal with AWS S3 signed URLs docs.aws.amazon.com.

Transcriptions

List All Transcriptions

curl "https://www.happyscribe.com/api/v1/transcriptions" \
  -H "Authorization: Bearer **your_api_key_here**"

fetch('https://www.happyscribe.com/api/v1/transcriptions', {
  headers: {
    authorization: 'Bearer **your_api_key_here**'
  }
})

The above command returns JSON structured like this:

{
    "results": [
        {
            "id": "e458099e7f8da14f9625854ba7b6a026917ad306",
            "name": "interview1.mov",
            "createdAt": "2024-10-29T14:31:29.799Z",
            "updatedAt": "2024-10-29T14:31:38.495Z",
            "state": "automatic_done",
            "sharingEnabled": false,
            "language": "en-GB",
            "audioLengthInSeconds": 42,
            "_links": {
              "self": {
                "url": "https://www.happyscribe.com/api/v1/transcriptions/e458099e7f8da14f9625854ba7b6a026917ad306"
              }
            },
            "tags": ["To do"],
        },
        {
            "id": "9jossdjdf09j309omsldknslkjndfjknsdfs",
            "name": "interview2.mov",
            "createdAt": "2024-10-29T14:31:29.799Z",
            "updatedAt": "2024-10-29T14:31:38.495Z",
            "state": "automatic_done",
            "sharingEnabled": false,
            "language": "en-GB",
            "audioLengthInSeconds": 42,
            "_links": {
              "self": {
                "url": "https://www.happyscribe.com/api/v1/transcriptions/9jossdjdf09j309omsldknslkjndfjknsdfs"
              }
            },
            "tags": [],
        },
        ...
    ],
    "_links": {
      "next": {
        "url": "https://www.happyscribe.com/api/v1/transcriptions?page=2"
      }
    }
}

Returns a list of transcriptions you’ve previously created. The transcriptions are returned in sorted order, with the most recent charges appearing first. The information returned is metadata about each transcription, not the actual transcript. To retrieve a specific transcript you have to use the export endpoint.

HTTP Request

GET https://www.happyscribe.com/api/v1/transcriptions

Query Parameters

Parameter Default Description
organization_id - (required) Id of the organization to get the transcriptions from
folder_id All folders When set, filters the list to transcriptions that are inside the specified folder or its subfolders. To get the folder id, navigate to the given folder in the web application and copy the id from the URL.
page 0 Request a specific page

Create a Transcription

curl -X POST "https://www.happyscribe.com/api/v1/transcriptions" \
  -H "Authorization: Bearer **your_api_key_here**" \
  -H "Content-Type: application/json" \
  -d '{
    "transcription": {
        "name": "My Interview",
        "language": "en-GB",
        "tmp_url": "https://example.com/my_media.mp3",
        "is_subtitle": false,
        "organization_id": "413",
        "folder_id": "521"
      }
    }'


fetch('https://www.happyscribe.com/api/v1/transcriptions', {
  method: 'POST',
  headers: {
    authorization: 'Bearer **your_api_key_here**',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    transcription: {
      name: 'My Interview',
      language: 'en-GB',
      tmp_url: 'https://example.com/my_media.mp3',
      is_subtitle: false,
      organization_id: '413'
    }
  })
})

The above command returns JSON structured like this:

{
  "id": "9josdjdfo09j309omsldknslkjndfjknsdfs",
  "name": "My Interview",
  "createdAt": "2024-10-29T14:31:29.799Z",
  "updatedAt": "2024-10-29T14:31:38.495Z",
  "sharingEnabled": false,
  "state": "ingesting",
  "language": "en-GB",
  "_links": {
    "self": {
      "url": "https://www.happyscribe.com/api/v1/transcriptions/f6511f81s5611daede28dc85f25a796ae7996d11"
    },
  }
}

This endpoint creates a new transcription. After a transcription is created, the system will proceed to automatically transcribe it. You can watch if the transcription process has finished by retrieving a transcription.

HTTP Request

POST https://www.happyscribe.com/api/v1/transcriptions

Parameters

Parameter Type Description
name String (required) Name of the transcription
language String (required) BCP-47 language code. Full list here
tmp_url String (required) A url where the media file is located and can be retrieved by our server.
is_subtitle Boolean (default: false) If set to true, we will treat this transcription as subtitles.
service String auto(default) : Machine generated transcription/subtitles.
pro : transcription/subtitles hand-crafted by human professionals.
alignment: Align the text provided in document_url with the media from tmp_url
Note: check the supported languages.
organization_id String (required) Id of the organization to save the transcription in.
folder String (optional) Path of the folder to save the transcription in. Example: path/to/my folder.
folder_id String (optional) Id of the folder to save the transcription in.
document_url String (only for alignment ) An accessible url to a plain text document that needs to be aligned with the media provided in tmp_url.
sharing_enabled Boolean (default: false) If set to true, everyone with the editor url will be able to access it.

Retrieve a Transcription

curl "https://www.happyscribe.com/api/v1/transcriptions/<ID>" \
  -H "Authorization: Bearer **your_api_key_here**"

fetch('https://www.happyscribe.com/api/v1/transcriptions/<ID>', {
  headers: {
    authorization: 'Bearer **your_api_key_here**'
  }
})

The above command returns JSON structured like this:

{
  "id": "9josdjdfo09j309omsldknslkjndfjknsdfs",
  "name": "interview2.mov",
  "createdAt": "2024-10-29T14:31:29.799Z",
  "updatedAt": "2024-10-29T14:31:38.495Z",
  "failureReason": null,
  "sharingEnabled": false,
  "state": "automatic_done",
  "language": "en-GB",
  "audioLengthInSeconds": 42,
  "soundwaveUrl":"https://hs-soundwaves-prod.s3-eu-west-1.amazonaws.com/e4c8e370a92aafb8b03da708c5016bb6-10.dat",
  "_links": {
    "self": {
      "url": "https://www.happyscribe.com/api/v1/transcriptions/f6511f81156114aede28dc85325a796ae7996d11"
    },
    "editor": {
      "url": "https://www.happyscribe.com/transcriptions/9josdjdfo09j309omsldknslkjndfjknsdfs/edit_v2",
    },
  }
}

This endpoint retrieves information about a specific transcription. To retrieve the transcript you have to use the export endpoint.

HTTP Request

GET https://www.happyscribe.com/api/v1/transcriptions/<ID>

Soundwave

It's only generated for subtitles ("is_subtitle": true). The soundwaveUrl is not available until the state is automatic_done

Additional transcription properties

Value Description
deliveryEstimatedAt Estimated time for the transcription to be delivered. It can change over time.
failureReason Error code for the failure.
failureMessage User friendly message explaining the failure root cause.

Transcription State Descriptions

Value Description
initial Transcription is waiting to be processed
ingesting Media file is being ingested
automatic_transcribing Audio is being transcribed to text
automatic_done Transcription is finished and ready to export!
aligning Text is being realigned with the audio
locked Transcription is locked due to insufficient credits
failed File failed to process
demo The initial demo file

Delete a Transcription

curl -X DELETE "https://www.happyscribe.com/api/v1/transcriptions/<ID>" \
  -H "Authorization: Bearer **your_api_key_here**"

fetch('https://www.happyscribe.com/api/v1/transcriptions/<ID>', {
  headers: {
    authorization: 'Bearer **your_api_key_here**'
  }
})

This endpoint deletes a transcription.

HTTP Request

DELETE https://www.happyscribe.com/api/v1/transcriptions/<ID>

Query Parameters

Parameter Default Description
permanent false When set to "true" the action is irreversible. Otherwise, the transcription can be found in the Trash.

Exports

Create an Export

curl -X POST "https://www.happyscribe.com/api/v1/exports" \
  -H "Authorization: Bearer **your_api_key_here**" \
  -H 'Content-Type: application/json' \
  -d '{
    "export": {
      "format": "txt",
      "transcription_ids": [
        "**transcription_id_1**"
      ]
    }
  }'


fetch('https://www.happyscribe.com/api/v1/exports', {
  method: 'POST',
  headers: {
    authorization: 'Bearer **your_api_key_here**',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    export: {
      format: 'txt', 
      transcription_ids: 
      [
        '**transcription_id_1**'
      ] 
    }
  })
})

The above command returns JSON structured like this:

{
   "id":"**export_id**",
   "state":"pending",
   "format":"txt",
   "show_timestamps":false,
   "show_speakers":false,
   "show_comments":false,
   "show_highlights":false,
   "transcription_ids":[
      "**transcription_id_1**"
   ]
}

This endpoint creates a new export. After an export is created, the system will proceed to generate it. You can watch if the exporting process has finished by retrieving an export.

The exporting process is generally very fast. Each file takes ~10s to complete. You can submit more than one file at the same time.

HTTP Request

POST https://www.happyscribe.com/api/v1/exports

JSON Parameters

Parameter Default Description
format none (required) Specify the export format (see chart below)
show_timestamps false Include timestamps (only formats: txt, docx, pdf )
timestamps_frequency nil Include inline timecodes at a given frequency (valid values: 5s, 10s, 15s, 20s, 30s, 60s)
show_speakers false Include speaker labels (only formats: txt, docx, pdf )
show_comments false Include comments (only formats: txt, docx, pdf )
show_highlights false Include highlights (only formats: docx, pdf )
show_highlights_only false Include only highlights (only formats: docx, pdf )

Export formats

Value Description
txt Text Document (.txt)
docx Word Document (.docx)
pdf PDF Document (.pdf)
srt Subtitles (SubRip .srt)
vtt Subtitles (WebVTT .vtt)
stl Subtitles (EBU-STL .stl)
avid Avid Markers (.txt)
html Interactive Transcript (.html)
premiere Premiere Pro (Beta) (.xml)
maxqda Maxqda (.txt)
json JSON (.json)
fcp Final Cut Pro (.fcp)

Retrieve an Export

curl "https://www.happyscribe.com/api/v1/exports/<ID>" \
  -H "Authorization: Bearer **your_api_key_here**"

fetch('https://www.happyscribe.com/api/v1/exports/<ID>', {
  headers: {
    authorization: 'Bearer **your_api_key_here**'
  }
})

The above command returns JSON structured like this:

{
   "id":"**export_id**",
   "state":"ready",
   "format":"txt",
   "show_timestamps":false,
   "show_speakers":false,
   "show_comments":false,
   "show_highlights":false,
   "transcription_ids":[
      "**transcription_id_1**",
   ],
   "download_link":"**download_link**"
}

This endpoint retrieves information about a specific export. To download it you can use the returned download_link.

HTTP Request

GET https://www.happyscribe.com/api/v1/exports/<ID>

Export State Descriptions

Value Description
pending Waiting to be processed.
processing The export is being generated.
ready The export is ready to download.
expired No longer available.
failed A problem occurred.

Translations

Create a Translation Task

curl -X POST "https://www.happyscribe.com/api/v1/task/transcription_translation" \
  -H "Authorization: Bearer **your_api_key_here**" \
  -H 'Content-Type: application/json' \
  -d '{
    "source_transcription_id": "**source_transcription_id**",
    "target_language": "es"
  }'


fetch('https://www.happyscribe.com/api/v1/task/transcription_translation', {
  method: 'POST',
  headers: {
    authorization: 'Bearer **your_api_key_here**',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    source_transcription_id: "**source_transcription_id**",
    target_language: "es"
  })
})

The above command returns JSON structured like this:

{
  "id": "054fe9f3aa0b446baea730fba688f96c",
  "state": "working",
  "failureReason": null,
  "progressPercent": null,
  "targetLanguage": "es"
}

Creates a new translation task given a source transcription and a target language code. After a translation task is created, the system will proceed to generate a new transcription with the translated content. You can watch the task status and get the result by retrieving a translation task using the response id property.

The translation task typically takes ~10s to complete but can take up to two minutes if the source transcription is large.

HTTP Request

POST https://www.happyscribe.com/api/v1/task/transcription_translation

JSON Parameters

Parameter Default Description
source_transcription_id none (required) Specify the id of the transcription you want to translate from. It must be in one of the supported source translation languages.
target_language none (required) The language code of the language you want to translate to. Full list here.

Target translation languages

Code Language
af Afrikaans
sq Albanian
am Amharic
ar Arabic
hy Armenian
az Azerbaijani
eu Basque
bn Bengali
bs Bosnian
bg Bulgarian
ca Catalan
zh Chinese
hr Croatian
cs Czech
da Danish
nl Dutch
en English
et Estonian
fil Filipino
fi Finnish
fr French
gl Galician
ka Georgian
de German
el Greek
gu Gujarati
he Hebrew
hi Hindi
hu Hungarian
is Icelandic
id Indonesian
it Italian
ja Japanese
jv Javanese
kn Kannada
km Khmer
ko Korean
lo Lao
lv Latvian
lt Lithuanian
mk Macedonian
ms Malay
ml Malayalam
mr Marathi
mn Mongolian
my Burmese
ne Nepali
no Norwegian
fa Persian
pl Polish
pt-PT Portuguese (Portugal)
pt-BR Portuguese (Brazil)
pa Punjabi
ro Romanian
ru Russian
sr Serbian
si Sinhala
sk Slovak
sl Slovenian
es Spanish
su Sundanese
sw Swahili
sv Swedish
ta Tamil
te Telugu
th Thai
tr Turkish
uk Ukrainian
ur Urdu
uz Uzbek
vi Vietnamese
zu Zulu

Supported source translation languages

Language Code Language Name
af Afrikaans
sq Albanian
am Amharic
ar Arabic
hy Armenian
az Azerbaijani
eu Basque
bn Bengali
bs Bosnian
bg Bulgarian
ca Catalan
cmn-Hans-CN Chinese, Mandarin (Simplified, China)
cmn-Hans-HK Chinese, Mandarin (Simplified, Hong Kong)
cmn-Hant-TW Chinese, Mandarin (Traditional, Taiwan)
hr Croatian
cs Czech
da Danish
nl Dutch
en English
et Estonian
fil Filipino
fi Finnish
fr French
gl Galician
ka Georgian
de German
el Greek
gu Gujarati
he Hebrew
hi Hindi
hu Hungarian
is Icelandic
id Indonesian
it Italian
ja Japanese
jv Javanese
kn Kannada
km Khmer
ko Korean
lo Lao
lv Latvian
lt Lithuanian
mk Macedonian
ms Malay
ml Malayalam
mr Marathi
mn Mongolian
my Burmese
ne Nepali
no Norwegian
fa Persian
pl Polish
pt Portuguese
pa Punjabi
ro Romanian
ru Russian
sr Serbian
si Sinhala
sk Slovak
sl Slovenian
es Spanish
su Sundanese
sw Swahili
sv Swedish
ta Tamil
te Telugu
th Thai
tr Turkish
uk Ukrainian
ur Urdu
uz Uzbek
vi Vietnamese
zu Zulu

Retrieve a Translation Task

curl "https://www.happyscribe.com/api/v1/task/transcription_translation/<ID>" \
  -H "Authorization: Bearer **your_api_key_here**"

fetch('https://www.happyscribe.com/api/v1/task/transcription_translation/<ID>', {
  headers: {
    authorization: 'Bearer **your_api_key_here**'
  }
})

The above command returns a JSON structured like the following:

{
  "id": "054fe9f3aa0b446baea730fba688f96c",
  "state": "done",
  "failureReason": null,
  "progressPercent": 100.0,
  "targetLanguage": "es",
  "translatedTranscriptionId": "372e9530d8f24ba68ccbcce11de43f9d"
}

This endpoint returns information about a translation task. To get the translated transcription when the task has finished you can use the translatedTranscriptionId property in the response. Remember that you can use the transcription endpoint or the export endpoint to retrieve the information and content of the transcription given the transcription id.

HTTP Request

GET https://www.happyscribe.com/api/v1/task/transcription_translation/<id>

Translation task state descriptions

Value Description
initial The task is waiting to be processed
working The translation is being generated
failed A problem occured. See the failureReason attribute.
done The translated transcription is ready. The translatedTranscriptionId attribute can be used to retrieve the translated transcription.
shell javascript