Management API

Authentication

Create a key under Settings → Connections → API keys. The plaintext is shown once; Fillo stores only its hash. Send it as a bearer token on every request:

curl https://fillo.so/api/v1/manage/forms \
  -H "Authorization: Bearer fsk_your_key_here"

Scopes

Every key stores an explicit set of scopes. A request for a scope the key lacks returns 403 with a stable message that names the missing scope. Mint keys in the dashboard or with fillo keys create --preset read|agent|full: read is the three read scopes, agent adds forms:write, forms:publish, and responses:export, and full is every scope except the irreversible delete tier. Delete scopes are never part of a preset — name them explicitly to grant them.

Endpoints

A form path segment accepts a form id or slug. Any id outside the key’s project returns 404 (never 403), so the API never reveals whether an inaccessible id exists.

Everything a workspace member can do in the dashboard is here, including the outward and the irreversible actions. On this API the scope is the consent: whoever minted the key chose it. Irreversible operations ask for one thing more — a body confirm field naming the exact target: a member's email address, a token, grant, or server id, an account's exact name, a respondent's external id, or the literal identity. A value that does not match is a 409 and nothing changes, and a boolean true is rejected outright, so a bare confirmation can never stand in for a typed one.

A response row looks like this:

{
  "id": "resp_…",
  "formId": "form_…",
  "data": { "fld_score": 9 },
  "meta": { "source": "app.example.com/feedback", "respondent": { "id": "user_42", "verified": true } },
  "formVersionId": "ver_…",
  "createdAt": "2026-07-13T10:00:00.000Z",
  "updatedAt": null
}

Pagination and filters

List endpoints return { data, nextCursor }. Pass nextCursor back as cursor for the next page; a null cursor means the last page. limit is 1–100 (default 50). Response filters use the same grammar as the responses grid and CSV export — range, q, source, respondent, and a repeatable where=fieldId:op:value.

Accepted responses only by default. The withheld queue is reachable through held=1, which swaps the rows rather than mixing them into a page and needs responses:manage on top of responses:read.

# Filter + walk pages. 'where' is repeatable as fieldId:op:value.
curl -G "https://fillo.so/api/v1/manage/forms/FORM_ID/responses" \
  -H "Authorization: Bearer $FILLO_KEY" \
  --data-urlencode "range=30d" \
  --data-urlencode "where=fld_score:gt:8" \
  --data-urlencode "limit=100"

# → { "data": [ … ], "nextCursor": "resp_abc" }
# Next page: add --data-urlencode "cursor=resp_abc"

curl -X DELETE "https://fillo.so/api/v1/manage/responses/RESPONSE_ID" \
  -H "Authorization: Bearer $FILLO_KEY"
# → { "id": "RESPONSE_ID", "deleted": true }

Versioning and deprecation

The public contract is versioned in the URL under /api/v1. Compatible additions can ship within v1; a breaking request or response change requires a new URL version. No v1 operation is currently deprecated. If that changes, the affected response will carry the RFC 9745 Deprecation date, an RFC 8594 Sunset date when removal is scheduled, and a rel="deprecation" link to migration instructions. The changelog and OpenAPI contract will name the replacement before the sunset date.

Errors and rate limits

Errors are a stable { "error": "…" } body with the matching status. Every response advertises its quota with RateLimit-Policy; RateLimit-Limit supports clients using the earlier convention. Auth responses with current limiter state also include RateLimit, RateLimit-Remaining, RateLimit-Reset, and an authoritative Retry-After on a 429. Treat Retry-After as authoritative.

Remote MCP

The same scopes back Fillo’s remote MCP server at /api/mcp (Streamable HTTP, stateless): connect a hosted MCP client to run forms and read responses over OAuth instead of pasting a bearer key. It uses OAuth 2.1 with PKCE and Dynamic Client Registration, discoverable at /.well-known/oauth-protected-resource. Consent is shown in product language with the read-only scopes pre-selected; approving mints a backing project key that appears in your keys list as MCP: <client> and is revocable there. When a grant asks for per-publish approval, the publish tool returns an approval URL instead of publishing directly. See the MCP server docs for setup, tools, and the local stdio server.