Introduction

The FormTs API allows PRO users to programmatically create and update forms. Use this API to integrate FormTs into your CI/CD pipelines, automate form deployments, or build custom tooling.

The API is also designed for AI-assisted development. Tools like Claude Code, GitHub Copilot, or other AI coding assistants can use this API to create and deploy forms directly from your IDE or terminal.

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

Header

Authorization: ApiKey sk_formts_...

API Key Management

Generate and manage your API keys in User Settings. You can create up to 10 API keys per account.

Endpoints

POST/api/forms

Create a new form or update an existing one.

Request Body

JSON

{
  "externalId": "frm_abc123xyz",
  "versionNo": 1,
  "name": "Contact Form",
  "code": "export function contactForm(form: FormTs) { ... }",
  "aiInterviewerSettings": {
    "instructions": "Ask follow-up questions",
    "maxFollowUps": 3
  }
}

Request Fields

Field	Type	Required	Description
`externalId`	string	No	Unique form identifier. If omitted, server generates one. Use existing ID to update.
`versionNo`	number	Yes	Version number. Use 1 for new forms, increment for updates.
`name`	string	Yes	Human-readable form name.
`code`	string	Yes	TypeScript form code. Must export a valid form function.
`aiInterviewerSettings`	object \| null	Yes	AI interviewer configuration or null to disable. See structure below.

AI Interviewer Settings

The AI Interviewer is an optional feature that allows an AI to ask follow-up questions based on user responses. Set to null to disable.

Field	Type	Description
`instructions`	string	Custom instructions for the AI interviewer. Guides the AI on what follow-up questions to ask and how to interact with the user.
`maxFollowUps`	number	Maximum number of follow-up questions the AI can ask per form submission.

Response

JSON

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

Example Request

cURL

curl -X POST https://formts.com/api/forms \
  -H "Authorization: ApiKey sk_formts_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "versionNo": 1,
    "name": "Contact Form",
    "code": "export function contactForm(form: FormTs) { ... }",
    "aiInterviewerSettings": {
      "instructions": "Ask follow-up questions to clarify the user needs",
      "maxFollowUps": 3
    }
  }'

GET/api/forms

List all your forms.

Response

JSON

{
  "forms": [
    {
      "externalId": "frm_abc123xyz",
      "versionNo": 2,
      "name": "Contact Form",
      "codeHash": "a1b2c3d4...",
      "submissionLinksCount": 3,
      "aiInterviewerSettings": {
        "instructions": "Ask clarifying questions",
        "maxFollowUps": 3
      },
      "updatedAt": "2026-02-03T10:30:00Z"
    }
  ]
}

Example Request

cURL

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

GET/api/forms/:formExternalId

Get details for a specific form.

Path Parameters

Parameter	Type	Description
`formExternalId`	string	The form's unique identifier (e.g., `frm_abc123xyz`)

Response

JSON

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

Example Request

cURL

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

GET/api/forms/code/:formExternalId/:codeHash

Retrieve the TypeScript source code of a specific form version.

Path Parameters

Parameter	Type	Description
`formExternalId`	string	The form's unique identifier
`codeHash`	string	The code hash from form details or list response

Response

JSON

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

Example Request

cURL

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

Version Control

Use this endpoint to retrieve source code for backup, version comparison, or synchronizing forms with your Git repository.

Rate Limits

API requests are rate limited to ensure fair usage and system stability.

20requests per minute

per API keyrate limit scope

Rate Limit Exceeded

When you exceed the rate limit, the API returns a 429 Too Many Requests error. Wait before retrying.

Need Higher Limits?

If you need a higher rate limit for your use case, contact us and we'll work with you to find a solution.

Error Codes

The API uses standard HTTP status codes to indicate success or failure.

Code	Status	Description
`200`	OK	Request successful.
`400`	Bad Request	Invalid request body. Check your JSON syntax and required fields.
`401`	Unauthorized	Invalid or missing API key. Verify your Authorization header.
`403`	Forbidden	PRO subscription required. Upgrade your plan.
`409`	Conflict	Version conflict. Another update was made. Fetch the latest version and retry.
`429`	Too Many Requests	Rate limit exceeded. Wait before retrying.
`500`	Server Error	Internal server error. Please try again later.

Best Practices

Version Control: Always increment versionNo when updating forms to avoid conflicts.
Error Handling: Implement retry logic with exponential backoff for rate limit errors.
Validate Locally: Test your form code in the editor before deploying via API.
Secure Keys: Never expose API keys in client-side code. Use environment variables.

Need Help?

If you have questions or encounter issues with the API:

Check the Tutorials for form code examples
Review the Types Reference for available field types
Contact support for API-specific issues

API Documentation

Introduction

Authentication

Endpoints

Request Body

Request Fields

AI Interviewer Settings

Response

Example Request

Response

Example Request

Path Parameters

Response

Example Request

Path Parameters

Response

Example Request

Rate Limits

Error Codes

Best Practices

Need Help?