AgentForms Documentation

AgentForms is an API-first platform that lets AI agents create web forms, collect structured human input, and receive JSON responses — via plain HTTP from any language, or through the MCP server.

What is AgentForms?

AgentForms is an API that lets AI agents collect structured input from humans through web forms. When an agent needs information it cannot generate on its own — a shipping address, an approval decision, a file upload — it creates a form with a single API call, shares the hosted form link with the human, and receives the submitted data as structured JSON via a webhook or polling endpoint.

AgentForms handles the form UI, validation, hosting, expiration, and delivery. The agent never needs to build a frontend. It supports 8 field types (text, email, select, checkbox, date, number, textarea, file), HMAC-signed webhooks, automatic form expiration, and works with any language or framework via its REST API — or natively through its MCP server for Claude Desktop, Cursor, and other MCP-compatible clients.

Think of it as the missing bridge between AI agents and humans: agents talk JSON, humans fill out forms, AgentForms translates between the two.

Quick Start

Get up and running in three steps.

Register and get your API key

Register via the API to get your key (one per IP, no email required):

curl -X POST https://api.agentforms.dev/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project"}'

Save the returned api_key — it won't be shown again.

Create a form

Send a POST request to create a form with one or more fields. You'll get back a URL to share with the person who needs to fill it out.

Receive the response

Poll the responses endpoint, or set up a webhook to get notified immediately when the form is submitted.

Example: Python

No SDK needed — just plain HTTP with any library you like:

Python
import requests

API = "https://api.agentforms.dev/api/v1"
HEADERS = {
    "Authorization": "Bearer af_live_...",
    "Content-Type": "application/json",
}

# Create a form
form = requests.post(f"{API}/forms", headers=HEADERS, json={
    "title": "Contact Info",
    "fields": [
        {"key": "name", "type": "text", "label": "Full Name", "required": True},
        {"key": "email", "type": "email", "label": "Email", "required": True},
        {"key": "role", "type": "select", "label": "Role",
         "config": {"options": ["Engineer", "Designer", "PM"]}},
    ],
    "expires_in": "24h",
}).json()

print(form["url"])  # Share this URL with the human

# Poll for responses
responses = requests.get(
    f"{API}/forms/{form['id']}/responses",
    headers=HEADERS,
).json()
print(responses)
# [{"data": {"name": "Jane Doe", "email": "[email protected]", "role": "Engineer"}, ...}]

Example: cURL

bash
# Create a form
curl -X POST https://api.agentforms.dev/api/v1/forms \
  -H "Authorization: Bearer af_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Contact Info",
  "fields": [
    {"key": "name", "type": "text", "label": "Full Name", "required": true},
    {"key": "email", "type": "email", "label": "Email", "required": true},
    {"key": "role", "type": "select", "label": "Role",
     "config": {"options": ["Engineer", "Designer", "PM"]}}
  ],
  "expires_in": "24h"
}'

# Response includes form URL and ID
# {"id": "01JN...", "url": "https://api.agentforms.dev/f/01JN...", ...}

# Check for responses
curl https://api.agentforms.dev/api/v1/forms/FORM_ID/responses \
  -H "Authorization: Bearer af_live_..."

Next Steps