API Reference
Endpoints, authentication, error codes, and the OpenAPI spec
This API reference covers Flowback's public API: the endpoints, authentication, error codes, rate limits, and response conventions. The API is exposed as a hosted Model Context Protocol server — a single JSON-RPC 2.0 endpoint over Streamable HTTP — rather than a set of REST routes. Any MCP client (or plain HTTP client speaking JSON-RPC) can drive it. For step-by-step client setup, see the MCP Server guide.
Endpoint
All requests are POSTs to the MCP endpoint:
https://mcp.flowback.co/mcp
The same handler is also reachable at https://www.flowback.co/api/mcp. Tool invocations use the standard MCP tools/call method with the tool name and arguments.
OpenAPI spec
A machine-readable description of the API — the endpoint, auth scheme, error model, and the input schema of every tool — is published as an OpenAPI 3.1 document at /openapi.json. It is generated from the live server's tool registry, so it always matches the deployed tools. An MCP discovery manifest is also available at /.well-known/mcp.json.
Authentication
Every request authenticates with a workspace-scoped API key passed as a Bearer token:
Authorization: Bearer fb_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Keys are created from Settings → Integrations → API & MCP in the dashboard and carry either read-only or read + write scopes. Scopes are documented in the MCP Server guide.
Error codes
Error handling follows JSON-RPC 2.0. Authentication and rate-limit failures are returned as HTTP-level error responses with a JSON-RPC error body; failures inside a tool call (insufficient scope, not found, validation) are returned in-band as MCP tool errors with a message explaining the fix. The error codes and responses you can encounter:
| Error | Where it surfaces | What it means and how to fix it |
|---|---|---|
| Missing API key | HTTP 401, code -32001 | No Authorization header. Include `Authorization: Bearer fb_sk_…` in your client configuration. |
| Invalid API key | HTTP 401, code -32001 | The key is malformed or has been revoked. Create a fresh key from the dashboard. |
| Rate limit exceeded | HTTP 429, code -32001 | One of three limits was hit: workspace/minute, workspace/day, or per-key/minute. Wait for the Retry-After window, then retry. |
| Insufficient scope | Tool error | The tool requires a scope this key doesn't carry. Recreate the key with the read + write preset. |
| Workspace read-only | Tool error | The trial ended or the subscription was canceled, so write tools are blocked. Reactivate billing to create or update issues. |
| Not found | Tool error | The issue or submission identifier didn't match anything in your workspace. Issues accept a UUID, native reference (FB-123), or external URL. |
| Validation error | Tool error | An argument failed validation; the message names the field and the reason. |
| Key limit reached | Tool error | The workspace already has the maximum number of API keys for its plan. Revoke an unused key or upgrade. |
| Internal error | Tool error | Something went wrong on our end. Retry shortly; if it persists, contact support@flowback.co. |
Rate limits
Three independent rate limits apply per request — workspace requests per minute, workspace requests per day, and per-key requests per minute — with plan-specific ceilings. Successful responses carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers; exceeded limits return HTTP 429 with a Retry-After header. The full per-plan table is in the MCP Server guide.
Pagination
List tools (list_issues, list_submissions, and friends) accept page and per_page arguments — per_page caps at 100. Every response pairs a human-readable summary with a structured JSON payload, so agents can parse results directly while narrating what they found.
Testing and sandbox workspaces
There is no separate test-mode API: keys always operate on the workspace they were created in. To experiment safely, create a second workspace as a sandbox — it gets its own API keys, its own data, and its own onboarding demo data — and point your agent or integration at that key while you build. Nothing you create in a sandbox workspace touches your production inbox, and you can revoke its key the moment you're done.
Versioning
This is v1 of the API. Tools, scopes, and rate limits are stable; new tools and scopes are added in a backward-compatible way, and any breaking change will ship under a separate endpoint version rather than changing this one.