> ## 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. # Update a feed > 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. ## OpenAPI ````yaml https://app.octolens.com/api/v2/openapi.json patch /api/v2/feeds/{id} 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 hour (sliding hourly window). 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"`. ### 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. ### 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: [] paths: /api/v2/feeds/{id}: patch: tags: - Feeds summary: Update a feed description: >- 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. operationId: updateFeed parameters: - in: path name: id schema: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateFeedRequest' responses: '200': description: 200 response content: application/json: schema: $ref: '#/components/schemas/Feed' '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' components: schemas: UpdateFeedRequest: description: >- Partial update. Passing `simpleFilters` or `advancedFilters` replaces that side of the filter. Destinations are all-or-nothing — include the full list to update any of them. type: object properties: name: description: Replace feed name. type: string minLength: 1 icon: $ref: '#/components/schemas/FeedIcon' simpleFilters: $ref: '#/components/schemas/SimpleFilters' advancedFilters: $ref: '#/components/schemas/AdvancedFilters' destinations: description: >- If provided, replaces all destinations. If omitted, destinations are unchanged. type: array items: $ref: '#/components/schemas/Destination' Feed: description: A saved filter with optional notification destinations. type: object properties: id: description: Feed ID. type: integer minimum: -9007199254740991 maximum: 9007199254740991 name: description: Display name shown in the app and included in notifications. example: Competitor mentions type: string icon: $ref: '#/components/schemas/FeedIcon' simpleFilters: anyOf: - $ref: '#/components/schemas/SimpleFiltersOutput' - type: 'null' advancedFilters: anyOf: - $ref: '#/components/schemas/AdvancedFiltersOutput' - type: 'null' isDefault: description: If `true`, this feed is pinned as the org's default view. type: boolean destinations: description: >- Notification destinations. Empty array = filter-only feed with no notifications. type: array items: $ref: '#/components/schemas/DestinationOutput' createdAt: type: string format: date-time 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))$ updatedAt: type: string format: date-time 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))$ required: - id - name - icon - simpleFilters - advancedFilters - isDefault - destinations - createdAt - updatedAt additionalProperties: false ErrorResponse: description: >- Standard error envelope returned for all non-2xx responses. The `code` field is stable — safe to branch on programmatically. 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: {} required: - code - message - status additionalProperties: false required: - error additionalProperties: false FeedIcon: description: Icon identifier for UI display (Heroicons outline set). example: BellIcon type: string enum: - InboxStackIcon - HeartIcon - AtSymbolIcon - ExclamationTriangleIcon - MegaphoneIcon - ArrowTrendingUpIcon - BuildingOffice2Icon - ArrowTrendingDownIcon - BellIcon - BuildingLibraryIcon - ChartBarIcon - ChatBubbleLeftIcon - ChatBubbleLeftRightIcon - CheckCircleIcon - CloudIcon - CodeBracketIcon - ComputerDesktopIcon - CursorArrowRaysIcon - DevicePhoneMobileIcon - DocumentIcon - DocumentTextIcon - EnvelopeIcon - EyeIcon - FaceSmileIcon - FaceFrownIcon - FireIcon - FlagIcon - FolderIcon - GlobeAltIcon - GlobeAmericasIcon - HandThumbUpIcon - HashtagIcon - InboxArrowDownIcon - LightBulbIcon - PaperClipIcon - RocketLaunchIcon - RssIcon - SignalIcon - SparklesIcon - StarIcon - TrophyIcon - UserGroupIcon - WalletIcon SimpleFilters: description: Simple AND-combined filter list. type: object properties: conditions: description: Flat list of conditions. Implicitly combined with AND. type: array items: $ref: '#/components/schemas/SimpleFilterCondition' required: - conditions AdvancedFilters: description: Nested filter expression — groups of conditions combined with AND/OR. type: object properties: top_level_operator: description: How the groups combine at the top level. type: string enum: - AND - OR groups: description: One or more filter groups. type: array items: $ref: '#/components/schemas/AdvancedFilterGroup' required: - top_level_operator - groups Destination: description: >- One delivery configuration. The relevant `*Destination` sub-object is populated based on `type`. type: object properties: type: $ref: '#/components/schemas/DestinationType' frequency: $ref: '#/components/schemas/DestinationFrequency' deliveryMode: description: >- `batch` sends one digest per period; `individual` sends one message per matching mention. Ignored on `WEBHOOK` (always individual). type: string enum: - batch - individual time: description: Wall-clock time for daily/weekly delivery, `HH:mm` 24-hour. example: '09:00' type: string timezone: description: IANA timezone or UTC offset paired with `time`. example: UTC type: string dayOfWeek: description: 0 (Sunday) through 6 (Saturday). Required for `frequency=weekly`. type: integer minimum: 0 maximum: 6 emailDestination: description: Present when `type=EMAIL`. type: object properties: emails: $ref: '#/components/schemas/EmailList' required: - emails slackDestination: description: Present when `type=SLACK`. type: object properties: channels: description: Comma-separated Slack channel IDs, e.g. `C0123ABC,C0456DEF`. type: string minLength: 1 channelNamesMap: description: >- Optional comma-separated `id:name` pairs matching `channels` — used for UI display. type: string required: - channels webhookDestination: description: Present when `type=WEBHOOK`. type: object properties: url: $ref: '#/components/schemas/HttpUrl' example: https://example.com/webhook description: HTTP(S) URL to POST events to. required: - url required: - type - frequency SimpleFiltersOutput: description: Simple AND-combined filter list. type: object properties: conditions: description: Flat list of conditions. Implicitly combined with AND. type: array items: $ref: '#/components/schemas/SimpleFilterConditionOutput' required: - conditions additionalProperties: false AdvancedFiltersOutput: description: Nested filter expression — groups of conditions combined with AND/OR. type: object properties: top_level_operator: description: How the groups combine at the top level. type: string enum: - AND - OR groups: description: One or more filter groups. type: array items: $ref: '#/components/schemas/AdvancedFilterGroupOutput' required: - top_level_operator - groups additionalProperties: false DestinationOutput: description: >- One delivery configuration. The relevant `*Destination` sub-object is populated based on `type`. type: object properties: type: $ref: '#/components/schemas/DestinationType' frequency: $ref: '#/components/schemas/DestinationFrequency' deliveryMode: description: >- `batch` sends one digest per period; `individual` sends one message per matching mention. Ignored on `WEBHOOK` (always individual). type: string enum: - batch - individual time: description: Wall-clock time for daily/weekly delivery, `HH:mm` 24-hour. example: '09:00' type: string timezone: description: IANA timezone or UTC offset paired with `time`. example: UTC type: string dayOfWeek: description: 0 (Sunday) through 6 (Saturday). Required for `frequency=weekly`. type: integer minimum: 0 maximum: 6 emailDestination: description: Present when `type=EMAIL`. type: object properties: emails: $ref: '#/components/schemas/EmailList' required: - emails additionalProperties: false slackDestination: description: Present when `type=SLACK`. type: object properties: channels: description: Comma-separated Slack channel IDs, e.g. `C0123ABC,C0456DEF`. type: string minLength: 1 channelNamesMap: description: >- Optional comma-separated `id:name` pairs matching `channels` — used for UI display. type: string required: - channels additionalProperties: false webhookDestination: description: Present when `type=WEBHOOK`. type: object properties: url: $ref: '#/components/schemas/HttpUrl' example: https://example.com/webhook description: HTTP(S) URL to POST events to. required: - url additionalProperties: false required: - type - frequency 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). **Not found (404)** — generic `NOT_FOUND` plus domain-specific variants: `FEED_NOT_FOUND`, `KEYWORD_NOT_FOUND`, `POST_NOT_FOUND`, `SUMMARY_NOT_FOUND`, `SUGGESTION_NOT_FOUND`, `COMPANY_NOT_FOUND`, `ORG_NOT_FOUND`, `SETTINGS_NOT_FOUND`. **Business-rule violations (400)** — `KEYWORD_LIMIT_EXCEEDED` (plan cap hit), `LAST_ADMIN` (refuses to remove the only admin), `ITEM_EXISTS` (duplicate), `INVALID_DOMAIN`, `INVALID_TIMEZONE`. type: string enum: - UNAUTHORIZED - FORBIDDEN - RATE_LIMITED - VALIDATION_ERROR - INTERNAL_ERROR - NOT_FOUND - FEED_NOT_FOUND - KEYWORD_NOT_FOUND - POST_NOT_FOUND - SUMMARY_NOT_FOUND - SUGGESTION_NOT_FOUND - COMPANY_NOT_FOUND - ORG_NOT_FOUND - SETTINGS_NOT_FOUND - KEYWORD_LIMIT_EXCEEDED - LAST_ADMIN - ITEM_EXISTS - INVALID_DOMAIN - INVALID_TIMEZONE SimpleFilterCondition: type: object properties: field: description: >- Field name to filter on. Common values: `Keywords`, `Source`, `Sentiment`, `Relevance`, `Language`, `Tag`, `Author`, `Engaged`, `StartDate`, `EndDate`, `MinXFollowers`, `MaxXFollowers`. Field names are case-sensitive. example: Keywords type: string values: description: >- Values to match. Most fields accept comma-separated values (IDs for `Keywords`, uppercase enum values for `Source`, `Sentiment`, etc.). Prefix the field name with `!` on the parent form to invert. example: 42,43 type: string required: - field - values AdvancedFilterGroup: type: object properties: group_operator: description: How conditions *within* this group combine. type: string enum: - AND - OR conditions: description: Conditions inside this group. type: array items: $ref: '#/components/schemas/AdvancedFilterCondition' isSingleCondition: description: >- UI hint. When `true`, the group was created from a single condition in the builder. type: boolean required: - group_operator - conditions DestinationType: type: string enum: - EMAIL - SLACK - WEBHOOK DestinationFrequency: description: >- Delivery cadence. `hourly` fires on a rolling window; `hourlyAtTopOfHour` on the hour; `daily`/`weekly` use `time`+`timezone` (and `dayOfWeek` for weekly). type: string enum: - hourly - hourlyAtTopOfHour - daily - weekly EmailList: description: Comma-separated email addresses. example: alice@example.com, bob@example.com type: string HttpUrl: example: https://example.com/webhook type: string format: uri SimpleFilterConditionOutput: type: object properties: field: description: >- Field name to filter on. Common values: `Keywords`, `Source`, `Sentiment`, `Relevance`, `Language`, `Tag`, `Author`, `Engaged`, `StartDate`, `EndDate`, `MinXFollowers`, `MaxXFollowers`. Field names are case-sensitive. example: Keywords type: string values: description: >- Values to match. Most fields accept comma-separated values (IDs for `Keywords`, uppercase enum values for `Source`, `Sentiment`, etc.). Prefix the field name with `!` on the parent form to invert. example: 42,43 type: string required: - field - values additionalProperties: false AdvancedFilterGroupOutput: type: object properties: group_operator: description: How conditions *within* this group combine. type: string enum: - AND - OR conditions: description: Conditions inside this group. type: array items: $ref: '#/components/schemas/AdvancedFilterConditionOutput' isSingleCondition: description: >- UI hint. When `true`, the group was created from a single condition in the builder. type: boolean required: - group_operator - conditions additionalProperties: false AdvancedFilterCondition: type: object properties: field: description: >- Field name to filter on. Common values: `Keywords`, `Source`, `Sentiment`, `Relevance`, `Language`, `Tag`, `Author`, `Engaged`, `StartDate`, `EndDate`, `MinXFollowers`, `MaxXFollowers`. Field names are case-sensitive. type: string operator: description: >- Comparison operator. `in`/`not in` work with comma-separated `values`; `equals`/`=`/`>=`/`<=` treat `values` as a single scalar. type: string enum: - in - not in - equals - '>=' - <= - '=' values: description: >- Comma-separated values for `in`/`not in`, single value for comparisons. example: 42,43 type: string required: - field - operator - values AdvancedFilterConditionOutput: type: object properties: field: description: >- Field name to filter on. Common values: `Keywords`, `Source`, `Sentiment`, `Relevance`, `Language`, `Tag`, `Author`, `Engaged`, `StartDate`, `EndDate`, `MinXFollowers`, `MaxXFollowers`. Field names are case-sensitive. type: string operator: description: >- Comparison operator. `in`/`not in` work with comma-separated `values`; `equals`/`=`/`>=`/`<=` treat `values` as a single scalar. type: string enum: - in - not in - equals - '>=' - <= - '=' values: description: >- Comma-separated values for `in`/`not in`, single value for comparisons. example: 42,43 type: string required: - field - operator - values additionalProperties: false securitySchemes: ApiKey: type: http scheme: bearer description: >- Clerk API key. Create one in Settings → API Keys. Pass as `Authorization: Bearer `. ````