Quickstart: create a form, share it and read the responses

Updated 2026-10-30

You need 4 steps and about 5 minutes. Get an API key. Send one POST to create a form. Share the link that comes back. Call one GET to read the responses as JSON or CSV. Every example works as written once you set your key.

The base URL for every request is https://aiformapi.com/v1. All bodies are JSON.

1. Get an API key

  1. Open aiformapi.com and enter your email. You can also call POST /v1/signup with {"email": "you@example.com"}.
  2. We send you a magic link. There is no password.
  3. The link signs you in to the dashboard. The dashboard shows your first API key once. Copy it now.

Your key starts with afk_. Put it in an environment variable. Never paste it into a file you commit.

bash
export AIFORMAPI_KEY="afk_paste_your_key_here"

If you lose the key, rotate it in the dashboard settings and copy the new one. See Authentication.

2. Create a form

This request creates a small RSVP form. It has 3 fields and agent fill turned on. See Forms and fields for every field type.

curl

bash
curl -X POST https://aiformapi.com/v1/forms \
  -H "Authorization: Bearer $AIFORMAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Friday dinner RSVP",
    "description": "Tell us if you can come. It takes 20 seconds.",
    "fields": [
      {"id": "full_name", "label": "Your name", "type": "short_text", "required": true},
      {"id": "attending", "label": "Can you come?", "type": "single_choice",
       "required": true, "options": ["Yes", "No", "Maybe"]},
      {"id": "guests", "label": "How many people are you bringing?", "type": "number",
       "min": 0, "max": 5}
    ],
    "settings": {"agent_fill": true, "confirmation_message": "Thanks. See you Friday."}
  }'

JavaScript (Node 18 or newer)

js
const BASE = "https://aiformapi.com/v1";
const KEY = process.env.AIFORMAPI_KEY;
if (!KEY) throw new Error("Set AIFORMAPI_KEY first.");

async function api(path, options = {}) {
  const res = await fetch(`${BASE}${path}`, {
    ...options,
    headers: {
      Authorization: `Bearer ${KEY}`,
      "Content-Type": "application/json",
      ...options.headers,
    },
  });
  const isJson = (res.headers.get("content-type") || "").includes("json");
  const body = isJson ? await res.json() : await res.text();
  if (!res.ok) {
    const e = body.error || {};
    throw new Error(`${res.status} ${e.code}: ${e.message}`);
  }
  return body;
}

const form = await api("/forms", {
  method: "POST",
  body: JSON.stringify({
    title: "Friday dinner RSVP",
    description: "Tell us if you can come. It takes 20 seconds.",
    fields: [
      { id: "full_name", label: "Your name", type: "short_text", required: true },
      {
        id: "attending",
        label: "Can you come?",
        type: "single_choice",
        required: true,
        options: ["Yes", "No", "Maybe"],
      },
      { id: "guests", label: "How many people are you bringing?", type: "number", min: 0, max: 5 },
    ],
    settings: { agent_fill: true, confirmation_message: "Thanks. See you Friday." },
  }),
});

console.log(form.public_url);

Save this as create.mjs and run node create.mjs.

Python (requests)

python
import os
import requests

BASE = "https://aiformapi.com/v1"
KEY = os.environ.get("AIFORMAPI_KEY")
if not KEY:
    raise SystemExit("Set AIFORMAPI_KEY first.")

session = requests.Session()
session.headers.update({"Authorization": f"Bearer {KEY}"})

resp = session.post(
    f"{BASE}/forms",
    json={
        "title": "Friday dinner RSVP",
        "description": "Tell us if you can come. It takes 20 seconds.",
        "fields": [
            {"id": "full_name", "label": "Your name", "type": "short_text", "required": True},
            {
                "id": "attending",
                "label": "Can you come?",
                "type": "single_choice",
                "required": True,
                "options": ["Yes", "No", "Maybe"],
            },
            {"id": "guests", "label": "How many people are you bringing?", "type": "number", "min": 0, "max": 5},
        ],
        "settings": {"agent_fill": True, "confirmation_message": "Thanks. See you Friday."},
    },
    timeout=30,
)
resp.raise_for_status()
form = resp.json()
print(form["public_url"])

What comes back

A successful call returns 201.

json
{
  "id": "frm_4k9QeV2mTc8Xa1",
  "slug": "k3p9x2m7qa",
  "public_url": "https://aiformapi.com/f/k3p9x2m7qa",
  "status": "open",
  "created_at": "2026-10-30T09:00:00Z"
}

Keep the id. You need it to read responses.

Send the public_url to anyone. They need no account. The page works on a phone.

Because agent_fill is true (it is the default), the page also shows a card that says "Want your AI agent to fill this?". A visitor can copy a prompt, give it to Claude, ChatGPT or any agent, and the agent fills the form for them. Read Agent fill to see how it works.

You can also put the form on your own page. See Embed.

4. Read the responses

After someone submits, ask for the responses. Replace FORM_ID with the id from step 2.

curl, JSON

bash
curl "https://aiformapi.com/v1/forms/FORM_ID/responses?format=json" \
  -H "Authorization: Bearer $AIFORMAPI_KEY"

curl, CSV

bash
curl "https://aiformapi.com/v1/forms/FORM_ID/responses?format=csv" \
  -H "Authorization: Bearer $AIFORMAPI_KEY" \
  -o responses.csv

JavaScript

js
// Uses the api() helper from step 2.
const page = await api(`/forms/${form.id}/responses?format=json`);
for (const row of page.data) {
  console.log(row.submitted_at, row.source, row.answers);
}

Python

python
r = session.get(f"{BASE}/forms/{form['id']}/responses", params={"format": "json"}, timeout=30)
r.raise_for_status()
for row in r.json()["data"]:
    print(row["submitted_at"], row["source"], row["answers"])

A response looks like this:

json
{
  "data": [
    {
      "id": "rsp_9Zt3mWq7Lx2KbN",
      "form_id": "frm_4k9QeV2mTc8Xa1",
      "source": "agent_api",
      "submitted_at": "2026-10-30T09:14:02Z",
      "answers": {"full_name": "Ada Lovelace", "attending": "Yes", "guests": 1}
    }
  ],
  "next_cursor": null
}

The source tells you how the answer arrived: human, paste, agent_api or agent_mcp. See Responses for paging, since and CSV columns.

What the free plan gives you

  • 3 open forms per account.
  • 100 responses per account per calendar month (UTC).
  • 30 requests per minute and 1,000 per day for each API key.

The full table is in Rate limits and quotas.

Next steps

  • Ask your AI agent to do all of this for you with the MCP server.
  • Get a call on your server for each new response with webhooks.
  • Start from one of the form templates.
  • Look up an error code in Errors.