Skip to main content
POST
/
api
/
v2
/
feedback
Submit relevance feedback
curl --request POST \
  --url https://app.octolens.com/api/v2/feedback \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sourceId": "reddit_t3_1abc234",
  "timestamp": "2026-05-06 13:35:37.000",
  "keywordId": 0,
  "source": "reddit",
  "feedbackType": "RELEVANT",
  "postId": 0,
  "feedbackReason": "<string>",
  "feedbackSource": "API",
  "originalRelevanceScore": 123
}
'
{
  "id": 0,
  "sourceId": "<string>",
  "timestamp": "<string>",
  "organizationId": "<string>",
  "postId": 0,
  "keywordId": 0,
  "source": "<string>",
  "feedbackType": "RELEVANT",
  "feedbackReason": "<string>",
  "feedbackSource": "API",
  "originalRelevanceScore": 123,
  "createdBy": "<string>",
  "createdAt": "2023-11-07T05:31:56Z"
}

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

Body

application/json

Submit or upsert a relevance feedback record for a mention.

​
sourceId
string
required

Mention's sourceId (e.g. reddit_t3_1abc234).

Example:

"reddit_t3_1abc234"

​
timestamp
string
required

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. Required to uniquely key the feedback row.

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"

​
keywordId
integer
required

ID of the keyword the mention matched (from Keyword.id).

Required range: -9007199254740991 <= x <= 9007199254740991
​
source
string
required

Platform source (e.g. reddit, twitter).

Example:

"reddit"

​
feedbackType
enum<string>
required

The user's verdict on the mention. RELEVANT = the mention matters, NOT_RELEVANT = it's noise.

Available options:
RELEVANT,
NOT_RELEVANT
​
postId
integer

Optional internal post id for extra joinability.

Required range: -9007199254740991 <= x <= 9007199254740991
​
feedbackReason
string

Optional free-text reason shown to the relevance agent as extra context.

​
feedbackSource
enum<string>
default:WEB

Where the feedback came from. WEB = app UI, EMAIL = digest email link, API = programmatic.

Available options:
WEB,
EMAIL,
API
Example:

"API"

​
originalRelevanceScore
number

What the AI originally scored the mention (0=high, 1=medium, 2=low). Captured for analytics.

Response

200 response

A persisted feedback record.

​
id
integer
required

Feedback record id.

Required range: -9007199254740991 <= x <= 9007199254740991
​
sourceId
string
required

Mention key.

​
timestamp
string
required

Mention timestamp, echoed back as submitted (Tinybird-style YYYY-MM-DD HH:mm:ss.SSS or ISO 8601).

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

Workspace id that owns this record.

​
postId
integer | null
required

Linked internal post id, when known.

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

Keyword id this feedback is about.

Required range: -9007199254740991 <= x <= 9007199254740991
​
source
string
required

Platform source.

​
feedbackType
enum<string>
required

The user's verdict on the mention. RELEVANT = the mention matters, NOT_RELEVANT = it's noise.

Available options:
RELEVANT,
NOT_RELEVANT
​
feedbackReason
string | null
required

Free-text reason, if provided.

​
feedbackSource
enum<string>
required

Where the feedback came from. WEB = app UI, EMAIL = digest email link, API = programmatic.

Available options:
WEB,
EMAIL,
API
Example:

"API"

​
originalRelevanceScore
number | null
required
​
createdBy
string | null
required

User id of the submitter, if known.

​
createdAt
string<date-time>
required
Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$