Formasty Forms API
Machine-readable reference

Canonical production base URL
- https://formasty.com/api/v1

Authentication
- Send: Authorization: Bearer <api_key>
- Send JSON bodies with: Content-Type: application/json
- Use Idempotency-Key on create/publish POST requests when safe retries matter.

Core model
- Forms API responses use:
  - data: form summary
  - draft_schema: current resolved draft schema
  - published_schema: latest published snapshot or null
- The draft_schema contract is the same shared schema/property model used by the main Formasty builder UI.
- That means API clients can configure:
  - steps
  - fields
  - field labels
  - field properties/settings
  - workflow/routing
  - design/theme options

Form summary fields
- id
- workspace_id
- title
- status
- draft_updated_at
- draft_revision
- published_version
- published_at
- public_id
- public_url
- responses_count

Draft vs published
- All create/update/draft-save endpoints mutate the draft.
- Public forms serve published snapshots only.
- Publish copies the current draft into the live published snapshot.

Endpoints

1. POST /api/v1/forms
Purpose
- Create a new form.
- You can create an empty starter draft or send a full draftSchema.

Request body
- title: optional string
- draftSchema: optional object

Behavior
- If draftSchema is present, its settings.name becomes the stored form title.
- Returns data, draft_schema, published_schema.

2. GET /api/v1/forms
Purpose
- List forms in the authenticated workspace.

Response
- data: array of form summaries
- next_cursor: null (current implementation)

3. GET /api/v1/forms/{form_id}
Purpose
- Reopen a form for continued API-driven editing.

Response
- data
- draft_schema
- published_schema

4. PATCH /api/v1/forms/{form_id}
Purpose
- Update title only, or replace the current draft with a new full draftSchema.

Request body
- title: optional string
- draftSchema: optional object
- draft_revision: optional number
- force: optional boolean

Behavior
- If draftSchema is sent, Formasty saves it immediately as the current draft.
- Returns data, draft_schema, published_schema.
- When draftSchema is used, the response also includes draft_updated_at and draft_revision.

5. PUT /api/v1/forms/{form_id}/draft
Purpose
- Save the full draft schema snapshot.

Request body
- draftSchema: required object
- draft_revision: optional number
- force: optional boolean

Response
- data
- draft_schema
- published_schema
- draft_updated_at
- draft_revision

6. POST /api/v1/forms/{form_id}/publish
Purpose
- Validate the current draft and publish it.

Request body
- draftSchema: optional object
- draft_revision: optional number
- force: optional boolean

Behavior
- If draftSchema is included, Formasty saves that draft first and then publishes it.

Response
- data
- draft_schema
- published_schema
- published_at
- public_url

7. DELETE /api/v1/forms/{form_id}
Purpose
- Delete the form.

Full API workflow
1. Create a form with POST /api/v1/forms and a full draftSchema.
2. Store data.id and data.public_url.
3. Re-fetch later with GET /api/v1/forms/{form_id}.
4. Send another full draftSchema through PATCH /api/v1/forms/{form_id} or PUT /api/v1/forms/{form_id}/draft.
5. Publish with POST /api/v1/forms/{form_id}/publish.
6. Use public_url for the hosted live form.
7. The same saved draft can be opened in the Formasty builder UI.

Schema notes
- draftSchema is builder-compatible.
- Use stable IDs for steps and fields.
- Keep your integration as the source of truth for the full schema.
- Save the next full schema revision instead of trying to patch individual nested fields server-side.

Minimal draftSchema shape
{
  "version": 1,
  "steps": [
    {
      "id": "step_intro",
      "title": "Step 1",
      "fields": [
        {
          "id": "fld_name",
          "type": "text",
          "label": "Full name",
          "required": true,
          "placeholder": "Jane Doe"
        }
      ]
    }
  ],
  "settings": {
    "name": "Lead Capture",
    "slug": "lead-capture",
    "submitButtonLabel": "Request demo"
  },
  "theme": {
    "primaryColor": "#4C3F8C",
    "background": { "type": "solid", "value": "#FAFAFB" }
  },
  "workflow": {
    "version": 1,
    "enabled": false,
    "rules": []
  }
}

Validation highlights
- invalid draftSchema returns 400
- stale draft_revision returns 409
- duplicate slug returns 409
- invalid/missing API key returns 401
- form outside the key's workspace returns 404

Important URLs
- Human docs: /documentation/api-overview
- Agent overview: /llms.txt
- Agent plain-text API reference: /api-docs.txt