Public API
Use the Feeblo Public API v1 to read and manage a workspace's posts, comments, votes, tags, boards, changelog entries, companies, and end users over HTTP with an API key.
The Public API is the versioned HTTP surface for one workspace. Use it to sync feedback with a CRM, file posts from a support tool, publish changelog entries from a CMS, or read end-user records without a browser session.
It is not the widget HTTP API, which anonymous visitors call, and not the dashboard transport. The dashboard uses session-authenticated RPC; the Public API uses an API key on every request.
| Surface | Where |
|---|---|
| Base URL | https://api.feeblo.com/api/v1 |
| OpenAPI 3.1 document | https://api.feeblo.com/api/v1/openapi.json |
| Reference (readable without a key) | api.feeblo.com/api/v1/docs |
| MCP endpoint | https://api.feeblo.com/mcp — see MCP server |
| Agent authentication guide | feeblo.com/auth.md |
Self-hosted installations serve the same paths from their own API_URL.
Authentication
Send a workspace API key in the x-api-key header. There is no OAuth flow and no session cookie.
curl https://api.feeblo.com/api/v1/boards \
-H "x-api-key: fbk_..."A workspace admin or owner creates keys in the dashboard under Settings → Developers. The plaintext key is shown once, starts with fbk_, and is bound to the workspace that owns it. No request parameter can point a key at another workspace.
The Public API is included in the Starter and Professional plans. A workspace on the Free plan cannot create keys. Keys survive a downgrade and start working again after an upgrade — no rotation is required. See Plans.
Scopes
A key is created with a fixed set of scopes and never gains one later. Every key receives the read scopes for boards, posts, comments, votes, tags, and changelog. The write scopes, the CRM scopes, and the end-user scopes are opt-in at creation:
| Capability | Read scopes | Write scopes |
|---|---|---|
| Boards | boards.read |
— |
| Posts | posts.read |
posts.create, posts.update, posts.delete, posts.merge |
| Comments | comments.read |
comments.create, comments.update, comments.delete, comments.pin |
| Votes | votes.read |
votes.create, votes.delete |
| Tags | tags.read |
tags.create, tags.update, tags.delete, tags.assign |
| Changelog | changelog.read |
changelog.create, changelog.update, changelog.delete, changelog.publish |
| Companies | companies.read |
companies.create, companies.update, companies.delete |
| End users | end_users.read |
end_users.write |
Publishing is separate from editing because it emails every changelog subscriber. Merging is separate from editing because it archives one post and moves its comments and votes onto another. If an integration needs more than the key was issued, create a new key with the wider set; a key cannot be widened.
Requests and responses
Every response is JSON. Errors carry a machine-readable _tag:
{
"_tag": "FORBIDDEN_SCOPE",
"message": "This API key is missing the posts.create scope."
}| Status | _tag |
Meaning |
|---|---|---|
| 401 | MISSING_API_KEY |
No x-api-key header, or an empty one. |
| 401 | INVALID_API_KEY |
Unknown, revoked, expired, or disabled key. |
| 403 | FORBIDDEN_SCOPE |
The key lacks the scope the endpoint requires. |
| 403 | PLAN_REQUIRES_UPGRADE |
The workspace plan does not include the Public API. |
| 404 | NOT_FOUND |
The record does not exist in this workspace. |
| 409 | CONFLICT |
The write conflicts with the current state. |
| 429 | RATE_LIMITED |
The per-key budget is exhausted; read Retry-After. |
| 500 | INTERNAL_ERROR |
Unexpected server failure. |
| 503 | SERVICE_UNAVAILABLE |
A required dependency is unavailable; requests fail closed. |
Switch on _tag, not on message. Codes are append-only within v1.
List endpoints accept limit (1–100, default 25) and an opaque cursor. The response carries the next cursor as nextCursor:
{
"data": [],
"nextCursor": null
}Rate limits
Limits are per key, not per IP, and are shared by reads and writes: 300 requests per minute. Every successful response and every 429 reports the budget:
| Header | Meaning |
|---|---|
X-RateLimit-Limit |
Requests allowed in the current window. |
X-RateLimit-Remaining |
Requests left after this one. |
X-RateLimit-Reset |
When the budget next allows a request, as a Unix timestamp in seconds. |
A request refused before it spends a budget — a missing key, an invalid key, or a plan without the API — carries none of these headers.
Plans
The Public API is included in Starter and Professional. On the Free plan, key creation is blocked and existing keys answer 403 PLAN_REQUIRES_UPGRADE. Keys are kept while the workspace is on Free, can still be revoked, and work again on upgrade.
Versioning
The path carries the version (/api/v1). Within v1, fields may be added, new error codes may appear, and optional request fields may be added. Existing fields keep their meaning and type, and are not removed. A breaking change ships as /api/v2; when a v2 exists, v1 responses carry Deprecation and Sunset headers.
Companion surfaces
- MCP: the same operations as tools over streamable HTTP at
https://api.feeblo.com/mcp, with the same key. See MCP server. - Discovery:
https://feeblo.com/.well-known/api-catalog,https://api.feeblo.com/.well-known/api-catalog, andhttps://api.feeblo.com/.well-known/mcp.json. - Agent guide:
https://feeblo.com/auth.mdandhttps://api.feeblo.com/auth.mdcover key creation and client setup without a browser. - Full endpoint reference: api.feeblo.com/api/v1/docs, generated from the same OpenAPI document the API serves.