Overview

Use the Formasty Forms API to create, update, publish, and manage forms programmatically over HTTP.

Section 01

What the Forms API is for

The Forms API manages draft form structure (steps, fields, logic, design), publishing, and metadata. It is intended for backend services, automation jobs, internal tools, and platform integrations.

Base URL and protocol

Environment	Base URL	Notes
Production	https://app.formasty.com/api/v1	Use for live workloads and production API keys.

Versioning: path-based (`/v1`). Breaking changes ship in a new version path.
Content-Type: `application/json` for request bodies.
Authentication: `Authorization: Bearer <api_key>`.
MCP clients connect to `https://app.formasty.com/api/mcp` and should prefer OAuth discovery from `/.well-known/oauth-authorization-server` plus `/.well-known/oauth-protected-resource/api/mcp`.
Developer-controlled MCP clients can still fall back to `Authorization: Bearer <api_key>` when OAuth is not available yet.
MCP agents can create forms without visiting the UI by calling `formasty_create_form` with an optional builder-compatible `draftSchema`, then `formasty_publish_form`.
All write endpoints mutate the draft unless explicitly publishing.

Warning

Internal environments

Non-production API environments are internal and not publicly documented. They require developer-controlled authentication and access controls.

Note

GPT Action / OpenAPI pack

A GPT Action-ready OpenAPI schema is stored at `/openapi.yaml`. It covers the API-key-safe `/api/v1` surface. Use MCP OAuth for per-user ChatGPT app connections and live tool discovery.

Tip

Machine-readable docs

Agents and other non-human readers should use `/llms.txt` for the overview, `/api-docs.txt` for the plain-text Forms API reference, and `/openapi.yaml` when configuring a GPT Action.

Section 02

Quickstart: create, save, and publish a form

curl -X POST "https://app.formasty.com/api/v1/forms" \
  -H "Authorization: Bearer $FORMASTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @draft-schema.json

curl -X PUT "https://app.formasty.com/api/v1/forms/frm_01JZ7A2E0M8Q1W9B5XK4J0R8YH/draft" \
  -H "Authorization: Bearer $FORMASTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @draft-schema.json

curl -X POST "https://app.formasty.com/api/v1/forms/frm_01JZ7A2E0M8Q1W9B5XK4J0R8YH/publish" \
  -H "Authorization: Bearer $FORMASTY_API_KEY" \
  -H "Content-Type: application/json"

JSON

{
  "data": {
    "id": "frm_01JZ7A2E0M8Q1W9B5XK4J0R8YH",
    "workspace_id": "wrk_01JZ79Y7YJ9Y2VD8QSE2RC1D8Q",
    "title": "Customer Intake",
    "status": "draft",
    "draft_updated_at": 1771759697,
    "draft_revision": 0,
    "published_version": 0,
    "published_at": null,
    "public_id": "pub_01JZ7A36D8C0QJEXAMPLE",
    "public_url": "https://app.formasty.com/f/pub_01JZ7A36D8C0QJEXAMPLE",
    "responses_count": 0
  },
  "draft_schema": {
    "version": 1,
    "steps": [],
    "settings": {
      "name": "Customer Intake"
    }
  },
  "published_schema": null
}

Section 03

MCP agent quickstart

Use this flow when you want Codex, Claude, or another MCP-capable agent to create Formasty forms without opening the Formasty UI.

