FeedNest Health API

openapi: 3.2.0
info:
  title: FeedNest Public Health 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: Health
  description: Service health checks
paths:
  /api/v1/health:
    get:
      operationId: getHealth
      tags:
      - Health
      summary: Health check
      description: Returns service health, API version, and a timestamp. Needs no API key, so an agent can confirm the API is reachable and read the advertised rate-limit policy from the `RateLimit-Policy` header before it has credentials.
      security: []
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - ok
                  version:
                    type: string
                  timestamp:
                    type: string
                    format: date-time
                required:
                - status
                - version
                - timestamp
        '503':
          description: Service degraded or unavailable
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  description: Database degraded
                  properties:
                    status:
                      type: string
                      enum:
                      - degraded
                    version:
                      type: string
                    timestamp:
                      type: string
                      format: date-time
                  required:
                  - status
                  - version
                  - timestamp
                - type: object
                  description: API disabled via kill switch
                  properties:
                    error:
                      type: object
                      properties:
                        code:
                          type: string
                          enum:
                          - SERVICE_UNAVAILABLE
                        message:
                          type: string
                      required:
                      - code
                      - message
                    status:
                      type: string
                      enum:
                      - unavailable
                    version:
                      type: string
                    timestamp:
                      type: string
                      format: date-time
                  required:
                  - error
                  - status
                  - version
                  - timestamp
components:
  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