Skip to main content
PATCH
/
api
/
v2
/
keywords
/
{id}
Update a keyword
curl --request PATCH \
  --url https://app.octolens.com/api/v2/keywords/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "context": "<string>",
  "additionalTerms": "<string>",
  "additionalTermsAndOr": true,
  "caseSensitive": true,
  "symbolSensitive": true,
  "platforms": [
    "reddit"
  ],
  "excludeWords": "<string>",
  "wildcardExcludeWords": "<string>",
  "excludeAuthors": "<string>",
  "color": "#7c3aed",
  "tag": "own_brand"
}
'
{
  "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",
  "color": "#7c3aed",
  "tag": "own_brand",
  "paused": true,
  "isSubReddit": true
}

Documentation Index

Fetch the complete documentation index at: https://octolens.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
id
integer
required
Required range: -9007199254740991 <= x <= 9007199254740991

Body

application/json

Partial update. Omitted fields are left unchanged. Pass an empty string to clear a text-list field; pass an empty array to require explicit platform reset (not allowed).

​
context
string

Replace the relevance-context sentence.

Maximum string length: 200
​
additionalTerms
string

Replace comma-separated additional terms. Empty string clears.

Maximum string length: 500
​
additionalTermsAndOr
boolean

OR (true) or AND (false) for additional terms.

​
caseSensitive
boolean

Toggle case-sensitive matching.

​
symbolSensitive
boolean

Toggle "exact match" mode.

​
platforms
enum<string>[]

Replace the platforms list. Must be a non-empty subset of plan-allowed sources.

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
​
excludeWords
string

Replace comma-separated exact-match exclusions. Empty string clears.

Maximum string length: 1000
​
wildcardExcludeWords
string

Replace comma-separated wildcard exclusions. Empty string clears.

Maximum string length: 1000
​
excludeAuthors
string

Replace comma-separated excluded author handles. Empty string clears.

Maximum string length: 1000
​
color
string

6-digit hex color with leading #, e.g. #7c3aed.

Pattern: ^#[0-9a-fA-F]{6}$
Example:

"#7c3aed"

​
tag
enum<string>

Classification of what this keyword represents. Used to route posts to brand / competitor / industry-context workflows and pick the right AI prompt.

Available options:
own_brand,
competitor,
industry_term
Example:

"own_brand"

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
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"

​
color
string
required

UI color tag shown next to the keyword.

Pattern: ^#[0-9a-fA-F]{6}$
Example:

"#7c3aed"

​
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.