NAV navbar
bash

Introduction

Authentication

All API requests must be authenticated using your accounts API key. This can be found in the 3Scribe portal, in the API key page here. The API key must be added to the header of the request using the case-sensitive paramater key: APIKey.

/jobs

GET

# For a basic request

curl --request GET \
  --url 'https://api.3scri.be/jobs' \
  --header 'APIKey: YOUR_API_KEY'

# For a more filtered request

curl --request GET \
  --url 'https://api.3scri.be/jobs?page=2&perpage=25&order=4&direction=2' \
  --header 'APIKey: YOUR_API_KEY'

You can use this endpoint to retrieve a list of transcription jobs in your account. For a basic call, the servers will return a 'page' of 10 records sorted by the transcription job name in ascending order. However, you can add parameters to selection different amounts of data, a different page of data, sorted and ordered by different fields.

The following parameters can be passed as part of the request:

Parameter Name Allowed Values Description
page Any positive integer value This will request a page of up to the number of records specified in the 'perpage' parameter or 10 by default. If the page number specified exceeds the number of potential pages of data contained in your account, an empty data set will be returned.
perpage 10, 25, 50 or 100 This specifies the number of records to be returned in each request
order 1, 2, 3 or 4 The field to order the data by:
1. Job Name
2. Duration
3. Job Status
4. Date Created
direction 1 or 2 The direction to organize the retrieved data
1. Ascending
2. Descending

Response

A successful request will return an array of data formatted like the example below.

[{
  "jobid": "JobA",
  "jobname": "sample-A.mp3",
  "creationdate": "2020-04-07T01:03:20Z",
  "jobstatus": "Completed",
  "duration": 60
},
{
  "jobid": "JobB",
  "jobname": "sample-B.flac",
  "creationdate": "2020-04-07T01:03:20Z",
  "jobstatus": "Completed",
  "duration": 60
},{
  "jobid": "JobC",
  "jobname": "sample-C.ogg",
  "creationdate": "2020-04-07T01:03:20Z",
  "jobstatus": "Completed",
  "duration": 60
},{
  "jobid": "JobD",
  "jobname": "sample-D.wav",
  "creationdate": "2020-04-07T01:03:20Z",
  "jobstatus": "Completed",
  "duration": 60
}]

If successful the servers will respond with a 200 http code and an array of JSON objects containing the following fields:

Parameter Name Data Type Description
jobid string The unique, identifying code for this transcription job
jobname string The name the user provided to identify the job
creationdate date time The UTC time and date the transcription job was created, stored in ISO-8601 format
jobstatus string The current status of the transcription job. Possible status's are: Completed, Inactive, Requested, Processing, Error
duration integer The length of the uploaed audio or video file in seconds

/jobs/{jobid}

By attaching a job ID code as part of the endpoint request two actions can be carried out on a specific transcription job: retrieving details about the job or deleting the job from the 3Scribe system.

GET

This action will retrieve details about the job or deleting the job from the 3Scribe system.

# For a basic request

curl --request GET \
  --url 'https://api.3scri.be/jobs/JobA' \
  --header 'APIKey: YOUR_API_KEY'

Response

A successful request will return a JSON object of data formatted like the example below.

{
    "jobid": "JobA",
    "jobname": "sample-A.mp3",
    "url": null,
    "jobstatus": "Completed",
    "creationdate": "2019-10-16T22:55:11Z",
    "duration": 7,
    "errormessage": null,
    "transcription": {
        "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
        "words": [
            {
                "word": "Lorem",
                "confidence": 1.0,
                "timing": 412
            },
            {
                "word": "ipsum",
                "confidence": 1.0,
                "timing": 745
            },
            {
                "word": "dolor",
                "confidence": 1.0,
                "timing": 1010
            }
        ]
    }
}

If successful the servers will respond with a 200 http code and a JSON object containing the following fields:

