---
title: "Create an idempotent private draft"
method: POST
path: "/api/v1/agent/forms"
---

# Create an idempotent private draft

`POST /api/v1/agent/forms`

## Request

- Base URL: `https://api.formbuilder.com`
- URL: `https://api.formbuilder.com/api/v1/agent/forms`
- Auth: HTTP bearer

Requires forms:create. See https://formbuilder.com/developers#agent-workflows and https://formbuilder.com/help/agent-permissions-and-safety. Permissions are account-wide.

## Request body

- object
  - `request_id` string, required: Unique operation UUID. Reuse only with identical input for an exact retry.
  - `form` AgentForm, required
    - `title` string
    - `description` string
    - `submit_button_text` string
    - `fields` object[]
      - `id` string: Existing ID for edits only; omit to add a field.
      - `label` string, required
      - `type` 'text' | 'textarea' | 'email' | 'number' | 'phone' | 'url' | 'date' | 'select' | 'radio' | 'checkbox' | 'file', required
      - `required` boolean
      - `placeholder` string
      - `options` string[]
      - `page` integer

## Response `201`

Successful result. Mutation receipts include id, revision, status, edit_url, preview_url, public_url and replayed.

## Other responses

- `401`: Missing, expired or revoked credential
- `403`: Missing explicit scope
- `409`: Revision, idempotency or transactional conflict; inspect code
- `422`: Invalid form structure or unsupported field change
- `423`: Publication safety review blocked the operation

---

[API](https://skmtc.dev/formbuilder/apis/formbuilder-api.md) · [All operations](https://skmtc.dev/formbuilder/apis/formbuilder-api/llms.txt) · [OpenAPI document](https://skmtc.dev/formbuilder/apis/formbuilder-api/revisions/bcfbad019ae6?raw)