---
title: "Connect a feed"
method: POST
path: "/v1/feeds"
tags: ["Feeds"]
---

# Connect a feed

`POST /v1/feeds`

## Request

- Base URL: `https://api.mentio.dev`
- URL: `https://api.mentio.dev/v1/feeds`
- Auth: HTTP bearer

Connect an RSS or Atom feed: a feed's address, or a page's (a forum, a community, a blog), in which case the feed the page advertises is used, else a usual address such as /feed or /rss. Every keyword of the workspace with readsWorkspaceFeeds (the default) reads these feeds: an item holding its term is one of its mentions, with its matching rules, billed like any mention. Each feed is read every hour; reading it is free. At most 500 a workspace. A new feed brings each reading keyword the newest 10 items of the last 30 days that hold its term, never as instant alerts. A feed the workspace reads already comes back with 200 (connecting is idempotent). A members-only forum answers `feed_login_required`: send it again with `auth` (a cookie or a header), stored encrypted and read for this workspace alone.

## Request body

- object: One feed to connect, with a sign-in when it is members-only.
  - `url` string, required: A feed's address (https://forum.example.com/posts.rss), or a page's (https://forum.example.com): the feed the page advertises is used.
  - `auth` union: A sign-in for a members-only feed: a cookie, or one header. Write-only: stored encrypted, sent to the feed's own site alone, never shown again. A feed with a sign-in is read for this workspace alone.
    - object
      - `type` 'cookie', required
      - `value` string, required: The Cookie header your browser sends to the forum (devtools, Network, the feed's request, Request Headers, cookie).
    - object
      - `type` 'header', required
      - `name` string, required: The header name, e.g. Api-Key (Discourse) or Authorization.
      - `value` string, required: Its value.

## Response `200`

The workspace reads this feed already

- Feed: An RSS or Atom feed every keyword of the workspace reads.
  - `id` string, required: Feed id (fd_...).
  - `url` string, required: The feed itself (after redirects, or the one the page advertised): what is polled.
  - `title` string, nullable, required: The feed's own title, when it has one.
  - `connectedAt` string, required: When the workspace connected it.
  - `readingSince` string, required: Nothing published before this is a live mention: the connection, or the last time its sign-in was added or removed (signed in and signed out, a post is read as two different posts, so the switch starts over rather than bill one twice).
  - `auth` object, nullable, required: The sign-in the feed is read with, or null for a public feed. PATCH { auth } replaces it, { auth: null } removes it.
    - `type` 'cookie' | 'header', required: cookie or header. The value is never shown.
  - `health` object, required: Whether the hourly read works.
    - `status` 'ok' | 'failing', required: failing: the last 3 hourly reads or more failed (a feed.failing event went out); ok otherwise.
    - `reason` 'login_required' | 'login_expired' | 'blocked' | 'not_found' | 'not_a_feed' | 'unreachable', nullable, required: Why the last read failed; null when it read well.
    - `detail` string, nullable, required: What the last failed read saw.
    - `failures` integer, required: Failed hourly reads in a row.
    - `since` string, nullable, required: While failing: since when.
  - `stats` object, required: How the hourly poll of this feed is going.
    - `lastPolledAt` string, nullable, required: When the feed was last read; null until its first poll (within the hour).
    - `emptyPolls` integer, required: Polls in a row that brought nothing new; a feed that keeps reading empty may have moved.

## Other responses

- `201`: The feed, connected now
- `400`: feed_login_required: a sign-in wall, send auth. feed_login_expired: the auth sent does not read it. feed_unreadable: no feed there, or the site blocks readers (the message says which).
- `401`: Missing or invalid API key
- `409`: feed_limit_reached: the workspace reads 500 feeds already
- `429`: More than 30 feeds checked in a minute
- `503`: feed_auth_not_configured: a sign-in was sent and this deployment cannot store one

---

[API](https://skmtc.dev/mentio/apis/mentio-api.md) · [All operations](https://skmtc.dev/mentio/apis/mentio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mentio/apis/mentio-api/revisions/b16a21d0ed02?raw)