---
title: "Create Form"
method: POST
path: "/workspaces/{workspace_id}/forms"
tags: ["forms"]
---

# Create Form

`POST /workspaces/{workspace_id}/forms`

## Request

- Base URL: `https://platform.tracecat.com/api`
- URL: `https://platform.tracecat.com/api/workspaces/{workspace_id}/forms`
- Auth: one of:
  - API key in cookie `fastapiusersauth`
  - HTTP bearer

Create the form of a workflow.

## Path parameters

- `workspace_id` string, uuid, required

## Request body

- FormCreate
  - `workflow_id` union, required
    - string
    - string
  - `status` 'online' | 'offline': Whether a form accepts submissions.
  - `config` FormConfigInput: Presentation layer of a form. The workflow input schema supplies the rest.
    - `title` string, nullable: Defaults to the workflow title.
    - `description` string, nullable: Markdown. Defaults to the workflow description.
    - `success_message` string, nullable
    - `layout` union[], nullable: Ordered blocks. Inputs left out are appended in schema order.
      - union
        - FormFieldEntry: Presentation of one workflow input.
          - `field` string, required: Name of the workflow input.
          - `label` string, nullable
          - `help` string, nullable
          - `placeholder` string, nullable
          - `widget` 'text' | 'long_text' | 'number' | 'toggle' | 'select' | 'multi_select' | 'cards' | 'tags' | 'date' | 'datetime' | 'user' | 'file': Input controls a form field can render as.
          - `options` FormOption[], nullable
            - `value` string, required
            - `label` string, nullable
            - `description` string, nullable
            - `image` string, nullable: Inline PNG, JPEG or WebP data URI.
          - `visible_if` FormVisibleIf: Show a field only while another field has this value.
            - `field` string, required
            - `equals` union, required
              - …
          - `autofill` 'requester' | 'requester.user_id' | 'requester.email' | 'requester.first_name' | 'requester.last_name' | 'submission.id': Values the server fills in on submit.
          - `hidden` boolean, nullable
          - `accept` string[], nullable: File extensions or MIME types a file field takes.
          - `max_files` integer, nullable
        - FormHeadingEntry
          - `heading` string, required
        - FormTextEntry
          - `text` string, required: Markdown.
        - FormNoticeEntry
          - `notice` string, required
          - `tone` 'info' | 'success' | 'warning' | 'danger'
        - FormDividerEntry
          - `divider` true, required

## Response `201`

Successful Response

- FormRead
  - `id` string, uuid, required
  - `workspace_id` string, uuid, required
  - `workflow_id` string, required
  - `workflow_title` string, required
  - `workflow_version` integer, nullable: Published workflow version the inputs come from, if any.
  - `status` 'online' | 'offline', required: Whether a form accepts submissions.
  - `config` FormConfigOutput, required: Presentation layer of a form. The workflow input schema supplies the rest.
    - `title` string, nullable: Defaults to the workflow title.
    - `description` string, nullable: Markdown. Defaults to the workflow description.
    - `success_message` string, nullable
    - `layout` union[], nullable: Ordered blocks. Inputs left out are appended in schema order.
      - union
        - FormFieldEntry: Presentation of one workflow input.
          - `field` string, required: Name of the workflow input.
          - `label` string, nullable
          - `help` string, nullable
          - `placeholder` string, nullable
          - `widget` 'text' | 'long_text' | 'number' | 'toggle' | 'select' | 'multi_select' | 'cards' | 'tags' | 'date' | 'datetime' | 'user' | 'file': Input controls a form field can render as.
          - `options` FormOption[], nullable
            - `value` string, required
            - `label` string, nullable
            - `description` string, nullable
            - `image` string, nullable: Inline PNG, JPEG or WebP data URI.
          - `visible_if` FormVisibleIf: Show a field only while another field has this value.
            - `field` string, required
            - `equals` union, required
              - …
          - `autofill` 'requester' | 'requester.user_id' | 'requester.email' | 'requester.first_name' | 'requester.last_name' | 'submission.id': Values the server fills in on submit.
          - `hidden` boolean, nullable
          - `accept` string[], nullable: File extensions or MIME types a file field takes.
          - `max_files` integer, nullable
        - FormHeadingEntry
          - `heading` string, required
        - FormTextEntry
          - `text` string, required: Markdown.
        - FormNoticeEntry
          - `notice` string, required
          - `tone` 'info' | 'success' | 'warning' | 'danger'
        - FormDividerEntry
          - `divider` true, required
  - `config_version` string, required: Version of the saved config.
  - `issues` FormIssue[], required
    - `severity` 'error' | 'warning', required
    - `code` 'unknown_field' | 'duplicate_field' | 'incompatible_widget' | 'no_widget_for_type' | 'unsupported_widget_option' | 'options_required' | 'options_not_supported' | 'option_not_in_enum' | 'default_invalid' | 'conditional_field_required' | 'visible_if_unknown_field' | 'visible_if_invalid_controller' | 'visible_if_invalid_value' | 'autofill_type_mismatch' | 'hidden_with_autofill' | 'unrendered_optional_input' | 'integer_out_of_range', required: Problems the resolver finds in a form config.
    - `message` string, required
    - `loc` union[], required: Path to the offending config key.
      - union
        - string
        - integer
  - `url` string, required
  - `counts` FormCounts
    - `views` integer, required
    - `submissions` integer, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `404`: Not Found
- `409`: Conflict
- `422`: Unprocessable Entity

---

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