Quick Start — 3 Steps + Optional Proxy

✓ No API Key Needed

POST https://agentsforms.com/api/forms/create

{
  "name": "My form",
  "slug": "my-form",
  "fields": [
    {"id": "email", "type": "email", "label": "Your email", "required": true},
    {"id": "message", "type": "textarea", "label": "Message", "required": false}
  ],
  "delivery": {"type": "email", "to": ""}
}

Response includes "activate_url": "/api/forms/{ID}/activate?token=…" — you need this for step 2.

POST the activate_url with your email

curl -X POST "https://agentsforms.com" + activate_url \
  -H "Content-Type: application/json" \
  -d '{"email": ""}'

Response: "status": "published". Save the form.id from step 1 for step 3.

POST visitor answers from your frontend

const response = await fetch(
  'https://agentsforms.com/api/forms/{FORM_ID}/submissions',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      source: 'site',
      answers: { name, email, message }
    })
  }
);

Direct browser submissions are supported in production. CORS preflight returns 204 and POST returns "ok": true.

Optional: add a same-origin proxy for validation and spam control

// Use a proxy when you want to validate input, add rate limits,
// block open relay abuse, or normalize data before forwarding.

// Minimal proxy example (Node.js / Express-style route)
export async function POST({ params, request }) {
  const body = await request.json();
  const email = body?.answers?.email;

  if (typeof email !== 'string' || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
    return new Response(JSON.stringify({ error: 'valid email is required' }), {
      status: 400,
      headers: { 'Content-Type': 'application/json' }
    });
  }

  const res = await fetch(
    `https://agentsforms.com/api/forms/${params.id}/submissions`,
    { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) }
  );
  return new Response(res.body, { status: res.status, headers: { 'Content-Type': 'application/json' } });
}

// Astro proxy example (src/pages/api/forms/[id]/submissions.ts)
import type { APIRoute } from 'astro';

export const POST: APIRoute = async ({ params, request }) => {
  const body = await request.json();
  const email = body?.answers?.email;

  if (!params.id || typeof email !== 'string' || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
    return new Response(JSON.stringify({ error: 'valid email is required' }), {
      status: 400,
      headers: { 'Content-Type': 'application/json' }
    });
  }

  const res = await fetch(
    `https://agentsforms.com/api/forms/${params.id}/submissions`,
    { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) }
  );
  const data = await res.json();
  return new Response(JSON.stringify(data), { status: res.status });
};

export const OPTIONS = () => new Response(null, { status: 204, headers: {
  'Access-Control-Allow-Origin': '*',
  'Access-Control-Allow-Headers': 'Content-Type',
  'Access-Control-Allow-Methods': 'POST, OPTIONS',
}});

Most sites can POST directly to AgentsForms. Use this proxy pattern when you want extra production controls on your own domain.

Set up a form backend in 30 seconds.

This page is designed for AI coding agents. Read this page, ask the user 2 questions, and integrate the form.

API live — https://agentsforms.com/api

What to do

Step 1 — Ask the user these 2 questions:

What information do you need to collect? (e.g. name, email, message, phone, etc.)
Where should submissions be sent? (email address)

Step 2 — Create the form backend via API:

POST /api/forms/create

{
  "name": "Contact form",
  "slug": "contact",
  "fields": [
    { "id": "name", "type": "text", "label": "Name", "required": false },
    { "id": "email", "type": "email", "label": "Email", "required": true },
    { "id": "message", "type": "textarea", "label": "Message", "required": false }
  ],
  "delivery": { "type": "email", "to": "" }
}

Step 3 — Publish the form:

POST /api/forms/{FORM_ID}/activate?token=<TOKEN>

{"email": ""}

Step 4 — Wire the frontend form to POST answers:

POST /api/forms/{FORM_ID}/submissions

const response = await fetch(
  'https://agentsforms.com/api/forms/{FORM_ID}/submissions',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      source: 'site',
      answers: { name, email, message }
    })
  }
);

API endpoints

Base URL & Methods

POST /api/forms/create — Create a draft form from a JSON schema
POST /api/forms/:id/activate?token=... — Activate form with the token returned by create
POST /api/forms/:id/submissions — Submit answers to a published form
POST /api/forms/:id/sessions — Create a hosted form session
POST /api/demo — Demo endpoint (no auth, stores + emails)

Form schema reference

Supported field types

text textarea email url number boolean date select multi_select radio checkbox hidden

Example: contact form with 3 fields

forms/contact.json

{
  "name": "Contact form",
  "slug": "contact",
  "fields": [
    { "id": "name", "type": "text", "label": "Name", "required": false },
    { "id": "email", "type": "email", "label": "Email", "required": true },
    { "id": "message", "type": "textarea", "label": "Message", "required": false }
  ],
  "settings": {
    "submitLabel": "Send message",
    "successMessage": "Thanks — we'll be in touch."
  }
}

Quick CLI setup (alternative)

Install and create a form in one flow:

npm install -g @agentsforms/cli
agentsforms login
agentsforms init
agentsforms forms create forms/contact.json --email 
agentsforms forms publish contact

Delivery modes

Email (default)

Submissions are sent to the specified email address via AgentMail.

Webhook (MVP2)

Set "delivery": { "type": "webhook", "url": "https://your-app.com/webhook" } to receive signed webhook events instead of email.

Hosted form URLs (zero-UI fallback)

Create a hosted session

POST /api/forms/{FORM_ID}/sessions

{
  "id": "sess_abc123",
  "form_url": "https://agentsforms.com/f/sess_abc123?t=public_token"
}

Share the form_url with users — it's a fully functional hosted form.

Questions to ask the user

Q1: What information do you need to collect from visitors?

Examples: Name + email (contact), email only (waitlist), name + email + budget (intake), name + email + approval status (workflow gate).

Q2: Where should form submissions be sent?

Get a valid email address. This is where AgentMail will deliver submissions.

Q3: Do you need a hosted form URL, or will you build the frontend?

Hosted URLs are instant (zero code). Custom frontends let you keep the form in your site's design system.

Ready to integrate?

All API endpoints are live at https://agentsforms.com/api

Read the full docs →