---
title: "Create a form"
method: POST
path: "/forms"
tags: ["Forms"]
---

# Create a form

`POST /forms`

## Request

- Base URL: `https://api.clipform.io/v1`
- URL: `https://api.clipform.io/v1/forms`
- Auth: HTTP bearer

Creates a form, optionally with all its nodes in one request.

## Request body

- object
  - `title` string, required: Form title
  - `workspace_id` string, uuid, required: Target workspace for the new form. Obtain from GET /v1/me.
  - `is_live` boolean: Whether the form is immediately live (online for respondents). Defaults to true so created forms are shareable right away - pass false explicitly to create offline.
  - `first_run` boolean: Internal first-run flag. Set by the dashboard cold-start gate when it auto-scaffolds a new user's starter form, to suppress the first_form_created activation milestone - the scaffold is not authoring. Leave unset for normal creates.
  - `nodes` object[]: Optional batch build: ordered list of nodes to create with the form, all-or-nothing. Each node matches the add-node shape (type, prompt, label?, required?, config?, options?).
    - `type` string, required: Node type (see the node-type reference)
    - `prompt` string, required
    - `label` string
    - `required` boolean
    - `config` object: Type-specific configuration
    - `options` object[]
      - `content` string, required
      - `is_correct` boolean
      - `score` number
      - `scores` object
  - `settings` object: Form settings applied with a batch build (ignored without nodes). If any node has scored options, show_step_counter and disable_back_navigation default to true unless set explicitly here.
    - `show_step_counter` boolean
    - `disable_back_navigation` boolean
    - `primary_color` string: 6-digit hex, e.g. "#FF5500"
    - `background_color` string: 6-digit hex

## Response `201`

Form created

- object
  - `form_id` string, uuid
  - `share_id` string
  - `form_url` string, uri, nullable: Null for a normal authenticated create. For an anonymous caller in the shared public-company workspace (web/bot/email channels), a save/claim link to move the form into a real account. For an MCP-minted anonymous session's first form (#3330), a one-time same-UID claim URL instead - null on any later create reusing that same session.
  - `viewer_url` string, uri: A live public URL for an authenticated/claimed workspace. For an MCP-minted anonymous session (#3330), a time-limited `?mode=preview&pt=...` link only the caller can open - never public until the account is claimed and the form is published.
  - `nodes` object[]: Present on batch builds - created nodes in order
    - `id` string, uuid
    - `type` string
    - `prompt` string

## Other responses

- `401`: Missing or invalid credentials
- `403`: workspace_id does not match the API key's workspace
- `429`: Rate limit exceeded.

---

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