Skip to main content
POST
/
api
/
v2
/
keywords
Create a keyword
curl --request POST \
  --url https://app.octolens.com/api/v2/keywords \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "keyword": "acme corp",
  "context": "<string>",
  "additionalTerms": "deployment, preview",
  "additionalTermsAndOr": true,
  "caseSensitive": false,
  "symbolSensitive": true,
  "platforms": [
    "reddit"
  ],
  "excludeWords": "<string>",
  "wildcardExcludeWords": "<string>",
  "excludeAuthors": "<string>",
  "tag": "own_brand",
  "isSubReddit": true
}
'
{
  "id": 42,
  "keyword": "acme corp",
  "context": "Acme is a cloud storage company, not the cartoon.",
  "additionalTerms": "deployment, preview",
  "additionalTermsAndOr": true,
  "caseSensitive": true,
  "symbolSensitive": true,
  "platforms": [
    "reddit",
    "twitter",
    "youtube"
  ],
  "excludeWords": "jobs, hiring, is-for-sale",
  "wildcardExcludeWords": "<string>",
  "excludeAuthors": "spambot1, crypto_guy",
  "tag": "own_brand",
  "paused": true,
  "isSubReddit": true
}

Authorizations

​
Authorization
string
header
required

Clerk API key. Create one in Settings → API Keys. Pass as Authorization: Bearer <key>.

Body

application/json

Create a new monitored keyword. Triggers an immediate first data-stream run.

​
keyword
string
required

The phrase to track.

Required string length: 1 - 100
Example:

"acme corp"

​
context
string

Short sentence describing what this keyword is tracking. Used for AI relevance scoring. If omitted, a context sentence is auto-generated from your company profile.

Maximum string length: 200
​
additionalTerms
string

Comma-separated terms required alongside the main keyword.

Maximum string length: 500
Example:

"deployment, preview"

​
additionalTermsAndOr
boolean
default:true

If true (default), any one of the additional terms must appear alongside the keyword (OR). If false, all of them must appear (AND). Matches the app UI.

​
caseSensitive
boolean
default:false

If true, matching is case-sensitive.

​
symbolSensitive
boolean
default:true

Exact-match mode. If true (default), the keyword is matched as a whole phrase — for multi-word keywords, the words must appear together. If false, each word can appear anywhere in the post, which typically produces noisier results. Matches the app UI's "Exact match" toggle.

​
platforms
enum<string>[]

Platforms to monitor. Optional — when omitted, the server defaults to every plan-allowed source. Pass an explicit subset only to narrow the monitoring (e.g. Reddit + Twitter only).

Minimum array length: 1

Platform a mention can originate from / a keyword can be monitored on.

Available options:
dev,
github,
hackernews,
linkedin,
producthunt,
reddit,
stackoverflow,
twitter,
youtube,
tiktok,
medium,
reddit_comment,
bluesky,
newsletter,
podcasts,
news,
firehose
​
excludeWords
string

Comma-separated exact-match exclusions.

Maximum string length: 1000
​
wildcardExcludeWords
string

Comma-separated wildcard exclusion patterns (use *).

Maximum string length: 1000
​
excludeAuthors
string

Comma-separated author handles to filter out.

Maximum string length: 1000
​
tag
enum<string>

Optional. When omitted, the AI classifies the keyword from the company profile (own_brand / competitor / industry_term) and persists it alongside the rest of the AI enrichment (context, excludeWords, additionalTerms). Pass an explicit value only when the user has already classified it.

Available options:
own_brand,
competitor,
industry_term
Example:

"own_brand"

​
isSubReddit
boolean

Set to true if this keyword represents a subreddit rather than a free-text phrase.

Response

200 response

One monitored keyword.

​
id
integer
required

Stable numeric keyword ID.

Required range: -9007199254740991 <= x <= 9007199254740991
Example:

42

​
keyword
string
required

The phrase being tracked.

Example:

"acme corp"

​
context
string | null
required

Short sentence disambiguating the keyword for AI relevance scoring. Auto-generated from the company profile when a keyword is created without an explicit context.

Example:

"Acme is a cloud storage company, not the cartoon."

​
additionalTerms
string | null
required

Additional terms required alongside the main keyword (comma-separated). Combined with additionalTermsAndOr to form AND/OR semantics.

Example:

"deployment, preview"

​
additionalTermsAndOr
boolean
required

How additionalTerms combine: true = OR (any one must appear), false = AND (all must appear).

​
caseSensitive
boolean
required

If true, matching is case-sensitive. Default false.

​
symbolSensitive
boolean
required

Also known as "exact match" in the UI. When true, multi-word keywords require the words to appear together. When false, each word can appear anywhere in the post (noisier).

​
platforms
enum<string>[]
required

Platforms this keyword is monitored on.

Platform a mention can originate from / a keyword can be monitored on.

Available options:
dev,
github,
hackernews,
linkedin,
producthunt,
reddit,
stackoverflow,
twitter,
youtube,
tiktok,
medium,
reddit_comment,
bluesky,
newsletter,
podcasts,
news,
firehose
Example:
["reddit", "twitter", "youtube"]
​
excludeWords
string | null
required

Comma-separated words that disqualify a post if present. Applied as exact-match terms.

Example:

"jobs, hiring, is-for-sale"

​
wildcardExcludeWords
string | null
required

Comma-separated wildcard exclusion patterns. Supports * for prefix/suffix match (e.g. spam* matches spammer).

​
excludeAuthors
string | null
required

Comma-separated author handles / usernames whose posts should be filtered out.

Example:

"spambot1, crypto_guy"

​
tag
enum<string> | null
required

Classification tag. null for legacy keywords without a tag.

Available options:
own_brand,
competitor,
industry_term
Example:

"own_brand"

​
paused
boolean
required

When true, data collection is paused for this keyword.

​
isSubReddit
boolean | null
required

When true, this keyword represents a subreddit to monitor rather than a free-text phrase. null for non-Reddit keywords.