Table of contents

Keywords API

The Keywords 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 keyword groups and words

GET /api/data/keywords

Returns a list of all groups + words

{
    "keyword_groups": [
        {
            "keyword_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"
            ]
        },
        {
            "keyword_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"
            ]
        }
    ]
}

Keyword Group Detail

Return a single keyword group

GET /api/data/keyword-groups/{id}
  • {id} - (string) The ID of the Keyword Group
{
    "keyword_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"
    ]
}

Create a new Keyword Group

Add a new keyword group

POST /api/data/keyword-groups
{
	"name": "TV-MA",
	"color": "#FFFF00"
}
  • name - Required (string) Human-readable name of the keyword group to create
  • color - Required (string) full hex color, starting with “#” - e.g. “#FFFF00”

Response

The API will respond with a body exactly like the “Keyword Group Detail” endpoint returns

Delete a Keyword Group

DELETE /api/data/keyword-groups/{id}
  • id - Required (string) unique ID of the keyword group to delete

Add a word or words to a keyword group

POST /api/data/keywords/{id}
{
    "word": "predator, die hard, top gun"
}
  • id - Required (string) unique ID of the keyword group to add words to
  • word - Required (string) single or multiple words separated by a comma

Response

Newly added words will appear in the added_words array, and any duplicate words which were ignored will be in the duplicate_words array

{
    "keyword_group_id": "596fd91dd5fec5aae37fe02f9d393df8",
    "added_words": ["predator", "top gun"],
    "duplicate_words": [
        "die hard"
    ]
}

Delete a word from a keyword group

Delete a single word from a keyword group

DELETE /api/data/keywords/{id}?word={word}
  • id - Required (string) unique ID of the keyword group to delete the word from
  • word - Required (string) the word to delete

Response

If deletion was successful, API will respond as so:

{
    "word": "die hard",
    "keyword_group_id": "596fd91dd5fec5aae37fe02f9d393df8",
    "deleted": true
}

Get all Keyword Group and Keyword hits for an item:

GET /api/data/keywords/hits/{item_id}

Response

{
    "insights": [
        {
            "group_name": "Supplier",
            "color": "#4DD0E1",
            "words": [
                "content delivery",
                "exclusive",
                "hollywood",
                "payments",
                "pepsi",
                "price increase",
                "term",
                "termination"
            ],
            "matches": [
                {
                    "type": "captions",
                    "timeline": [
                        {
                            "start_at": 30.03,
                            "end_at": 44.97,
                            "count": 1
                        }
                    ],
                    "source": "2minuteVideo.srt"
                },
                {
                    "type": "captions",
                    "timeline": [
                        {
                            "start_at": 30.03,
                            "end_at": 44.97,
                            "count": 1
                        }
                    ],
                    "source": "2minuteVideo.srt"
                },
                {
                    "type": "captions",
                    "timeline": [
                        {
                            "start_at": 30.03,
                            "end_at": 44.97,
                            "count": 1
                        }
                    ],
                    "source": "2minuteVideo.srt"
                }
            ]
        }
    ]
}

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.