# Formeo

> Formeo is a hosted form builder for businesses. Build forms in the dashboard or through the REST API, publish them, share or embed them on any site, and collect submissions you read and export from the dashboard or the API. On Pro and Enterprise, also documents from templates to e-sign.

These docs are written for developers and AI coding agents. Every page is plain Markdown at a
stable URL, and examples run as copied: start with a quickstart (listed first under Docs).

**Base URL.** The API is served under `/api` on your Formeo API host: `$FORMEO_URL/api`, for
example `https://api.formeo.io/api`. Root-relative links in this file resolve against the
host that serves this file; when the API has a host of its own, links to it are absolute.

**Authentication.** Use an organization API key, sent as `Authorization: Bearer fmo_...`. An
owner or admin creates keys in the dashboard (**Developer → API Keys**); each acts on one
organization and carries scopes such as `forms:read`, `forms:write` and `forms:delete`.
A `403` names the missing scope in `required`. Give each agent its own key with the fewest
scopes it needs, keep the key in an environment variable
(`FORMEO_API_KEY`), never in prompts or logs, and never use a dashboard session. Public forms
can be loaded and submitted without a key. Details:
[Authentication and API keys](https://formeo.io/docs/authentication.md).

**Key endpoints** (full list in the [API reference](https://formeo.io/docs/api.md) and the OpenAPI spec):

- `GET /api/v1/forms`, `POST /api/v1/forms`, `GET|PUT|DELETE /api/v1/forms/:id`: forms
  (`forms:read`, `forms:write`, `forms:delete`)
- `GET /api/v1/forms/public/:id`: a published form, to render it (no key needed)
- `POST /api/v1/forms/:formId/submissions`: submit to a published form (no key needed)
- `GET /api/v1/forms/:formId/submissions`, `GET /api/v1/submissions`,
  `GET /api/v1/submissions/export`: read and export submissions (`submissions:read`), with
  search (answers and option labels), field filters and sorting (`search`,
  `filter[<fieldId>]`, `choice[<fieldId>]`, `sort=field:<fieldId>`; choice fields filter and
  sort by their option labels too, and a matrix by its column labels, one row being
  `<fieldId>[<row>]`)

Responses are JSON: `{ "success": true, "data": ..., "message": "..." }`, or
`{ "success": false, "error": "...", "requestId": "..." }` on errors.

```bash
export FORMEO_URL=https://api.formeo.io
export FORMEO_API_KEY=fmo_...
H="Authorization: Bearer $FORMEO_API_KEY"

# Create a form (draft). Needs forms:write
FORM_ID=$(curl -s -X POST "$FORMEO_URL/api/v1/forms" -H "$H" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Signup","schema":{}}' | jq -r .data.id)

# Publish it, so it accepts submissions
curl -s -X PUT "$FORMEO_URL/api/v1/forms/$FORM_ID" -H "$H" \
  -H 'Content-Type: application/json' -d '{"status":"published"}'

# Submit (public: no key needed)
curl -s -X POST "$FORMEO_URL/api/v1/forms/$FORM_ID/submissions" \
  -H 'Content-Type: application/json' -d '{"data":{"email":"ada@example.com"}}'

# List its submissions. Needs submissions:read
curl -s "$FORMEO_URL/api/v1/forms/$FORM_ID/submissions" -H "$H"
```

**Rate limits** apply per key, per organization (all its keys together, by plan) and per IP for
public requests. On `429`, wait `Retry-After` seconds; pace requests with `RateLimit-Remaining`.
See "Rate limits" in the [API reference](https://formeo.io/docs/api.md).

**MCP server and SDK** (0.x previews on npm): `@draggable/formeo-mcp-server` (run with
`npx -y @draggable/formeo-mcp-server`; MCP Registry: `io.formeo/mcp-server`) is a local
(stdio) MCP server with tools to manage forms, get embed code and search or delete submissions,
using `FORMEO_API_KEY` and `FORMEO_URL` ([MCP server](https://formeo.io/docs/mcp.md)); `@draggable/formeo-sdk` is a
typed JS/TS client with typed errors and retries (`npm install @draggable/formeo-sdk`,
[SDK](https://formeo.io/docs/sdk.md)). **Webhooks** push `submission.created`, `form.published` and
`form.unpublished` as signed `POST`s ([Webhooks](https://formeo.io/docs/webhooks.md)); with `format: "slack"` they
post Slack messages instead. **Documents** (Pro, Enterprise): templates, records, recipient links,
signing order, versions, e-signatures, signed PDFs and .docx/PDF import:
[Documents](https://formeo.io/docs/documents.md).
**Zapier and n8n**: the Formeo Zapier app ([Zapier app](https://formeo.io/docs/zapier.md)) and n8n nodes
(`n8n-nodes-formeo`, [n8n nodes](https://formeo.io/docs/n8n.md)), or webhooks and the API:
[Integrations](https://formeo.io/docs/integrations.md). **Not available yet:** SDKs for other languages.

## Docs

- [All docs in one file](https://formeo.io/llms-full.txt): Every page below, concatenated in this order, for loading in one fetch.
- [Formeo docs](https://formeo.io/docs/index.md): What Formeo is, how to reach and authenticate to the API, and where every page lives.
- [Quickstart: REST API with curl](https://formeo.io/docs/quickstart-curl.md): Create, publish and submit to a form, then list and export its submissions, with curl and jq in five minutes. Every step shows its expected output.
- [Quickstart: JavaScript/TypeScript SDK](https://formeo.io/docs/quickstart-sdk.md): Create, publish and submit to a form with the Formeo SDK in one Node script, then receive new submissions on your server with a signed webhook, with polling as a backfill.
- [Quickstart: using Formeo from an AI agent](https://formeo.io/docs/quickstart-ai-agents.md): Give an AI agent a Formeo API key and the MCP server, what to ask it, which tools it calls, how it should find the docs and spec, and the rules for agents writing Formeo integration code.
- [Quickstart: embed a form](https://formeo.io/docs/quickstart-embed.md): Put a published Formeo form on a plain HTML page, in a React app or in a Next.js App Router app, with copy-paste code that resizes to fit and reports submissions.
- [Authentication and API keys](https://formeo.io/docs/authentication.md): How to authenticate to Formeo - dashboard sessions vs organization API keys, scopes, organization scoping, rotation and revocation, and exact auth errors.
- [API reference](https://formeo.io/docs/api.md): Every endpoint an API key can call, plus the public form and docs endpoints, with requests, responses, errors, curl examples and the OpenAPI 3.1 spec.
- [Sharing and embedding forms](https://formeo.io/docs/embedding.md): Share a published form by link, or embed it with an iframe, a script tag, or a React or Vue component.
- [MCP server](https://formeo.io/docs/mcp.md): Connect Claude Code, Cursor, Claude Desktop, VS Code, Windsurf or any MCP client to Formeo with an API key, to build forms, publish them, get embed code and read submissions from an AI agent.
- [JavaScript/TypeScript SDK](https://formeo.io/docs/sdk.md): The typed Formeo SDK for JavaScript and TypeScript (@draggable/formeo-sdk) - forms, submissions and webhooks with an API key, webhook signature verification, typed errors, rate-limit-aware retries. Runs on Node 22+, browsers, Deno, Bun and edge runtimes.
- [Webhooks](https://formeo.io/docs/webhooks.md): Receive signed HTTPS callbacks when forms get submissions or are published, verify their signatures, and handle retries, rotation and redelivery.
- [Integrations (Slack, Zapier, n8n)](https://formeo.io/docs/integrations.md): Post new submissions to Slack, and connect Formeo to Zapier and n8n with webhooks and the API, including signature checks you can paste in.
- [Zapier app](https://formeo.io/docs/zapier.md): Formeo's Zapier app: verified submission and form publishing triggers, form and submission actions, and searches.
- [n8n nodes](https://formeo.io/docs/n8n.md): Formeo's n8n nodes, a verified trigger for form events and a node for forms, submissions, files and the webhook delivery log.
- [Conditional logic](https://formeo.io/docs/conditions.md): Show, hide, check or fill in fields based on other answers, set up in the form builder or written into a form's schema.
- [File uploads](https://formeo.io/docs/file-uploads.md): Let respondents attach files to a form - limits and allowed types per field, how uploads work through the API, how files are checked and scanned for malware, storage limits, downloads, retention and deletion.
- [Email notifications](https://formeo.io/docs/email-notifications.md): Email your team about each new submission and send respondents an auto-reply, with subjects and messages that can include the form's name and the submission's ID.
- [Form templates](https://formeo.io/docs/templates.md): Ready-made forms to start from, built-in or saved by your organization, in English and European Portuguese.
- [Form themes](https://formeo.io/docs/form-themes.md): Your colors on hosted forms and embeds, from organization form themes or per form, and on Pro and Enterprise your logo without the Formeo badge.
- [Organizations, members and roles](https://formeo.io/docs/organizations.md): Organizations, the owner, admin, editor and member roles, inviting people, leaving an organization, transferring ownership, membership activity and deleting an organization.
- [Document generation and e-signatures](https://formeo.io/docs/documents.md): Templates, records, recipient links, e-signatures, signed PDFs, the API and plan limits.

## API

- [OpenAPI 3.1 spec](https://api.formeo.io/api/openapi.json): Every endpoint an API key can call and the public endpoints, with the scope each needs, schemas and examples.
- [Form data JSON Schema](https://api.formeo.io/api/schemas/form.json): JSON Schema (2020-12) of a form's `schema` field, the formeo form data format.

## Optional

- [Docs index (JSON)](https://formeo.io/docs/index.json): Every page with its title, description, HTML URL and Markdown URL.
- [Docs discovery (JSON)](https://api.formeo.io/api/docs): Served by the API: links to these docs, llms.txt and the OpenAPI spec.
- [formeo library docs](https://draggable.github.io/formeo/): The open-source form builder and renderer behind the Formeo editor.