In ChatGPT on the web, open `Settings -> Apps -> Advanced settings -> Developer mode` and enable Developer mode.
Open `Settings -> Apps`, click `Create app`, and choose a remote MCP server.
Add a remote MCP server named `formasty`.
Set the app name to `formasty` and the server URL to `https://app.formasty.com/api/mcp`.
Complete the OAuth sign-in and consent flow. Formasty publishes OAuth metadata, dynamic client registration, authorization-code PKCE, and protected-resource metadata from the MCP origin.
OAuth is the recommended setup path for ChatGPT, Codex, and other remote MCP clients that support it.
Claude remote connectors, Codex, Cursor, ChatGPT, and other direct remote-MCP clients should use the same Streamable HTTP server URL.
Claude Desktop or other stdio-only MCP clients can bridge the remote endpoint with `npx -y mcp-remote https://app.formasty.com/api/mcp`.
Formasty exposes standard MCP utility and discovery methods including `ping`, `tools/list`, `resources/list`, `resources/templates/list`, and `prompts/list`; tool definitions include `readOnlyHint` and `destructiveHint` annotations for hosts that show safety prompts.
If your MCP client cannot complete OAuth yet, create a dedicated Formasty API key from Developer settings and use `Authorization: Bearer <api_key>` as the fallback transport.
For create-and-publish workflows, grant `forms:create`, `forms:read`, and `forms:publish`. Add `forms:update`, `forms:steps:write`, `forms:fields:write`, `forms:logic:write`, and `forms:design:write` only when the agent should refine drafts after creation.
After ChatGPT imports the server, review the discovered tools and keep only the tools you want enabled.
Start a normal chat, add the Formasty app to the conversation, and ask ChatGPT to begin with `tools/list`, then `formasty_list_workspaces`, then the create/edit flow.
If the authenticated Formasty user has multiple writable workspaces, use `recommendedCreateWorkspaceId` when present. If it is `null`, tell the model to ask you which workspace to use instead of guessing.
Use `formasty_list_starter_templates` plus `formasty_create_form_from_starter_template` when you want the agent to start from a seeded Formasty template instead of generating a draft from scratch.
Use `formasty_clone_form` to duplicate an existing working form before editing, and `formasty_delete_form` to clean up unused drafts when the agent no longer needs them.

Warning

ChatGPT plan and mode requirements

Use regular chat with the Formasty app attached when you need write actions such as create, update, validate, or publish. Do not rely on deep research or Agent mode for Formasty write workflows. If your ChatGPT plan or workspace only supports read/fetch MCP access, install the app but use Codex or another MCP client for create/edit/publish actions.

These ChatGPT install steps match OpenAI's Apps and Developer mode flow as of April 22, 2026. ChatGPT menu names can change over time.

Copy-paste this setup prompt into ChatGPT or another MCP-capable assistant after you connect the Formasty MCP server.

JSON

{
  "mcpServers": {
    "formasty": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.formasty.com/api/mcp"]
    }
  }
}

Example

You are my Formasty build agent.
Use the configured remote MCP server named formasty.
If the Formasty MCP server is unavailable in this chat, tell me what is missing and stop.

If you can browse documentation, use these Formasty references as the source of truth:
- https://formasty.com/documentation/api-overview
- https://formasty.com/documentation/api-authentication
- https://formasty.com/documentation/api-endpoints-forms
- https://formasty.com/api-docs.txt
- https://formasty.com/llms.txt

Before you make changes:
1. Initialize MCP and inspect tools/list.
2. Call formasty_list_workspaces first and use recommendedCreateWorkspaceId when present. If it is null or ambiguous, ask me which workspace to use.
3. If a seeded template is the best fit, call formasty_list_starter_templates and formasty_create_form_from_starter_template. Otherwise call formasty_create_form with a stable idempotencyKey.
4. After each major change, call formasty_get_form so you are working from the latest draft state.
5. Make edits only through Formasty MCP tools that actually appear in tools/list.
6. Call formasty_validate_draft before any publish step and fix blockers first.
7. Publish only when I explicitly ask you to publish.
8. When finished, return the formId, draftRevision, and publicUrl if one exists.
9. Do not open the browser UI unless I explicitly ask for visual review.

When I give you a form brief, convert it into a production-ready Formasty draft, not just a generic outline.

JSON

{
  "jsonrpc": "2.0",
  "id": "create-form",
  "method": "tools/call",
  "params": {
    "name": "formasty_create_form",
    "arguments": {
      "idempotencyKey": "customer-feedback-create-1",
      "title": "Customer Feedback",
      "draftSchema": {
        "version": 1,
        "steps": [],
        "settings": {
          "name": "Customer Feedback"
        },
        "theme": {
          "primaryColor": "#4C3F8C",
          "brandPalette": []
        },
        "workflow": {
          "version": 1,
          "enabled": false,
          "rules": []
        }
      }
    }
  }
}

Section 04

Draft vs published behavior

Tip

Important

Create/update endpoints write draft data only. Public respondents see `published` snapshots only. Call Publish after draft changes are complete.

Related guides

Common follow-ups and adjacent pages that are usually needed next.