flowground for Business Customers

Technical Specifications

startFlow

OnInit
./lib/triggers/startFlow.js
OnStartup
-
OnClose
-

Attributes

-

get_v1_bundles

Gets the list of bundles. Links to each item are in the _links with link relation items.

After getting the initial list, use the first, last, next, prev link relations to get more bundles in the list. Note that next will not be available at the end of the list and prev will not be available at the start of the list. If the results are exactly one page neither prev nor next will be available.

The embed parameter specifies link relations to embed in the results. The models for the specified link relations will be in an array in the embedded object with the link relation as the key. For example, if you do embed=items, _embedded will contain a property items whose value is the array of bundle models. For link relations that are curies (ex. "clarify:metadata"), you may simply use the base name (ex. "metadata").

OnInit
./lib/actions/get_v1_bundles.js
OnStartup
-
OnClose
-

Attributes

-

post_v1_bundles

Create a new bundle with the specified name, media url, and optional JSON metadata.

name can be any string you wish to associate with the bundle.

media_url must be a publicly accessible url to a media file. It will be fetched asynchronously after the REST call returns. The audio can be mono or stereo.

audio_channel is used to specify audio channels if the media is a stereo file. A value of left or right signifies that only the specified channel will be used. If no value or an empty string is specified for audio_channel, all channels will be used in a single track. If your stereo channels were recorded separately with each channel containing distinct content (for example if 2 legs of a phone call were recorded separately and combined into a single stereo file), for best speech recognition, create two tracks, with audio_channel set to left and right in each track respectively. If your stereo file is simply a recording made with a stereo microphone, audio_channel should be set to an empty string (or not be specified.) If you have audio channels as separate media files, after creating the bundle with one media_url, POST another media_url to /bundles/{bundle_id}/tracks.

