Create Keyword

POST/v2/organizations/{organizationId}/keywords

Creates a new keyword (monitoring query) within the specified organization.

2 req/10s

Parameters

Path Parameters

organizationIdintegerrequiredpath

The unique identifier of the organization (int64).

Body Parameters

groupIdintegerrequiredbody

The ID of the group to add the keyword to (int64).

namestringrequiredbody

Display name for the keyword.

keywordjsonrequiredbody

Keyword definition object containing the search query and filters. See keyword object fields below.

Keyword Object Fields

Field	Type	Description
naturalQuery	string	The search query in natural language. Supports boolean operators like OR, AND, and quoted phrases.
naturalFilters	string	Filters written in the natural filter syntax: one key:value,value filter per line. Use author: and not_author: to filter by author. See Filtering by Author.
mayAuthors	array of object	Only keep mentions written by one of these authors. Each entry is an Author Object. Equivalent to author: in naturalFilters.
notAuthors	array of object	Exclude mentions written by any of these authors. Each entry is an Author Object. Equivalent to not_author: in naturalFilters.
mayLangs	array of string	Language codes to include (e.g. ["en", "de"]). Use the Languages endpoint to get valid codes.
mayLocations	array of string	Location codes to include (e.g. ["US", "GB"]). Use the Locations endpoint to get valid codes.
maySourceTypes	array of string	Source types to monitor. Allowed values: WEB, FACEBOOK, TWITTER, FORUM, COMMENT, YOUTUBE, INSTAGRAM, REDDIT, TIKTOK, PRINT, RADIO, TV, BLUESKY

Author Object

Field	Type	Description
author	string	The author name or handle to match. Compared against the whole author string of a mention, not as a substring. See How author matching works.
caseSensitive	boolean	Match the exact casing of author. Defaults to false (case-insensitive).

Additional filter fields

The keyword object supports many additional filter fields beyond those listed above. The fields documented here cover the most common use cases. Contact support for information about advanced filtering options.

Request Body Example

{
  "groupId": 456,
  "name": "Tesla Mentions",
  "keyword": {
    "naturalQuery": "Tesla OR \"Elon Musk\"",
    "naturalFilters": "not_author:\"Tesla Fan Club\"",
    "mayLangs": ["en", "de"],
    "maySourceTypes": ["WEB", "TWITTER", "FACEBOOK"]
  }
}

Filtering by Author

Author filters include or exclude mentions by specific authors. They are part of the keyword object and can be written in two equivalent ways.

Natural filters (recommended)

naturalFilters is a plain-text field. Write one filter per line as key:value1,value2,.... Separate values with commas and wrap values that contain spaces in double quotes. Filters may also be separated by spaces instead of new lines. author: keeps only mentions written by one of the listed authors, and not_author: excludes mentions written by any of them.

{
  "groupId": 123,
  "name": "Starbucks",
  "keyword": {
    "naturalQuery": "Starbucks AND coffee",
    "naturalFilters": "author:Starbucks,\"Starbucks Coffee\"\nnot_author:\"Some Blogger\""
  }
}

Structured fields

The same filters as arrays of Author Objects inside the keyword object. Only this form lets you set caseSensitive per author, shown here on one entry.

"keyword": {
  "naturalQuery": "Starbucks AND coffee",
  "mayAuthors": [
    { "author": "Starbucks" },
    { "author": "Starbucks Coffee", "caseSensitive": true }
  ],
  "notAuthors": [
    { "author": "Some Blogger" }
  ]
}

Both forms can be combined with other filters in the same request. If the same filter is provided in both forms, the value from naturalFilters is used.

How author matching works

• The author value is compared against the whole author string of the mention. It is an exact match, not a "contains" search.
• Matching is case-insensitive by default. Set caseSensitive: true to require the exact casing.
• Accents and diacritics are not folded: Jose does not match José. Different Unicode encodings of the same characters are treated as equal, so how the name was typed does not matter.
• What counts as the author depends on the source type. When a source records several author values, matching any one of them is enough.

Source type	Author filter is matched against
WEB	The article byline. Articles without a byline never match.
COMMENT	The comment author's name.
TWITTER, BLUESKY	The display name and the handle.
INSTAGRAM	The full name (when set) and the username.
FACEBOOK	The page or user name and the numeric page/user ID.
YOUTUBE	The channel name and the channel ID.
REDDIT, TIKTOK	The username.
PRINT, RADIO, TV	The author field of the article or clip, when available.
FORUM	No author is recorded for forum mentions, so author filters never match them.

Validation rules

• Author lists must not be empty and must not contain duplicates.
• The same author cannot appear in both the include list and the exclude list.
• An unknown filter key or a malformed value returns HTTP 400. See Errors & Rate Limits.

Validate a definition before creating it

POST /v2/keywords/validate with the body { "keyword": { ... } } checks a keyword definition without creating anything. The response contains the normalized naturalFilters and the structured definition, so you can see exactly how your filters were interpreted.

Try it

Parameters

organizationId *integer

Organization ID

Keyword

Group ID *integer

The group to add the keyword to

Keyword Name *string

Display name for the keyword

Keyword Definition

Search Query *string

Natural language search query

Filters text

Natural filters such as author: and not_author: (see Filtering by Author)

Languages select multiple

Include mentions in these languages

Locations select multiple

Include mentions from these locations

Source Types select multiple

Include mentions from these sources

Response

{
  "id": 789,
  "name": "Tesla Mentions",
  "color": "#4A90D9",
  "naturalQuery": "Tesla OR \"Elon Musk\"",
  "active": true,
  "createdAt": "2024-01-15T10:30:00Z",
  "editedAt": "2024-01-15T10:30:00Z"
}

Response Fields

Field	Type	Description
id	integer (int64)	Unique identifier for the created keyword
name	string	Display name of the keyword
color	string	Hex color code assigned to the keyword
naturalQuery	string	The search query as provided in the request
active	boolean	Whether the keyword is actively monitoring
createdAt	string (ISO 8601)	Timestamp of when the keyword was created
editedAt	string (ISO 8601)	Timestamp of the last edit to the keyword