support@3scri.be

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 parameter key: APIKey.

Transcription Job Methods

Transcription Job Methods allow developers to retrieve and manage existing transcriptions within their account.
Endpoints
Get/jobsFetch a list of Transcription Jobs
Get/jobs/:jobidFetch a specifc Transcription Job
Delete/jobs/:jobidDelete the specified Transcription Job

The Transcription Job object

An object containing information about a transcription job including it's current status and the transcript both in complete form and individual utterances.
Attributes
jobidstring

The unique, identifying code for this transcription job

jobnamestring

The name the user provided to identify the job

creationdatedatetime

The UTC time and date the transcription job was created, stored in ISO-8601 format

jobstatusstring

The current status of the transcription job. Possible status's are: Completed, Inactive, Requested, Processing, Error

durationinteger

The length of the uploaed audio or video file in seconds

languagestring

The language code denoting the language used when transcribing the job

sourcestring

The source of the job request i.e. direct (web front-end) or one of our integrations such as Zapier or Zendesk

errormessagestring

If the system was unable to retrieve the requested data this field will contain an explaination.

transcriptionobject

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 Attributes
textstring

The raw text transcript

wordsarray

An array of word objects breaking down the transcript into individual utterances with additional information on the speaker, timing etc. See below for detailed information on the object

Word Object Attributes
wordstring

The individual word along with any associated punctuation

speakerinteger

An integer value indicating which of the identified speakers made the utterance.

confidencedecimal

A decimal value containing the percentage confidence that the word presented was the word uttered. 1.0 = 100% confidence

timinginteger

An integer value representing the number of milliseconds elapsed from the beginning of the audio to the beginning of the word

The Transcription Job object
{
    "jobid": "JobA",
    "jobname": "sample-A.mp3",
    "url": null,
    "jobstatus": "Completed",
    "creationdate": "2019-10-16T22:55:11Z",
    "duration": 7,
    "language": "en-US",
    "source": "Zendesk",
    "errormessage": null,
    "transcription": {
        "text": "Lorem ipsum dolor",
        "words": [
            {
                "word": "Lorem",
                "confidence": 1.0,
                "timing": 412
            },
            {
                "word": "ipsum",
                "confidence": 1.0,
                "timing": 745
            },
            {
                "word": "dolor",
                "confidence": 1.0,
                "timing": 1010
            }
        ]
    }
}

The Transcription Job List Item object

A subset of the main Transcription Job object goving information about a job but omitting the transcript information. Used when retrieving lists of jobs.
Attributes
jobidstring

The unique, identifying code for this transcription job

jobnamestring

The name the user provided to identify the job

creationdatedatetime

The UTC time and date the transcription job was created, stored in ISO-8601 format

jobstatusstring

The current status of the transcription job. Possible status's are: Completed, Inactive, Requested, Processing, Error

durationinteger

The length of the uploaed audio or video file in seconds

languagestring

The language code denoting the language used when transcribing the job

sourcestring

The source of the job request i.e. direct (web front-end) or one of our integrations such as Zapier or Zendesk

The Transcription Job List Item object
{
  "jobid": "JobA",
  "jobname": "sample-A.mp3",
  "creationdate": "2025-04-07T01:03:20Z",
  "jobstatus": "Completed",
  "duration": 60,
  "language": "en-US",
  "source": "Direct"
}

List Transcription Jobs

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 query parameters to select different amounts of data, a different page of data, sorted and ordered by different fields.
Parameters
pageinteger

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.

perpageinteger

This specifies the number of records to be returned in each request. Allowed values are: 10, 25, 50 or 100. A value outside of this list will default to 10.

orderinteger

The field to order the data by. Allowed values are:

1. Job Name
2. Duration
3. Job Status
4. Date Created

directioninteger

The direction to organize the retrieved data. Allowed values are:

1. Ascending
2. Descending

Returns

If successful the servers will respond with a 200 http code and an array of Transcription Job List Item objects.

