Mentions

Update a mention

Set the engaged state, or update AI-judged relevance or sentiment. The action field selects the operation. For engage, pass engaged: true|false for an absolute, idempotent write; omitting it toggles the current value.

Returns the COMMITTED mention row (same shape as GET /api/v2/mentions/{sourceId}), never an echo of the request — e.g. relevance: 3 (clear) answers with the restored AI verdict, and the engaged field is the value the toggle actually stored. No follow-up GET is needed to learn the resulting state.

For ids that cannot ride in a URL path segment, use PATCH /api/v2/mentions/by-id?sourceId=… with the same body.

PATCH

api

mentions

{sourceId}

Update a mention

curl --request PATCH \
  --url https://app.octolens.com/api/v2/mentions/{sourceId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "action": "engage",
  "postId": 0,
  "timestamp": "2026-05-06 13:35:37.000",
  "engaged": true
}
'

import requests

url = "https://app.octolens.com/api/v2/mentions/{sourceId}"

payload = {
    "action": "engage",
    "postId": 0,
    "timestamp": "2026-05-06 13:35:37.000",
    "engaged": 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({
    action: 'engage',
    postId: 0,
    timestamp: '2026-05-06 13:35:37.000',
    engaged: true
  })
};

fetch('https://app.octolens.com/api/v2/mentions/{sourceId}', 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/mentions/{sourceId}",
  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([
    'action' => 'engage',
    'postId' => 0,
    'timestamp' => '2026-05-06 13:35:37.000',
    'engaged' => 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/mentions/{sourceId}"

	payload := strings.NewReader("{\n  \"action\": \"engage\",\n  \"postId\": 0,\n  \"timestamp\": \"2026-05-06 13:35:37.000\",\n  \"engaged\": 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/mentions/{sourceId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"action\": \"engage\",\n  \"postId\": 0,\n  \"timestamp\": \"2026-05-06 13:35:37.000\",\n  \"engaged\": true\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"action\": \"engage\",\n  \"postId\": 0,\n  \"timestamp\": \"2026-05-06 13:35:37.000\",\n  \"engaged\": true\n}"

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

{
  "id": 0,
  "sourceId": "reddit_t3_1abc234",
  "url": "https://reddit.com/r/example/comments/abc123/...",
  "title": "<string>",
  "body": "<string>",
  "source": "reddit",
  "timestamp": "2026-05-06 13:35:37.000",
  "author": "jane.doe",
  "authorName": "<string>",
  "authorAvatar": "<string>",
  "authorUrl": "<string>",
  "authorFollowers": 0,
  "relevance": "relevant",
  "relevanceComment": "<string>",
  "sentiment": "Neutral",
  "language": "english",
  "tags": [
    "competitor_mention",
    "pricing"
  ],
  "keywords": [
    {
      "id": 42,
      "keyword": "social listening"
    }
  ],
  "engaged": true,
  "relevanceScore": 123,
  "feedbackRelevant": 123,
  "imageUrl": "<string>",
  "keywordId": 123
}

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

Path Parameters

sourceId

string

required

Body

application/json

Option 1
Option 2
Option 3

Mutation request for a mention. The action field discriminates which update to apply.

action

string

required

Set the engaged-with flag on the mention. Pass engaged for an absolute, idempotent write; omit it to TOGGLE the current value.

Allowed value: "engage"

postId

integer

required

Internal post id.

Required range: -9007199254740991 <= x <= 9007199254740991

timestamp

string

required

The mention's timestamp, copied verbatim from the list/export response. Tinybird-style format (YYYY-MM-DD HH:mm:ss.SSS, UTC, no Z suffix); ISO 8601 also accepted. Used together with sourceId / postId to uniquely key the mention.

Pattern: ^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2}(\.\d{1,9})?(Z|[+-]\d{2}:?\d{2})?$

Example:

"2026-05-06 13:35:37.000"

engaged

boolean

Target state: true marks the mention engaged, false un-marks it. The write is absolute and idempotent — safe to retry and safe to call concurrently. OMITTING it toggles the current value, which is what the web app's engage button does; non-interactive callers should always pass it.

Example:

true

Response

200 response

A single mention collected from a social platform. Canonical shape shared by list_mentions (MCP), GET /api/v2/mentions (REST), and the tRPC feed.

integer

required

Internal post id (numeric). Pass as postId to PATCH /api/v2/mentions/{sourceId}.

Required range: -9007199254740991 <= x <= 9007199254740991

sourceId

string

required

Stable composite key for the mention across the collection pipeline (e.g. reddit_t3_1abc234). Use this as the path parameter for PATCH /api/v2/mentions/{sourceId} and as the sourceId field on POST /api/v2/feedback.

Example:

"reddit_t3_1abc234"

url

string

required

Canonical URL to the original post.

Example:

"https://reddit.com/r/example/comments/abc123/..."

title

string | null

required

Post title. null for platforms that don't have titles (tweets, etc.).

body

string | null

required

Post body / content. May be empty or null for posts with no text.

source

string

required

Platform the mention was collected from. Lowercase values like reddit, twitter, linkedin. Historical rows may be uppercase.

Example:

"reddit"

timestamp

string

required

When the mention was posted. Tinybird-style datetime string (YYYY-MM-DD HH:mm:ss.SSS, UTC, no Z suffix).

Example:

"2026-05-06 13:35:37.000"

author

string | null

required

Handle/username of the mention's author. null if not captured.

Example:

"jane.doe"

authorName

string | null

required

Display name of the author, when distinct from the handle.

authorAvatar

string | null

required

URL to the author's avatar image. null if not captured.

authorUrl

string | null

required

URL to the author's profile page. null if not captured.

authorFollowers

integer | null

required

Author's follower count at collection time. null if not available.

Required range: -9007199254740991 <= x <= 9007199254740991

relevance

enum<string>

required

Relevance classification. Always one of relevant / not_relevant (unscored posts collapse to not_relevant).

Available options:

relevant,

not_relevant

Example:

"relevant"

relevanceComment

string | null

required

Free-text justification the AI produced for its relevance verdict, when available.

sentiment

enum<string> | null

required

Sentiment classification. null until the AI has scored this mention.

Available options:

Positive,

Neutral,

Negative

Example:

"Neutral"

language

string | null

required

Detected language as a full lowercase English name (english, spanish, …; undetermined when detection fails) — never an ISO 639-1 code.

Example:

"english"

tags

enum<string>[]

required

AI-assigned topic tags applied to the mention.

AI-assigned topic tag. Applied by the relevance worker during scoring. A post can carry multiple tags.

Available options:

buy_intent,

competitor_mention,

customer_testimonial,

promotional_post,

own_brand_mention,

industry_insights,

hiring,

event,

product_question,

pricing,

churn_intent,

launch_announcement,

bug_report,

user_feedback,

ai_generated

Example:

["competitor_mention", "pricing"]

keywords

object[]

required

Monitored keywords this mention matched, with id + display text.

Show child attributes

Example:

[{ "id": 42, "keyword": "social listening" }]

engaged

boolean

required

Whether a workspace member has marked this mention as engaged-with (replied, liked on-platform, etc.).

relevanceScore

number | null

Raw internal relevance score (0 = high, 1 = medium, 2 = low). The public relevance field is derived from this. Optional; not all consumers populate it.

feedbackRelevant

number

User feedback on this mention's relevance: 1 for thumbs up, -1 for thumbs down, 0 for no feedback. Optional.

imageUrl

string | null

URL to a preview image attached to the post, when present.

keywordId

number

Denormalized first-matched keyword id. Convenience for callers that need a single keyword reference without scanning keywords[].

Update a mention

curl --request PATCH \
  --url https://app.octolens.com/api/v2/mentions/{sourceId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "action": "engage",
  "postId": 0,
  "timestamp": "2026-05-06 13:35:37.000",
  "engaged": true
}
'

import requests

url = "https://app.octolens.com/api/v2/mentions/{sourceId}"

payload = {
    "action": "engage",
    "postId": 0,
    "timestamp": "2026-05-06 13:35:37.000",
    "engaged": 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({
    action: 'engage',
    postId: 0,
    timestamp: '2026-05-06 13:35:37.000',
    engaged: true
  })
};

fetch('https://app.octolens.com/api/v2/mentions/{sourceId}', 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/mentions/{sourceId}",
  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([
    'action' => 'engage',
    'postId' => 0,
    'timestamp' => '2026-05-06 13:35:37.000',
    'engaged' => 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/mentions/{sourceId}"

	payload := strings.NewReader("{\n  \"action\": \"engage\",\n  \"postId\": 0,\n  \"timestamp\": \"2026-05-06 13:35:37.000\",\n  \"engaged\": 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/mentions/{sourceId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"action\": \"engage\",\n  \"postId\": 0,\n  \"timestamp\": \"2026-05-06 13:35:37.000\",\n  \"engaged\": true\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"action\": \"engage\",\n  \"postId\": 0,\n  \"timestamp\": \"2026-05-06 13:35:37.000\",\n  \"engaged\": true\n}"

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

{
  "id": 0,
  "sourceId": "reddit_t3_1abc234",
  "url": "https://reddit.com/r/example/comments/abc123/...",
  "title": "<string>",
  "body": "<string>",
  "source": "reddit",
  "timestamp": "2026-05-06 13:35:37.000",
  "author": "jane.doe",
  "authorName": "<string>",
  "authorAvatar": "<string>",
  "authorUrl": "<string>",
  "authorFollowers": 0,
  "relevance": "relevant",
  "relevanceComment": "<string>",
  "sentiment": "Neutral",
  "language": "english",
  "tags": [
    "competitor_mention",
    "pricing"
  ],
  "keywords": [
    {
      "id": 42,
      "keyword": "social listening"
    }
  ],
  "engaged": true,
  "relevanceScore": 123,
  "feedbackRelevant": 123,
  "imageUrl": "<string>",
  "keywordId": 123
}

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