Update a keyword - Octolens

PATCH

api

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": [],
  "excludeWords": "<string>",
  "wildcardExcludeWords": "<string>",
  "excludeAuthors": "<string>",
  "tag": "own_brand",
  "paused": true
}
'

import requests

url = "https://app.octolens.com/api/v2/keywords/{id}"

payload = {
    "context": "<string>",
    "additionalTerms": "<string>",
    "additionalTermsAndOr": True,
    "caseSensitive": True,
    "symbolSensitive": True,
    "platforms": [],
    "excludeWords": "<string>",
    "wildcardExcludeWords": "<string>",
    "excludeAuthors": "<string>",
    "tag": "own_brand",
    "paused": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    context: '<string>',
    additionalTerms: '<string>',
    additionalTermsAndOr: true,
    caseSensitive: true,
    symbolSensitive: true,
    platforms: [],
    excludeWords: '<string>',
    wildcardExcludeWords: '<string>',
    excludeAuthors: '<string>',
    tag: 'own_brand',
    paused: true
  })
};

fetch('https://app.octolens.com/api/v2/keywords/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.octolens.com/api/v2/keywords/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'context' => '<string>',
    'additionalTerms' => '<string>',
    'additionalTermsAndOr' => true,
    'caseSensitive' => true,
    'symbolSensitive' => true,
    'platforms' => [
        
    ],
    'excludeWords' => '<string>',
    'wildcardExcludeWords' => '<string>',
    'excludeAuthors' => '<string>',
    'tag' => 'own_brand',
    'paused' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.octolens.com/api/v2/keywords/{id}"

	payload := strings.NewReader("{\n  \"context\": \"<string>\",\n  \"additionalTerms\": \"<string>\",\n  \"additionalTermsAndOr\": true,\n  \"caseSensitive\": true,\n  \"symbolSensitive\": true,\n  \"platforms\": [],\n  \"excludeWords\": \"<string>\",\n  \"wildcardExcludeWords\": \"<string>\",\n  \"excludeAuthors\": \"<string>\",\n  \"tag\": \"own_brand\",\n  \"paused\": true\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://app.octolens.com/api/v2/keywords/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"context\": \"<string>\",\n  \"additionalTerms\": \"<string>\",\n  \"additionalTermsAndOr\": true,\n  \"caseSensitive\": true,\n  \"symbolSensitive\": true,\n  \"platforms\": [],\n  \"excludeWords\": \"<string>\",\n  \"wildcardExcludeWords\": \"<string>\",\n  \"excludeAuthors\": \"<string>\",\n  \"tag\": \"own_brand\",\n  \"paused\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.octolens.com/api/v2/keywords/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"context\": \"<string>\",\n  \"additionalTerms\": \"<string>\",\n  \"additionalTermsAndOr\": true,\n  \"caseSensitive\": true,\n  \"symbolSensitive\": true,\n  \"platforms\": [],\n  \"excludeWords\": \"<string>\",\n  \"wildcardExcludeWords\": \"<string>\",\n  \"excludeAuthors\": \"<string>\",\n  \"tag\": \"own_brand\",\n  \"paused\": true\n}"

response = http.request(request)
puts response.read_body

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

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404,
    "details": [
      "<unknown>"
    ],
    "upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
    "upgradeCommand": "octolens upgrade"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404,
    "details": [
      "<unknown>"
    ],
    "upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
    "upgradeCommand": "octolens upgrade"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404,
    "details": [
      "<unknown>"
    ],
    "upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
    "upgradeCommand": "octolens upgrade"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404,
    "details": [
      "<unknown>"
    ],
    "upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
    "upgradeCommand": "octolens upgrade"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404,
    "details": [
      "<unknown>"
    ],
    "upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
    "upgradeCommand": "octolens upgrade"
  }
}

Authorizations

Authorization

string

header

required

Clerk API key. Create one in Settings → API Keys. Pass as Authorization: Bearer <key>. Keys carry a scope — read, write (implies read) or admin (implies write) — chosen when the key is minted. Each operation's security requirement (and its x-required-scope extension) names the minimum scope it needs; request the least-privileged key that covers the operations you call.

Path Parameters

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: 1000

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.

Minimum array length: 1

Platform a text or subreddit keyword can monitor. Review sources are configured through Settings → Platforms → Customer reviews instead.

Available options:

dev,

github,

hackernews,

linkedin,

producthunt,

