Table of contents
Insights API
The Insights API allows you to create groups of words to search for in audio tracks (speech to text) and various other document text. Useful for compliance issues and flagging specific spoken/written phrases.
List all insight groups with associated words
GET /api/data/v3/insights
Response
A successful create will respond with a Status OK (200) response status/code 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
Return a single insight group
GET /api/data/v3/insights/{id}
{id}- (string) The ID of the Insight Group
Response
A successful create will respond with a Status OK (200) response status/code 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 will be a Status Not Found (404), with an error message as follows:
{
"error": "resource not found",
"request_id": UNIQUE_REQUEST_ID
}
Create a new Insight Group
Add a new insight group
POST /api/data/v3/insights
{
"name": "TV-MA",
"color": "#FFFF00",
"words": [
"keyword1",
"keyword2"
]
}
name- Required (string) Human-readable name of the insight group to createcolor- Required (string) full hex color, starting with “#” - e.g. “#FFFF00”words- Optional [string] is the keywords to associate with this insights group
Response
A successful create will respond with a Status Created (201) response status/code. The API will respond 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": []
}
Delete an Insight Group
DELETE /api/data/v3/insights/{id}
id- Required (string) unique ID of the insight group to delete
Response
A successful delete will respond with a Status No Content (204).
Add a words to a insight group
POST /api/data/v3/insights/{id}/keywords
{
"words": [
"predator",
"die hard",
"top gun",
"a failed word"
]
}
id- Required (string) unique ID of the insight group to add words towords- Required [string] collection of keywords to associate with the insight group
Note: All words provided will be downcased, leading/training white space removed, and words deduplicated before being created.
Response
A successful create will respond 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 then a Status Unprocessable Entity (422) will be returned with the same response body where duplicate words and failed words will be able to track what happened for the submitted keywords. All responses can be a mix of successfully added words, duplicate words, and failed words.
Delete a word from a insight group
Delete a single word from a insight group
DELETE /api/data/v3/insights/{id}/keywords/{word}
id- Required (string) unique ID of the insight group to delete the word fromword- Required (string) the word to delete
Response
A successful delete will respond with a Status No Content (204).
Search an item for insight groups combined timeline outputs
GET /api/data/v3/items/{item_id}/insights
item_idis the item_id
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 will return a Status OK (200) and any unexpected errors will return a Status Interval Server Error (500).
Search an item for insight group with combined timeline and word level outputs
GET /api/data/v3/items/{item_id}/insights/{insight_group_id}
item_idis the item_idinsight_group_idis 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 will return a Status OK (200) and any unexpected errors will return a Status Interval Server Error (500).
Add one or more access groups to an insight group
Adds 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 groupids- ([]string) Required. The list of access group identifiers to add to the insight group
Add User Groups Response
Expect a 204 status code.
Replace all access groups on an insight group
Removes any existing access groups and replaces 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 groupids- ([]string) Required. The list of access group identifiers to add to the insight group
Replace User Groups Response
Expect a 204 status code.
Delete 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 groupaccess_group_id- (string) Required. The access group identifier to remove from the insight group
Delete Access Group Response
Expect a 204 status code.
This documentation is generated from the latest version of GrayMeta Platform. For documentation relevant to your own deployed version, please use the documentation inside the application.
© 2021 GrayMeta, Inc.