FeedNest Folders API

openapi: 3.2.0
info:
  title: FeedNest Public Folders 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: Folders
  description: Feed folder organization
paths:
  /api/v1/folders:
    get:
      operationId: listFolders
      tags:
      - Folders
      summary: List all folders
      description: Returns the user's folders in display order, each with the number of feeds it contains. Folders group subscriptions and drive `GET /api/v1/articles/by-folder/{folderId}`. Requires the `read` scope.
      responses:
        '200':
          description: Folder list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/FolderV1'
                required:
                - data
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '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
  schemas:
    FolderV1:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        color:
          type: string
        feed_count:
          type: integer
      required:
      - id
      - name
      - color
      - feed_count
    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
  responses:
    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'
  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