V-Spark Online Help

Reference for the /request API

If you have submitted audio files for processing using V‑Spark or submitted zip files that contain audio files and optional metadata through the /transcribe API method that is described in Reference for the /transcribe API, the /request API method enables you to retrieve overall status information, short and long status/summary information in JSON format, and various results of transcribing and analyzing those audio files. The /request API is typically only directly used when you want to embed result retrieval in applications and you therefore cannot use the V‑Spark GUI and its callback server mechanism.

Important

Before you can begin interacting with V‑Spark via the REST API you must create a Folder using the V‑Spark GUI. Each Folder has associated configuration information such as the language model to use for transcription and the names of metadata fields available for filtering. See the V‑Spark Quickstart Guide and the V‑Spark Management Guide for more information. These documents are available under the Help pulldown immediately after logging into the V‑Spark GUI.

Synopsis

http://SERVER/request/ORG_SHORT/VERB?requestid=REQUESTID&token=AUTH_TOKEN

Variables used in this example command are the following:

SERVER

The name or IP address of the computer system on which V‑Spark is installed

ORG_SHORT

The short name of the organization that you are using. Finding that information is shown in /transcribe API Reference.

VERB

The action that you want the /request API to perform. These verbs and the data that they return are described in the next section (DESCRIPTION).

REQUESTID

The unique identifier for the request about which you want to retrieve results or status information

AUTH_TOKEN

The authorization token that you are using to retrieve information. Locating an authorization token for the company associated with the folder that you are uploading to is shown in V‑Spark API Permission Requirements.

Description

The /request API enables you to retrieve status information and converted content for files that you have submitted for transcription.

The items in the rest of this section refer to retrieving status information or transcription results from both zip and audio files that have been submitted for transcription. Remember that while both the /transcribe API and V‑Spark enable you to submit audio and metadata files individually, only files that have been encapsulated into a single zip file and uploaded at the same time will be associated properly.

The /request method takes the following verbs to identify the type of information that you are attempting to retrieve based on a requestid:

status

Possible return values for this verb are the following:

analyzing

The zip or audio file associated with the specified requestid has been received and is in the process of being transcribed and analyzed by V‑Spark

done

Transcription of all of the audio files in the zip or audio file associated with the specified requestid has completed

error

No results will ever be available. Check the contents of the zip or audio file that is associated with the specified requestid to verify that it contains valid audio files.

received

The zip or audio file associated with the specified requestid has been received and the audio file(s) that it contains are in the process of being transcribed

summary

Returns a short response in JSON format that contains the following information about the request that was identified by the specified requestid:

  • a time_submit timestamp which identifies the time that the request was submitted

  • a time_complete timestamp which identifies the time that analyzing the contents of the zip or audio file was completed

  • counts of the following categories:

    • number of audio files that were submitted in the zip or audio file that is associated with the specified requestid

    • number of audio files that were successfully processed in the zip or audio file that is associated with the specified requestid

    • number of audio files that were successfully analyzed in the zip or audio file that is associated with the specified requestid

    • number of audio files in the zip or audio file that is associated with the specified requestid that generated an error when being processed or analyzed

    Note

    Count information is not provided for fields that are NULL.

  • status: the overall status of handling the zip or audio file associated with the request that is associated with the specified requestid. This is the same value as returned by the status verb, with the same list of possible values.

details

Returns a long response in JSON format that contains:

  • the information provided by the summary verb for the zip or audio file that was uploaded under the specified requestid

  • a filedetails section that provides a fullfilename and the same information for each file that was part of the request that was identified by the specified requestid:

result

A zip file containing different types of data that is associated with the transcription of the zip or audio file that was uploaded under the specified requestid. Optional Boolean parameters identify the type of data that is contained in this zip file:

json

Include the complete transcription information (transcribed text, emotion, sentiment, and so on) in JSON format for each audio file. By default, this option is "on" ("1").

mp3

Include the mp3 version of each audio file. By default, this option is "off" ("0").

txt

Include a text file containing the transcription of each audio file. By default, this option is "off" ("0").

If the /request method's result verb is called with all output formats disabled, the API call will return a 404 and the message "No file types were specified".

Content Types

  • status verb returns plain text data with the "text/html" MIME type

  • summary verb returns JSON-formatted data with the "application/json" MIME type

  • details verb returns JSON-formatted data with the "application/json" MIME type

  • result verb returns a zip file with the "application/zip" MIME type

  • Errors will be returned with the "text/html" MIME type

In this section:

Short for JavaScript Object Notation. Allows for information to be stored in a hierarchical fashion within a single document.