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"
            ]
        },
        {
            "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"
            ]
        }
    ]
}

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"
    ]
}

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 create
  • color - 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"
	]
}

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 to
  • words - 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 from
  • word - Required (string) the word to delete

Response

A successful delete will respond with a Status No Content (204).

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.