📝 Agent Form

Hosted forms for human-in-the-loop data collection. Your agent creates a form via API, humans fill it out at a public URL, and submissions are delivered to your webhook.

How it works

Create a form with custom fields via the API. You get a unique public URL (/f/{token}) that you can share with humans. When someone submits the form, the data is stored and forwarded to your webhook URL.

The public form page requires no authentication — anyone with the URL can submit responses.

Create a form

curl -X POST https://www.agent-utils.com/api/form \

-H "x-api-key: au_your_key" \

-H "Content-Type: application/json" \

-d '{"title":"Customer Feedback","fields":[{"name":"name","label":"Your Name","type":"text","required":true},{"name":"email","label":"Email","type":"email","required":true},{"name":"rating","label":"Rating","type":"select","options":["Excellent","Good","Fair","Poor"]},{"name":"comments","label":"Comments","type":"textarea","placeholder":"Tell us more..."}],"webhookUrl":"https://myapp.com/webhook","ttl":604800}'

# Response (201)

{"success":true,"data":{"id":"...","token":"a1b2c3...","url":"https://www.agent-utils.com/f/a1b2c3...","title":"Customer Feedback","status":"active"}}

List forms

curl https://www.agent-utils.com/api/form \

-H "x-api-key: au_your_key"

# Response

{"success":true,"data":{"items":[{"id":"...","title":"Customer Feedback","status":"active","responseCount":5,"url":"https://www.agent-utils.com/f/a1b2c3...","expiresAt":"..."}],"total":1}}

Get form + responses

# Get form details + latest 100 responses

curl https://www.agent-utils.com/api/form/{form_id} \

-H "x-api-key: au_your_key"

# Response

{"success":true,"data":{"form":{...},"responses":[{"id":"...","data":{"name":"Alice","email":"alice@example.com","rating":"Excellent","comments":"Great service!"},"sourceIp":"1.2.3.4","createdAt":"..."}]}}

Delete a form

curl -X DELETE https://www.agent-utils.com/api/form/{form_id} \

-H "x-api-key: au_your_key"

# Response

{"success":true,"data":{"deleted":true}}

Public form page (no auth)

Share the public URL with humans. The form is rendered as a styled page with your custom fields. No API key or login required.

# Open in any browser — no auth needed

https://www.agent-utils.com/f/{token}

# Submit programmatically

curl -X POST https://www.agent-utils.com/api/form-submit/{token} \

-H "Content-Type: application/json" \

-d '{"name":"Alice","email":"alice@example.com","rating":"Excellent","comments":"Great!"}'

# Returns HTML thank-you page

Field types

Type	Description
text	Single-line text input
email	Email input with validation
number	Numeric input
textarea	Multi-line text input
select	Dropdown with options array
checkbox	Boolean checkbox

Parameters

Param	Method	Type	Description
title	POST	string	Form title shown to humans (required)
fields	POST	array	Array of field objects (required, non-empty)
webhookUrl	POST	string	URL to receive submission payloads (required)
ttl	POST	number	Time-to-live in seconds (default: 604800 / 7 days)
limit	GET	query	Max forms to return (default: 50, max: 100)
offset	GET	query	Pagination offset (default: 0)

Python

import requests

headers = {"x-api-key": "au_your_key"}

# Create a form

form = requests.post("https://www.agent-utils.com/api/form", headers=headers, json={

"title": "Customer Feedback",

"fields": [

{"name": "name", "label": "Your Name", "type": "text", "required": True},

{"name": "comments", "label": "Comments", "type": "textarea"}

"webhookUrl": "https://myapp.com/webhook"

}).json()["data"]

print(f"Form URL: {form['url']}")

# Retrieve responses

result = requests.get(

f"https://www.agent-utils.com/api/form/{form['id']}",

headers=headers

).json()["data"]

for resp in result["responses"]:

print(resp["data"])

Tier limits

Tier	Max Forms	Default TTL
Free	5	7 days
Builder	25	7 days
Pro	100	7 days
Enterprise	Unlimited	7 days