# Octolens

- [Introduction](https://octolens.com/docs/index.md): Learn how to use Octolens to monitor brand, competitor, and keyword mentions across Reddit, X, GitHub, podcasts, newsletters, and 9 more platforms.
- [Company Context](https://octolens.com/docs/quickstart/company-context.md): Tell Octolens about your business so the AI can judge which mentions are actually relevant to you.
- [Choosing Keywords](https://octolens.com/docs/quickstart/keywords.md): Pick keywords that surface real conversations, and learn how to add, pause, and delete them from the Keywords page.
- [Keyword Settings](https://octolens.com/docs/quickstart/keyword-settings.md): Control what each keyword matches. Platforms, context, include/exclude rules, and match strictness.
- [Global Keyword Settings](https://octolens.com/docs/quickstart/global-keyword-settings.md): Account-wide filters. Cut noise across every keyword without editing them one at a time.
- [Feeds](https://octolens.com/docs/quickstart/feeds.md): Saved filters over your mentions. Use defaults like Brand Mentions and Buy Intent, or build your own. Send any feed to a destination.
- [Destinations](https://octolens.com/docs/quickstart/destinations.md): Send any feed to email, Slack, or a webhook. Pick recipients and frequency per destination.
- [Connect Slack](https://octolens.com/docs/quickstart/connect-slack.md): Connect your Slack workspace once, then send any feed to the channels you choose.
- [Webhooks](https://octolens.com/docs/quickstart/webhooks.md): Pipe any feed into your own systems. Send new mentions as JSON to any URL.
- [CSV Export](https://octolens.com/docs/quickstart/csv-export.md): Download your mentions as a CSV, including platform, author, sentiment, AI relevance score, and tags, for analysis in Excel, Sheets, or your own BI tool.
- [Team Members](https://octolens.com/docs/quickstart/team-members.md): Invite teammates to your Octolens workspace, unlimited seats on every plan. Admins manage billing and invites, while members have full access to mentions.
- [Dashboard](https://octolens.com/docs/learn/dashboard.md): Mentions over time, plan and API/MCP usage, and a recent mentions feed — your morning glance at how the workspace is doing.
- [Mention Limits](https://octolens.com/docs/learn/mention-limits.md): Understand what counts toward your monthly mention quota, why your feed shows less than your counter, and how to reduce mention burn.
- [AI Relevance & Tags](https://octolens.com/docs/learn/ai-relevance.md): How Octolens AI scores relevance and applies tags like Own Brand Mention, Competitors, Buy Intent, and Product Question, so you only see what matters.
- [Sentiment Analysis](https://octolens.com/docs/learn/sentiment.md): How Octolens classifies each mention as positive, neutral, or negative, and how to use sentiment in feeds, destinations, and the dashboard to spot brand risk early.
- [Tracked Platforms](https://octolens.com/docs/learn/platforms/overview.md): Overview of the platforms and data sources Octolens monitors for your keywords
- [Web tracking](https://octolens.com/docs/learn/platforms/web.md): How Octolens monitors indexed web pages across the open web
- [List of Newsletters](https://octolens.com/docs/learn/platforms/newsletter-list.md): The full list of 200+ newsletters Octolens monitors for your keywords, from Substacks and industry digests to developer-focused and B2B SaaS publications.
- [FAQs](https://octolens.com/docs/learn/faqs.md): Answers to common questions about Octolens: getting started, plans, keywords, platforms, destinations, team, developer access, and troubleshooting.
- [Attio](https://octolens.com/docs/integrations/attio.md): Bring Octolens social signals into Attio workflows. Trigger automations on new mentions, pull a person's mentions on demand, then create records, enrich contacts, and add timeline notes — you decide how the data maps to your CRM.
- [Octolens CLI](https://octolens.com/docs/cli/overview.md): The terminal interface to Octolens — read, triage and act on your mentions from a shell, by hand or from a script.
- [Install & login](https://octolens.com/docs/cli/install.md): Install the octolens CLI from npm, sign in through the browser or with an API key, and understand scopes and plan requirements.
- [Quickstart](https://octolens.com/docs/cli/quickstart.md): Your first ten minutes with the octolens CLI — sign up or log in, run your first search, triage a mention, save a feed and read the numbers.
- [Sign up & search — the Agents plan](https://octolens.com/docs/cli/agents.md): Create a workspace from the terminal with octolens signup, run one-time AI-scored searches, understand the Agents allowance and quota headers, and upgrade with octolens upgrade.
- [Initialize a workspace](https://octolens.com/docs/cli/init.md): Bootstrap a new workspace from the terminal with the guided onboarding wizard.
- [The --json contract](https://octolens.com/docs/cli/contract/json-output.md): --json emits exactly one machine-readable JSON document on stdout with no decoration; progress and diagnostics go to stderr.
- [Exit codes](https://octolens.com/docs/cli/contract/exit-codes.md): Exit codes are frozen — branch on codes (and the error envelope's code), never on message text.
- [The error envelope](https://octolens.com/docs/cli/contract/error-envelope.md): Every failure renders one envelope: { "error": { "code", "message", "status" } }.
- [Retries and timeouts](https://octolens.com/docs/cli/contract/retries-and-timeouts.md): Every request runs under a per-operation deadline (default 30s; a few long operations carry raised defaults, and the global --timeout overrides them all uniformly).
- [RESPONSE_LOST — the indeterminate write](https://octolens.com/docs/cli/contract/response-lost.md): A state-changing request whose 2xx status line arrived but whose response body was lost answers RESPONSE_LOST (status 502, exit 10): the server accepted the write and the outcome…
- [The auth preflight](https://octolens.com/docs/cli/contract/auth-preflight.md): Credentials are resolved per run: an API key in OCTOLENS_API_KEY, or a profile stored by octolens login.
- [Global flags](https://octolens.com/docs/cli/contract/global-flags.md): The 6 flags every octolens command accepts.
- [Mentions](https://octolens.com/docs/cli/commands/mentions.md): Track, triage and export the conversations that mention you.
- [Feeds](https://octolens.com/docs/cli/commands/feeds.md): Save filtered views of your mention stream, and watch them live from the terminal.
- [Keywords](https://octolens.com/docs/cli/commands/keywords.md): Manage the terms you monitor, and review the AI's keyword-tuning suggestions.
- [Notifications](https://octolens.com/docs/cli/commands/notifications.md): Send new mentions to Slack, email or a webhook, on the schedule you choose.
- [Analytics](https://octolens.com/docs/cli/commands/analytics.md): Read mention volume, sentiment and keyword trends without leaving the terminal.
- [Filters, tags & feedback](https://octolens.com/docs/cli/commands/filters.md): Cut noise with global filters and tags, and teach the relevance model with feedback.
- [Auth](https://octolens.com/docs/cli/commands/auth.md): Sign in, switch workspaces and check which identity a run will use.
- [Admin](https://octolens.com/docs/cli/commands/admin.md): Administer the workspace: company profile, members, organization settings and billing.
- [Utilities](https://octolens.com/docs/cli/commands/core.md): The CLI's own housekeeping: version, help and shell autocompletion.
- [Auth, profiles & workspaces](https://octolens.com/docs/cli/concepts/auth-profiles.md): What a profile is, how login creates one, switching between workspaces, what logout does and does not do, and how an environment API key interacts with it all.
- [API keys & scopes](https://octolens.com/docs/cli/concepts/keys-scopes.md): The cumulative read, write, admin scope ladder — where keys are minted, which scope each endpoint requires, and how to preflight a credential instead of discovering its limits through failures.
- [Output modes](https://octolens.com/docs/cli/concepts/output-modes.md): The three renderings every octolens command has — human output on a TTY, header-free TSV records for pipes, and the --json document — and what headless means.
- [Pagination & time windows](https://octolens.com/docs/cli/concepts/pagination-windows.md): How --limit and --all bound a list, what pagination.nextCursor means in --json output, and the shapes and defaults of --since and --until.
- [Telemetry](https://octolens.com/docs/cli/concepts/telemetry.md): What usage telemetry the published CLI collects, what it can never contain, why it cannot affect a command, and the two environment variables that turn it off.
- [Triage your mentions from the terminal](https://octolens.com/docs/cli/guides/triage-mentions.md): Work through your mention stream from a shell: narrow the list, inspect one mention, correct the AI's verdicts, teach the model, and mark what you have handled.
- [Watch a feed live](https://octolens.com/docs/cli/guides/watch-live.md): Follow your mention stream in real time with feeds watch: keyboard triage on a TTY, tail-only streams for automation, and the NDJSON contract a pipeline can trust.
- [Build feeds & filters](https://octolens.com/docs/cli/guides/feeds-and-filters.md): Slice your mention stream into saved feeds — with flags, a full filter object, or plain English — and cut workspace-wide noise with the org filter lists.
- [Export & report](https://octolens.com/docs/cli/guides/export-and-report.md): Get your mentions out of Octolens — CSV for a spreadsheet, JSON for a script, a cron job for every Monday morning, and the analytics commands when you only need the numbers.
- [Notifications end-to-end](https://octolens.com/docs/cli/guides/notifications.md): Wire a feed to Slack, email or a webhook from the terminal — connect the workspace, create the delivery rule, then prove it delivers with a real test.
- [Keywords & AI suggestions](https://octolens.com/docs/cli/guides/keywords-and-suggestions.md): Manage the terms Octolens monitors — add, tune, pause and remove keywords from the terminal, and work through the AI's keyword-tuning suggestions.
- [Workspace admin](https://octolens.com/docs/cli/guides/workspace-admin.md): Run the workspace from the terminal — members and invitations, the company profile that steers the AI, and usage against your plan.
- [The agent contract](https://octolens.com/docs/cli/scripting/agent-contract.md): The behavioral guarantees every octolens command honors for scripts and agents — JSON purity, a machine-parseable stderr, bounded runs, no prompts, guarded deletes, and exit codes that report outcomes rather than data.
- [JSON output & jq cookbook](https://octolens.com/docs/cli/scripting/jq-cookbook.md): Real payload shapes and copy-pasteable jq recipes for the common asks — new mentions since a date, sentiment slices, per-keyword counts, CSV — plus the TSV pipe contract for quick shell work.
- [Handling failure in scripts](https://octolens.com/docs/cli/scripting/handling-failure.md): How to branch when an octolens run fails: the exit-code map, testing auth-family membership instead of one code, when a retry is safe — and the one exit you must never auto-retry.
- [CI recipes](https://octolens.com/docs/cli/scripting/ci-recipes.md): Run octolens from GitHub Actions: API-key auth from a secret, a pinned CLI version, a weekly CSV export uploaded as an artifact, and a scheduled triage digest.
- [Using with AI agents](https://octolens.com/docs/cli/scripting/ai-agents.md): Give an AI coding agent working knowledge of Octolens: install the Agent Skill, point LLMs at llms.txt, and choose between the CLI, MCP and REST for the task at hand.
- [API Reference](https://octolens.com/docs/api/v2/overview.md): Use the Octolens REST API v2 to query mentions, manage keywords and feeds, run analytics, and pipe social listening data into your own apps, dashboards, and internal automations.
- [Introspect the credential](https://octolens.com/docs/api-reference/auth/introspect-the-credential.md): Returns the authenticated credential: the workspace it is bound to, how it authenticates, and its effective scopes. Use this to preflight whether the key can perform writes (`write`) or admin actions (`admin`) before calling a mutating endpoint. Keys minted before scoping existed report `["read"]` —…
- [List feeds](https://octolens.com/docs/api-reference/feeds/list-feeds.md): Returns all feeds. A feed combines a saved filter (view) with optional notification destinations.
- [Create a feed](https://octolens.com/docs/api-reference/feeds/create-a-feed.md)
- [Get a feed](https://octolens.com/docs/api-reference/feeds/get-a-feed.md)
- [Delete a feed](https://octolens.com/docs/api-reference/feeds/delete-a-feed.md): Delete a feed. This also deletes the notification attached to it, if any — their ids come back in `deletedNotificationIds`. Deleting a feed that is already gone returns 404 `FEED_NOT_FOUND`, including when it was removed by a concurrent caller.
- [Update a feed](https://octolens.com/docs/api-reference/feeds/update-a-feed.md): Update any combination of name, icon, filters, default flag, or destinations. Omit `destinations` to leave them unchanged; pass an empty array to remove all destinations.
- [List keywords](https://octolens.com/docs/api-reference/keywords/list-keywords.md): Returns all keywords being tracked by the authenticated organization.
- [Create a keyword](https://octolens.com/docs/api-reference/keywords/create-a-keyword.md): Start monitoring a new keyword. The keyword is immediately added to the data collection pipeline. Creating a term that is already tracked (case-insensitive exact match) is a no-op: the existing keyword is returned with `alreadyExisted: true` and nothing new is created — pass `allowDuplicate: true` t…
- [Delete a keyword](https://octolens.com/docs/api-reference/keywords/delete-a-keyword.md): Stops monitoring and removes the keyword. Feeds whose filters reference only this keyword are deleted too, and each of those feeds takes its notification with it. The response names both: `deletedFeeds` and `deletedNotifications` are always present, and empty when nothing else was destroyed. Use `GE…
- [Update a keyword](https://octolens.com/docs/api-reference/keywords/update-a-keyword.md)
- [Pause or resume a keyword](https://octolens.com/docs/api-reference/keywords/pause-or-resume-a-keyword.md): Moves a keyword to an explicit `paused` state. The write is ABSOLUTE and idempotent — `{ "paused": true }` on an already-paused keyword changes nothing and answers `changed: false` — so it is safe to retry and safe to call concurrently. The `paused` field in the response is the COMMITTED value read…
- [Preview what deleting a keyword would destroy](https://octolens.com/docs/api-reference/keywords/preview-what-deleting-a-keyword-would-destroy.md): Lists the feeds that would be deleted along with this keyword (their filters reference only it) and the notifications attached to those feeds, which go with them. Changes nothing. Both arrays are empty when the keyword can be deleted with no collateral. A preview is a snapshot, not a lock — a feed c…
- [List keyword suggestions](https://octolens.com/docs/api-reference/keywords/list-keyword-suggestions.md): AI-generated tweaks for keyword config. Pass `keywordId` for per-keyword view, or omit for org-wide enriched list.
- [Accept a keyword suggestion](https://octolens.com/docs/api-reference/keywords/accept-a-keyword-suggestion.md): Apply the suggestion to the source keyword. Pass `modifiedValue` to override the suggested text.
- [Reject keyword suggestion(s)](https://octolens.com/docs/api-reference/keywords/reject-keyword-suggestions.md): Pass `suggestionId` to reject one suggestion, or `keywordId` to reject all pending suggestions for a keyword. Answers `rejectedCount` and `rejectedSuggestionIds` on both branches, so a bulk dismissal reports what it dismissed rather than a bare success (rejecting is terminal — accept/reject act only…
- [List mentions](https://octolens.com/docs/api-reference/mentions/list-mentions.md): Returns mentions scoped to the authenticated organization. Filter by keyword, source, sentiment, date range, or custom filter groups.
- [List mentions by author](https://octolens.com/docs/api-reference/mentions/list-mentions-by-author.md): Returns mentions authored by one person on a specific platform — e.g. to enrich a CRM record with everything a prospect has said. Scoped to the authenticated organization and always to a single `source` (the same handle can belong to different people on different platforms). Identify the author by `…
- [Get a mention](https://octolens.com/docs/api-reference/mentions/get-a-mention.md): Returns one mention by its stable platform-native `sourceId` (e.g. `reddit_t3_1abc234`). The internal numeric `id` from a `POST /api/v2/mentions` row is also accepted, for recent and archived mentions alike. Shape matches items in `POST /api/v2/mentions`.
- [Update a mention](https://octolens.com/docs/api-reference/mentions/update-a-mention.md): 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.
- [Get a mention (id as query parameter)](https://octolens.com/docs/api-reference/mentions/get-a-mention-id-as-query-parameter.md): Returns one mention by its stable platform-native `sourceId` (e.g. `reddit_t3_1abc234`), passed as a query parameter. The internal numeric `id` from a `POST /api/v2/mentions` row is also accepted, for recent and archived mentions alike. Shape matches items in `POST /api/v2/mentions`.
- [Update a mention (id as query parameter)](https://octolens.com/docs/api-reference/mentions/update-a-mention-id-as-query-parameter.md): Set the engaged state, or update AI-judged relevance or sentiment, addressing the mention by a `sourceId` query parameter. The `action` field in the body selects the operation — same body as `PATCH /api/v2/mentions/{sourceId}`.
- [Export mentions](https://octolens.com/docs/api-reference/mentions/export-mentions.md): Export up to 50,000 mentions matching the given view and filters. Body shape matches `POST /api/v2/mentions` (v1-compatible) plus a `format` selector, an optional total-row `limit` cap, and an optional `author` pivot (one author's mentions on a single `source`). Returns a downloadable file. Pass `fo…
- [Sentiment distribution](https://octolens.com/docs/api-reference/analytics/sentiment-distribution.md): Returns the count of mentions for each sentiment label (Positive, Neutral, Negative, unknown) within the filter window.
- [Mention volume over time](https://octolens.com/docs/api-reference/analytics/mention-volume-over-time.md): Counts mentions per bucket (day or hour) across the filter window, sorted chronologically.
- [Source/platform breakdown](https://octolens.com/docs/api-reference/analytics/sourceplatform-breakdown.md): Counts mentions grouped by platform (reddit, twitter, linkedin, …) within the filter window, sorted by count desc.
- [Per-keyword breakdown](https://octolens.com/docs/api-reference/analytics/per-keyword-breakdown.md): Counts mentions per tracked keyword within the filter window. A post that matched multiple keywords contributes to each. Sorted by count desc.
- [Composite dashboard overview](https://octolens.com/docs/api-reference/analytics/composite-dashboard-overview.md): Volume trend, per-keyword breakdown, sentiment split, and plan usage in one response. Each section matches the corresponding focused endpoint (`/analytics/volume`, `/analytics/keywords`, `/analytics/sentiment`, `/org/usage`) exactly, but the whole dashboard costs one request and one rate-limit token…
- [Get organization](https://octolens.com/docs/api-reference/organization/get-organization.md): Returns the authenticated workspace: name, plan, enabled platforms, lifecycle timestamps.
- [Update organization](https://octolens.com/docs/api-reference/organization/update-organization.md): Update editable workspace settings. Currently: `name` and `platforms`. Other fields (plan, billing, global filters, company profile, members) have their own endpoints.
- [Get usage stats](https://octolens.com/docs/api-reference/organization/get-usage-stats.md): Mention and keyword counts for the current billing cycle, plus plan limits. Includes flex (usage-based) state when enabled. On the Agents plan a `searches` block reports the lifetime search allowance (used/limit/remaining).
- [Mint an authenticated upgrade link](https://octolens.com/docs/api-reference/organization/mint-an-authenticated-upgrade-link.md): Mints a **single-use, short-lived** sign-in URL that opens the workspace's upgrade page (Agents plan) or billing page (other plans) already authenticated — no sign-in step, even for workspaces created headlessly that have never had a browser session. The embedded ticket is consumed on first redempti…
- [Get company profile](https://octolens.com/docs/api-reference/organization/get-company-profile.md): Returns the monitored company profile for the authenticated organization.
- [Update company profile](https://octolens.com/docs/api-reference/organization/update-company-profile.md): Update any combination of the monitored company's fields (name, description, social handles, AI guidelines).
- [Submit relevance feedback](https://octolens.com/docs/api-reference/feedback/submit-relevance-feedback.md): Submit thumbs-up / thumbs-down feedback on a mention. Updates Tinybird and adjusts relevance + tags so the feed reflects user intent immediately.
- [Remove relevance feedback](https://octolens.com/docs/api-reference/feedback/remove-relevance-feedback.md): Remove a stored feedback record by mention key. Always succeeds; `removed` reports whether a record actually existed (`false` = nothing was stored — a harmless no-op).
- [Get feedback stats](https://octolens.com/docs/api-reference/feedback/get-feedback-stats.md): Aggregated relevance-feedback totals for the workspace: how many mentions were marked `RELEVANT` vs `NOT_RELEVANT`, and the resulting false-positive rate. Pass `keywordId` to narrow the stats to a single keyword.
- [Convert natural language to filters](https://octolens.com/docs/api-reference/ai/convert-natural-language-to-filters.md): Uses an LLM to convert a natural-language query (e.g. "posts from twitter influencers about pricing this week") into a structured filter object usable with /api/v2/mentions.
- [Recommend monitoring settings from search history](https://octolens.com/docs/api-reference/ai/recommend-monitoring-settings-from-search-history.md): Turns the workspace's actual search history into recommended monitoring settings: a ranked keyword set (with rationale and evidence), platform recommendations, and relevance-guideline hints — capped at the target plan's keyword allowance. Workspaces with little or no search history fall back to comp…
- [List organization members](https://octolens.com/docs/api-reference/members/list-organization-members.md): Lists all members of the authenticated organization.
- [Invite a member](https://octolens.com/docs/api-reference/members/invite-a-member.md): Sends an email invitation to join the authenticated organization. The invitee must accept the invitation from their email before appearing in `GET /org/members`; until then it is listed by `GET /org/members/invitations`. IDEMPOTENT: re-inviting an address that already has an outstanding invitation r…
- [List pending invitations](https://octolens.com/docs/api-reference/members/list-pending-invitations.md): Lists invitations that have been sent but not yet accepted. Accepted members appear in `GET /org/members` instead; a pending invitation appears in neither until this endpoint. Revoke one with `DELETE /org/members/{id}`, passing the `orginv_…` id.
- [Remove a member or revoke an invitation](https://octolens.com/docs/api-reference/members/remove-a-member-or-revoke-an-invitation.md): Removes a member from the organization. The member loses access immediately. You cannot remove the last remaining admin. Pass an `orginv_…` id instead to REVOKE a pending invitation (OCT-1415) — before that, anything `POST /org/members/invite` created could not be undone through the API at all.
- [Get global filters](https://octolens.com/docs/api-reference/filters/get-global-filters.md): Returns all five org-wide filter lists (negative keywords, authors, subreddits, positive subreddits, repos).
- [Update global filters](https://octolens.com/docs/api-reference/filters/update-global-filters.md): Replace any of the five filter lists. Pass `[]` to clear a list; omit a field to leave it unchanged.
- [Add values to a global filter list](https://octolens.com/docs/api-reference/filters/add-values-to-a-global-filter-list.md): Append values to one org-wide filter list, merged server-side against the committed row so concurrent callers converge instead of overwriting each other. Values already on the list are skipped silently; values already in the mutually-exclusive counterpart list (`negativeSubreddits` ↔ `positiveSubred…
- [Remove values from a global filter list](https://octolens.com/docs/api-reference/filters/remove-values-from-a-global-filter-list.md): Remove values from one org-wide filter list, merged server-side against the committed row so a removal is never resurrected by a concurrent add. Values not present are ignored. A removal that would leave the list EMPTY is refused with 400 `CLEAR_NOT_CONFIRMED` unless `allowEmpty: true` is set — empt…
- [List filterable tags](https://octolens.com/docs/api-reference/filters/list-filterable-tags.md): Returns the tag names you can pass to the `tag` / `!tag` filter on `POST /api/v2/mentions`. Result is the union of tags the AI has assigned to this org's mentions and a conventional fallback set, deduped and sorted alphabetically.
- [Search Slack channels](https://octolens.com/docs/api-reference/integrations/search-slack-channels.md): Returns the workspace's accessible Slack channels filtered by name. Designed as a discovery tool for feed-destination configuration — pass returned `id` values to `Destination.slackDestination.channels`. Fails with 400 `SLACK_NOT_CONNECTED` when the Slack integration isn't installed for the workspac…
- [Slack connection status](https://octolens.com/docs/api-reference/integrations/slack-connection-status.md): Returns whether the workspace has a linked, installed Slack integration. `connected` is `true` only when both hold — poll this after starting the browser OAuth flow to know when the connection is live.
- [List past on-demand searches](https://octolens.com/docs/api-reference/search/list-past-on-demand-searches.md): Returns the workspace's past on-demand searches, most recent first. Paginated.
- [Run an on-demand mention search](https://octolens.com/docs/api-reference/search/run-an-on-demand-mention-search.md): Runs a one-time search for `query` across the workspace's enabled sources over the last 1/7/30 days and AI-scores the results inline using the workspace's company profile. Results belong to the search (they do NOT appear in the mentions feed); new results count against the monthly mention quota, whi…
- [Get an on-demand search](https://octolens.com/docs/api-reference/search/get-an-on-demand-search.md): Returns the current state of a search: `running` (with `partialStats`, a `pollUrl`, and a `Retry-After` header), `completed` (with the full `mentions` array + `stats`), `failed`, or `quota_exhausted`.
- [List notifications](https://octolens.com/docs/api-reference/notifications/list-notifications.md): Returns all notifications. A notification delivers mentions matching a feed's filters to its configured destinations (email, Slack, webhook).
- [Create a notification](https://octolens.com/docs/api-reference/notifications/create-a-notification.md): Create a notification for an existing feed (a feed can have at most one). Slack destinations are validated against the workspace's Slack connection — every channel id must resolve; webhook URLs must be public http(s) endpoints (a URL whose host is, or resolves to, a private/loopback address is refus…
- [Get a notification](https://octolens.com/docs/api-reference/notifications/get-a-notification.md)
- [Delete a notification](https://octolens.com/docs/api-reference/notifications/delete-a-notification.md): Delete the notification and all its destinations. The linked feed is not affected.
- [Update a notification](https://octolens.com/docs/api-reference/notifications/update-a-notification.md): Partial update: any combination of name, feed, enabled flag, or destinations. `destinations`, when provided, sets the destination LIST (one per type) — a type in the array is PATCHED onto the stored destination of that type (omitted fields such as `frequency`, `time` or `timezone` keep their current…
- [Test a notification](https://octolens.com/docs/api-reference/notifications/test-a-notification.md): Performs a REAL delivery of the latest mention matching the notification's feed filters to every configured destination (email is actually sent, Slack message actually posted, webhook actually called) and returns a per-destination outcome. Watermarks and delivery logs are untouched, so scheduled del…
- [Agency overview](https://octolens.com/docs/api-reference/agency/agency-overview.md): Plan, shared mentions pool usage, keyword pool, and workspace counts for the agency the master key belongs to. Requires an agency master API key; the `x-octolens-organization-id` header is not needed (agency-scoped).
- [List agency workspaces](https://octolens.com/docs/api-reference/agency/list-agency-workspaces.md): All workspaces of the agency, including per-workspace usage, limit overrides, and flex settings. The returned `organizationId` values are what the `x-octolens-organization-id` header takes on data-API calls.
- [Create an agency workspace](https://octolens.com/docs/api-reference/agency/create-an-agency-workspace.md): Provision a new child workspace: Clerk organization, workspace settings (onboarding skipped), company profile enriched from the domain, and superadmin access for every agency superadmin. Fails with 403 AGENCY_WORKSPACE_LIMIT at the workspace cap. `companyEnriched: false` means enrichment failed and…
- [Get an agency workspace](https://octolens.com/docs/api-reference/agency/get-an-agency-workspace.md)
- [Delete an agency workspace](https://octolens.com/docs/api-reference/agency/delete-an-agency-workspace.md): Permanently removes the workspace (settings first, then the Clerk organization). The anchor workspace cannot be deleted. `clerkOrgDeleted: false` means the workspace was removed from the agency but the Clerk organization needs out-of-band cleanup.
- [Update workspace limits / flex](https://octolens.com/docs/api-reference/agency/update-workspace-limits-flex.md): Partial update: only the provided concerns are touched. `mentionsLimitOverride` / `keywordsLimitOverride` accept `null` to clear the override (back to the shared pool / plan default). Enabling flex requires a saved mentions cap, a positive budget, and configured agency Stripe billing (412 `AGENCY_BI…
- [List workspace members](https://octolens.com/docs/api-reference/agency/list-workspace-members.md): Current members, pending invitations, and queued access grants (bulk-invite overflow awaiting account creation) of one agency workspace.
- [Invite members to workspaces](https://octolens.com/docs/api-reference/agency/invite-members-to-workspaces.md): Invite one or many emails to one/many/all agency workspaces (`targetOrgIds: "all"`). Existing Octolens accounts get direct membership grants (no email — `action: granted`). New users receive exactly ONE invitation email for their first selected workspace (`action: invited`); every additional workspa…
- [Remove a member from workspaces](https://octolens.com/docs/api-reference/agency/remove-a-member-from-workspaces.md): Remove a user from one/many/all agency workspaces (`orgIds: "all"`). Superadmins cannot be removed this way — demote them via the agency admin panel first.
- [API Reference](https://octolens.com/docs/api/overview.md): Use the Octolens REST API to query mentions, manage keywords, and pipe social listening data into your own apps, dashboards, and internal automations.
- [Agent Skill](https://octolens.com/docs/skill/overview.md): Install the official Octolens Agent Skill to give Claude Code, Cursor, and other AI coding agents built-in expertise for working with your Octolens workspace via the CLI or the REST API.
- [MCP Server](https://octolens.com/docs/mcp/v2/overview.md): Connect Claude, ChatGPT, Cursor, and other AI agents to your Octolens workspace via MCP v2 — query mentions, run analytics, and manage keywords and feeds in natural language.
- [Setup Guides](https://octolens.com/docs/mcp/v2/setup-guides.md): Step-by-step guides to connect the Octolens MCP v2 server to Claude Code, Claude Desktop/Web, ChatGPT, Cursor, and other tools that support Model Context Protocol.
- [Tools Reference](https://octolens.com/docs/mcp/v2/tools.md): Every tool exposed by the Octolens MCP v2 server — mentions, analytics, keywords, feeds, destinations, workspace, and usage — with what each does and when your AI assistant uses it.
- [Use Cases](https://octolens.com/docs/mcp/v2/use-cases.md): Real prompts and workflows for the Octolens MCP v2 server. Turn brand mentions into briefs, lead lists, and competitive intelligence — and manage keywords and feeds without leaving your AI assistant.
- [MCP Server (v1)](https://octolens.com/docs/mcp/overview.md): Legacy Octolens MCP v1 setup. Connects Claude, ChatGPT, Cursor, and other AI agents to your Octolens mentions via a token-in-URL connection.
- [Setup Guides](https://octolens.com/docs/mcp/setup-guides.md): Step-by-step guides to connect the Octolens MCP server to Claude Desktop, ChatGPT, Cursor, Cline, and other tools that support Model Context Protocol.
- [Use Cases](https://octolens.com/docs/mcp/use-cases.md): Real prompts and workflows for the Octolens MCP server. Turn brand mentions into weekly briefs, lead lists, support triage, and competitive intelligence.

## OpenAPI Specs

- [openapi](https://app.octolens.com/api/v2/openapi.json)