reddit,

stackoverflow,

twitter,

youtube,

tiktok,

medium,

reddit_comment,

bluesky,

newsletter,

podcasts,

news,

firehose,

instagram

excludeWords

string

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

Maximum string length: 5000

wildcardExcludeWords

string

Replace comma-separated wildcard exclusions. Empty string clears.

Maximum string length: 5000

excludeAuthors

string

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

Maximum string length: 5000

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"

paused

boolean

true pauses collection, false resumes it. Omit to leave it unchanged.

Response

200 response

One monitored keyword.

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,

trustpilot_reviews,

google_reviews,

app_store_reviews,

google_play_reviews,

instagram

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.

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": [],
  "excludeWords": "<string>",
  "wildcardExcludeWords": "<string>",
  "excludeAuthors": "<string>",
  "tag": "own_brand",
  "paused": true
}
'

import requests

url = "https://app.octolens.com/api/v2/keywords/{id}"

payload = {
    "context": "<string>",
    "additionalTerms": "<string>",
    "additionalTermsAndOr": True,
    "caseSensitive": True,
    "symbolSensitive": True,
    "platforms": [],
    "excludeWords": "<string>",
    "wildcardExcludeWords": "<string>",
    "excludeAuthors": "<string>",
    "tag": "own_brand",
    "paused": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    context: '<string>',
    additionalTerms: '<string>',
    additionalTermsAndOr: true,
    caseSensitive: true,
    symbolSensitive: true,
    platforms: [],
    excludeWords: '<string>',
    wildcardExcludeWords: '<string>',
    excludeAuthors: '<string>',
    tag: 'own_brand',
    paused: true
  })
};

fetch('https://app.octolens.com/api/v2/keywords/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.octolens.com/api/v2/keywords/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'context' => '<string>',
    'additionalTerms' => '<string>',
    'additionalTermsAndOr' => true,
    'caseSensitive' => true,
    'symbolSensitive' => true,
    'platforms' => [
        
    ],
    'excludeWords' => '<string>',
    'wildcardExcludeWords' => '<string>',
    'excludeAuthors' => '<string>',
    'tag' => 'own_brand',
    'paused' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.octolens.com/api/v2/keywords/{id}"

	payload := strings.NewReader("{\n  \"context\": \"<string>\",\n  \"additionalTerms\": \"<string>\",\n  \"additionalTermsAndOr\": true,\n  \"caseSensitive\": true,\n  \"symbolSensitive\": true,\n  \"platforms\": [],\n  \"excludeWords\": \"<string>\",\n  \"wildcardExcludeWords\": \"<string>\",\n  \"excludeAuthors\": \"<string>\",\n  \"tag\": \"own_brand\",\n  \"paused\": true\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://app.octolens.com/api/v2/keywords/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"context\": \"<string>\",\n  \"additionalTerms\": \"<string>\",\n  \"additionalTermsAndOr\": true,\n  \"caseSensitive\": true,\n  \"symbolSensitive\": true,\n  \"platforms\": [],\n  \"excludeWords\": \"<string>\",\n  \"wildcardExcludeWords\": \"<string>\",\n  \"excludeAuthors\": \"<string>\",\n  \"tag\": \"own_brand\",\n  \"paused\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.octolens.com/api/v2/keywords/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"context\": \"<string>\",\n  \"additionalTerms\": \"<string>\",\n  \"additionalTermsAndOr\": true,\n  \"caseSensitive\": true,\n  \"symbolSensitive\": true,\n  \"platforms\": [],\n  \"excludeWords\": \"<string>\",\n  \"wildcardExcludeWords\": \"<string>\",\n  \"excludeAuthors\": \"<string>\",\n  \"tag\": \"own_brand\",\n  \"paused\": true\n}"

response = http.request(request)
puts response.read_body

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

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404,
    "details": [
      "<unknown>"
    ],
    "upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
    "upgradeCommand": "octolens upgrade"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404,
    "details": [
      "<unknown>"
    ],
    "upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
    "upgradeCommand": "octolens upgrade"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404,
    "details": [
      "<unknown>"
    ],
    "upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
    "upgradeCommand": "octolens upgrade"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404,
    "details": [
      "<unknown>"
    ],
    "upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
    "upgradeCommand": "octolens upgrade"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "status": 404,
    "details": [
      "<unknown>"
    ],
    "upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
    "upgradeCommand": "octolens upgrade"
  }
}