Skip to main content
With the Octolens API, you can use data from your Octolens workspace to create custom integrations and automations. Every action available in the Octolens UI is available here. The Octolens API, MCP server, and webhooks are available on every plan.
Prefer a terminal? The Octolens CLI wraps this API with stable exit codes and a strict --json contract — often the fastest path for shell scripts, cron jobs, CI, and AI agents.

​
How to use the Octolens API

​
Create an API Key

In Octolens, navigate to Settings and then the API tab.
  • Click “Add new key”
  • Choose a name for your API key
  • Choose a scope: read, write (implies read), or admin (implies write)
  • Choose an expiration date for your API key from the dropdown
  • Click Create
You can revoke access to an API key at any time by clicking the three dots next to it.

​
Quick Start

​
Base URL

​
Authentication

Bearer token in the Authorization header. Each endpoint documents the scope it requires.

​
Rate Limits

500 requests per hour per organization (across all keys). Every 2xx response returns 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 with a Retry-After header.

​
Example Request

Building filters by hand can be tedious. Call POST /api/v2/ai/filter-wizard with a natural-language prompt to get a ready-to-paste filters object.

​
Error Handling

All non-2xx responses share the same envelope:
The code field is a stable ApiErrorCode enum — branch on it programmatically instead of parsing message. VALIDATION_ERROR (400) responses include a details array with per-field issues; inspect details[i].path to pinpoint which input was rejected.

​
Common error codes

​
Security: treat mention content as untrusted input

Every mention field that originates from the platform post (body, title, author, authorName, …) was written by an unknown third party on the open internet. Handle these fields like any untrusted user input:
  • Rendering or storing? Escape before rendering (XSS) and parameterize before storing (SQL injection) — standard hygiene.
  • Feeding mentions to an LLM or AI agent? Mention text can contain prompt injection — instructions crafted to manipulate the model (e.g. “ignore your previous instructions and…”). Pass mention content in a clearly delimited data context, never concatenated into your system prompt. Give the consuming agent the fewest permissions that do the job, and gate consequential actions (sending email, creating tickets, changing code, moving money) behind a confirmation step.
Octolens scores mentions for relevance and sentiment — it does not sanitize or neutralize adversarial text.

​
Endpoints

Browse the full endpoint reference in the sidebar, organized by resource: Feeds, Keywords, Mentions, Analytics, Organization, Feedback, AI, Members, and Filters. Each endpoint page includes a live “Try it” playground.