Parameter Name Data Type Description
jobid string The unique, identifying code for this transcription job
jobname string The name the user provided to identify the job
url string The URL of the file provided during a transcription request API call
jobstatus string The current status of the transcription job. Possible status's are: Completed, Inactive, Requested, Processing, Error
creationdate date time The UTC time and date the transcription job was created, stored in ISO-8601 format
duration integer The length of the uploaed audio or video file in seconds
errormessage string If the system was unable to retrieve the requested data this field will contain an explaination.
transcription object The transcription object contains information about the transcript. Currently this just contains the text of the transcription but will be exanded to include timings, word confidence, sentiment etc. See below for details on the transcription object

Transcription Object

Parameter Name Data Type Description
text string The raw text transcript
words array An array of each word of the transcript along with additional metadata as detailed below

Words

Parameter Name Data Type Description
word string The individual word along with any associated punctuation
confidence number A decimal value containing the percentage confidence that the word presented was the word uttered. 1.0 = 100% confidence
timing number An integer value representing the number of milliseconds elapsed from the beginning of the audio to the beginning of the word

DELETE

This action will delete the job from the 3Scribe system. All files and texts are completly removed and cannot be restored.

# For a basic request

curl --request DELETE \
  --url 'https://api.3scri.be/jobs/JobA' \
  --header 'APIKey: YOUR_API_KEY'

If successful the servers will respond with a 200 http code.

/transcribe

POST

For a request requiring a pre-signed URL

curl --request POST \
  --url https://api.3scri.be/transcribe \
  --header 'APIKey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  -d '{ "name" : "testjob", "requesturl" : true }'

For a request passing a publically available file

curl --request POST \
  --url https://api.3scri.be/transcribe \
  --header 'APIKey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  -d '{ "name" : "testjob", "url" : "your file url"}'

This endpoint will request the 3Scribe system to process a file. Parameters for this type of request must be formatted as JSON. The file can be passed to us in a number of differnt ways depending on the fields passed in the request. A user can:

  1. Request a pre-signed URL granting them permission to upload a file to a secure AWS S3 bucket using a suqsequent PUT request. Once uploaded files are instantly moved from this public facing location to our secure storage and the transcription processing begins.

  2. Provide a publically accessable URL to 3Scribe. If provided, the processing will begin and the file will be downloaded to our secure storage as part of the process.

Parameter Name Allowed Values Description
name (required) string A descriptive title for the transcription job that will allow the user to identify the job in the 3Scribe portal.
url valid URL to a single file Either this parameter or requesturl must be provided
requesturl filename of the file to upload Either this parameter or the url must be provided
language ISO standard language and country code If omitted, the accounts default language will be assumed. Acceptable values are as per the following table.

Languages

Language Code Language Name
en-US English (United States)
en-GB English (Great Britain)
da-dk Danish
nl-NL Dutch
fi-FI Finnish
fr-FR French
de-DE German
it-IT Italian
nb-NO Norwegian
pt-PT Portugese
es-US Spanish (United States)
es-ES Spanish (Spain)
sv-SE Swedish

Responses

A successful request will return a JSON object of data formatted like the example below.

{
    "jobid": "JobE",
    "jobname": "testjob",
    "url": "A pre-signed URL",
    "jobstatus": "loading",
    "creationdate": "0001-01-01T00:00:00",
    "duration": 0,
    "errormessage": "",
    "transcription": null
}

If successful the servers will respond with a 200 http code and a JSON object containing the following fields:

Parameter Name Data Type Description
jobid string The unique, identifying code for this transcription job
jobname string The name the user provided to identify the job
url string The pre-signed URL you may use to upload the file itself using a PUT request
jobstatus string The current status of the transcription job. This will be set to 'loading'
creationdate date time The time and date the transcription job was created
duration integer The length of the uploaed audio or video file in seconds. This will be zero as the file has not yet been examined.
errormessage string If the system was unable to retrieve the requested data this field will contain an explaination.
transcription object The transcription object contains information about the transcript. This will be null as the file is not yet loaded.

Errors

The 3Scribe API uses the following error codes:

Error Code Meaning
400 Bad Request -- The request could not be understood by the server due to malformed syntax.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The requested resource is is not available publically.
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.
429 Too Many Requests -- You're requesting too many resource
500 Internal Server Error -- We had a problem with our server. Please try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
bash