audio_language can be used to specify the language of the audio media. This is an optional parameter and if not specified or an empty string, the language of the track will be automatically detected. If specified, it must be a language code as described in RFC5646 (see http://tools.ietf.org/html/rfc5646). Supported languages: en-US, en-UK, es, fr.

label is a short name for the track.

metadata is a single-level JSON object of your own definition, containing key-values that can be searched and filtered on. Metadata can be used to hold text such as names, titles, descriptions and values for segregating bundles, for example by user, topic, folder name etc. The keys (property names) can be up to 64 characters and must contain only alphanumeric characters and underscore (but not start with underscore) and must not be a reserved name. Reserved names are "true", "false", and "null". Values can be strings, numbers, boolean true/false, date-times represented as a string in ISO 8601 format (ex. "2014-02-25T14:23:45.000Z"), or an array of these primitive types. Strings can be up to 2000 characters and strings in arrays can be up to 128 characters each. Nested objects are not allowed. Metadata can contain up to 50 key-value pairs up to a total JSON size of 4000 characters.

start_time a time in seconds that the media starts, relative to start time of the bundle. This allows you to specify sequential parts of media. If not specified, the default is 0.

parts_pending a boolean flag specifying if more media parts will subsequently be added to the track. If true, a subsequent API call must be made to signify that the track is complete. If not specified, the default is false.

external_id is an optional parameter that can be used to logically link a bundle to an item in an external system. The external_id can be whatever you use to identify items in your own database.

notify_url is a webhook. It must be a publicly accessible url (http or https) on your server to which notifications for the bundle will be POSTed. There are three types of notifications: Track Notifications, Insight Notifications and Bundle Notifications. For more information on the content of notifications and when they are sent, see the notification docs page.

If a track was created along with the budle, the link relation clarify:track will be included with a link to the new track.

OnInit
./lib/actions/post_v1_bundles.js
OnStartup
-
OnClose
-

Attributes

-

delete_v1_bundles__bundle_id_

Delete a bundle and its related metadata and tracks. This will only delete media stored on Clarify systems and not delete the source media on remote systems.

Successful response will be a HTTP code 204 with an empty body.

OnInit
./lib/actions/delete_v1_bundles__bundle_id_.js
OnStartup
-
OnClose
-

Attributes

-

get_v1_bundles__bundle_id_

Get a bundle that has previously been created.

OnInit
./lib/actions/get_v1_bundles__bundle_id_.js
OnStartup
-
OnClose
-

Attributes

-

put_v1_bundles__bundle_id_

Update a bundle. To update the tracks, media, or metadata of a bundle, use the tracks and metadata endpoints.

name can be any string you wish to associate with the bundle.

external_id is an optional parameter that can be used to logically link a bundle to an item in an external system. The external_id can be whatever you use to identify items in your own database.

notify_url is a webhook. It must be a publicly accessible url (http or https) on your server to which notifications for the bundle will be POSTed. There are three types of notifications: Track Notifications, Insight Notifications and Bundle Notifications. For more information on the content of notifications and when they are sent, see the notification docs page.

If version is specified, the bundle will only be updated if the current version matches this parameter value. If the version doesn't match, a 409 Conflict error will be returned. If version not specified, the bundle will always be updated.

OnInit
./lib/actions/put_v1_bundles__bundle_id_.js
OnStartup
-
OnClose
-

Attributes

-

get_v1_bundles__bundle_id__insights

Gets the insights for a bundle.

URLs of the available insights for the bundle are in the _links object, with the link relations (keys) of the format insight:insight_name.

Documentation on the insights available and the data returned can be found at http://docs.clarify.io/insights/

OnInit
./lib/actions/get_v1_bundles__bundle_id__insights.js
OnStartup
-
OnClose
-

Attributes

-

post_v1_bundles__bundle_id__insights

Request an insight to be run on a bundle. Note that most insights are set to automatically run on all bundles so you commonly won't need to call this endpoint except to request transcripts. To configure which insights are automatically run for an app, visit the Clarify Developer Portal.

Insights that are not configured to autorun can be requested to run on an individual bundle using this endpoint. The following insights can be requested:

transcript_r9 - High-accuracy transcript of the speech in audio media.

Transcripts will produced on the mixed audio of all tracks in the bundle and are charged per minute (rounded up for partial minutes), based on the duration of the longest track. If the request has already been made, this method has no effect other than to return the existing insight.

Transcripts will typically take about 48 hours. When the transcript is ready, an InsightNotification webhook will be POSTed to the bundle notify_url.

For more information see Human Transcripts Quick Start.

captions_r9 - High-accuracy captions of the speech in video media.

Captions will be generated on the first track in the bundle. and are charged per minute (rounded up for partial minutes), based on the duration of the media. See the pricing page. If the request has already been made, this method has no effect other than to return the existing insight.

Captions will typically take about 72 hours. When the captions are ready, an InsightNotification webhook will be POSTed to the bundle notify_url.

For more information see Captions Quick Start.

spoken_keywords - Spoken words of interest found in audio media. Note: Normally spoken_keywords is set to autorun so you do not need to run it explicitly.

spoken_topics - Topics spoken about in the audio media.

OnInit
./lib/actions/post_v1_bundles__bundle_id__insights.js
OnStartup
-
OnClose
-

Attributes

-

v1bundlesbundle_idinsightsinsight_id

Gets a particular insight for a bundle. Typically, you will hit this endpoint from a link contained in a response to /v1/bundles/{bundle_id}/insights

The insight response may contain a data object containing insight-specific data and/or an array of objects called track_data, where the array indexes correspond to the tracks in the bundle. Each object in the array contains the track_id, track_label and insight-specific data related to that insight. For example, in the spoken_words insight, the track_data objects contain the field word_count which is the number of spoken words found in the track.

Documentation on the insights available and the data returned can be found at http://docs.clarify.io/insights/

Insights that contain data in different file formats (such as for video captions) will have one or more link relations in the _links array for the corresponding data. Note that the href URLs in these links have a limited lifespan and should not be stored locally.

OnInit
./lib/actions/v1bundlesbundle_idinsightsinsight_id.js
OnStartup
-
OnClose
-

Attributes

-

delete_v1_bundles__bundle_id__metadata

Delete the metadata of a bundle and set data to {} (empty object.) This is functionally equivalent to an update metadata request with data set to {}.

Successful response will be a HTTP code 204 with an empty body.

OnInit
./lib/actions/delete_v1_bundles__bundle_id__metadata.js
OnStartup
-
OnClose
-

Attributes

-

get_v1_bundles__bundle_id__metadata

Gets the metadata for a bundle.

OnInit
./lib/actions/get_v1_bundles__bundle_id__metadata.js
OnStartup
-
OnClose
-

Attributes

-

put_v1_bundles__bundle_id__metadata

Update the metadata for a bundle.

The metadata is a single-level JSON object of your own definition, containing key-values that can be searched and filtered on. Metadata can be used to hold text such as names, titles, descriptions and values for segregating bundles, for example by user, topic, folder name etc. The keys (property names) can be up to 64 characters and must contain only alphanumeric characters and underscore (but not start with underscore) and must not be a reserved name. Reserved names are "true", "false", and "null". Values can be strings, numbers, boolean true/false, date-times represented as a string in ISO 8601 format (ex. "2014-02-25T14:23:45.000Z"), or an array of these primitive types. Strings can be up to 2000 characters and strings in arrays can be up to 128 characters each. Nested objects are not allowed. Metadata can contain up to 50 key-value pairs up to a total JSON size of 4000 characters.

To clear the metadata for a bundle, send data={}.

If version specified, the metadata will only be updated if the current version matches this parameter value. If the version doesn't match, a 409 Conflict will be returned. If version not specified, the metadata will always be updated.

OnInit
./lib/actions/put_v1_bundles__bundle_id__metadata.js
OnStartup
-
OnClose
-

Attributes

-

delete_v1_bundles__bundle_id__tracks

Delete tracks of a bundle. This will only delete media stored on Clarify systems and not delete the source media on remote systems.

Successful response will be a HTTP code 204 with an empty body.

OnInit
./lib/actions/delete_v1_bundles__bundle_id__tracks.js
OnStartup
-
OnClose
-

Attributes

-

get_v1_bundles__bundle_id__tracks

Gets the array of tracks for a bundle. This includes the specification of the media and the status of fetching and processing it.

Media for tracks is fetched asynchronously. Until media has been retrieved, a track's duration and size will both be set to -1.

OnInit
./lib/actions/get_v1_bundles__bundle_id__tracks.js
OnStartup
-
OnClose
-

Attributes

-

post_v1_bundles__bundle_id__tracks

Add a new track to a bundle. This will insert or append a new track in the tracks array or return an error if the maximum number of tracks (12) has been reached or the track number specifies an invalid index.

Once all media parts have been added to a track it is immutable, meaning it cannot be modified. If you wish to modify a track, simply add a new one and delete the existing one.

label is a short name for the track.

media_url must be a publicly accessible url to a media file. It will be fetched asynchronously after the REST call returns. The audio can be mono or stereo.

audio_channel is used to specify audio channels if the media is a stereo file. A value of left or right signifies that only the specified channel will be used. If no value or an empty string is specified for audio_channel, all channels will be used in a single track. If your stereo channels were recorded separately with each channel containing distinct content (for example if 2 legs of a phone call were recorded separately and combined into a single stereo file), for best speech recognition, create two tracks with audio_channel to be left and right. If your stereo file is simply a recording made with a stereo microphone, audio_channel should be set to an empty string (or not be specified.)

audio_language can be used to specify the language of the audio media. This is an optional parameter and if not specified or an empty string, the language of the track will be automatically detected. If specified, it must be a language code as described in RFC5646 (see http://tools.ietf.org/html/rfc5646). Supported languages: en-US, en-UK, es, fr.

start_time a time in seconds that the media starts, relative to start time of the bundle. This allows you to specify sequential parts of media. If not specified, the default is 0.

parts_pending a boolean flag specifying if more media parts will subsequently be added to the track. If true, a subsequent API call must be made to signify that the track is complete. If not specified, the default is false.

track is the index in the tracks array where the new track will be added. Track numbers start at 0. If this parameter is not specified the new track will always be appended to the end of the array. If the track specified is greater than the last index of the array + 1, an error will be returned.

If version specified, the track will only be added if the current version matches this parameter value. If the version doesn't match, a 409 Conflict error will be returned. If version not specified, the track will always be updated.

OnInit
./lib/actions/post_v1_bundles__bundle_id__tracks.js
OnStartup
-
OnClose
-

Attributes

-

put_v1_bundles__bundle_id__tracks

Update tracks for a bundle.

parts_complete a boolean true or false. If true, any tracks in the PENDING state will be queued for processing and no more media parts may be added to the tracks. Default is false.

If version specified, the track will only be updated if the current version matches this parameter value. If the version doesn't match, a 409 Conflict error will be returned. If version not specified, the track will always be updated.

OnInit
./lib/actions/put_v1_bundles__bundle_id__tracks.js
OnStartup
-
OnClose
-

Attributes

-

delete_v1_bundles__bundle_id__tracks__track_id_

Delete a track of a bundle. This will only delete media stored on Clarify systems and not delete the source media on remote systems.

Successful response will be a HTTP code 204 with an empty body.

OnInit
./lib/actions/delete_v1_bundles__bundle_id__tracks__track_id_.js
OnStartup
-
OnClose
-

Attributes

-

get_v1_bundles__bundle_id__tracks__track_id_

Gets a single track in a bundle. This includes the specification of the media and the status of fetching and processing it.

Media for a track is fetched asynchronously. Until media has been retrieved, a track's duration and size will both be set to -1.

OnInit
./lib/actions/get_v1_bundles__bundle_id__tracks__track_id_.js
OnStartup
-
OnClose
-

Attributes

-

put_v1_bundles__bundle_id__tracks__track_id_

Add media to an existing track of a bundle. This can only be called on a track that currently has no media set or has parts pending.

Once all media parts have been added to a track it is immutable, meaning it cannot be modified. If you wish to modify a track, simply add a new one and delete the existing one.

media_url must be a publicly accessible url to a media file. It will be fetched asynchronously after the REST call returns. The audio can be mono or stereo.

audio_channel is used to specify audio channels if the media is a stereo file. A value of left or right signifies that only the specified channel will be used. If no value or an empty string is specified for audio_channel, all channels will be used in a single track. If your stereo channels were recorded separately with each channel containing distinct content (for example if 2 legs of a phone call were recorded separately and combined into a single stereo file), for best speech recognition, create two tracks with audio_channel to be left and right. If your stereo file is simply a recording made with a stereo microphone, audio_channel should be set to an empty string (or not be specified.)

audio_language can be used to specify the language of the audio media. This is an optional parameter and if not specified or an empty string, the language of the track will be automatically detected. If specified, it must be a language code as described in RFC5646 (see http://tools.ietf.org/html/rfc5646). Supported languages: en-US, en-UK, es, fr.

start_time a time in seconds that the media starts, relative to start time of the bundle. This allows you to specify sequential parts of media. If not specified, the default is 0.

parts_pending a boolean flag specifying if more media parts will subsequently be added to the track. If true, a subsequent API call must be made to signify that the track is complete. If not specified, the default is false.

If version specified, the track will only be added if the current version matches this parameter value. If the version doesn't match, a 409 Conflict error will be returned. If version not specified, the track will always be updated.

OnInit
./lib/actions/put_v1_bundles__bundle_id__tracks__track_id_.js
OnStartup
-
OnClose
-

Attributes

-

v1reportsscores

Analyzes bundle content over a series of time periods grouped by the value of group_field metadata field and generates a report of top scores.

interval specifies the duration of each time period in the report. For example, you can generate a report that gives monthly statistics. If there are no bundles for a given period, that period will not be present in the report.

score_field specifies a bundle, insights, or metadata field to use as a score. The scores will be averaged across the group and listed in descending order.

group_field specifies a metadata field by which to group statistics. Typically the field will represent a user or team id to get a report of the scores for the top users or teams.

filter is used to limit the bundles in the report according to specific criteria based on metadata and bundle values. A report filter behaves in the same way as a search filter. It uses an expression syntax similar to Javascript boolean expressions. An expression is made up of zero or more terms joined by logical operators with each term having a field, a comparison operator, and a literal value. Parentheses can be used to logically group terms.

A filter term is of the form: field-name comparison-operator literal-value where:

field-name is a metadata field or bundle.name, bundle.id, bundle.external_id, bundle.created, or bundle.updated.

comparison-operator is ==, <, >, <=, >=, or !=

literal-value is a number (integer or decimal), boolean true or false, or a string with either double quotes (") or single quotes (').

Logical operators between terms (and groups of terms) can be && (logical AND), || (logical OR). A logical NOT is ! and can be placed before a term (or group of terms.)


An example filter expression (assuming you have used metadata fields category and tag):


category=="music" && (tag == "soft" || tag == "smooth") && tag != "jazz" && bundle.created > "2014-03-15T00:00:00.0Z"


language parameter specifies the language to use for analyzing the report. This value is only relevant for language-related insight data. Supported languages: en, en-UK, en-US, es, fr.

OnInit
./lib/actions/v1reportsscores.js
OnStartup
-
OnClose
-

Attributes

-

v1reportstrends

Analyzes bundle content over a series of time periods and generates a trend report.

interval specifies the duration of each time period in the report. For example, you can generate a report that gives monthly statistics. If there are no bundles for a given period, that period will not be present in the report.

content specifies the content type to analyze and include in the report. These can include tracks and insights. Multiple values can be specified to generate a rich report. If content is not specified, only bundle counts are included in the report.

filter is used to limit the bundles in the report according to specific criteria based on metadata and bundle values. A report filter behaves in the same way as a search filter. It uses an expression syntax similar to Javascript boolean expressions. An expression is made up of zero or more terms joined by logical operators with each term having a field, a comparison operator, and a literal value. Parentheses can be used to logically group terms.

A filter term is of the form: field-name comparison-operator literal-value where:

field-name is a metadata field or bundle.name, bundle.id, bundle.external_id, bundle.created, or bundle.updated.

comparison-operator is ==, <, >, <=, >=, or !=

literal-value is a number (integer or decimal), boolean true or false, or a string with either double quotes (") or single quotes (').

Logical operators between terms (and groups of terms) can be && (logical AND), || (logical OR). A logical NOT is ! and can be placed before a term (or group of terms.)


An example filter expression (assuming you have used metadata fields category and tag):


category=="music" && (tag == "soft" || tag == "smooth") && tag != "jazz" && bundle.created > "2014-03-15T00:00:00.0Z"


language parameter specifies the language to use for analyzing the report. This value is only relevant for language-related insight data. Supported languages: en, en-UK, en-US, es, fr.

OnInit
./lib/actions/v1reportstrends.js
OnStartup
-
OnClose
-

Attributes

-

v1search

Searches the bundles and returns a list of matching bundles, along with what matched and where for each bundle.

query is used to search for text in the audio and metadata. It uses a simple query language similar to Google. At its simplest, it can be a space separated list of words (ex. open voice) which will find all bundles matching all the words. To search for a phrase, put it in quotes (ex. "open source") You can exclude bundles that contain a word by putting a minus (hyphen) in front of the word (ex. -opaque) To search for one word or another, use OR (in uppercase) between the words (ex. pizza OR pasta). As an alternative to OR, you can use | (pipe character). A full query could look something like: restaurant "little italy" pizza OR pasta -mushrooms

query_fields is used to specify what data in a bundle the query will search. It can contain one or more of insights.spoken_words, metadata fields, and/or bundle fields. Multiple values can be either an array of strings or a comma or space separated single string. By default (if the query_fields param is not included in a request or is a single empty string) all data will be searched.

query_fieldsBundle data searched
*all dataThis is the default value.
insights.spoken_words[spoken words]All audio tracks are searched.
fieldnamemetadata.fieldnameYour custom metadata field. Wildcard metadata.* searches all metadata fields.
bundle.fieldnamebundle.fieldnameThe searchable bundle fieldnames are name, id, external_id, created and updated. Wildcard bundle.* searches all bundle fields

As an example, suppose you have metadata fields name and description that you would like to search and other metadata fields you don't want to search. You also want to search the audio words, so you could specify query_fields = "insights.spoken_words, name, description".

filter is used to limit the search results according to specific criteria based on metadata and bundle values. It uses an expression syntax similar to Javascript boolean expressions. An expression is made up of zero or more terms joined by logical operators with each term having a field, a comparison operator, and a literal value. Parentheses can be used to logically group terms.

A filter term is of the form: field-name comparison-operator literal-value where:

field-name is a metadata field or bundle.name, bundle.id, bundle.external_id, bundle.created, or bundle.updated.

comparison-operator is ==, <, >, <=, >=, or !=

literal-value is a number (integer or decimal), boolean true or false, or a string with either double quotes (") or single quotes (').

Logical operators between terms (and groups of terms) can be && (logical AND), || (logical OR). A logical NOT is ! and can be placed before a term (or group of terms.)


An example filter expression (assuming you have used metadata fields category and tag):


category=="music" && (tag == "soft" || tag == "smooth") && tag != "jazz" && bundle.created > "2014-03-15T00:00:00.0Z"


language parameter specifies the language of the words in the search query. This value is used for word-stemming etc. while searching text. Regardless of what you set for this parameter, all your bundles will be searched, no matter what language content they contain. Supported languages: en, en-UK, en-US, es, fr.

After getting the initial list, use the first, next, prev link relations to get more bundles in the list. Note that next will not be available at the end of the list and prev will not be available at the start of the list. A maximum of limit items will be returned. If the results are exactly one page neither prev nor next will be available.

The embed parameter specifies link relations to embed in the results. For link relations that are curies (ex. "clarify:metadata"), you may simply use the base name (ex. "metadata").

OnInit
./lib/actions/v1search.js
OnStartup
-
OnClose
-

Attributes

-

No data available for terms

No data available for environment