# 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](/docs/payments/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](/docs/payments/errors#when-payment-settles-but-the-service-fails).
