Forms API
Reference for Munition's hosted forms API: an agent creates a form, people answer, the agent reads the answers. Routes, input, output, price and limits.
An agent creates a web form with up to 20 questions and gets a public link. People answer from any browser, without an account. The agent then reads the answers as JSON, and can close the form early. Creating a form is paid; reading and closing it are free.
Forms exist only while the forms service is enabled on the server. When it is off, every forms route answers 404 forms_disabled, the forms tools are not in GET /v1/tools/prices, and the remote MCP connector does not list them.
Routes and prices
Create a form
| Paid with | Route or tool | Tool id | Price (USDC) |
|---|---|---|---|
| x402 | POST /v1/forms |
create_form_direct |
0.01 |
| MPP | POST /v1/mpp/forms |
create_form_mpp |
0.01 |
| Account balance | MCP tool create_form |
create_form |
0.01 |
Read answers and close
| Paid with | Route or tool | Tool id | Price (USDC) |
|---|---|---|---|
| Free | GET /v1/forms/{id}/responses |
— | Free |
| Free | POST /v1/forms/{id}/close |
— | Free |
| Free | MCP tool form_responses |
— | Free |
| Free | MCP tool close_form |
— | Free |
The two HTTP routes are for forms created over x402 or MPP, and take the form's readToken. The MCP tools read and close the forms of the account that created them.
Create a form
On both routes, a request without payment gets the 402 without its body being read. A paid request is checked first: an invalid form gets 400 form_invalid, a form that asks for passwords, codes or bank details gets 400 form_forbidden_content, and neither costs anything.
Body of POST /v1/forms and POST /v1/mpp/forms:
| Field | Type | Required | Default | Limits and notes |
|---|---|---|---|---|
title |
string | yes | — | 1 to 120 characters, shown to people. |
description |
string | no | — | Up to 1,000 characters under the title. Plain text: line breaks are kept, links are not clickable. |
fields |
array of objects | yes | — | 1 to 20 questions, shown in this order. |
closesAt |
string | no | — | When the form stops taking answers: a date-time with a time zone, between 5 minutes and 30 days from now. Leave it out for 30 days. |
successMessage |
string | no | — | Up to 300 characters, shown after an answer is sent. |
Any other field is refused. Each question in fields[] of POST /v1/forms:
| Field | Type | Required | Default | Limits and notes |
|---|---|---|---|---|
id |
string | yes | — | The key of this question in the answers: a lowercase letter, then up to 39 lowercase letters, digits or _. Unique in the form. |
label |
string | yes | — | The question, 1 to 200 characters. |
type |
string | yes | — | text (answers up to 2,000 characters), long_text (up to 5,000), email, number, choice (one option) or multi_choice (any number of options). |
required |
boolean | no | false | Whether people must answer it. |
options |
array of strings | no | — | 2 to 20 options of 1 to 100 characters, unique ignoring case. Required for choice and multi_choice, not allowed otherwise. |
Response of POST /v1/forms and POST /v1/mpp/forms:
| Field | Type | Always present | Notes |
|---|---|---|---|
formId |
string | yes | The form id, frm_ and 22 characters. |
publicUrl |
string | yes | The link to share, on forms.munition.io. |
closesAt |
string | yes | When the form stops taking answers. |
maxResponses |
integer | yes | 100. The form closes when it is reached. |
responsesReadableUntil |
string | yes | The answers can be read until then, 7 days after closesAt. |
readToken |
string | no | Over x402 and MPP: the secret to read and close the form. |
Keep readToken secret. Anyone who has it can read the answers and close the form. The paid response returns it. A retry returns it again only when it carries the same Idempotency-Key, with the same payment and body, so always send an Idempotency-Key when creating a form.
Read the answers
GET /v1/forms/{id}/responses with Authorization: Bearer <readToken>. Answers come oldest first, 50 per page by default. Query parameters: limit, from 1 to 100, and cursor, the nextCursor of the previous page. Without a valid token the answer is 401; with another form's token, or after responsesReadableUntil, it is 404 form_not_found.
Response of GET /v1/forms/{id}/responses:
| Field | Type | Always present | Notes |
|---|---|---|---|
form |
object | yes | The form: formId, publicUrl, title, description, fields, status (open, closed or suspended), closeReason (expired, full, creator, reports or null), closesAt, responseCount, maxResponses and responsesReadableUntil. |
responses |
array of objects | yes | Each has id, submittedAt and answers, one key per question id: null for an empty optional question, an array for multi_choice, a number for number. |
nextCursor |
string or null | yes | Pass it as cursor for the next page; null on the last page. |
Close a form
POST /v1/forms/{id}/close with the same Authorization: Bearer <readToken> header and no body. The form stops taking answers at once, for good; its answers stay readable until responsesReadableUntil. Closing a closed form changes nothing.
Response of POST /v1/forms/{id}/close:
| Field | Type | Always present | Notes |
|---|---|---|---|
form |
object | yes | The form, as in the answers response, with status closed. |
Limits
- 1 to 20 questions per form, and 100 answers: the form closes at the hundredth.
- A form is open from 5 minutes to 30 days (30 days by default), and its answers are readable 7 days after
closesAt. - People answer at
https://forms.munition.io/f/<formId>, without an account. Every form shows a notice that an AI agent created it and that people should never enter a password, code or bank details. - One network address can send 5 answers per hour to a form. A form reported from 3 network addresses is suspended.
- Forms that ask for passwords, codes, card or bank details, recovery phrases or private keys are refused.
Example
Creating a lunch RSVP form. Called without payment, it answers 402 with the price in the PAYMENT-REQUIRED header; pay and send it again, with an Idempotency-Key, as in Copy-paste examples.
curl -sS -i https://api.munition.io/v1/forms \
-H 'Content-Type: application/json' \
--data '{"title":"Team lunch RSVP","fields":[{"id":"name","label":"Your name","type":"text","required":true},{"id":"attending","label":"Are you coming?","type":"choice","options":["Yes","No"],"required":true}]}'Paid, it costs 0.01 USDC. A response of POST /v1/forms looks like this:
{
"formId": "frm_AAAAAAAAAAAAAAAAAAAAAA",
"publicUrl": "https://forms.munition.io/f/frm_AAAAAAAAAAAAAAAAAAAAAA",
"closesAt": "2026-12-03T12:00:00.000Z",
"maxResponses": 100,
"responsesReadableUntil": "2026-12-10T12:00:00.000Z",
"readToken": "frt_example"
}Then read the answers, for free:
curl -sS https://api.munition.io/v1/forms/frm_AAAAAAAAAAAAAAAAAAAAAA/responses \
-H "Authorization: Bearer $READ_TOKEN"If the form does not open after payment, the API answers 503 form_effect_pending: see Errors and refunds.