Insights API in Wasabi AiR

20 May 2024
5 Minutes to read

Insights API in Wasabi AiR

Updated on 20 May 2024
5 Minutes to read

Article summary

Did you find this summary helpful?

Thank you for your feedback

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/insights

Response

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.

Before the group is created, all words provided are changed to lowercase characters, leading/trailing white space is removed, and duplicate words are removed.

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.

What's Next

Item Object in Wasabi AiR

Table of contents

Listing All Insight Groups With Associated Words
Insight Group Detail
Creating a New Insight Group
Deleting an Insight Group
Adding a Word to an Insight Group
Deleting a Word From an Insight Group
Searching an Item
Adding One or More Access Groups to an Insight Group
Replacing All Access Groups On an Insight Group
Deleting an Access Group From an Insight Group

WASABI and the WASABI logo are trademarks of Wasabi Technologies LLC and may not be used without permission of Wasabi Technologies. All other names are used for identification purposes only and are trademarks or registered trademarks of their respective companies.

Information presented herein is subject to change without notice. Companies, names, and data used in examples are fictitious unless otherwise noted. No part of this information may be reproduced or transmitted in any form by means electronic or mechanical, for any purpose, without express written permission of Wasabi Technologies.