Profanity Filters API Documentation

Overview

These endpoints manage Profanity Filters: reusable word-to-substitution tied to a base_model, which you assign to a LEXI Live instance via profanity_filter_id (see Instances in the LEXI Live API documentation). The list format is the same idea as Topic Model substitutions: each entry maps a phrase in recognition output to replacement text (and optional case sensitivity). Additionally, there is a set of Default Profanity Filters provided for various languages, which are not editable, but can be used or duplicated as a base.

Denotes an optional parameter.

Profanity Filters

Default Profanity Filters: The list returned by GET /profanity-filters will always include EEG-provided Default Profanity Filters. You may read and duplicate defaults; PUT, DELETE, and any list changes (POST/PATCH under /profanity-filters/:pf_id/profanity) are rejected for Default Profanity Filters with a 403 error.
Resource Description
GET /profanity-filters

Action

Retrieves list of Profanity Filters available to your credential set, including Default Profanity Filters.

POST /profanity-filters

Action

Creates a new Profanity Filter (empty Profanity List until you upload or patch entries).

Parameters (JSON)
filter_name (string) Display name for the filter.
base_model (string) Base ASR model ID (same family as Topic Models), e.g. en-US_BroadbandModel. Must be one of the allowed base models.
GET /profanity-filters/:pf_id

Action

Returns filter metadata and the full profanity list as an array of entries.

Parameters (Path)
:pf_id (string) Profanity Filter ID.
PUT /profanity-filters/:pf_id

Action

Updates filter_name and base_model only (same JSON shape as POST /profanity-filters). Disallowed for Default Profanity Filters, resulting in a 403 error.

Parameters (Path)
:pf_id (string) Profanity Filter ID.
Parameters (JSON)
filter_name (string) Display name for the filter.
base_model (string) Base ASR model ID (same family as Topic Models), e.g. en-US_BroadbandModel. Must be one of the allowed base models.
DELETE /profanity-filters/:pf_id

Action

Deletes the filter and its stored list. Fails with HTTP 400 if any instance still references this pf_id in settings. Disallowed for Default Profanity Filters, resulting in a 403 error.

Parameters (Path)
:pf_id (string) Profanity Filter ID.
POST /profanity-filters/:pf_id/duplicate

Action

Creates a new Profanity Filter based on the "source" Profanity Filter, with a new name and base model. If the source has a Profanity List, the list is copied to the new Profanity Filter. Allowed for Default Profanity Filters, so you can fork a Default Profanity Filter into an editable Profanity Filter.

Parameters (Path)
:pf_id (string) Profanity Filter ID of the Profanity Filter to duplicate.
Parameters (JSON) 

If entire body is omitted, the new Profanity Filter will have the same name and base model as the source Profanity Filter. If either one of the field values is provided, then both must be provided.

filter_name (string) The name of the new Profanity Filter.
base_model (string) The base model of the new Profanity Filter.

Denotes an optional parameter.

Profanity List

Retrieving, bulk-uploading (CSV), and patching Profanity List entries for a Profanity Filter. This mirrors LEXI Topic Models substitutions: each row is a phrase to match in recognition output and the text to show instead. POST and PATCH are blocked for Default Profanity Filters.
Resource Description
GET /profanity-filters/:pf_id/profanity

Action

Returns the Profanity List as JSON. Unlike GET /profanity-filters/:pf_id, profanity_list is a dictionary whose keys are words and values are { "substitution", "caseSensitive" }.

Parameters (Path)
:pf_id (string) Profanity Filter ID.
Parameters (Query)
download (string)  If download=true, the response is a CSV file attachment instead of JSON. Filename is based on the filter name.
POST /profanity-filters/:pf_id/profanity

Action

Upload a CSV file to add or replace list entries (multipart form-data). Disallowed for Default Profanity Filters, resulting in a 403 error.

Parameters (Path)
:pf_id (string) Profanity Filter ID.
Parameters (Query)
overwrite (boolean)  true replaces the entire list with the file contents; false (default) merges with existing entries. Values: true or false.
Parameters (form-data)
profanity_filter_file CSV file (required).
CSV format

No header row. Exactly three columns per row (same idea as substitution CSV):

Phrase to match Substitution text Case sensitive (true or false)
Limits

Up to 10,000 entries per list; each word and substitution up to 50 characters (enforced on upload and patch).

HTTP 409 (Conflict)

If this Profanity Filter is assigned to a LEXI Instance that currently has an active captioning job, the request fails with 409 and a JSON error string indicating that an Instance is active and using this Profanity Filter.

PATCH /profanity-filters/:pf_id/profanity

Action

Applies a list of entry updates in one request (JSON body). Disallowed for Default Profanity Filters, resulting in a 403 error.

Parameters (Path)
:pf_id (string) Profanity Filter ID.
Parameters (JSON)
profanity_list (array) Array of objects: word (string), substitution (string), optional caseSensitive (boolean). Set substitution to JSON null to remove an entry for that word.
Example

This payload adds or updates one phrase and removes another:

{
    "profanity_list": [
        { "word": "BadWord", "substitution": "****", "caseSensitive": false },
        { "word": "BadWord2", "substitution": "", "caseSensitive": true },
        { "word": "OldWord", "substitution": null }
    ]
}
HTTP 409 (Conflict)

If this Profanity Filter is assigned to a LEXI Instance that currently has an active captioning job, the request fails with 409 and a JSON error string indicating that an Instance is active and using this Profanity Filter.

Denotes an optional parameter.

Base URL for all endpoints on this page: https://eegcloud.tv