Automate Form Deployments with the FormTs API

Deploying forms through a web UI works fine until you need to do it repeatedly. Update a pricing formula, copy-paste into the editor, click save, hope you didn't break anything. The API eliminates this friction. Deploy forms from scripts, CI/CD pipelines, or AI coding assistants - no browser required.

This isn't about replacing the visual editor. For building and testing forms, the editor with its live preview is still the best tool. But once your form works and you want to deploy changes reliably, or you want an AI to create forms for you, the API becomes essential.

Who This Is For

The API makes sense for a few specific workflows:

• Developers who want forms in version control alongside their application code
• Teams that need review processes before form changes go live
• AI coding assistants like Claude Code, GitHub Copilot, or Cursor that can create and deploy forms without leaving your terminal
• Automation scripts that generate forms dynamically - maybe from a spreadsheet or another system

If you're building a single form and updating it occasionally, stick with the web editor. If you're managing multiple forms, iterating frequently, or want AI to help create them - read on.

What You Can Do

The API currently supports these operations:

• Create forms - deploy a new form with code, name, and optional AI settings
• Update forms - push changes to existing forms with version control
• List forms - see all your forms and their current versions
• Get form details - retrieve metadata for a specific form
• Get form code - retrieve the TypeScript source code of any form version

Everything you can do in the editor's "save" action, you can do via API. The form code is validated and transpiled server-side, so you get the same error checking as the visual editor.

Authentication

All API requests require an API key in the Authorization header:

Authorization: ApiKey sk_formts_your_key_here

Generate API keys in your User Settings. You can create multiple keys - one per project, environment, or team member. Each key has full access to your forms, so treat them like passwords.

Creating Your First Form

Here's a complete request to create a new form:

curl -X POST https://formts.com/api/forms \
  -H "Authorization: ApiKey sk_formts_..." \
  -H "Content-Type: application/json" \
  -d '{
    "versionNo": 1,
    "name": "Contact Form",
    "code": "export function contactForm(form: FormTs) { ... }",
    "aiInterviewerSettings": null
  }'

The response tells you the form was created and gives you its ID:

{
  "success": true,
  "externalId": "frm_abc123xyz",
  "codeHash": "a1b2c3d4...",
  "message": "Form created successfully"
}

That externalId is your form's permanent identifier. Save it - you'll need it for updates. The codeHash is a fingerprint of your code, useful for detecting changes.

Request Fields Explained

• versionNo - Start at 1 for new forms. The server tracks this to prevent conflicts.
• name - Human-readable name shown in your dashboard.
• code - The TypeScript form code. Same format as the editor.
• externalId - Optional. If omitted, the server generates one. Include it when updating existing forms.
• aiInterviewerSettings - Optional AI follow-up configuration. Set to null to disable.

Updating Forms Safely

To update an existing form, include the externalId and increment the versionNo:

curl -X POST https://formts.com/api/forms \
  -H "Authorization: ApiKey sk_formts_..." \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "frm_abc123xyz",
    "versionNo": 2,
    "name": "Contact Form v2",
    "code": "export function contactForm(form: FormTs) { ... }",
    "aiInterviewerSettings": null
  }'

The version number prevents conflicts. If someone else updated the form while you were working, your request will fail with a 409 error instead of silently overwriting their changes.

The Safe Update Pattern

For reliable updates, especially in automated pipelines:

1. Fetch the current form to get its version number
2. Increment the version
3. POST your update
4. If you get a 409 conflict, fetch again and retry

curl https://formts.com/api/forms/frm_abc123xyz \
  -H "Authorization: ApiKey sk_formts_..."

Response:

{
  "externalId": "frm_abc123xyz",
  "versionNo": 2,
  "name": "Contact Form v2",
  "codeHash": "e5f6g7h8..."
}

This pattern ensures you never accidentally overwrite changes. In practice, conflicts are rare unless multiple people are editing the same form simultaneously.

Listing All Forms

To see all your forms and their current state:

curl https://formts.com/api/forms \
  -H "Authorization: ApiKey sk_formts_..."

This returns an array of all your forms with their names, versions, and code hashes. Useful for building dashboards or syncing state between systems.

Retrieving Form Source Code

