> ## 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. # List attention items > Returns the workspace's 'Needs your attention' signals — the seven rule-based kinds (no keywords, no destination, noisy keyword, pending suggestions, limit risk, delivery broken, uncaught relevant mentions) and the four insight kinds detected in the workspace's mention data (mention spike vs its own baseline, high-reach author unanswered, same-tag cluster in 24h, negative sentiment rising) — ranked by severity and capped at 5, minus dismissed items. Each item carries ONE action: `open` (an in-app path), `apply` (an approval-gated write-tool call — never run it without the user's confirmation), `ask` (a chat prompt) or `skill`. A store older than 15 minutes is recomputed before answering. ## OpenAPI ````yaml https://app.octolens.com/api/v2/openapi.json get /api/v2/attention 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 All v2 endpoints require an API key. Create one in **Settings > API** and pass it as `Authorization: Bearer `. Keys are scoped to the organization they were minted in; you cannot access another org's data. 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/attention: get: tags: - Attention summary: List attention items description: >- Returns the workspace's 'Needs your attention' signals — the seven rule-based kinds (no keywords, no destination, noisy keyword, pending suggestions, limit risk, delivery broken, uncaught relevant mentions) and the four insight kinds detected in the workspace's mention data (mention spike vs its own baseline, high-reach author unanswered, same-tag cluster in 24h, negative sentiment rising) — ranked by severity and capped at 5, minus dismissed items. Each item carries ONE action: `open` (an in-app path), `apply` (an approval-gated write-tool call — never run it without the user's confirmation), `ask` (a chat prompt) or `skill`. A store older than 15 minutes is recomputed before answering. operationId: listAttention responses: '200': description: 200 response content: application/json: schema: $ref: '#/components/schemas/AttentionListResponse' '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: - read components: schemas: AttentionListResponse: description: >- The ranked, capped (5) 'Needs your attention' list for the authenticated workspace, excluding dismissed items. Empty is a valid answer. type: object properties: data: type: array items: $ref: '#/components/schemas/AttentionItem' required: - data 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 AttentionItem: description: One 'Needs your attention' signal for the workspace. type: object properties: id: type: string minLength: 1 kind: $ref: '#/components/schemas/AttentionItemKind' dedupeKey: type: string minLength: 1 maxLength: 191 title: type: string minLength: 1 maxLength: 500 body: type: string maxLength: 2000 severity: $ref: '#/components/schemas/AttentionSeverity' score: type: number source: anyOf: - type: string - type: 'null' action: $ref: '#/components/schemas/AttentionAction' payload: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' createdAt: type: string expiresAt: anyOf: - type: string - type: 'null' required: - id - kind - dedupeKey - title - body - severity - score - action - createdAt 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. **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. **Business-rule violations (400)** — `INVALID_INPUT` (semantically invalid arguments), `KEYWORD_LIMIT_EXCEEDED` (plan cap hit), `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. **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 - 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 - 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_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 - FEED_FILTER_WRITE_CONFLICT - ENGAGE_FAILED - RELEVANCE_UPDATE_FAILED AttentionItemKind: description: >- Which producer made the item. Rules: `no_keywords` / `no_destination` / `noisy_keyword` / `pending_suggestions` / `limit_risk` get a workspace to its first useful alert; `delivery_broken` / `uncaught_relevant` keep it there; `volume_check` fires 24 h and 72 h after a setup was applied when a keyword's REAL volume lands in a different band than its pre-apply estimate (re-tune it). Insights (from the workspace's mention data): `mention_spike` (a community or source running hot vs its own baseline), `high_reach_unanswered` (a high-reach author asked something and nobody engaged), `tag_cluster` (several mentions of one keyword with the same tag in 24h), `negative_rising` (negative share up vs last week). type: string enum: - no_keywords - no_destination - noisy_keyword - pending_suggestions - limit_risk - delivery_broken - uncaught_relevant - volume_check - mention_spike - high_reach_unanswered - tag_cluster - negative_rising AttentionSeverity: description: 1 = low, 2 = medium, 3 = high. anyOf: - type: number const: 1 - type: number const: 2 - type: number const: 3 AttentionAction: description: >- The one affordance a row offers: `open` a deep link, `apply` an approval-gated write tool with the given `input`, `ask` the assistant a scoped prompt, or start a guided `skill` session. oneOf: - type: object properties: type: type: string const: open target: type: string minLength: 1 maxLength: 2048 label: type: string minLength: 1 maxLength: 60 required: - type - target - label additionalProperties: false - type: object properties: type: type: string const: apply target: $ref: '#/components/schemas/AttentionApplyTarget' label: type: string minLength: 1 maxLength: 60 input: type: object propertyNames: type: string additionalProperties: {} required: - type - target - label - input additionalProperties: false - type: object properties: type: type: string const: ask target: type: string minLength: 1 maxLength: 2000 label: type: string minLength: 1 maxLength: 60 keywordIds: type: array items: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 required: - type - target - label additionalProperties: false - type: object properties: type: type: string const: skill target: type: string minLength: 1 maxLength: 100 label: type: string minLength: 1 maxLength: 60 required: - type - target - label additionalProperties: false type: object AttentionApplyTarget: description: An agent write-tool name from the approval-gated allowlist. type: string enum: - add_keyword - update_keyword - pause_keyword - delete_keyword - accept_keyword_suggestion - reject_keyword_suggestion - create_feed - update_feed - delete_feed - add_feed_destination - remove_feed_destination - mention_feedback - export_mentions - apply_setup - cleanup_setup securitySchemes: ApiKey: type: http scheme: bearer description: >- Clerk API key. Create one in Settings → API Keys. Pass as `Authorization: Bearer `. 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.