# Fox Grove Forms — full documentation > Hosted form backend for static websites, with a REST API and an MCP server for AI agents. Fox Grove Forms is a hosted form backend for static websites, run by Fox Grove Media (Cascade, Idaho, USA). Build a form in the dashboard, paste a two-line embed snippet into any HTML page, and every submission is validated, stored, emailed to you and available in the dashboard, as a CSV export, through a REST API, and to AI agents through an MCP server. It works on any site that serves HTML: plain HTML, Eleventy, Astro, Hugo, Jekyll, Netlify, Cloudflare Pages, GitHub Pages, WordPress, Webflow and more. Your site stays static; there is no backend code to write. - Website: https://foxgrove.media - Sign up (free 14-day trial, no credit card): https://foxgrove.media/register - Log in: https://foxgrove.media/login - Documentation: https://foxgrove.media/docs (Markdown: https://foxgrove.media/docs.md) - Pricing: https://foxgrove.media/pricing (Markdown: https://foxgrove.media/pricing.md) - OpenAPI spec: https://foxgrove.media/openapi.json - MCP server: https://foxgrove.media/mcp ## Embedding a form 1. Start a free trial and build a form on the Forms page of the dashboard. 2. Open the form's Embed tab and copy its snippet. It contains the form token. 3. Paste the snippet where the form should appear on your page. ```html
``` The script finds the element with the ID `FGMFormWrapper`, loads the form's HTML into it, and handles validation messages, hCaptcha and submission. Load the script once per page. To show more than one form on a page, give each container a `data-fgm-form` attribute (with its own `data-id`) instead of the `FGMFormWrapper` ID. ### Styling hooks Forms are plain HTML with stable IDs and classes: - `#FGMFormWrapper` — your container; the form renders inside it. - `#FGMForm` — the form element. - `.fgm-field-wrapper` — wraps each field's label, input and error message. - `#error-{field_name}` — the validation message for a field. - `#error-captcha`, `#error-form` — captcha and form-wide messages. - `#successMsg` — where the success message appears. The default markup uses Tailwind CSS utility classes, including a `brand-*` color scale (brand-500, brand-600, brand-900). Sites that use Tailwind should define those colors and compile the classes. You can also add your own CSS classes to the form, each field, each field wrapper and the buttons in the form builder. ## Field types Every input field has a label and a name. The name (letters, numbers, dashes and underscores; unique within the form) is the key used in submissions, emails, exports and the API. Name the email field `email` to enable reply-to, auto-replies and Mailchimp. | Field | Type key | Collects a value | Notes | | --- | --- | --- | --- | | Text | `text` | yes | Collects a value. | | Email | `email` | yes | Validated as an email address. | | Phone | `tel` | yes | Collects a value. | | Number | `number` | yes | Collects a value. | | URL | `url` | yes | Collects a value. | | Date | `date` | yes | Collects a value. | | Time | `time` | yes | Collects a value. | | Paragraph | `textarea` | yes | Collects a value. | | Dropdown | `select` | yes | Needs a list of options. | | Single choice | `radio` | yes | Radio buttons; visitors pick one option. Needs a list of options. | | Multiple choice | `checkboxes` | yes | Checkboxes; visitors tick any number of options, submitted as `name[]` and stored as a list. Needs a list of options. | | Checkbox | `checkbox` | yes | A single checkbox that submits "Yes", or its one option if set; when required it must be ticked. With two or more options (e.g. "Email, Phone, Text message") it becomes a group where visitors tick several, submitted as `name[]` and stored as a list. | | US state | `state` | yes | Dropdown of US states and DC. | | File upload | `file` | yes | Paid plans with file uploads. Stored privately; the size limit depends on the plan. | | Hidden | `hidden` | yes | Sends a fixed value (stored in the field's placeholder). | | Submit button | `submit` | no | Replaces the default submit button. | | Reset button | `reset` | no | Replaces the default reset button. | | Open group | `open-div` | no | Starts a wrapper element (put classes such as "grid grid-cols-2 gap-4" in wrapper_css) so fields can sit side by side. | | Close group | `close-div` | no | Ends the most recent group. | | Divider | `horizontal-rule` | no | A visual divider. | Required fields are checked in the browser and on the server. Email, number, URL and date fields are validated for their format automatically. ## Spam protection - **Honeypot:** every form includes a hidden `_fgm_hp` field that people never see but bots fill in. Those submissions are discarded while appearing successful. - **hCaptcha:** turn on the captcha in a form's settings and the widget is added automatically. Submissions without a valid `h-captcha-response` are rejected. - **Rate limiting:** each visitor can send up to 10 submissions a minute to a form. - **Allowed domains:** list the domains a form lives on (subdomains included) and submissions whose `Origin`/`Referer` is anywhere else are refused. Requests with no `Origin` or `Referer` are refused too when a list is set. ## Notifications, auto-replies and integrations - **Notification emails:** each submission is emailed to the addresses listed on the form (or the team owner when none are listed). When the form has an `email` field, replying to the notification goes to the submitter. A field named `subject` becomes the email's subject line. - **Auto-replies** (plans with the auto-reply feature): a confirmation email to the submitter. Use placeholders with any field name in the subject and body, e.g. `Thanks, {{ first_name }}! We'll reply to {{ email }} soon.` The body can be plain text or HTML. Auto-replies are sent from the platform address with your team or form name; set a reply-to address so responses reach you. - **Redirects and messages:** after a successful submission visitors see the form's success message in place, or are redirected to the form's `redirect_url` (e.g. a thank-you page). - **File uploads** (plans with uploads): files are kept in private storage and shared only through expiring links. - **Mailchimp** (Pro and Agency): connect a Mailchimp API key under Team → Integrations, then enable Mailchimp on a form with an audience ID. First and last names come from `first_name`/`last_name` fields, or are split from a `name` field. Double opt-in is optional. - **Dashboard:** search, read, export (CSV) and delete submissions; invite teammates or clients as owners, admins or managers. ## Submitting a form (public endpoint) The embed script handles this, but you (or an agent) can post to a form directly. No API token is needed. `POST https://foxgrove.media/api/forms/{token}` - Body: fields keyed by their names, as JSON (`Content-Type: application/json`), `multipart/form-data` (required for file uploads) or `application/x-www-form-urlencoded`. Send `Accept: application/json`. - Leave the honeypot `_fgm_hp` out or empty. Include `h-captcha-response` when the form requires hCaptcha. - If the form has an allowed-domains list, the request must come from one of those domains (`Origin` or `Referer` header). - `GET https://foxgrove.media/api/forms/{token}/html` returns `{"html": "..."}` with the rendered form. ```bash curl -X POST https://foxgrove.media/api/forms/YOUR_FORM_TOKEN \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"name": "Avery Parker", "email": "avery@example.com", "message": "Hi! We would love a quote."}' ``` Responses: - `200` — `{"success": true, "message": "...", "redirect": "https://example.com/thanks"}` (`redirect` only when the form has one). - `400` — validation failed: `{"success": false, "errors": {"email": ["The Email field must be a valid email address."]}}`, keyed by field name. - `401` — the captcha was missing or invalid (`errors.captcha`). - `403` — the submission came from a domain that isn't allowed (`errors.form`). - `404` — `{"message": "Form Not Found!"}`: the form doesn't exist, is turned off, or its team has no active plan. - `429` — too many submissions from this visitor, or the team's monthly submission limit was reached (`errors.form`). ## REST API (v1) Manage forms and read stored submissions from your own code. Available on plans that include API access (Pro and Agency). - **Base URL:** `https://foxgrove.media/api/v1` - **OpenAPI 3.1 spec:** https://foxgrove.media/openapi.json (also `https://foxgrove.media/api/v1/openapi.json`; no token needed) - **Authentication:** create a token in the dashboard under Team → API tokens and send it as `Authorization: Bearer YOUR_API_TOKEN`, with `Accept: application/json`. - **Abilities:** every token can read (`read`). Turn on "Allow creating, editing and deleting" when creating the token to add `write`, which create, update and delete need. - **Team scope:** a token belongs to one team and only sees that team's forms and submissions. It stops working if its creator leaves the team. - **Rate limit:** 60 requests per minute per token. ### Endpoints | Method | Path | Ability | What it does | | --- | --- | --- | --- | | GET | `/team` | read | The team, its plan, plan limits (null = unlimited) and current usage. | | GET | `/field-types` | read | Every field type a form can use. | | GET | `/forms` | read | List forms (paginated; `per_page` up to 100, `page`). | | POST | `/forms` | write | Create a form. Returns `201` with the form. | | GET | `/forms/{token}` | read | One form with its settings, fields and embed code. | | PATCH | `/forms/{token}` | write | Update a form (send only what changes; PUT also accepted). | | DELETE | `/forms/{token}` | write | Move a form to the trash (`204`). It stops loading on websites; restore it from the dashboard. | | GET | `/forms/{token}/submissions` | read | Submissions, newest first. Filters: `since`, `until` (ISO 8601), `search`, `unread`, `per_page`, `page`. | | GET | `/forms/{token}/submissions/{id}` | read | One submission. | | DELETE | `/forms/{token}/submissions/{id}` | write | Move a submission to the trash (`204`). | ### Form payload Create and update accept the same keys the form responses return, so you can read a form, edit it and send it back: `name`, `description`, `is_active`, `show_title`, `success_message`, `redirect_url`, `form_css`, `submit_text`, `submit_css`, `show_cancel`, `cancel_text`, `cancel_css`, `captcha_enabled`, `allowed_domains`, `notify_enabled`, `notify_emails`, `auto_reply_enabled`, `auto_reply_subject`, `auto_reply_body`, `auto_reply_from_name`, `auto_reply_from_email`, `auto_reply_reply_to`, `mailchimp_enabled`, `mailchimp_audience_id`, `mailchimp_double_opt_in`, and `fields`. - `name` is required on create. Without `fields`, a new form starts with name, email and message fields. - `fields` is the complete, ordered list of fields. On update it **replaces all existing fields**, so read the form first and send the whole edited list. - Each field is an object with `type` (see field types), `name`, `label`, `required`, `show_label`, `published` (false hides the field from the live form without deleting it), `placeholder`, `options` (for `select`, `radio` and `checkboxes`; optional for `checkbox`, where two or more make a multi-select), `input_css` and `wrapper_css`. Input fields need a unique `name` and a `label`. - Plan rules: `auto_reply_enabled` needs a plan with auto-replies plus `auto_reply_subject` and `auto_reply_body`; `mailchimp_enabled` needs a plan with Mailchimp, Mailchimp connected for the team and `mailchimp_audience_id`; `file` fields need a plan with file uploads. - Form responses also include `token`, `embed` (`snippet`, `script_url`, `html_url`, `submit_url`), `accepting_submissions`, `submissions_count` (when counted), `dashboard_url`, `created_at` and `updated_at`. Submission objects look like `{"id": 1042, "form_token": "...", "values": {"name": "Avery Parker", "email": "avery@example.com"}, "files": [{"field": "resume", "name": "cv.pdf", "size": 102400, "mime_type": "application/pdf", "url": "..."}], "read": false, "created_at": "2026-11-10T18:24:51+00:00"}`. `values` holds the submitted values keyed by field name; file URLs are download links that expire after 30 minutes. Lists are wrapped as `{"data": [...], "links": {...}, "meta": {...}}` and single objects as `{"data": {...}}`. ### Errors - `401` — missing or invalid token. - `402` — the team's plan doesn't include API access, or (with `"code": "plan_limit_reached"`) creating a form would exceed the plan's form limit. - `403` — the token lacks the needed ability (`read`/`write`) or isn't linked to a team its owner belongs to. - `404` — no form or submission with that identifier belongs to the token's team. - `422` — validation failed: `{"message": "...", "errors": {"fields.2.name": ["..."]}}`. - `429` — rate limited. ### Examples ```bash # Create a form curl -X POST https://foxgrove.media/api/v1/forms \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "name": "Contact", "redirect_url": "https://example.com/thanks", "notify_emails": ["hello@example.com"], "fields": [ {"type": "open-div", "wrapper_css": "grid grid-cols-2 gap-4"}, {"type": "text", "name": "first_name", "label": "First name", "required": true}, {"type": "text", "name": "last_name", "label": "Last name"}, {"type": "close-div"}, {"type": "email", "name": "email", "label": "Email", "required": true}, {"type": "textarea", "name": "message", "label": "Message", "required": true} ] }' # List this month's submissions curl "https://foxgrove.media/api/v1/forms/YOUR_FORM_TOKEN/submissions?since=2026-11-01" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json" ``` ## AI agents (MCP) The Model Context Protocol (MCP) lets AI assistants such as Claude use outside services as tools. Fox Grove Forms runs an MCP server so an agent can create and edit forms, fetch embed codes and read submissions for you. - **Endpoint:** `https://foxgrove.media/mcp` (Streamable HTTP transport) - **Authentication:** the same team API token as the REST API, sent as `Authorization: Bearer YOUR_API_TOKEN`. Create one under Team → API tokens; turn on write access if the agent should create, change or delete forms. API access needs a plan that includes it. - The agent only sees the token's team. Rate limit: 60 requests per minute per token. Claude Code: ```bash claude mcp add --transport http foxgrove-forms https://foxgrove.media/mcp --header "Authorization: Bearer YOUR_API_TOKEN" ``` Other MCP clients (JSON config): ```json { "mcpServers": { "foxgrove-forms": { "type": "http", "url": "https://foxgrove.media/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN" } } } } ``` Tools: - `get_team` — the team's plan, limits and usage (read). - `list_forms` — the team's forms with tokens, status and embed codes (read). - `get_form` — one form with its settings, fields and embed code (read). - `create_form` — create a form, optionally with fields and settings (write). - `update_form` — change settings and/or fields; sending `fields` replaces all existing fields, so read the form first (write). - `delete_form` — move a form to the trash (write, destructive). - `list_submissions` — a form's submissions, newest first, with date, search and unread filters (read). - `get_submission` — one submission, including expiring file links (read). - `delete_submission` — move a submission to the trash (write, destructive). Destructive tools move items to the trash rather than deleting them permanently; a person can restore them from the dashboard. Agents should confirm with the user before using them. ## Plans and pricing There is no free plan. New accounts get a 14-day free trial of the Pro plan with no credit card required. Choosing a plan during the trial starts billing when the trial ends. If no plan is chosen by the end of the trial, the team's forms pause (they stop loading and accepting submissions) until it subscribes; forms and submissions are kept. Plans are billed monthly or yearly through Stripe and can be changed or cancelled from the billing page. Prices are in US dollars. | Plan | Monthly | Yearly | Forms | Submissions / month | Team members | Upload size | Features | | --- | --- | --- | --- | --- | --- | --- | --- | | Starter | $9 | $90 | 5 | 1,000 | 3 | 5 MB | Auto-reply emails, File uploads | | Pro | $29 | $290 | Unlimited | 10,000 | 10 | 25 MB | Auto-reply emails, File uploads, Mailchimp integration, REST API access | | Agency | $79 | $790 | Unlimited | 50,000 | Unlimited | 50 MB | Auto-reply emails, File uploads, Mailchimp integration, REST API access | Every plan includes email notifications, spam protection (honeypot, hCaptcha, rate limiting, allowed domains), redirects and success messages, the submissions dashboard, CSV export, team roles, and forms without "Powered by" branding. - **Starter:** For small businesses with a few forms. - **Pro:** For growing teams that need integrations. - **Agency:** For agencies running forms across client sites. When a team reaches its monthly submission limit, its forms stop accepting submissions until the limit resets at the start of the next month or the team upgrades. ## Legal and contact - Terms of Service: https://foxgrove.media/terms - Privacy Policy: https://foxgrove.media/privacy - Accessibility Statement: https://foxgrove.media/accessibility - Contact: legal@foxgrovemedia.com · +1 (208) 965-1563 · Fox Grove Media, PO Box #48, Ola, Idaho 83657, USA