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

# Track a whole Discord server as a keyword

> Creates a keyword for the connected server (`kind: discord_server`, named after the server) and binds every message of the server (or of `channelIds`) to it, without a text match; each message is still checked for relevance. It uses one ordinary keyword slot (`400 KEYWORD_LIMIT_EXCEEDED` when none is left) and pauses, resumes and deletes like any keyword (`/api/v2/keywords/{id}`). Idempotent per server: when the workspace already tracks it, the existing keyword and binding are answered with `alreadyExisted: true` and nothing is created, even at the keyword limit. Its posts count toward the workspace's monthly mention allowance; `dailyCap` (1–2000) adds an optional per-UTC-day budget, and omitting it or sending `null` means none. Every `channelIds` entry must be a readable channel of the server inside its channel scope (`400 DISCORD_CHANNEL_INVALID`). Ordinary keywords need none of this: they match Discord messages when their platforms include `discord`. Requires an `admin`-scoped key; `404 DISCORD_LINK_NOT_FOUND` for a disconnected or another workspace's server, `403 DISCORD_SOURCE_UNAVAILABLE` while the Discord source is not enabled for the workspace.



## OpenAPI

````yaml https://app.octolens.com/api/v2/openapi.json post /api/v2/integrations/discord/servers/{linkId}/keyword
openapi: 3.1.0
info:
  title: Octolens API
  version: 2.0.0
  description: >-
    The Octolens API lets you query mentions, manage keywords, and configure
    feeds programmatically. Every action available in the Octolens UI is
    available here.


    ### Authentication


    Public v2 endpoints require an API key. Create one in **Settings > API** and
    pass it as `Authorization: Bearer <key>`. Keys are scoped to the
    organization they were minted in; you cannot access another org's data.
    Internal UI endpoints (`x-internal: true`) require a member session in the
    active workspace instead, and a trusted browser origin for writes.


    API keys carry a scope — `read`, `write` (implies read), or `admin` (implies
    write). Each endpoint documents the scope it needs via the
    `x-required-scope` OpenAPI extension and the scope badge in the docs
    surface.


    ### Rate limiting


    The v2 API is rate-limited at **500 requests per hour per organization**,
    across all keys for that org. The limit resets at the top of each clock hour
    (fixed hourly window — the counter is keyed by the UTC hour bucket, not a
    rolling trailing hour).


    Every 2xx response carries three headers so clients can pace themselves:

    * `X-RateLimit-Limit` — the hourly cap (500)

    * `X-RateLimit-Remaining` — requests left in the current window

    * `X-RateLimit-Reset` — Unix timestamp (seconds) when the window resets


    When the cap is hit, the endpoint returns **429 Rate Limited** with an
    additional `Retry-After` header (seconds until the next window). The
    response body is the standard `ErrorResponse` with `code: "RATE_LIMITED"`.


    `POST /api/v2/mentions/export` additionally has its own, stricter limits —
    **5 exports per hour and 2 concurrent exports per organization** — because a
    single export fans out into up to 500 backing queries. See that endpoint's
    description; prefer one filtered export over polling exports on a schedule.


    ### Response timing


    Every response also carries a standard `Server-Timing` header with the
    server-side breakdown of that request — `auth` (credential verification,
    plan gate and rate limiting), `handler` (the endpoint's own work) and
    `total`, in milliseconds. Use it to tell whether a slow call was spent in
    the API's request pipeline, in the query behind the endpoint, or on the
    network in between; browsers surface it automatically in devtools. Responses
    rejected before the endpoint ran carry `auth` and `total` only, and an
    endpoint may publish extra metrics of its own alongside these three — parse
    the header as a list, not as a fixed triple.


    ### Error handling


    All non-2xx responses share the same `ErrorResponse` envelope: `{ error: {
    code, message, status, details? } }`. The `code` field is a stable
    `ApiErrorCode` enum — branch on it programmatically instead of parsing
    `message`. See the `ApiErrorCode` schema for the full catalog grouped by
    category.


    `VALIDATION_ERROR` (400) responses include a `details` array with per-field
    Zod issues — inspect `details[i].path` to pinpoint which input was rejected.


    Unknown paths under `/api/v2/` (including the bare `/api/v2` root) answer
    **404** with the same envelope (`code: "NOT_FOUND"`) and a message pointing
    back at this spec — never an HTML error page. Legacy `/api/v1/` paths behave
    the same with v1's lowercase-code envelope (`code: "not_found"`).


    ### Discovery


    Machine-readable entry points, for agents and tooling:

    * `GET /api/v2/openapi.json` — this document (also mirrored at
    `https://octolens.com/openapi.json`)

    * `GET /api/v2/docs` — human-readable reference rendered from it

    * `GET /.well-known/oauth-protected-resource/api/v2` — RFC 9728
    protected-resource metadata for this API, declaring `scopes_supported:
    [read, write, admin]`

    * `GET /.well-known/oauth-protected-resource` — the same metadata for the
    MCP server (`/api/mcp/v2`, OAuth)


    ### Building filter bodies


    Endpoints that accept `simpleFilters` / `advancedFilters` (e.g. `POST
    /api/v2/mentions`, `PATCH /api/v2/feeds/{id}`) take a structured object that
    can be tricky to hand-craft. If you just have a natural-language description
    of what you want ("negative posts about pricing on reddit in the last
    week"), call `POST /api/v2/ai/filter-wizard` with that prompt and it will
    return a ready-to-use filter object you can pass straight through.
servers:
  - url: https://app.octolens.com
    description: Production
  - url: http://localhost:3000
    description: Local development
security:
  - ApiKey:
      - read
paths:
  /api/v2/integrations/discord/servers/{linkId}/keyword:
    post:
      tags:
        - Integrations
      summary: Track a whole Discord server as a keyword
      description: >-
        Creates a keyword for the connected server (`kind: discord_server`,
        named after the server) and binds every message of the server (or of
        `channelIds`) to it, without a text match; each message is still checked
        for relevance. It uses one ordinary keyword slot (`400
        KEYWORD_LIMIT_EXCEEDED` when none is left) and pauses, resumes and
        deletes like any keyword (`/api/v2/keywords/{id}`). Idempotent per
        server: when the workspace already tracks it, the existing keyword and
        binding are answered with `alreadyExisted: true` and nothing is created,
        even at the keyword limit. Its posts count toward the workspace's
        monthly mention allowance; `dailyCap` (1–2000) adds an optional
        per-UTC-day budget, and omitting it or sending `null` means none. Every
        `channelIds` entry must be a readable channel of the server inside its
        channel scope (`400 DISCORD_CHANNEL_INVALID`). Ordinary keywords need
        none of this: they match Discord messages when their platforms include
        `discord`. Requires an `admin`-scoped key; `404 DISCORD_LINK_NOT_FOUND`
        for a disconnected or another workspace's server, `403
        DISCORD_SOURCE_UNAVAILABLE` while the Discord source is not enabled for
        the workspace.
      operationId: createDiscordServerKeyword
      parameters:
        - in: path
          name: linkId
          schema:
            description: The connected server's link id (`DiscordServer.linkId`).
            example: 12
            type: integer
            exclusiveMinimum: 0
            maximum: 9007199254740991
          required: true
          description: The connected server's link id (`DiscordServer.linkId`).
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                channelIds:
                  description: >-
                    Channels to collect; omit or `[]` for every channel the
                    server link reads. Each id must be a readable channel of the
                    server and inside its channel scope.
                  example: []
                  maxItems: 500
                  type: array
                  items:
                    description: >-
                      A Discord snowflake id as a decimal string (64-bit — never
                      parse it as a number).
                    example: '1290000000000000200'
                    type: string
                    pattern: ^\d{1,20}$
                dailyCap:
                  description: >-
                    Optional daily budget: posts this server may add per UTC day
                    (1–2000). Omit or `null` for none: the server's messages
                    then count only toward the workspace's monthly mention
                    allowance.
                  example: null
                  anyOf:
                    - type: integer
                      minimum: 1
                      maximum: 2000
                    - type: 'null'
                tag:
                  $ref: '#/components/schemas/KeywordTag'
                  description: >-
                    The keyword's tag. Default `own_brand` (a workspace's own
                    community server).
                  example: own_brand
                color:
                  description: Display colour, `#RRGGBB`. Default `#7c3aed`.
                  example: '#6D62F2'
                  type: string
                  pattern: ^#[0-9A-Fa-f]{6}$
      responses:
        '200':
          description: 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscordServerKeyword'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden (insufficient plan or permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKey:
            - admin
components:
  schemas:
    KeywordTag:
      description: >-
        Classification of what this keyword represents. Used to route posts to
        brand / competitor / industry-context workflows and pick the right AI
        prompt.
      example: own_brand
      type: string
      enum:
        - own_brand
        - competitor
        - industry_term
    DiscordServerKeyword:
      type: object
      properties:
        keyword:
          $ref: '#/components/schemas/Keyword'
          description: 'The whole-server keyword (`kind: discord_server`).'
        monitor:
          $ref: '#/components/schemas/DiscordMonitor'
          description: Its binding to the server.
        alreadyExisted:
          description: >-
            `true` when this workspace already tracked the server (by its link,
            so another invite of the same server counts): nothing new was
            created and no keyword slot was used.
          type: boolean
      required:
        - keyword
        - monitor
        - alreadyExisted
      additionalProperties: false
    ErrorResponse:
      description: >-
        Standard error envelope returned for all non-2xx responses. The `code`
        field is stable — safe to branch on programmatically. `code`, `message`
        and `status` are always present; anything else is additive and per-code
        (`details` on `VALIDATION_ERROR`, `upgradeUrl`/`upgradeCommand` on
        `UPGRADE_REQUIRED`).
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              $ref: '#/components/schemas/ApiErrorCode'
              description: >-
                Machine-readable error code. See `ApiErrorCode` for the full
                list.
              example: NOT_FOUND
            message:
              description: Human-readable error message.
              example: Resource not found
              type: string
            status:
              description: HTTP status code — always matches the response status.
              example: 404
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            details:
              description: >-
                Present on `VALIDATION_ERROR` responses. Contains Zod issues
                describing each failing field (path, code, message).
              type: array
              items: {}
            upgradeUrl:
              description: >-
                Present on `UPGRADE_REQUIRED` responses (additive — see
                `ApiErrorCode`): the URL of the upgrade page for this workspace.
              example: https://app.octolens.com/me/upgrade?src=agents
              type: string
            upgradeCommand:
              description: >-
                Present on `UPGRADE_REQUIRED` responses (additive): the CLI
                command that mints a single-use, already-authenticated link into
                the upgrade page.
              example: octolens upgrade
              type: string
          required:
            - code
            - message
            - status
          additionalProperties: false
      required:
        - error
      additionalProperties: false
    Keyword:
      description: One monitored keyword.
      type: object
      properties:
        id:
          description: Stable numeric keyword ID.
          example: 42
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        keyword:
          description: The phrase being tracked.
          example: acme corp
          type: string
        context:
          description: >-
            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.
          anyOf:
            - type: string
            - type: 'null'
        additionalTerms:
          description: >-
            Additional terms required alongside the main keyword
            (comma-separated). Combined with `additionalTermsAndOr` to form
            AND/OR semantics.
          example: deployment, preview
          anyOf:
            - type: string
            - type: 'null'
        additionalTermsAndOr:
          description: >-
            How `additionalTerms` combine: `true` = OR (any one must appear),
            `false` = AND (all must appear).
          type: boolean
        caseSensitive:
          description: If `true`, matching is case-sensitive. Default `false`.
          type: boolean
        symbolSensitive:
          description: >-
            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).
          type: boolean
        platforms:
          description: Platforms this keyword is monitored on.
          example:
            - reddit
            - twitter
            - youtube
          type: array
          items:
            $ref: '#/components/schemas/Platform'
        excludeWords:
          description: >-
            Comma-separated words that disqualify a post if present. Applied as
            exact-match terms.
          example: jobs, hiring, is-for-sale
          anyOf:
            - type: string
            - type: 'null'
        wildcardExcludeWords:
          description: >-
            Comma-separated wildcard exclusion patterns. Supports `*` for
            prefix/suffix match (e.g. `spam*` matches `spammer`).
          anyOf:
            - type: string
            - type: 'null'
        excludeAuthors:
          description: >-
            Comma-separated author handles / usernames whose posts should be
            filtered out.
          example: spambot1, crypto_guy
          anyOf:
            - type: string
            - type: 'null'
        tag:
          description: Classification tag. `null` for legacy keywords without a tag.
          anyOf:
            - $ref: '#/components/schemas/KeywordTag'
            - type: 'null'
        paused:
          description: When `true`, data collection is paused for this keyword.
          type: boolean
        isSubReddit:
          description: >-
            When `true`, this keyword represents a subreddit to monitor rather
            than a free-text phrase. `null` for non-Reddit keywords.
          anyOf:
            - type: boolean
            - type: 'null'
        kind:
          description: >-
            `text`: matched by its words on its platforms. `discord_server`:
            collects every message of one connected Discord server (its binding:
            `GET /api/v2/integrations/discord/monitors?keywordId=`); `keyword`
            is the server's name and is never matched as text. Absent = `text`.
          example: text
          type: string
          enum:
            - text
            - discord_server
      required:
        - id
        - keyword
        - context
        - additionalTerms
        - additionalTermsAndOr
        - caseSensitive
        - symbolSensitive
        - platforms
        - excludeWords
        - wildcardExcludeWords
        - excludeAuthors
        - tag
        - paused
        - isSubReddit
      additionalProperties: false
    DiscordMonitor:
      type: object
      properties:
        id:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        linkId:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        guildId:
          description: >-
            A Discord snowflake id as a decimal string (64-bit — never parse it
            as a number).
          example: '1290000000000000200'
          type: string
          pattern: ^\d{1,20}$
        keywordId:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        channelIds:
          description: Watched channel ids; `[]` = every channel the server link reads.
          type: array
          items:
            description: >-
              A Discord snowflake id as a decimal string (64-bit — never parse
              it as a number).
            example: '1290000000000000200'
            type: string
            pattern: ^\d{1,20}$
        legacy:
          description: >-
            `true`: this monitor hangs off an ordinary text keyword (the
            pre-November 2026 per-keyword watch). It collects nothing; delete
            it, and track the server as its own keyword instead. `false`: the
            binding of a whole-server keyword (`keywordId`).
          type: boolean
        status:
          description: >-
            `paused`: paused by an admin. `paused_bot_removed`: waits for the
            bot to be re-added to the server, then resumes on its own.
          type: string
          enum:
            - active
            - paused
            - paused_bot_removed
        dailyCap:
          description: >-
            Optional daily budget (posts per UTC day); `null` = none, only the
            workspace's monthly mention allowance applies.
          example: null
          anyOf:
            - type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        todayCount:
          description: Posts created so far this UTC day.
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        lastErrorCode:
          description: >-
            e.g. `missing_access` when the bot can read none of the watched
            channels.
          anyOf:
            - type: string
            - type: 'null'
        estimatedMonthlyMentions:
          description: >-
            Expected mentions per month, capped by the daily budget when one is
            set; null = unknown (no stats yet).
          anyOf:
            - type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        createdAt:
          example: '2026-10-28T12:00:00.000Z'
          type: string
        updatedAt:
          example: '2026-10-28T12:00:00.000Z'
          type: string
      required:
        - id
        - linkId
        - guildId
        - keywordId
        - channelIds
        - legacy
        - status
        - dailyCap
        - todayCount
        - lastErrorCode
        - estimatedMonthlyMentions
        - createdAt
        - updatedAt
      additionalProperties: false
    ApiErrorCode:
      description: >-
        Stable, machine-readable error code. Grouped as follows:


        **Auth / request shape** — `UNAUTHORIZED` (401), `FORBIDDEN` (403),
        `RATE_LIMITED` (429), `VALIDATION_ERROR` (400 — response carries a
        `details` array with Zod issues), `INTERNAL_ERROR` (500).


        **Agency master-key org selection** — `ORGANIZATION_REQUIRED` (400 — an
        agency master key must pass the `x-octolens-organization-id` header to
        select a target workspace), `FORBIDDEN_ORGANIZATION` (403 — the
        requested organization does not belong to the key's agency).


        **Plan / quota walls** — `UPGRADE_REQUIRED` (403 — an Agents-plan wall:
        a cap was hit (the lifetime search allowance or the monthly mention
        quota), or the endpoint is not part of the Agents plan at all — on that
        plan only search, org/usage/auth introspection, the upgrade link and
        monitoring recommendations are available, and every other endpoint
        answers this code before validating input; the envelope carries two
        ADDITIVE fields alongside the standard three, `upgradeUrl` (the upgrade
        page) and `upgradeCommand` (`octolens upgrade`, which mints a single-use
        authenticated link into that page), so an agent gets an actionable next
        step, not just prose), `QUOTA_EXCEEDED` (402 — the monthly mention quota
        is exhausted on a non-Agents plan; enable flex pricing or upgrade). The
        search routes also send `X-Octolens-Searches-Remaining` /
        `X-Octolens-Mentions-Remaining` response headers on success so clients
        can self-throttle before either wall.


        **Manual workspace review** — `WORKSPACE_PENDING_REVIEW` (403 — the
        workspace is waiting for a review by the Octolens team; every endpoint
        except `GET /api/v2/auth` answers this code until it is approved, and
        the very next request after approval succeeds; retry later).


        **Not found (404)** — generic `NOT_FOUND` plus domain-specific variants:
        `FEED_NOT_FOUND`, `KEYWORD_NOT_FOUND`, `KEYWORDS_NOT_FOUND`,
        `POST_NOT_FOUND`, `MENTION_NOT_FOUND`, `SUMMARY_NOT_FOUND`,
        `SEARCH_NOT_FOUND`, `SUGGESTION_NOT_FOUND`, `COMPANY_NOT_FOUND`,
        `ORG_NOT_FOUND`, `SETTINGS_NOT_FOUND`, `NOTIFICATION_NOT_FOUND`,
        `VIEW_NOT_FOUND`, `ALERT_NOT_FOUND`, `ATTENTION_ITEM_NOT_FOUND`. A
        resource id that exists but belongs to another workspace answers the
        SAME not-found as an unused id — existence is never leaked across
        tenants. `FEATURE_DISABLED` (404) — the endpoint is behind a feature
        flag (beta) that is off for this workspace.


        **Authorization (403)** — generic `FORBIDDEN` (the caller is not
        permitted to perform the operation, e.g. insufficient API-key scope).
        There are deliberately NO per-resource 403 codes: cross-workspace access
        reads as the resource's 404. `WEB_SOURCE_UNAVAILABLE`,
        `INSTAGRAM_SOURCE_UNAVAILABLE`, `FACEBOOK_SOURCE_UNAVAILABLE`,
        `DISCORD_SOURCE_UNAVAILABLE`, `THREADS_SOURCE_UNAVAILABLE` (403) — a
        keyword or workspace `platforms` write newly enables a source that is
        still rolling out and not available to this workspace; drop that
        platform and retry.


        **Discord servers and watch monitors (`/integrations/discord/*`)** —
        `DISCORD_SOURCE_UNAVAILABLE` (403) also answers every write there while
        Discord is not enabled for the workspace (a disconnect excepted),
        `DISCORD_ADMIN_ONLY` (403 — the caller is not an admin: a member, or a
        key without the `admin` scope; also answered by `PATCH` / `DELETE
        /keywords/{id}`, `POST /keywords/{id}/pause` and author excludes on a
        whole-server Discord keyword), `DISCORD_LINK_NOT_FOUND` /
        `DISCORD_MONITOR_NOT_FOUND` (404), `DISCORD_CHANNEL_INVALID` (400 — a
        channel id is not a readable channel of the server, or is outside its
        channel scope; the envelope adds `invalidChannelIds`),
        `DISCORD_MONITOR_KEYWORD_OWNED` (409 — the monitor is a whole-server
        keyword's binding; delete the keyword instead), `DISCORD_LINK_BUSY` /
        `DISCORD_MONITOR_BUSY` (409 — it kept changing concurrently; retry).


        **Business-rule violations (400)** — `INVALID_INPUT` (semantically
        invalid arguments), `KEYWORD_LIMIT_EXCEEDED` (plan cap hit),
        `KEYWORD_SOURCE_MANAGED` (a whole-server Discord keyword's platforms,
        terms and exclusions cannot change), `KEYWORD_OPERATOR_SYNTAX` (the
        keyword carries search-operator syntax — quotes, a leading `+`, a
        `-term`, `AND`/`OR`, a mid-string `*` — which is matched literally and
        would never hit; the envelope adds `suggestion`, the stripped string to
        track instead, plus `alternatives` and `excludeWords`), `LAST_ADMIN`
        (refuses to remove the only admin), `ITEM_EXISTS` (duplicate),
        `INVALID_DOMAIN`, `INVALID_TIMEZONE`, `SLACK_NOT_CONNECTED` /
        `SLACK_CHANNEL_NOT_FOUND` / `SLACK_CHANNEL_REQUIRED` (Slack destination
        validation), `WEBHOOK_URL_INVALID` (webhook URL rejected),
        `NO_DESTINATIONS` / `NO_SAMPLE_MENTION` (notification test delivery
        preconditions), `INVALID_DESTINATION` (a destination is
        missing/mismatched its type-specific sub-object, or two share a type) /
        `DESTINATION_INDEX_OUT_OF_RANGE` (feed destination index),
        `FILTER_LIMIT_EXCEEDED` (the effective mention query has more than 50
        caller-authored conditions), `FILTER_CONDITION_LIMIT_EXCEEDED` (a saved
        feed would have more than 50 conditions across both filter sides),
        `ENGAGEMENT_METRICS_DISABLED` (engagement filtering is unavailable in
        this deployment), and `ATTENTION_ACTION_NOT_APPLY` (the attention item's
        action is not an `apply`).


        **Conflict (409)** — `FEED_FILTER_WRITE_CONFLICT` means another writer
        changed the saved feed after it was read; fetch the latest feed and
        retry the filter update. `SETUP_DECISION_PENDING` means the onboarding
        mentions step is still removing the noise; step 3 removes it
        automatically, so try again in a few seconds.


        **Onboarding (`/api/v2/onboarding/*`)** — `MENTIONS_PREVIEW_NOT_READY`
        (400, poll), `MENTIONS_NOT_VIEWED` (409), `KEYWORDS_STEP_INVALID` (400),
        `ONBOARDING_STEP_NOT_CURRENT` (409), `ONBOARDING_REVISION_CHANGED`
        (409), `ONBOARDING_IN_PROGRESS` (409, retry in 5 s),
        `SETUP_DRAFT_NOT_FOUND` (404), `PAYWALL` / `SANDBOX_WORKSPACE` /
        `SECOND_FREE_TRIAL_FORBIDDEN` (403, with `upgradeUrl`),
        `AUTH_LOOKUP_UNAVAILABLE` (503, retry), `FEED_NOT_ONBOARDING` (400 — a
        Slack route for a feed the setup did not make) and `NOT_IMPLEMENTED`
        (501 — the route is not live yet).


        **Operation failures (500)** — `ENGAGE_FAILED` /
        `RELEVANCE_UPDATE_FAILED` carry a specific code so clients can
        distinguish a failed mutation from a generic `INTERNAL_ERROR`.
      type: string
      enum:
        - UNAUTHORIZED
        - FORBIDDEN
        - RATE_LIMITED
        - VALIDATION_ERROR
        - INTERNAL_ERROR
        - MEMBER_REQUIRED
        - BRIEF_DISABLED
        - INVALID_BRIEF_LINK
        - PREFERENCE_CHANGED
        - BRIEF_NOT_FOUND
        - INVALID_BRIEF_WINDOW
        - INVALID_RECIPIENT_COUNT
        - ORGANIZATION_REQUIRED
        - FORBIDDEN_ORGANIZATION
        - MASTER_KEY_REQUIRED
        - AGENCY_INACTIVE
        - NOT_AN_AGENCY_WORKSPACE
        - AGENCY_NOT_FOUND
        - WORKSPACE_NOT_IN_AGENCY
        - ANCHOR_WORKSPACE
        - AGENCY_WORKSPACE_LIMIT
        - INVITE_FANOUT_TOO_LARGE
        - SUPERADMIN_REMOVE_FORBIDDEN
        - USER_REQUIRED
        - FLEX_REQUIRES_CAP
        - FLEX_REQUIRES_BUDGET
        - AGENCY_BILLING_NOT_CONFIGURED
        - WORKSPACE_CREATE_FAILED
        - WORKSPACE_SETUP_FAILED
        - WORKSPACE_ACCESS_FAILED
        - UPGRADE_REQUIRED
        - QUOTA_EXCEEDED
        - WORKSPACE_PENDING_REVIEW
        - SETUP_DECISION_PENDING
        - MENTIONS_PREVIEW_NOT_READY
        - MENTIONS_NOT_VIEWED
        - KEYWORDS_STEP_INVALID
        - ONBOARDING_STEP_NOT_CURRENT
        - ONBOARDING_REVISION_CHANGED
        - ONBOARDING_IN_PROGRESS
        - SETUP_DRAFT_NOT_FOUND
        - PAYWALL
        - SANDBOX_WORKSPACE
        - SECOND_FREE_TRIAL_FORBIDDEN
        - AUTH_LOOKUP_UNAVAILABLE
        - NOT_IMPLEMENTED
        - FEED_NOT_ONBOARDING
        - NOT_FOUND
        - FEED_NOT_FOUND
        - KEYWORD_NOT_FOUND
        - KEYWORDS_NOT_FOUND
        - POST_NOT_FOUND
        - MENTION_NOT_FOUND
        - SUMMARY_NOT_FOUND
        - SEARCH_NOT_FOUND
        - SUGGESTION_NOT_FOUND
        - COMPANY_NOT_FOUND
        - ORG_NOT_FOUND
        - SETTINGS_NOT_FOUND
        - NOTIFICATION_NOT_FOUND
        - VIEW_NOT_FOUND
        - ALERT_NOT_FOUND
        - ATTENTION_ITEM_NOT_FOUND
        - FEATURE_DISABLED
        - MENTION_KEYWORD_UNKNOWN
        - EXPORT_LINK_UNAVAILABLE
        - INVALID_INPUT
        - KEYWORD_LIMIT_EXCEEDED
        - KEYWORD_SOURCE_MANAGED
        - KEYWORD_OPERATOR_SYNTAX
        - LAST_ADMIN
        - ITEM_EXISTS
        - INVALID_DOMAIN
        - INVALID_TIMEZONE
        - SLACK_NOT_CONNECTED
        - SLACK_CHANNEL_NOT_FOUND
        - SLACK_CHANNEL_REQUIRED
        - WEBHOOK_URL_INVALID
        - NO_DESTINATIONS
        - NO_SAMPLE_MENTION
        - INVALID_DESTINATION
        - DESTINATION_INDEX_OUT_OF_RANGE
        - FILTER_LIMIT_EXCEEDED
        - FILTER_CONDITION_LIMIT_EXCEEDED
        - ENGAGEMENT_METRICS_DISABLED
        - ATTENTION_ACTION_NOT_APPLY
        - WEB_SOURCE_UNAVAILABLE
        - INSTAGRAM_SOURCE_UNAVAILABLE
        - FACEBOOK_SOURCE_UNAVAILABLE
        - DISCORD_SOURCE_UNAVAILABLE
        - THREADS_SOURCE_UNAVAILABLE
        - DISCORD_ADMIN_ONLY
        - DISCORD_LINK_NOT_FOUND
        - DISCORD_MONITOR_NOT_FOUND
        - DISCORD_CHANNEL_INVALID
        - DISCORD_MONITOR_KEYWORD_OWNED
        - DISCORD_LINK_BUSY
        - DISCORD_MONITOR_BUSY
        - FEED_FILTER_WRITE_CONFLICT
        - ENGAGE_FAILED
        - RELEVANCE_UPDATE_FAILED
    Platform:
      description: Platform a mention can originate from / a keyword can be monitored on.
      example: reddit
      type: string
      enum:
        - dev
        - github
        - hackernews
        - linkedin
        - producthunt
        - reddit
        - stackoverflow
        - twitter
        - youtube
        - tiktok
        - medium
        - reddit_comment
        - bluesky
        - newsletter
        - podcasts
        - news
        - web
        - trustpilot_reviews
        - google_reviews
        - app_store_reviews
        - google_play_reviews
        - instagram
        - facebook
        - discord
        - threads
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      description: >-
        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.
      x-key-scopes:
        read: >-
          Read-only access: list/query mentions, keywords, feeds, analytics, org
          metadata.
        write: >-
          Read plus mutations: create/update/delete keywords, feeds, tags,
          filters, notifications. Implies `read`.
        admin: >-
          Write plus org administration: member management, invitations, agency
          workspaces. Implies `write`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.