GET  /jobs
# 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'
Response
[{
  "jobid": "JobA",
  "jobname": "sample-A.mp3",
  "creationdate": "2020-04-07T01:03:20Z",
  "jobstatus": "Completed",
  "duration": 60,
  "language": "en-US",
  "source": "Direct"
},
{
  "jobid": "JobB",
  "jobname": "sample-B.flac",
  "creationdate": "2020-04-07T01:03:20Z",
  "jobstatus": "Completed",
  "duration": 60,
  "language": "en-US",
  "source": "Direct"
},
{
  "jobid": "JobC",
  "jobname": "sample-C.ogg",
  "creationdate": "2020-04-07T01:03:20Z",
  "jobstatus": "Completed",
  "duration": 60,
  "language": "fr-FR",
  "source": "Zapier"
}]

Retrieve a Transcription Job

This action will retrieve the details for the specified job from the 3Scribe system.
Path Parameters
jobidstring

The unique, identifying code for this transcription job

Returns

A Transcription Job object containing information regarding the specified job.

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

Delete a Transcription Job

This action will delete the specified job from the 3Scribe system. All files and transcripts will be completly removed and cannot be restored.
Path Parameters
jobidstring

The unique, identifying code for this transcription job

Returns

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

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

Transcribe Methods

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:
Endpoints
Post/transcribeSubmit a new job for transcribing

Create a new Transcription Job (via a pre-signed URL)

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.
Body Parameters
namestring Required

A descriptive title for the transcription job that will allow the user to identify the job in the 3Scribe portal.

requesturlstring Required

Filename of the file to upload.

languagestring

ISO standard language and country code If omitted, the accounts default language will be assumed. Acceptable values are as per this list.

detectlanguageboolean

An optional boolean value that overrides the language setting and requests that the language spoken be detected from the dialog.

Returns

A Transcription Job object containing information about the newly created job.

POST  /transcribe
curl --request POST \
  --url https://api.3scri.be/transcribe \
  --header 'APIKey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  -d '{ "name" : "testjob", "requesturl" : true }'
Response
{
    "jobid": "JobE",
    "jobname": "testjob",
    "url": "A pre-signed URL",
    "jobstatus": "loading",
    "creationdate": "0001-01-01T00:00:00",
    "duration": 0,
    "errormessage": "",
    "transcription": null
}

Create a new Transcription Job (via a publically available file)

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.
Body Parameters
namestring Required

A descriptive title for the transcription job that will allow the user to identify the job in the 3Scribe portal.

urlstring Required

A URL to a publically available media file that can be retreived by the 3Scribe system for processing.

languagestring

ISO standard language and country code If omitted, the accounts default language will be assumed. Acceptable values are as per this list.

detectlanguageboolean

An optional boolean value that overrides the language setting and requests that the language spoken be detected from the dialog.

Returns

A Transcription Job object containing information about the newly created job.

POST  /transcribe
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"}'
Response
{
    "jobid": "JobE",
    "jobname": "testjob",
    "url": "A pre-signed URL",
    "jobstatus": "loading",
    "creationdate": "0001-01-01T00:00:00",
    "duration": 0,
    "errormessage": "",
    "transcription": null
}

Accepted Language Codes

Language Codes
en-USEnglish (United States)
en-GBEnglish (Great Britain)
bg-BGBulgarian
hr-HRCroatian
cs-CZCzech
da-dkDanish
nl-NLDutch
fi-FIFinnish
fr-FRFrench
de-DEGerman
el-GRGreek
hu-HUHungarian
it-ITItalian
nb-NONorwegian
pl-PLPolish
pt-PTPortugese
ro-RORomanian
sk-SKSlovak
sl-SISlovenian
es-USSpanish (United States)
es-ESSpanish (Spain)
sv-SESwedish
tr-TRTurkish

Response Error Codes

This error section describes some of the common error responses sent by 3Scribe servers in the event the requested method cannot be fulfilled. The 3Scribe API uses the following error codes:
HTTP Error Codes
400Bad Request - The request could not be understood by the server due to malformed syntax.
401Unauthorized - Your API key is wrong.
403Forbidden - The requested resource is is not available publically.
404Not Found - The specified resource could not be found.
405Method Not Allowed - You tried to access a resource with an invalid method.
406Not Acceptable - You requested a format that isn't JSON.
410Gone - The resource requested has been removed from our servers.
429Too Many Requests - You're requesting too many resource
500Internal Server Error - We had a problem with our server. Please try again later.
503Service Unavailable - We're temporarily offline for maintenance. Please try again later.