FeedNest Feeds API

openapi: 3.2.0
info:
  title: FeedNest Public Feeds API
  version: 1.0.0
  description: 'The FeedNest Public API gives AI agents, automation platforms, and custom integrations programmatic access to your feeds, articles, highlights, notes, tags, and reading stats.


    ## Base URL


    ```

    https://feednest.com/api/v1

    ```


    ## Authentication


    All endpoints require a **Bearer token** (API key) in the `Authorization` header. Generate keys in **Settings → Developer API** (requires a Pro subscription).


    ```

    Authorization: Bearer fn_live_XXXX

    ```


    Keys use the format `fn_live_` followed by 32 hex characters. Each key is scoped to specific permissions:


    | Scope | Description |

    |-------|-------------|

    | `read` | Read feeds, articles, folders, tags, stats, highlights, notes, saved items |

    | `write` | Mark as read/unread, save/unsave, tag, highlight, add notes, extract content |

    | `ai` | Text-to-speech audio generation |


    ## Rate Limits


    | Endpoint group | Limit |

    |----------------|-------|

    | Default | 1,000 requests/hour per key |

    | AI endpoints | 50 requests/hour |

    | Save URL | 100 requests/hour |


    Rate-limited responses return `429` with `Retry-After` and `X-RateLimit-*` headers.


    ## Pagination


    All list endpoints use **keyset pagination**. Pass `limit` (max 100) and use the last item''s cursor fields (`before_published_at` + `before_id`) to fetch the next page. Check `meta.has_more` to know if more results exist.


    ## Error Format


    ```json

    {

    "error": {

    "code": "ERROR_CODE",

    "message": "Human-readable description."

    }

    }

    ```


    ## Versioning and deprecation


    The API is versioned in the URL path. `/api/v1` is the current stable version, and no breaking change will ever be made inside a version.


    Backwards-compatible additions (a new endpoint, a new optional field, a new optional parameter) ship inside `v1` without notice, so clients must ignore unknown response fields rather than failing on them.


    A breaking change means a new version path, for example `/api/v2`. When that happens:


    | Signal | Meaning |

    |--------|---------|

    | `Deprecation` response header | RFC 9745. Carries the date the version was declared deprecated. |

    | `Sunset` response header | RFC 8594. Carries the date the version stops responding. |

    | `Link` header, `rel="successor-version"` | Points at the replacement endpoint. |


    A deprecated version keeps working for **at least 12 months** after the `Deprecation` date. Deprecations are announced on the changelog, which every API response links via the `X-API-Changelog` header.


    ## Looking for AI assistant integration?


    FeedNest also exposes an **MCP server** at `mcp.feednest.com` for connecting to Claude, ChatGPT, Cursor, and other AI assistants. See the MCP documentation.'
  contact:
    url: https://feednest.com
  license:
    name: Proprietary
  x-mcp-server:
    url: https://mcp.feednest.com
    docs: https://docs.feednest.com
  x-protected-resource-metadata: https://www.feednest.com/.well-known/oauth-protected-resource
  x-versioning:
    strategy: uri-path
    current: v1
    status: stable
    breaking_changes: new-version-path
    deprecation_headers:
    - Deprecation
    - Sunset
    - Link
    minimum_sunset_period_days: 365
    changelog: https://feednest.com/changelog
servers:
- url: https://feednest.com
  description: Production
security:
- BearerAuth: []
tags:
- name: Feeds
  description: RSS feed subscriptions
paths:
  /api/v1/feeds:
    get:
      operationId: listFeeds
      tags:
      - Feeds
      summary: List subscribed feeds
      description: Returns every feed the user subscribes to, with title, site URL, folder assignment, and unread count. The `id` on each item is the subscription id to pass to feed-scoped endpoints. Requires the `read` scope.
      parameters:
      - name: folder_id
        in: query
        schema:
          type: string
          format: uuid
        description: Filter feeds by folder
      - name: q
        in: query
        schema:
          type: string
        description: Search feeds by name
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        description: Maximum items to return (1–100, default 50 for feeds)
      - name: before_name
        in: query
        schema:
          type: string
        description: 'Cursor: return the next page of feeds sorted after this name'
      - $ref: '#/components/parameters/before_id'
      responses:
        '200':
          description: Paginated feed list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/FeedV1'
                  meta:
                    type: object
                    properties:
                      has_more:
                        type: boolean
                    required:
                    - has_more
                required:
                - data
                - meta
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /api/v1/feeds/export-opml:
    get:
      operationId: exportOpml
      tags:
      - Feeds
      summary: Export feeds as OPML
      description: Returns every subscribed feed as an OPML document, the interchange format other RSS readers import. The response is XML rather than the usual JSON envelope. Requires the `read` scope.
      responses:
        '200':
          description: OPML document
          content:
            application/xml:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  headers:
    Retry-After:
      schema:
        type: integer
      description: Seconds to wait before retrying (on 429 responses)
    X-RateLimit-Remaining:
      schema:
        type: integer
      description: Remaining requests in current window
    X-RateLimit-Limit:
      schema:
        type: integer
      description: Request limit per window
    X-RateLimit-Reset:
      schema:
        type: integer
      description: UTC epoch seconds when the window resets
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Insufficient permissions or subscription required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Rate limit exceeded
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    FeedV1:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        url:
          type: string
          description: The feed's address. Empty for a newsletter, which has none.
        description:
          type:
          - string
          - 'null'
        image:
          type:
          - string
          - 'null'
          format: uri
        category:
          type:
          - string
          - 'null'
        unread_count:
          type: integer
        folder_ids:
          type: array
          items:
            type: string
            format: uuid
      required:
      - id
      - name
      - url
      - description
      - image
      - category
      - unread_count
      - folder_ids
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - UNAUTHORIZED
              - FORBIDDEN
              - SUBSCRIPTION_REQUIRED
              - NOT_FOUND
              - RATE_LIMITED
              - INSUFFICIENT_TOKENS
              - VALIDATION_ERROR
              - INTERNAL_ERROR
              - SERVICE_UNAVAILABLE
            message:
              type: string
            details:
              type: object
          required:
          - code
          - message
      required:
      - error
  parameters:
    before_id:
      name: before_id
      in: query
      schema:
        type: string
        format: uuid
      description: 'Cursor: return items with IDs before this value'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'API key in the format `fn_live_XXXX`. Pass via `Authorization: Bearer fn_live_XXXX`.'
      x-scopes:
        read: Read feeds, articles, folders, tags, stats, highlights, notes, saved items
        write: Mark as read/unread, save/unsave, tag, highlight, add notes, extract content
        ai: Text-to-speech audio generation
      x-token-issuance:
        type: self-service-api-key
        url: https://www.feednest.com/dashboard/settings/developer-api
        documentation: https://docs.feednest.com/api-keys