Munition
Docs menu

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.

bash
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:

json
{
  "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:

bash
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.