NAV Navbar
shell javascript

Introduction

Welcome to the HappyScribe API!

Using this API, you can programmatically submit files to be transcribed by HappyScribe.
You can also access existing transcriptions and export them to various formats.

We try to be a RESTfull API, using appropriate 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 🙈

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "https://www.happyscribe.co/api/v1/" \
  -H "Authorization: Bearer **your_api_key_here**"
fetch('https://www.happyscribe.co/api/v1/', {
  headers: {
    authorization: 'Bearer **your_api_key_here**'
  }
})

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

HappyScribe uses API keys to allow access to the API. You can get your API key by logging in and going to settings

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 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.
Once you have the signed URL, you can upload files as you would to any AWS S3 bucket.

We provide two types of signed URLs:

Depending on which type of upload you require, you should request a signed URL from one of these two endpoints:

Binary Data File Upload

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

fetch('https://www.happyscribe.co/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: https://docs.aws.amazon.com/AmazonS3/latest/dev/PresignedUrlUploadObject.html

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.co/api/v1/uploads/new

Parameters

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

Multipart Uploads

curl "https://www.happyscribe.co/api/v1/uploads/new?multipart=true" \
  -H "Authorization: Bearer **your_api_key_here**"

fetch('https://www.happyscribe.co/api/v1/uploads/new?multipart=true', {
  headers: {
    authorization: 'Bearer **your_api_key_here**',
  }
})

The above command returns JSON structured like this:

{
  "url": "https://happy-scribe-domain.s3.eu-west-1.amazonaws.com",
  "form_fields": {
    "x-amz-signature": "xxxxxx",
    // ...other form fields
  }
}

This endpoint returns a URL and form fields which can be used to POST multipart uploads to our S3 bucket.
More information here: https://docs.aws.amazon.com/AmazonS3/latest/dev/uploadobjusingmpu.html

Once the file is uploaded, S3 will respond with a URL in the XML body, as well as in the headers.
You should use this URL as the tmp_url when creating the associated transcription.

HTTP Request

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

Parameters

Parameter Description
multipart (required) should be set to true

Transcriptions

List All Transcriptions

curl "https://www.happyscribe.co/api/v1/transcriptions" \
  -H "Authorization: Bearer **your_api_key_here**"
fetch('https://www.happyscribe.co/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"
        },
        {
            "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"
        },
        ...
    ],
    "total": 10,
    "_links": {
      "next": {
        "url": "https://www.happyscribe.co/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.co/api/v1/transcriptions

Query Parameters

Parameter Default Description
page 0 Request a specific page

Create a Transcription

curl -X POST "https://www.happyscribe.co/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.co/api/v1/transcriptions', {
  method: 'POST',
  headers: {
    authorization: 'Bearer **your_api_key_here**',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    transcription: {
      name: 'My Interview',
      lanugage: '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"
}

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.co/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.co/api/v1/transcriptions/<ID>" \
  -H "Authorization: Bearer **your_api_key_here**"
fetch('https://www.happyscribe.co/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"
}

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.co/api/v1/transcriptions/<ID>

Transcription State Descriptions

Value Description
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

An export is a first-class resource. They are created by calling the export endpoint and passing an array of transcription_ids. Exports are processed asynchronously. After they are created, you must poll the endpoint until the export has a status of ready. The export will then include a download_url parameter which is valid for 10 days.

Create an Export

curl -X POST "https://www.happyscribe.co/api/v1/exports" \
  -H "Authorization: Bearer **your_api_key_here**" \
  -H "Content-Type: application/json" \
  -d '{
    "export": {
        "transcriptionIds": [
          "xxxxxxxx",
          "yyyyyyyy",
          "zzzzzzzz"
        ],
        "format": "docx"
      }
    }'

fetch('https://www.happyscribe.co/api/v1/exports', {
  method: 'POST',
  headers: {
    authorization: 'Bearer **your_api_key_here**',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    export: {
      transcriptionIds: [
        'xxxxxxxx',
        'yyyyyyyy',
        'zzzzzzzz'
      ],
      format: 'docx'
    }
  })
})

The above command returns JSON structured like this:

{
    "id": "e458099e7f8da14f9625854ba7b6a026917ad306",
    "state": "pending",
    "format": "docx",
    "show_timestamps": false,
    "show_speakers": false,
    "show_comments": false,
    "show_highlights": false,
    "transcription_ids": [
      "xxxxxxxx",
      "yyyyyyyy",
      "zzzzzzzz"
    ]
}

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

HTTP Request

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

Parameters

Parameter Type Description
transcription_ids [String] (required) Array of ids of the transcriptions to export
format String (required) Desired export format. Full list below.
show_timestamps Boolean Include timestamps (only formats: txt, docx, pdf ). Default is false
show_speakers Boolean Include speaker labels (only formats: txt, docx, pdf ). Default is false
show_comments Boolean Include comments (only formats: txt, docx, pdf ). Default is false
show_highlights Boolean Include highlights (only formats: docx, pdf ). Default is false

Export formats

Value Description
txt Text Document (.txt)
docx Word Document (.docx)
pdf PDF Document (.pdf)
srt Subtitles (SubRip .srt)
stl Subtitles (EBU-STL .stl)
avid Avid Markers (.txt)
html Interactive Transcript (.html)
premiere Premiere Pro (Beta) (.xml)

Retrieve an Export

curl "https://www.happyscribe.co/api/v1/exports/<ID>" \
  -H "Authorization: Bearer **your_api_key_here**"
fetch('https://www.happyscribe.co/api/v1/exports/<ID>', {
  headers: {
    authorization: 'Bearer **your_api_key_here**'
  }
})

The above command returns JSON structured like this:

{
    "id": "e458099e7f8da14f9625854ba7b6a026917ad306",
    "state": "ready",
    "format": "docx",
    "show_timestamps": false,
    "show_speakers": false,
    "show_comments": false,
    "show_highlights": false,
    "transcription_ids": [
      "xxxxxxxx",
      "yyyyyyyy",
      "zzzzzzzz"
    ],
    "download_url": "https://www.some-host.com/some-path/e458099e7f8da14f9625854ba7b6a026917ad306.zip"
}

This endpoint retrieves information about a specific export.

HTTP Request

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

Export State Descriptions

Value Description
pending Export is the queue to be processed.
processing Export is being processed
ready Export is finished processing and the download_url is now available.
export Export has expired and is no longer available for download

Errors

The HappyScribe 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)
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)
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-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)
gl-ES Galician (Spain)
ka-GE Georgian (Georgia)
de-DE German (Germany)
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)
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)