The Insights API enables you to create groups of words to search for in audio tracks (speech-to-text) and various other document text. This is useful for compliance issues and flagging specific spoken or written phrases.
Listing All Insight Groups With Associated Words
GET /api/data/v3/insightsResponse
A successful create responds with a Status OK (200) with the following body, which includes a list of all groups with corresponding words:
{
"insight_groups": [
{
"insight_group_id": "596fd91dd5fec5aae37fe02f9d393df8",
"name": "Bad Words",
"color": "#FF0000",
"num_words": 7,
"created_at": "2017-07-19T22:11:41.752231Z",
"updated_at": "2017-07-19T22:16:46.122576Z",
"words": [
"ass",
"bad",
"boom",
"crap",
"fudge",
"poop",
"shoot"
],
"access_groups": [
"5ec36cca9f163654dc737e6fb8822321",
"5ec36cce7f5637d4815cac98a59173d0"
]
},
{
"insight_group_id": "596fd91dd5fec5aae37fe02f9d393df8",
"name": "Band Names",
"color": "#006699",
"num_words": 4,
"created_at": "2017-07-19T22:11:41.752231Z",
"updated_at": "2017-07-19T22:16:46.122576Z",
"words": [
"eagles",
"pink floyd",
"rolling stones",
"zz top"
],
"access_groups": []
}
]
}Insight Group Detail
To return a single insight group:
GET /api/data/v3/insights/{id}
- {id} - (string) The ID of the insight group.
Response
A successful create responds with a Status OK (200) with the following body:
{
"insight_group_id": "596fd91dd5fec5aae37fe02f9d393df8",
"name": "Band Names",
"color": "#006699",
"num_words": 4,
"created_at": "2017-07-19T22:11:41.752231Z",
"updated_at": "2017-07-19T22:16:46.122576Z",
"words": [
"eagles",
"pink floyd",
"rolling stones",
"zz top"
],
"access_groups": [
"5ec36cca9f163654dc737e6fb8822321",
"5ec36cce7f5637d4815cac98a59173d0"
]
}If the insight group is not found by that ID, the response is a Status Not Found (404) with an error message as follows:
{
"error": "resource not found",
"request_id": UNIQUE_REQUEST_ID
}Creating a New Insight Group
To add a new insight group:
POST /api/data/v3/insights
{
"name": "TV-MA",
"color": "#FFFF00",
"words": [
"keyword1",
"keyword2"
]
}- name - (string) Required. The human-readable name of the insight group to create.
- color - (string) Required. The full hex color, starting with # (for example, #FFFF00).
- words - [string] Optional. The keywords to associate with this insights group.
Response
A successful create responds with a Status Created (201). The API responds with a body as follows:
{
"insight_group_id": "xxxxd91dd5fec5aae37fe02f9d393df8",
"name": "TV-MA",
"color": "#FFFF00",
"num_words": 2,
"created_at": "2017-07-19T22:11:41.752231Z",
"updated_at": "2017-07-19T22:16:46.122576Z",
"words": [
"keyword1",
"zz keyword2"
],
"access_groups": []
}Deleting an Insight Group
DELETE /api/data/v3/insights/{id}- id - (string) Required. The unique ID of the insight group to delete.
Response
A successful delete responds with a Status No Content (204).
Adding a Word to an Insight Group
POST /api/data/v3/insights/{id}/keywords
{
"words": [
"predator",
"die hard",
"top gun",
"a failed word"
]
}- id - (string) Required. The unique ID of the insight group to which to add words.
- words - [string] Required. A collection of keywords to associate with the insight group.
Response
A successful create responds with a Status Created (201). The response body is as follows:
{
"insight_group_id": "596fd91dd5fec5aae37fe02f9d393df8",
"keywords": {
"added_words": ["predator", "top gun"],
"duplicate_words": ["die hard"],
"failed_words": ["a failed word"]
}
}If at least one word is added, a Status Created (201) is returned. If no words are created, a Status Unprocessable Entity (422) is returned with the same response body in which duplicate words and failed words can track what happened for the submitted keywords. All responses can be a mix of successfully added words, duplicate words, and failed words.
Deleting a Word From an Insight Group
To delete a single word from an insight group:
DELETE /api/data/v3/insights/{id}/keywords/{word}- id - (string) Required. The unique ID of the insight group from which to delete the word.
- word - (string) Required. The word to delete.
Response
A successful delete responds with a Status No Content (204).
Searching an Item
For Insight Groups Combined Timeline Outputs
GET /api/data/v3/items/{item_id}/insights- item_id - The ID of the item for which to search.
Response
{
"insights": [
{
"insight_group_id": "5d164334d1a18e38ca9291dee36040db",
"name": "US Cities",
"color": "#e8ef58",
"combined_timeline": {
"ocr": [
{
"start": 68,
"end": 70
}
]
},
"words": [
{
"word": "Abilene"
},
{
"word": "Yonkers"
}
]
},
{
"insight_group_id": "5d14d53b9b09e352421bb9d1698bc572",
"name": "kim kard group",
"color": "#f2a78e",
"combined_timeline": {
"caption": [
{
"start": 0.03,
"end": 4.92
},
...
{
"start": 223.929,
"end": 227.111
}
],
"ocr": [
{
"start": 12,
"end": 14
},
...
{
"start": 112,
"end": 122
}
],
"speech_to_text": [
{
"start": 0.12,
"end": 60.24
},
...
{
"start": 70.77,
"end": 131.5
}
]
},
"words": [
{
"word": "kardashian"
},
{
"word": "cramden"
},
{
"word": "kim"
}
]
},
...
]
}A successful response returns a Status OK (200) and any unexpected errors return a Status Interval Server Error (500).
For Insight Groups With Combined Timeline and Word Level Outputs
GET /api/data/v3/items/{item_id}/insights/{insight_group_id}- item_id - The ID of the item for which to search.
- insight_group_id - The insight group ID.
Response
{
"insight": {
"insight_group_id": "5d152df033f6d05fe864f6ea7a134ff6",
"name": "kim group",
"color": "#2e42f4",
"combined_timeline": {
"caption": [
{
"start": 0.03,
"end": 4.92
},
{
"start": 9.63,
"end": 18.452
}
],
"ocr": [
{
"start": 4,
"end": 8
},
...
{
"start": 112,
"end": 122
}
],
"speech_to_text": [
{
"start": 0.12,
"end": 10.28
}
]
},
"words": [
{
"word": "news",
"timelines": {
"ocr": [
{
"start": 4,
"end": 8
},
...
{
"start": 112,
"end": 122
}
]
}
},
{
"word": "kardashian",
"timelines": {
"caption": [
{
"start": 0.03,
"end": 4.92
},
{
"start": 9.63,
"end": 18.452
}
],
"ocr": [
{
"start": 18,
"end": 28
},
{
"start": 64,
"end": 68
}
],
"speech_to_text": [
{
"start": 0.12,
"end": 10.28
}
]
}
}
]
}
}A successful response returns a Status OK (200) and any unexpected errors return a Status Interval Server Error (500).
Adding One or More Access Groups to an Insight Group
To add the requested access groups to the specific insights group:
POST /api/data/v3/insights/{insight_group_id}/groups
{
ids: [
"5ec36cca9f163654dc737e6fb8822321",
"5ec36cce7f5637d4815cac98a59173d0"
]
}- insight_group_id - (string) Required. The unique identifier of the insight group.
- ids - ([]string) Required. The list of access group identifiers to add to the insight group.
Response
Expect a 204 status code.
Replacing All Access Groups On an Insight Group
To remove any existing access groups and replace them with the requested list of IDs.
PUT /api/data/v3/insights/{insight_group_id}/groups
{
ids: [
"5ec36cca9f163654dc737e6fb8822321",
"5ec36cce7f5637d4815cac98a59173d0"
]
}- insight_group_id - (string) Required. The unique identifier of the insight group.
- ids - ([]string) Required. The list of access group identifiers to add to the insight group.
Response
Expect a 204 status code.
Deleting an Access Group From an Insight Group
DELETE /api/data/v3/insights/{insight_group_id}/groups/{access_group_id}- insight_group_id - (string) Required. The unique identifier of the insight group.
- access_group_id - (string) Required. The access group identifier to be removed from the insight group.
Response
Expect a 204 status code.