NAV Navbar
shell javascript

Introduction

Base url

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

Welcome to the Happy Scribe API 👋

With this API you can automatically submit files to be transcribed by Happy Scribe, access existing transcriptions and export them to various formats.

This is a REST API that uses predictable resource names and verbs. Our API is versioned where breaking changes are released as incremental versions. We'll try our best not to release versions too often, and to reasonably support legacy versions.

If you have any questions, please write to us at dev@happyscribe.co. We'd love to hear from you!

— happyscribe team

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 API keys to allow access to the API. You can get your API key by logging in and going to settings

Happy Scribe 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 yourselves or a third-party. 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..."
curl -X PUT -T my_media.mp3 -L "https://signed-url..."

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": "2018-10-29T14:31:29.799Z",
            "updatedAt": "2018-10-29T14:31:38.495Z",
            "state": "automatic_done",
            "sharingEnabled": false,
            "language": "en-GB",
            "_links": {
              "self": {
                "url": "https://www.happyscribe.com/api/v1/transcriptions/e458099e7f8da14f9625854ba7b6a026917ad306"
              }
            }
        },
        {
            "id": "9jossdjdf09j309omsldknslkjndfjknsdfs",
            "name": "interview2.mov",
            "createdAt": "2018-10-29T14:31:29.799Z",
            "updatedAt": "2018-10-29T14:31:38.495Z",
            "state": "automatic_done",
            "sharingEnabled": false,
            "language": "en-GB",
            "_links": {
              "self": {
                "url": "https://www.happyscribe.com/api/v1/transcriptions/9jossdjdf09j309omsldknslkjndfjknsdfs"
              }
            }
        },
        ...
    ],
    "_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
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"
      }
    }'

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',
    }
  })
})

The above command returns JSON structured like this:

{
  "id": "9josdjdfo09j309omsldknslkjndfjknsdfs",
  "name": "My Interview",
  "createdAt": "2018-10-29T14:31:29.799Z",
  "updatedAt": "2018-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.

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": "2018-10-29T14:31:29.799Z",
  "updatedAt": "2018-10-29T14:31:38.495Z",
  "sharingEnabled": false,
  "state": "automatic_done",
  "language": "en-GB",
  "_links": {
    "self": {
      "url": "https://www.happyscribe.com/api/v1/transcriptions/f6511f81156114aede28dc85325a796ae7996d11"
    },
    "editor": {
      "url": "https://www.happyscribe.com/transcriptions/9josdjdfo09j309omsldknslkjndfjknsdfs/edit_v2",
    },
    "export": {  
      "url": "https://www.happyscribe.com/api/v1/transcriptions/f6511f81156114aede28dc85325a796ae7996d11/exports/new"
    },
  }
}

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>

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

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 )
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 )

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

Translation

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/exports', {
  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
en English
es Spanish
fr French
de German
zh Chinese
nl Dutch
pt-pt Portuguese (Portugal)
pt-br Portuguese (Brazil)
ru Russian
it Italian
pl Polish

Supported source translation languages

Code Language
de German
en English
fr French
it Italian
ja Japanese
es Spanish
nl Dutch
pl Polish
pt Portuguese
ru Russian
cmn-Hans-CN Chinese, Mandarin (Simplified, China)
cmn-Hans-HK Chinese, Mandarin (Simplified, Hong Kong)
cmn-Hant-TW Chinese, Mandarin (Traditional, Taiwan)

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 trancription 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.

Errors

The Happy Scribe API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong or you don't have permission to access that resource.
403 Forbidden -- The resource requested is hidden for administrators only.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access a resource with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The resource requested has been removed from our servers.
418 I'm a teapot.
422 Unprocessable Entity -- There was an error processing your request.
429 Too Many Requests -- You're requesting too many resources! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Languages

We support the following languages, by their IETF BCP-47 language codes:

Code Language
af-ZA Afrikaans (South Africa)
am-ET Amharic (Ethiopia)
ar-DZ Arabic (Algeria)
ar-BH Arabic (Bahrain)
ar-EG Arabic (Egypt)
ar-IQ Arabic (Iraq)
ar-IL Arabic (Israel)
ar-JO Arabic (Jordan)
ar-KW Arabic (Kuwait)
ar-LB Arabic (Lebanon)
ar-MA Arabic (Morocco)
ar-OM Arabic (Oman)
ar-QA Arabic (Qatar)
ar-SA Arabic (Saudi Arabia)
ar-PS Arabic (State of Palestine)
ar-TN Arabic (Tunisia)
ar-AE Arabic (United Arab Emirates)
ar-YE Arabic (Yemen)
hy-AM Armenian (Armenia)
az-AZ Azerbaijani (Azerbaijan)
eu-ES Basque (Spain)
bn-BD Bengali (Bangladesh)
bn-IN Bengali (India)
bg-BG Bulgarian (Bulgaria)
ca-ES Catalan (Spain)
yue-Hant-HK Chinese, Cantonese (Traditional, Hong Kong)
cmn-Hans-CN Chinese, Mandarin (Simplified, China)
cmn-Hans-HK Chinese, Mandarin (Simplified, Hong Kong)
cmn-Hant-TW Chinese, Mandarin (Traditional, Taiwan)
hr-HR Croatian (Croatia)
cs-CZ Czech (Czech Republic)
da-DK Danish (Denmark)
nl-NL Dutch (Netherlands)
nl-BE Dutch (Belgium)
en-AU English (Australia)
en-CA English (Canada)
en-GH English (Ghana)
en-IN English (India)
en-IE English (Ireland)
en-KE English (Kenya)
en-NZ English (New Zealand)
en-NG English (Nigeria)
en-PH English (Philippines)
en-ZA English (South Africa)
en-TZ English (Tanzania)
en-HK English (Hong Kong)
en-PK English (Pakistan)
en-SG English (Singapore)
en-GB English (United Kingdom)
en-US English (United States)
fil-PH Filipino (Philippines)
fi-FI Finnish (Finland)
fr-CA French (Canada)
fr-FR French (France)
fr-BE French (Belgium)
fr-CH French (Switzerland)
gl-ES Galician (Spain)
ka-GE Georgian (Georgia)
de-DE German (Germany)
de-AT German (Austria)
de-CH German (Switzerland)
el-GR Greek (Greece)
gu-IN Gujarati (India)
he-IL Hebrew (Israel)
hi-IN Hindi (India)
hu-HU Hungarian (Hungary)
is-IS Icelandic (Iceland)
id-ID Indonesian (Indonesia)
it-IT Italian (Italy)
it-CH Italian (Switzerland)
ja-JP Japanese (Japan)
jv-ID Javanese (Indonesia)
kn-IN Kannada (India)
km-KH Khmer (Cambodia)
ko-KR Korean (South Korea)
lo-LA Lao (Laos)
lv-LV Latvian (Latvia)
lt-LT Lithuanian (Lithuania)
ms-MY Malay (Malaysia)
ml-IN Malayalam (India)
mr-IN Marathi (India)
ne-NP Nepali (Nepal)
nb-NO Norwegian Bokmål (Norway)
fa-IR Persian (Iran)
pl-PL Polish (Poland)
pt-BR Portuguese (Brazil)
pt-PT Portuguese (Portugal)
ro-RO Romanian (Romania)
ru-RU Russian (Russia)
sr-RS Serbian (Serbia)
si-LK Sinhala (Srilanka)
sk-SK Slovak (Slovakia)
sl-SI Slovenian (Slovenia)
es-AR Spanish (Argentina)
es-BO Spanish (Bolivia)
es-CL Spanish (Chile)
es-CO Spanish (Colombia)
es-CR Spanish (Costa Rica)
es-DO Spanish (Dominican Republic)
es-EC Spanish (Ecuador)
es-SV Spanish (El Salvador)
es-GT Spanish (Guatemala)
es-HN Spanish (Honduras)
es-MX Spanish (Mexico)
es-NI Spanish (Nicaragua)
es-PA Spanish (Panama)
es-PY Spanish (Paraguay)
es-PE Spanish (Peru)
es-PR Spanish (Puerto Rico)
es-ES Spanish (Spain)
es-US Spanish (United States)
es-UY Spanish (Uruguay)
es-VE Spanish (Venezuela)
su-ID Sundanese (Indonesia)
sw-KE Swahili (Kenya)
sw-TZ Swahili (Tanzania)
sv-SE Swedish (Sweden)
ta-IN Tamil (India)
ta-MY Tamil (Malaysia)
ta-SG Tamil (Singapore)
ta-LK Tamil (Sri Lanka)
te-IN Telugu (India)
th-TH Thai (Thailand)
tr-TR Turkish (Turkey)
uk-UA Ukrainian (Ukraine)
ur-IN Urdu (India)
ur-PK Urdu (Pakistan)
vi-VN Vietnamese (Vietnam)
zu-ZA Zulu (South Africa)
sq-AL Albanian (Albania)
bs-BA Bosnian (Bosnia and Herzegovina)
my-MM Burmese (Myanmar)
et-EE Estonian (Estonia)
mk-MK Macedonian (North Macedonia)
mn-MN Mongolian (Mongolia)
pa-Guru-IN Punjabi (Gurmukhi India)
uz-UZ Uzbek (Uzbekistan)