API reference

Filly API

A small REST API to read your forms and responses, and to receive submissions in real time via webhooks. JSON in, JSON out, served from the edge.

BASE URL

https://api.filly.app/v1

Authentication

Authenticate with a bearer token from your dashboard. Pass it in the Authorization header on every request.

cURL copy

curl https://api.filly.app/v1/forms \
  -H "Authorization: Bearer fly_live_..."

List responses

GET /v1/forms/{id}/responses

Returns a paginated list of responses for a form, newest first.

Query parameters

limit integer Number of responses to return. Default 50, max 200.

cursor string Pagination cursor from a previous response.

since ISO 8601 Only return responses submitted after this timestamp.

Response

200 · application/json copy

{
  "data": [
    {
      "id": "resp_8fK2a",
      "submitted_at": "2026-06-20T14:03:11Z",
      "fields": {
        "name": "Ada Lovelace",
        "email": "ada@example.com"
      }
    }
  ],
  "next_cursor": "c_19ax"
}

Forms

Use the forms endpoints to list form metadata, inspect schema JSON, and connect API output to your own workspace tools.

Webhooks

Webhooks deliver new submissions to your endpoint. Manage endpoints from the dashboard and inspect delivery history per form.

HTTP MCP

Filly exposes a production HTTP MCP endpoint for clients that can call remote Model Context Protocol servers. Create a JWT API key from /app/api and send it as a bearer token.

POST https://filly.app/api/mcp

HTTP MCP uses JSON-RPC 2.0. Most MCP clients generate requests for you after reading the tool list.

Client configuration

mcp.json copy

{
  "mcpServers": {
    "filly": {
      "type": "http",
      "url": "https://filly.app/api/mcp",
      "headers": {
        "Authorization": "Bearer eyJ..."
      }
    }
  }
}

Tools

Forms list_forms, get_form, create_form, update_form, delete_form

Responses list_responses, get_response, export_responses_csv

Webhooks list_webhooks, create_webhook, update_webhook, delete_webhook, list_webhook_deliveries

API keys list_api_keys, create_api_key, revoke_api_key

JSON-RPC example

cURL copy

curl https://filly.app/api/mcp \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_forms",
      "arguments": { "limit": 25 }
    }
  }'

Rate limits

API requests are rate limited per token. Public form submissions have separate limits to keep forms available during spikes.

Errors

Errors return a stable JSON object with a code, message, and optional field details.