home
/
Guide for AI agents

Guide for AI agents

Written for AI coding agents (Claude Code, Cursor, Replit, Bolt, ChatGPT, v0, Lovable) and the humans wiring them up. When a user asks to "add a contact form" to a static site, this is the canonical path.

TL;DR — agent recipe

Check the user is logged in: formsubmit whoami --json. If it fails with 401, ask the user to run formsubmit login.
Check credits: formsubmit credits --json. If availableCredits is 0, ask the user to run formsubmit credits buy.
Create the form: formsubmit forms create --name "<label>" --json. Capture the id and endpoint.
Insert the HTML snippet — use formsubmit snippet <id> or paste the returned endpoint into the user's existing form.
Tell the user how to view submissions: formsubmit submissions list <id> or open the dashboard.

Why CLI, not REST?

Agents already know how to run shell commands. Skipping the REST/SDK layer means:

No API key paste-shenanigans — formsubmit login opens a browser.
No HTTP boilerplate to write or imagine.
Stable JSON output that's safe to pipe to jq or parse with one regex.

Output guarantees

Every read command supports --json.
When --json is set, only JSON goes to stdout.
Errors exit non-zero, with a one-line message on stderr.
HTTP 402 ("buy more credits") and 401 ("login") map to clear error messages mentioning the right next command.

Full agent flow in one block

# 1. ensure auth + credits
formsubmit whoami --json || formsubmit login

CREDITS=$(formsubmit credits --json | jq -r .availableCredits)
if [ "$CREDITS" -le 0 ]; then
  echo "User needs to buy credits: run 'formsubmit credits buy'"
  exit 2
fi

# 2. create + scaffold
FORM_JSON=$(formsubmit forms create --name "Contact" --json)
FORM_ID=$(echo "$FORM_JSON" | jq -r .id)
ENDPOINT=$(echo "$FORM_JSON" | jq -r .endpoint)

# 3. drop the snippet into the user's site
formsubmit snippet "$FORM_ID" --fields name,email,message > contact.html

# 4. point the user at submissions
echo "Form ready at $ENDPOINT"
echo "View submissions with: formsubmit submissions list $FORM_ID"

Discovery files

AI tools can find FormSubmit via the two discovery endpoints we publish:

/llms.txt — short human + agent-readable summary.
/.well-known/formsubmit.json — machine descriptor (capabilities, CLI install command, doc URLs).

Costs to surface to the user

Credit-based pricing: 1 credit = 1 form submission. Email notifications cost +1 extra credit per submission. Spam submissions are not charged. 100 credits cost $10. Credits never expire.

CLI reference → CLI source