The codeHash from form details isn't just a fingerprint - you can use it to retrieve the actual TypeScript source code:

curl https://formts.com/api/forms/code/frm_abc123xyz/a1b2c3d4... \
  -H "Authorization: ApiKey sk_formts_..."

Response:

{
  "code": "export function contactForm(form: FormTs) { ... }"
}

This enables powerful workflows:

• Backup forms - export all your forms to local files or Git
• Version comparison - diff code between versions to see what changed
• Migration - move forms between accounts or environments
• AI analysis - let AI assistants read and improve existing forms

Using TypeScript/JavaScript

Here's how to deploy a form from a Node.js script:

const response = await fetch('https://formts.com/api/forms', {
  method: 'POST',
  headers: {
    'Authorization': `ApiKey ${process.env.FORMTS_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    versionNo: 1,
    name: 'Quote Calculator',
    code: formCode,
    aiInterviewerSettings: null
  })
});

const result = await response.json();
console.log('Form deployed:', result.externalId);

This pattern works in any environment that can make HTTP requests. The same approach applies to Python, Go, Ruby, or shell scripts with curl.

AI-Assisted Workflows

This is where things get interesting. AI coding assistants can use the API to create and deploy forms without you touching the editor at all.

How It Works

AI tools like Claude Code, GitHub Copilot, and Cursor can make HTTP requests. Give them your API key (stored securely), explain what form you need, and they'll generate the code and deploy it.

A typical prompt might look like:

You have access to the FormTs API. Create a cleaning quote form with: - Square footage (number input) - Number of bedrooms and bathrooms - Cleaning type dropdown (standard, deep clean, move-out) - Recurring checkbox with 15% discount - Live price calculation Deploy it using the API.

The AI generates the TypeScript code, calls the API, and reports back the form URL. You test it, request tweaks ("make the discount 20%"), and the AI updates and redeploys. The whole cycle happens in your terminal or IDE.

Providing Context

For best results, give the AI our type definitions. Copy them from the types page and include them in your prompt or project context. This helps the AI understand the full FormTs API - every field type, every configuration option.

AI tools that support project-level context (like Claude Code's CLAUDE.md or Cursor's rules) can have the types available automatically for every conversation.

CI/CD Integration

The API enables treating forms like code: version controlled, reviewed, and deployed through pipelines.

Basic Pattern

Store your form code in your repository. When code changes merge to main, your pipeline deploys the updated forms:

# Pseudocode - adapt to your CI/CD system
on:
  push:
    branches: [main]
    paths: ['forms/**']

steps:
  - checkout code
  - for each form config in forms/:
      - read current version from API
      - if local code differs:
          - increment version
          - POST to /api/forms
          - log deployment result

The exact implementation depends on your CI/CD system. The key insight is that form deployment becomes part of your normal release process, not a separate manual step.

Benefits of This Approach

• Code review - form changes go through pull requests like any other code
• History - git tracks who changed what and when
• Rollback - revert to any previous version by deploying old code
• Consistency - staging and production forms stay in sync with your deployment process

This matters most for teams where forms are critical to the business. If your quote calculator generates revenue, it deserves the same rigor as your application code.

Rate Limits

The API allows 20 requests per minute per API key. This is plenty for normal usage - even aggressive CI/CD pipelines rarely hit it. If you're doing bulk operations (migrating many forms at once), add small delays between requests.

When you exceed the limit, you'll get a 429 response. Wait a minute and retry. Most HTTP clients have built-in retry logic that handles this automatically.

Error Handling

The API returns standard HTTP status codes:

• 200 - Success
• 400 - Invalid request (check your JSON and required fields)
• 401 - Invalid or missing API key
• 409 - Version conflict (someone else updated the form)
• 429 - Rate limit exceeded
• 500 - Server error (try again later)

For automated pipelines, handle 409 and 429 with retries. Other errors usually indicate a problem with your request that won't be fixed by retrying.

Getting Started

Ready to try it?

1. Generate an API key in User Settings
2. Test with curl - create a simple form to verify your key works
3. Build your workflow - integrate with your scripts, CI/CD, or AI tools

Start simple. Deploy one form via API. Then expand to automation as your needs grow.