{
    "openapi": "3.1.0",
    "info": {
        "title": "FormFormForm",
        "description": "Create online forms, read the questions on them, and read the responses people have sent. Forms are published at a public URL that can be shared or embedded.",
        "version": "1.1.0"
    },
    "servers": [
        {
            "url": "https://app.formformform.com"
        }
    ],
    "paths": {
        "/api/mcp/forms": {
            "get": {
                "operationId": "listForms",
                "summary": "List the forms on this account",
                "description": "Returns the newest forms first, with their public URL, question count, response count and whether they are currently accepting responses.",
                "x-openai-isConsequential": false,
                "security": [
                    {
                        "oauth2": [
                            "mcp:use",
                            "forms:read"
                        ]
                    }
                ],
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Which page of results to return. Starts at 1.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "How many forms to return per page.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 50
                        }
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "description": "Only return forms whose title contains this text.",
                        "schema": {
                            "type": "string",
                            "maxLength": 100
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "A page of forms.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Something went wrong; `error.message` says what, in words safe to repeat.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            },
            "post": {
                "operationId": "createForm",
                "summary": "Create a form from a list of questions",
                "description": "Builds and publishes a form. Start the field list with a heading and end it with a submit_button; either is added if missing. Returns the form with its public URL.",
                "x-openai-isConsequential": true,
                "security": [
                    {
                        "oauth2": [
                            "mcp:use",
                            "forms:write"
                        ]
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/FormSpec"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The created form.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Something went wrong; `error.message` says what, in words safe to repeat.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/mcp/forms/generate": {
            "post": {
                "operationId": "createFormFromDescription",
                "summary": "Create a form from a plain description",
                "description": "Describe the form in a sentence or two and FormFormForm drafts and publishes it. Use this when the questions are not already decided; use createForm when they are.",
                "x-openai-isConsequential": true,
                "security": [
                    {
                        "oauth2": [
                            "mcp:use",
                            "forms:write",
                            "ai:generate"
                        ]
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/GenerateRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The created form.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Something went wrong; `error.message` says what, in words safe to repeat.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/mcp/forms/{form}": {
            "get": {
                "operationId": "getForm",
                "summary": "Read one form and its questions",
                "description": "Returns the form settings and every element on it, in the order a visitor sees them.",
                "x-openai-isConsequential": false,
                "security": [
                    {
                        "oauth2": [
                            "mcp:use",
                            "forms:read"
                        ]
                    }
                ],
                "parameters": [
                    {
                        "name": "form",
                        "in": "path",
                        "required": true,
                        "description": "The form's uuid, as returned by listForms.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The form.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Something went wrong; `error.message` says what, in words safe to repeat.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/mcp/forms/{form}/submissions": {
            "get": {
                "operationId": "listSubmissions",
                "summary": "Read the responses sent to a form",
                "description": "Returns responses newest first, each as a list of question and answer. An end-to-end encrypted form returns no answers, only a note saying so.",
                "x-openai-isConsequential": false,
                "security": [
                    {
                        "oauth2": [
                            "mcp:use",
                            "submissions:read"
                        ]
                    }
                ],
                "parameters": [
                    {
                        "name": "form",
                        "in": "path",
                        "required": true,
                        "description": "The form's uuid, as returned by listForms.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Which page of responses to return. Starts at 1.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "How many responses to return per page.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 10
                        }
                    },
                    {
                        "name": "since",
                        "in": "query",
                        "required": false,
                        "description": "Only return responses received at or after this ISO 8601 date-time.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "A page of responses.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Something went wrong; `error.message` says what, in words safe to repeat.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "oauth2": {
                "type": "oauth2",
                "flows": {
                    "authorizationCode": {
                        "authorizationUrl": "https://app.formformform.com/oauth/authorize",
                        "tokenUrl": "https://app.formformform.com/oauth/token",
                        "scopes": {
                            "mcp:use": "Confirm who you are on FormFormForm",
                            "forms:read": "List and read your forms and their questions",
                            "forms:write": "Create, change and delete your forms",
                            "submissions:read": "Read the responses people have sent to your forms",
                            "ai:generate": "Draft forms for you with FormFormForm AI",
                            "offline_access": "Stay connected without asking you to sign in again"
                        }
                    }
                }
            }
        },
        "schemas": {
            "FormSpec": {
                "type": "object",
                "required": [
                    "title",
                    "fields"
                ],
                "properties": {
                    "title": {
                        "type": "string",
                        "maxLength": 250
                    },
                    "description": {
                        "type": "string",
                        "maxLength": 1990
                    },
                    "fields": {
                        "type": "array",
                        "minItems": 1,
                        "maxItems": 26,
                        "items": {
                            "$ref": "#/components/schemas/Field"
                        }
                    }
                }
            },
            "Field": {
                "type": "object",
                "required": [
                    "type"
                ],
                "properties": {
                    "type": {
                        "type": "string",
                        "enum": [
                            "short_text",
                            "long_text",
                            "email",
                            "number",
                            "phone",
                            "date",
                            "dropdown",
                            "radio",
                            "checkbox",
                            "file",
                            "heading",
                            "paragraph",
                            "divider",
                            "hidden",
                            "page_break",
                            "submit_button"
                        ]
                    },
                    "label": {
                        "type": "string",
                        "maxLength": 250
                    },
                    "content": {
                        "type": "string",
                        "maxLength": 9990
                    },
                    "placeholder": {
                        "type": "string",
                        "maxLength": 250
                    },
                    "options": {
                        "type": "array",
                        "maxItems": 25,
                        "items": {
                            "type": "string",
                            "maxLength": 250
                        }
                    },
                    "is_required": {
                        "type": "boolean"
                    }
                }
            },
            "GenerateRequest": {
                "type": "object",
                "required": [
                    "description"
                ],
                "properties": {
                    "description": {
                        "type": "string",
                        "minLength": 3,
                        "maxLength": 2000
                    },
                    "title": {
                        "type": "string",
                        "maxLength": 250
                    },
                    "is_active": {
                        "type": "boolean"
                    }
                }
            },
            "Error": {
                "type": "object",
                "properties": {
                    "error": {
                        "type": "object",
                        "properties": {
                            "code": {
                                "type": "string",
                                "enum": [
                                    "bad_request",
                                    "unauthenticated",
                                    "insufficient_scope",
                                    "forbidden",
                                    "form_not_found",
                                    "field_not_found",
                                    "submission_not_found",
                                    "template_not_found",
                                    "form_encryption_locked",
                                    "validation_failed",
                                    "generation_failed",
                                    "rate_limited",
                                    "generation_unavailable",
                                    "server_error"
                                ]
                            },
                            "message": {
                                "type": "string"
                            },
                            "details": {
                                "type": "object"
                            }
                        }
                    }
                }
            }
        }
    }
}