API Reference

Installation

npm install @formtress/js

Current version: 1.0.0

submitForm(options)

Submits form data to the Formtress endpoint.

import { submitForm } from '@formtress/js'

const result = await submitForm({
  url: 'https://app.formtress.com/api/f/your-form-id',
  data: new FormData(formElement),
})

Parameters

Name	Type	Required	Description
options	object	Yes	Submission options.
options.url	string	Yes	The form’s submit URL (https://app.formtress.com/api/f/your-form-id). Typically read from form.action.
options.data	FormData	Yes	A FormData instance containing the fields to submit.

Return value

Returns Promise<SubmitResult>.

interface SubmitResult {
  ok: boolean
  message?: string
  status?: number
}

Field	Type	Description
ok	boolean	true if the submission was accepted and passed validation.
message	string | undefined	Error message from the server. Only present when ok is false.
status	number | undefined	HTTP status code from the server.

Webflow script

The Webflow script progressively enhances standard HTML forms that submit directly to Formtress. Forms work without JavaScript — the script adds Webflow’s native success/error states and loading text support.

CDN URL

https://cdn.jsdelivr.net/npm/@formtress/js@1.0.0/dist/js/webflow.js

Behavior

1. On DOMContentLoaded, finds all <form> elements whose action points to the Formtress submit endpoint.
2. Attaches a submit handler to each form.
3. Intercepts and prevents the default form submission.
4. Collects form data and sends it to the form’s action URL via fetch.
5. On success: triggers Webflow’s native success state.
6. On error: triggers Webflow’s error state and updates any data-ft-error element.
7. Without the script: the form submits normally via standard HTML — spam protection still runs server-side.

Pinning a version

Always pin to a specific version in production:

<script src="https://cdn.jsdelivr.net/npm/@formtress/js@1.0.0/dist/js/webflow.js"></script>

To get the latest version automatically (not recommended for production):

<script src="https://cdn.jsdelivr.net/npm/@formtress/js@latest/dist/js/webflow.js"></script>

---

@formtress/server

npm install @formtress/server

Current version: 0.1.0

POST /public/api/v1/filter

The raw HTTP endpoint behind @formtress/server. No data is stored — this endpoint only returns a spam score.

Headers

Header	Required	Description
Authorization	Yes	Bearer ftk_<your-api-key>
Content-Type	Yes	application/json

Request body

{
  "ip": "1.2.3.4",
  "headers": Object.fromEntries(request.headers),
  "fields": [
    { "name": "email", "value": "test@gmail.com", "type": "email" },
    { "name": "message", "value": "Hello world", "type": "text" }
  ],
  "blockFreeEmailProviders": true
}

Field	Type	Required	Description
ip	string	Yes	End-user’s IP address (used for rate limiting).
headers	Record<string, string>	Yes	Forwarded request headers from the end-user’s browser.
fields	Array<{ name, value, type }>	No	Field values for content-level spam detection.
blockFreeEmailProviders	boolean	No	Flag free email providers (e.g. gmail.com) as spam. Defaults to false.

Response (200 OK)

{
  "isSpam": true,
  "score": 0.85,
  "rateLimited": false,
  "fieldErrors": {
    "email": "spam detected"
  }
}

Field	Type	Description
isSpam	boolean	Whether the submission was detected as spam.
score	number	Spam confidence score (0–1).
rateLimited	boolean	Whether the end-user was rate limited.
fieldErrors	Record<string, string>?	Per-field spam errors (only present if fields were flagged).

Response (401 Unauthorized)

{ "error": "Invalid or missing API key" }

Response (400 Bad Request)

{
  "error": "Invalid request body",
  "issues": { ... }
}

Endpoint URL

https://app.formtress.com/public/api/v1/filter