docswidgets, API and MCP
Everything public about a project lives under one slug. Replace your-project with yours.
Every widget on this page is live. This page loads the same embed.js you would, pointed at our demo project. Click things.
Your public hub
Every project gets a hub page with a tab per enabled module. Turn a module off in Settings and its tab disappears.
- https://feedfa.st/p/your-project
- Changelog: the hub's default tab
- https://feedfa.st/p/your-project/feedback
- Feedback board
- https://feedfa.st/p/your-project/status
- Status page
- https://feedfa.st/p/your-project/changelog/entry-slug
- A single changelog entry
Install the script
One script tag, then place widgets wherever you want them. Every widget renders inside a shadow root, so your CSS and ours can never collide.
<script src="https://feedfa.st/embed.js" data-project="your-project" defer></script>- data-project
- Required. Your project slug.
- data-theme
- auto (default, matches the page behind it) · light · dark
- data-accent
- Override the accent colour, e.g. #4F46E5
- data-badge
- false to turn the floating badge off
- data-position
- bottom-right (default) · bottom-left
- data-skin
- card (default) · drawer · paper · glass · bold. The look of the feedback modal and the What's new panel; a feedback trigger can set its own
- data-user-id / -email / -name
- Identify the signed-in user: see below
Feedback button
Put data-feedfast="feedback" on any element: a button, a link, a menu item. It opens a modal that posts straight to your board.
If the element already has content, we leave your markup and styling completely alone and only attach the click handler. Need a look for it? The feedback button gallery has 27 designs to paste.
<button class="my-button" data-feedfast="feedback">
Send feedback
</button>The modal asks for a category, title, optional details and an optional email: the same fields as the public board, with the same rate limiting and spam trap. The submitted idea starts with the author's own upvote.
Identify your users
When the button lives inside your dashboard, you already know who's clicking it. Pass them along and the modal drops its name and email fields entirely.
No setup. Whatever your page sends is accepted and stored, marked unverified.
<button
data-feedfast="feedback"
data-user-id="${user.id}"
data-user-email="${user.email}"
data-user-name="${user.name}"
>Send feedback</button>This is only asserted, not verified
- data-user-id
- Your own user id. Opaque to us, never shown publicly.
- data-user-email
- Prefills the author, and makes their votes portable.
- data-user-name
- Shown as “Posting as …” in the modal.
- data-user-hash
- HMAC-SHA256 of the user id. Required once a secret is set.
Set the same attributes on the loader script to cover every trigger on the page, or call Feedfast.identify(...) once your SPA has the session. Identity on a trigger beats identity on the loader, so one page can have both an authenticated and an anonymous entry point.
Feedfast.identify({ id: user.id, email: user.email, name: user.name });
Feedfast.identify(null); // back to anonymous on sign-outUptime bar
The same 90-day strip as your status page, with full labels or as bars alone.
<div data-feedfast="uptime"></div>- data-labels
- full (default) | none: the status line, names, percentages and day scale, or the bars alone
- data-size
- md (default) | sm: bar height
- data-monitor
- Show a single monitor, by name
- data-days
- 1–90. How much history to draw
- data-overall
- true | false: the status line and link above the bars
Which day is a bar?
data-slim is labels none at size sm, and data-compact is size sm.Changelog
Cards for a landing page or a “what's new” section, an inline list for a sidebar, or titles alone.
<div data-feedfast="changelog" data-variant="card" data-limit="3"></div>- data-variant
- card (default) | inline
- data-labels
- full (default) | none: the heading, dates, versions, tags and excerpts, or the titles alone
- data-limit
- 1–10. How many entries
- data-title
- The heading. Defaults to “What’s new”
- data-excerpt
- true | false: card variant only
- data-tags
- true | false: the tag pills
Floating badge
On by default: a “What's new” badge pinned to a corner, that shows the latest title, marked New, until the visitor opens it.
<!-- on by default -->
<script src="https://feedfa.st/embed.js" data-project="your-project" defer></script>
<!-- off, if you'd rather place widgets yourself -->
<script src="https://feedfa.st/embed.js" data-project="your-project" data-badge="false" defer></script>These docs load the script with data-badge="false", so the badge isn't pinned over the page. This button opens the same panel it would.
The unread state lives in the visitor's own browser. If maintenance is scheduled, a notice appears above the entries.
data-badge is read once, when the script boots. In a single-page app that is the page the visitor first landed on, so a route change into a screen with no room for the badge: a dashboard, a checkout, anything with its own floating button in that corner: needs to say so:
Feedfast.setBadge(false); // leaving a page that wants it
Feedfast.setBadge(true); // and backSafe to call before the script has finished loading only if you guard it, until then there is no window.Feedfast to call, and the attribute on the tag already describes the first page.
JavaScript API
The loader exposes window.Feedfast once it runs.
- Feedfast.openFeedback(opts?)
- Open the modal. { title, subtitle, user } frame it; { prefill } fills it in — see Feedback button → From code
- Feedfast.openChangelog()
- Open the “What's new” panel
- Feedfast.setBadge(visible)
- Show or hide the floating badge after load
- Feedfast.identify(user)
- Set the signed-in user; null clears it
- Feedfast.close()
- Close whatever is open
- Feedfast.refresh()
- Re-fetch and re-render every widget
- Feedfast.mount(root?)
- Scan for new widgets (usually automatic)
- Feedfast.data()
- The current payload, or null before first load
Private endpoints
A health check worth having is often one you would rather not leave open. A monitor can hold a credential and send it on every check.
Set it on the monitor, under Uptime → the monitor → Authentication. Three methods, which between them cover most APIs:
- Bearer token
- Sent as Authorization: Bearer <token>.
- Custom header
- Any header name you like, e.g. X-API-Key.
- Query parameter
- Appended to the URL, e.g. ?token=…
What your endpoint receives, so you know what to compare against. Prefer the bearer form: a token in a URL ends up in your own access logs, and in any proxy in front of them.
GET /api/health HTTP/1.1
Host: your-app.com
Authorization: Bearer <your token>
User-Agent: FeedFast-Monitor/1.0 (+https://feedfa.st)Unexpected redirect rather than forwarding it. Point the monitor at the final URL.Your token is encrypted before it is stored and is never shown again — the form only knows whether one is saved. Leave the field blank when editing a monitor to keep the existing token, or type a new one to replace it. If a check ever reports that the credential cannot be read, re-enter it: that means the deployment's signing secret changed.
Response assertions
A 200 says the web server answered, not that the app behind it is healthy. On Pro, a monitor can also check what the response says.
Add rules under Uptime → the monitor → Response assertions. Every rule must hold; if one doesn't, the check fails exactly like a wrong status code would: retried, then an incident and an alert naming the rule.
- Body text contains
- The raw response must include this text.
- Body text does not contain
- The response must not include it, e.g. Maintenance.
- JSON field equals / does not equal
- ok and "ok" both mean the string; true and 3 are compared as JSON.
- JSON field contains
- Substring of a string, or an item of an array.
- JSON field exists / does not exist
- The path is (or isn't) present.
- JSON field is greater / less than
- Numeric comparison, e.g. queue.depth less than 1000.
Paths use dots and brackets, with an optional leading $.. For this response:
{ "status": "ok", "checks": { "db": "ok", "queue": { "depth": 12 } }, "regions": ["eu", "us"] }- checks.db equals ok
- Holds.
- checks.queue.depth less than 1000
- Holds.
- regions[1] equals us
- Holds. regions.1 works too.
- checks.cache exists
- Fails: checks.cache missing.
Heartbeats
Some of what breaks has no URL to check: a nightly backup, a queue worker, an hourly import. A heartbeat turns it around. Your job checks in, and silence is the alarm.
Choose Uptime → Add monitor → Heartbeat, say how often the job runs and how much slack it needs, and save. You get a private check-in URL. Call it at the end of the job:
# crontab: check in only when the backup succeeded
0 3 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 --retry 3 https://feedfa.st/api/hb/<token> > /dev/nullIf a check-in doesn't arrive within the period plus the grace, the heartbeat goes down like any other monitor: an incident, an email, a chat alert if you set one up, and recovery on the next check-in. The && matters: a job that runs but fails then goes quiet too.
- Methods
- GET, POST or HEAD. Any body, no headers needed.
- Answer
- 200 OK, or 404 for an unknown URL.
- Paused
- Still answers 200, so pausing doesn't fail your job.
- Repeat check-ins
- Counted once per 10 seconds.
- Periods
- 1 minute (Pro) or 5 minutes up to 1 week. Grace up to 6 hours.
SSL certificate warnings
An expired certificate is an outage that announces itself weeks in advance. Every HTTPS monitor reads its certificate and warns you before the date.
There's nothing to set up. Every few hours, alongside a normal check, we read the expiry date from the TLS handshake. It shows on the monitor, and you get one email (and a chat alert) at 14, 7 and 1 day before it runs out. Renew, and the warnings reset for the next certificate.
Private monitors
Not every check belongs on your status page. A private monitor keeps checking and alerting you, and your users never see it.
Switch off Show on the public status page in the monitor's form, or use Make private in its drawer. A private monitor is left out of the status page, the uptime widget, the status RSS feed and the widget JSON, and its incidents are never emailed to status subscribers. Your own emails and chat alerts are unchanged, and the REST API and MCP server still list it, marked public: false.
Shipped requests
When a changelog entry ships something people asked for, they hear about it, with the release note.
Link an entry to the requests it ships with the Ships feedback row in the editor: search the board, tick the requests. Starting from Create changelog entry on a Done request ticks that one for you. One entry can ship many requests; a request ships in one entry.
Publishing the entry marks every linked request Done and emails everyone following it straight away: a "Shipped" email with a button to the release note. Following means they left an email when they posted or commented, and that includes the people whose duplicate requests were merged into it, because merging moves their follow across.
- Once per entry
- Editing or re-publishing an entry never emails anyone twice
- Linked later
- Ticking another request on a live entry tells only that request's followers
- Unlinked
- The request keeps its status; nothing is sent
- Merged after
- Merging into a request that already shipped: the merge email carries the release note
- Not reached
- People who voted without an email, and anyone who unsubscribed
On the public pages, the request shows Shipped in with a link to the entry, and the entry lists the requests it answered under Asked for on the feedback board.
Through the API, send the post ids as feedbackPostIds when creating or editing an entry (on PATCH it replaces the list; [] unlinks them all). The MCP tools publish_changelog and update_changelog take the same field, and resolve_feedback links its entry on its own.
curl -X POST https://feedfa.st/api/v1/projects/acme/changelog \
-H "Authorization: Bearer ff_…" \
-H "Content-Type: application/json" \
-d '{
"title": "CSV export",
"contentMd": "Export any view as CSV from the toolbar.",
"tags": ["New"],
"feedbackPostIds": ["cm1abc…", "cm2def…"]
}'Email subscribers
One list per project, for the status page and the changelog. Each person picks what they get.
Visitors subscribe at the bottom of your status page or your changelog, with no account, and can tick the other one too. Those subscriptions are double opt-in: the address only receives mail after the confirmation link is clicked.
Status subscribers are emailed when an incident opens or resolves, and at whichever maintenance milestones you enabled (scheduled, started, completed). Changelog subscribers get each entry the first time it is published, a minute later so an unpublish in time sends nothing. The editor has a box to skip the email for an entry not worth one.
Someone following a request the entry ships gets the "your request shipped" email instead (see Shipped requests), never both. Through the API or MCP, pass notifySubscribers: false to skip the email.
Every email carries a one-click unsubscribe for its own topic, so leaving the changelog emails doesn't stop outage alerts. The list is shared with the plan limit: 30 people per project on Free, 200 on Pro, each counted once whatever they get.
Importing a list
Already have subscribers somewhere else? Open the subscriber list on the Uptime or Changelog page and choose Import CSV. You see exactly what would happen before anything is written: who is new, who gets an extra topic, who is skipped and why, and every line with a problem.
email,name,topics
ada@example.com,Ada Lovelace,both
grace@example.com,,changelog- Required. Also reads Name <address> as exported by mail apps
- name
- Optional
- topics
- Optional: status, changelog or both. Empty rows get the topics you pick
- Format
- Comma, semicolon or tab separated, UTF-8, up to 2,000 rows / 512 KB
- Skipped
- Bad addresses, unknown topics, repeats, people who unsubscribed themselves, anyone past the plan limit
Imported people are added confirmed and aren't emailed about it, so the import asks you to confirm that everyone in the file agreed to hear from you.
From your app's signup
Put a "Send me product updates" box on your signup form, and when it's ticked, add the person from your server. Your app asked them, so they're confirmed straight away. Calling it again on every sign-in is safe: nobody is added twice, and a topic someone unsubscribed from stays off until they subscribe again themselves.
curl -X POST https://feedfa.st/api/v1/projects/acme/subscribers -H "Authorization: Bearer ff_…" -H "Content-Type: application/json" -d '{
"email": "ada@example.com",
"name": "Ada",
"externalId": "user_123",
"topics": ["changelog", "status"]
}'- topics
- changelog, status or both. Defaults to every module that's on
- 201 / 200
- Added / already there; topics lists what they now get
- optedOut
- Topics they unsubscribed from, which the call left off
- 402
- The project's list is full on its plan
- DELETE
- Same path, { email, topics? }: they unticked it in your settings
Server side only
Chat alerts
On Pro, alerts can also go to Slack, Discord or Telegram, so the team sees an outage where they already talk. Email alerts keep coming either way.
Add channels under Settings → Notifications, up to ten per project. Each one picks what it receives, so outages can go to #ops and new feedback to #product:
- Monitors
- Down, recovered, still down after 24 hours, auto-paused.
- Maintenance
- Started and completed.
- New feedback
- A new post on your board, with its category and body.
Messages use the same words as the alert emails (🔴 Acme: API is down), with the cause, the time in your timezone and a link to the dashboard. Monitor alerts follow the same rules as email: a monitor is only reported down after two failed checks in a row, and a recovery is announced once it has stayed up for a short while. New feedback shows the submitter's name, never their email address.
Slack
Slack posts through an incoming webhook: a URL that can post to one channel. Creating one takes a minute.
- Go to api.slack.com/apps and choose Create New App → From scratch. Name it FeedFast and pick your workspace.
- In the app's sidebar, go to Features → Incoming Webhooks and switch it on.
- Click Add New Webhook, pick the channel it should post to (public or private) and press Allow.
- Copy the webhook URL Slack adds to the list.
- In FeedFast, open Settings → Notifications, choose Slack, give the channel a name, paste the URL and press Connect Slack.
https://hooks.slack.com/services/T0000000/B0000000/XXXXXXXXXXXXXXXXXXXXXXXXFeedFast sends a "connected" message before it saves anything, so a mistyped or revoked URL fails right there with Slack's own reason. Each webhook posts to one channel: for a second channel, add a second webhook.
Discord
Discord also posts through a webhook. You need the Manage Webhooks permission on the server.
- Hover the text channel and click the gear: Edit Channel.
- Go to Integrations → Webhooks → New Webhook.
- Press Copy Webhook URL. The name and avatar don't matter; messages arrive as FeedFast.
- In FeedFast, open Settings → Notifications, choose Discord, give the channel a name, paste the URL and press Connect Discord.
https://discord.com/api/webhooks/123456789012345678/XXXXXXXXXXXXXXXXXXXXXXXXUse a text or announcement channel; forum channels need a thread for every post, which a webhook can't pick. Messages never ping @everyone or @here, whatever a feedback post contains.
Telegram
Telegram needs no URL. You connect the FeedFast bot to a private chat or a group, and the dashboard picks it up.
- In Settings → Notifications, choose Telegram, pick what it should receive and press Connect Telegram.
- Telegram opens a chat with the FeedFast bot. Press Start to get alerts in that private chat.
- For a team group instead, press Add to a group instead and pick the group. The bot joins and links itself.
- The bot replies to confirm, and the settings page updates on its own.
The link works once and expires after 15 minutes; press Connect again for a new one. Groups and supergroups both work, and a group that Telegram upgrades to a supergroup keeps receiving alerts. Broadcast channels aren't supported. If the group only lets admins post, make the bot an admin.
RSS feeds
Both feeds are RSS 2.0 with content:encoded, cached for five minutes.
- https://feedfa.st/p/your-project/rss.xml
- Published changelog entries
- https://feedfa.st/p/your-project/status.rss
- Incidents and maintenance windows
JSON payload
The widgets read one small public document. It's CORS-open and cached for 60 seconds, so you can build your own UI on top of it.
- GET https://feedfa.st/api/widget/your-project
- No auth required
{
"project": { "name": "Acme Analytics", "slug": "acme", "accentColor": "#4F46E5" },
"hubUrl": "https://feedfa.st/p/acme",
"modules": { "changelog": true, "feedback": true, "status": true },
"entries": [{ "id": "…", "title": "…", "version": "2.4.0", "url": "…", "excerpt": "…",
"tags": ["New"], "publishedAt": "2026-08-14T05:12:59.305Z" }],
"categories": [{ "id": "…", "slug": "bug", "name": "Bug",
"color": "#EF4444", "isDefault": false }],
"uptime": {
"overall": { "state": "operational", "label": "All systems operational" },
"monitors": [{ "name": "API", "state": "up", "uptimePct": 99.82,
"bars": "uuuuuuuuduuu…" }],
"days": 90, "startDay": "2026-05-19", "timezone": "Europe/Bucharest"
},
"maintenance": { "title": "Database upgrade", "status": "SCHEDULED",
"startsAt": "2026-08-19T08:41:12.638Z",
"endsAt": "2026-08-19T09:41:12.638Z" }
}Each character in bars is one day, oldest first: u up, d down, g degraded, m maintenance, n no data. Every timestamp is ISO 8601 in UTC.
Board filters
Feedback board filters live in the URL, so any view you can see is a link you can share.
- ?category=bug
- One category, by slug
- ?category=bug,feature-request
- Several categories
- ?status=open,planned
- Filter by status
- ?sort=top | new | trending
- Top votes (default), newest, or votes in the last 7 days
- ?q=slack
- Free-text search across title and body
API keys
The REST API and the MCP server both authenticate with a bearer key from Settings → Account. Reading works on every plan; writing is part of Pro.
Keys look like ff_…. Only a SHA-256 hash is stored, so the plaintext is shown exactly once, at creation.
curl https://feedfa.st/api/v1/projects \
-H "Authorization: Bearer ff_your_key_here"- Scope
- READ_ONLY or READ_WRITE, writes 403 on a read-only key
- Rate limit
- 120 requests per minute per key
- Plan
- Free: read-only keys, every GET endpoint. Pro: read & write keys. On Free any write gets 402, including from a read & write key made on Pro, until the account is back on Pro
- Reach
- Every project on the account that owns the key
REST API
Everything the dashboard can do to a project, over HTTP.
- GET /api/v1/projects
- Every project this key can reach
- GET /api/v1/projects/:slug/changelog
- ?status=&limit=
- POST /api/v1/projects/:slug/changelog
- Create, and publish by default; optional version, feedbackPostIds, notifySubscribers
- PATCH /api/v1/projects/:slug/changelog
- Edit, publish or unpublish; feedbackPostIds replaces the linked requests
- GET /api/v1/projects/:slug/feedback
- ?category=&status=&sort=&q=&limit=
- GET /api/v1/projects/:slug/feedback/:postId
- One post with its comment thread
- PATCH /api/v1/projects/:slug/feedback
- Status, category, pin, owner reply
- POST /api/v1/projects/:slug/feedback/:postId/resolve
- Close it, reply, and publish the changelog entry in one transaction
- GET /api/v1/projects/:slug/uptime
- ?days=, state, uptime windows, incidents
- GET /api/v1/projects/:slug/maintenance
- ?upcoming=true
- POST /api/v1/projects/:slug/maintenance
- Schedule a window
- PATCH /api/v1/projects/:slug/maintenance
- start | complete | cancel
- GET /api/v1/projects/:slug/subscribers
- ?email=&topic=&limit=
- POST /api/v1/projects/:slug/subscribers
- Add someone who opted in inside your app; safe to repeat
- DELETE /api/v1/projects/:slug/subscribers
- They opted out inside your app; remembered
Two ways to say when
timezone ("2026-09-01T02:00") or a full ISO instant ("2026-08-31T23:00:00Z"). The first is what a person would say; the second is what a machine already has.curl -X POST https://feedfa.st/api/v1/projects/acme/maintenance \
-H "Authorization: Bearer ff_…" \
-H "Content-Type: application/json" \
-d '{
"title": "Database upgrade",
"startsAt": "2026-09-01T02:00",
"endsAt": "2026-09-01T03:30",
"timezone": "Europe/Bucharest",
"monitors": ["API"]
}'MCP server
Connect Claude or any MCP client and let it publish release notes, schedule maintenance, and read your board and uptime. Point it at the hosted endpoint, or run the package locally.
Hosted: a URL and your key
Nothing to install and nothing to update: the server runs on ours. Works in Claude Code, Claude Desktop, Cursor, Windsurf and VS Code.
Claude Code
One command, then restart the session.
claude mcp add --transport http feedfast https://feedfa.st/api/mcp --header "Authorization: Bearer ff_your_key_here"Claude DesktopCursorWindsurfVS Code
The same object everywhere: only the config file's location differs.
{
"mcpServers": {
"feedfast": {
"type": "http",
"url": "https://feedfa.st/api/mcp",
"headers": {
"Authorization": "Bearer ff_your_key_here"
}
}
}
}Local: run it through npx
For clients without HTTP transport, and for when the key should stay on your machine. Fetched from npm on each run.
Claude Code
Add --scope project to commit it to the repo for your team.
claude mcp add feedfast --env FEEDFAST_API_KEY=ff_your_key_here -- npx -y feedfast-mcpClaude DesktopCursorWindsurfZedVS CodeGemini CLI
Same file as above.
{
"mcpServers": {
"feedfast": {
"command": "npx",
"args": [
"-y",
"feedfast-mcp"
],
"env": {
"FEEDFAST_API_KEY": "ff_your_key_here"
}
}
}
}Codex
TOML, in ~/.codex/config.toml.
[mcp_servers.feedfast]
command = "npx"
args = ["-y", "feedfast-mcp"]
env = { FEEDFAST_API_KEY = "ff_your_key_here" }The key comes from Settings → Account → API keys, and both transports take the same one. A read-only key lets an agent answer questions but never change anything. Give it a read-write key only when you want it to publish. The local form runs feedfast-mcp, fetched from npm on each run.
- list_projects
- Slugs, enabled modules and content counts
- get_uptime
- Monitor state, uptime windows, open and recent incidents
- list_feedback
- Filter by status, category, search; sort by top/new/trending
- get_feedback
- One post with its full comment thread
- update_feedback
- Status, category, pin, and public owner replies
- resolve_feedback
- Close the loop: mark it done, reply publicly, publish the changelog entry, link them
- list_changelog
- Published and draft entries
- publish_changelog
- Write a release note, public immediately
- update_changelog
- Edit, publish a draft, or unpublish
- list_maintenance
- Scheduled, in progress and completed windows
- schedule_maintenance
- Announce planned downtime
- transition_maintenance
- Start now, complete early, or cancel
It can only do what the key can
The hosted endpoint
POST https://feedfa.st/api/mcp speaks Streamable HTTP JSON-RPC, with the key as Authorization: Bearer instead of an environment variable. It is stateless: no session id, so every request carries its own key and nothing is pinned to a process. Tool calls are rate-limited per key, at the same 120 requests a minute as the REST API.Want to see it all working? Browse the live demo hub.