{
  "openapi": "3.1.0",
  "info": {
    "title": "Eformly API",
    "description": "Eformly provides tools for filling, editing, signing, and managing PDF forms online, and for building online forms and surveys. The primary public-facing capability is Quick Fill: open any publicly accessible PDF for online filling and text editing by constructing a URL with the pdfUrl parameter. The same editor is also available at /edit-pdf with the Edit Text tool front and center.",
    "version": "1.0.0",
    "contact": {
      "name": "Eformly Support",
      "url": "https://eformly.app/contact"
    },
    "license": {
      "name": "Terms of Service",
      "url": "https://eformly.app/terms"
    }
  },
  "servers": [
    {
      "url": "https://eformly.app",
      "description": "Eformly production server"
    }
  ],
  "tags": [
    { "name": "quick-fill", "description": "Anonymous PDF filling and text editing — no account required" },
    { "name": "standalone-forms", "description": "Online form and survey builder" },
    { "name": "forms", "description": "PDF-backed form templates" },
    { "name": "tools", "description": "Free public PDF and document tools" }
  ],
  "paths": {
    "/quick-fill": {
      "get": {
        "operationId": "openQuickFill",
        "tags": ["quick-fill"],
        "summary": "Open a PDF for online filling and editing",
        "description": "Opens a publicly accessible PDF in the Eformly Quick Fill editor. The user can fill form fields, add text, edit existing text in place (Edit Text tool), add signatures, and download the completed PDF. No account is required. This is a browser URL, not a JSON API — direct users to this URL.",
        "parameters": [
          {
            "name": "pdfUrl",
            "in": "query",
            "required": false,
            "description": "A publicly accessible HTTPS URL pointing to a PDF file. Must use HTTPS protocol. PDF must be under 10MB and publicly accessible without authentication. Always URL-encode this value.",
            "schema": {
              "type": "string",
              "format": "uri",
              "example": "https://example.com/contract.pdf"
            }
          },
          {
            "name": "sessionId",
            "in": "query",
            "required": false,
            "description": "Resume a previously saved Quick Fill session by its ID.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "filename",
            "in": "query",
            "required": false,
            "description": "Custom filename for the downloaded completed PDF (without extension).",
            "schema": {
              "type": "string",
              "example": "signed-contract"
            }
          },
          {
            "name": "mode",
            "in": "query",
            "required": false,
            "description": "Set to 'embed' when using inside an iframe or embedded application.",
            "schema": {
              "type": "string",
              "enum": ["embed"]
            }
          },
          {
            "name": "origin",
            "in": "query",
            "required": false,
            "description": "The origin of the calling application (required when mode=embed for postMessage communication).",
            "schema": {
              "type": "string",
              "example": "https://yourapp.com"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTML page — the Quick Fill PDF editor loaded in the browser."
          }
        }
      }
    },
    "/edit-pdf": {
      "get": {
        "operationId": "openEditPdf",
        "tags": ["quick-fill"],
        "summary": "Open a PDF for online text editing",
        "description": "Opens the Eformly PDF editor with the Edit Text tool front and center. The user can click any existing text in the PDF to rewrite it in place (matching the original size, color, and position), plus fill form fields, add checkmarks, sign, and download the edited PDF. Same editor as /quick-fill. No account is required. This is a browser URL, not a JSON API — direct users to this URL.",
        "parameters": [
          {
            "name": "pdfUrl",
            "in": "query",
            "required": false,
            "description": "A publicly accessible HTTPS URL pointing to a PDF file. Must use HTTPS protocol. PDF must be under 10MB and publicly accessible without authentication. Always URL-encode this value.",
            "schema": {
              "type": "string",
              "format": "uri",
              "example": "https://example.com/contract.pdf"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTML page — the PDF editor loaded in the browser."
          }
        }
      }
    },
    "/chrome-extension": {
      "get": {
        "operationId": "openChromeExtensionPage",
        "tags": ["quick-fill"],
        "summary": "Chrome extension for filling PDFs found while browsing",
        "description": "Landing page for the free Eformly Chrome extension. Once installed, users can open any PDF they encounter on the web in the Eformly editor: click the toolbar icon on a PDF tab, click the badge shown when hovering a PDF link, or use the right-click context menu. The extension collects no browsing data. This is a browser URL, not a JSON API — direct users to this URL to install the extension.",
        "responses": {
          "200": {
            "description": "HTML page — Chrome extension landing page with install link."
          }
        }
      }
    },
    "/q/{shareableId}": {
      "get": {
        "operationId": "openSharedSession",
        "tags": ["quick-fill"],
        "summary": "Open a shared Quick Fill session",
        "description": "Opens a shared Quick Fill session by its shareable ID. Recipients can view and continue filling the PDF. May be passcode-protected.",
        "parameters": [
          {
            "name": "shareableId",
            "in": "path",
            "required": true,
            "description": "Short shareable ID of the Quick Fill session.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTML page — the shared Quick Fill session."
          }
        }
      }
    },
    "/api/quick-fill/sessions": {
      "post": {
        "operationId": "createQuickFillSession",
        "tags": ["quick-fill"],
        "summary": "Create a new Quick Fill session",
        "description": "Creates a new anonymous Quick Fill session. Returns a session ID and shareable URL.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pdfUrl": {
                    "type": "string",
                    "format": "uri",
                    "description": "Publicly accessible HTTPS URL to the PDF."
                  },
                  "filename": {
                    "type": "string",
                    "description": "Optional custom filename."
                  }
                },
                "required": ["pdfUrl"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string" },
                    "shareableId": { "type": "string" },
                    "shareableUrl": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/standalone-forms/public/{slug}": {
      "get": {
        "operationId": "getPublicStandaloneForm",
        "tags": ["standalone-forms"],
        "summary": "Get a published standalone form",
        "description": "Returns the schema and configuration of a published standalone form (survey, quiz, or general form) by its slug. No authentication required.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The URL slug of the published form.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Form schema and configuration.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string" },
                    "slug": { "type": "string" },
                    "title": { "type": "string" },
                    "description": { "type": "string" },
                    "questions": { "type": "array", "items": { "type": "object" } },
                    "theme": { "type": "object" }
                  }
                }
              }
            }
          },
          "404": { "description": "Form not found or not published." }
        }
      }
    },
    "/api/standalone-forms/{id}/submit": {
      "post": {
        "operationId": "submitStandaloneForm",
        "tags": ["standalone-forms"],
        "summary": "Submit a standalone form response",
        "description": "Submit a response to a published standalone form. No authentication required.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The form ID.",
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "answers": {
                    "type": "object",
                    "description": "Map of question ID to answer value.",
                    "additionalProperties": true
                  }
                },
                "required": ["answers"]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Submission recorded successfully." },
          "400": { "description": "Validation error." },
          "429": { "description": "Submission limit reached." }
        }
      }
    },
    "/api/tools/pdf-to-word": {
      "post": {
        "operationId": "convertPdfToWord",
        "tags": ["tools"],
        "summary": "Convert a PDF to a Word document",
        "description": "Converts a PDF file to an editable Word (.docx) document.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "The PDF file to convert."
                  }
                },
                "required": ["file"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Word document returned.",
            "content": {
              "application/vnd.openxmlformats-officedocument.wordprocessingml.document": {
                "schema": { "type": "string", "format": "binary" }
              }
            }
          }
        }
      }
    },
    "/api/contact": {
      "post": {
        "operationId": "submitContactForm",
        "tags": ["tools"],
        "summary": "Send a contact message",
        "description": "Submit a contact request to the Eformly team.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string" },
                  "email": { "type": "string", "format": "email" },
                  "message": { "type": "string" }
                },
                "required": ["name", "email", "message"]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Message sent." }
        }
      }
    }
  },
  "x-tools": [
    {
      "name": "open_pdf_for_filling",
      "description": "Opens any publicly accessible PDF for online filling, signing, and downloading in the browser. No account required. Use when the user wants to fill a PDF, sign a document, or complete a form online without downloading software. Returns a URL the user can click.",
      "parameters": {
        "type": "object",
        "properties": {
          "pdf_url": {
            "type": "string",
            "description": "The publicly accessible HTTPS URL of the PDF to fill. Must start with https://."
          },
          "filename": {
            "type": "string",
            "description": "Optional custom name for the completed PDF download."
          }
        },
        "required": ["pdf_url"]
      },
      "returns": {
        "type": "object",
        "properties": {
          "fill_url": {
            "type": "string",
            "description": "The Eformly Quick Fill URL to open in the browser."
          }
        }
      },
      "implementation": "Construct: https://eformly.app/quick-fill?pdfUrl=<URL-encoded pdf_url>&filename=<filename if provided>"
    },
    {
      "name": "edit_pdf_text",
      "description": "Opens any publicly accessible PDF in a free online editor where the user can click existing text to rewrite it in place, plus fill, sign, and download. No account required. Use when the user wants to edit, change, or fix text inside a PDF. Returns a URL the user can click.",
      "parameters": {
        "type": "object",
        "properties": {
          "pdf_url": {
            "type": "string",
            "description": "The publicly accessible HTTPS URL of the PDF to edit. Must start with https://. Optional — without it the user can upload a file in the browser."
          }
        },
        "required": []
      },
      "returns": {
        "type": "object",
        "properties": {
          "edit_url": {
            "type": "string",
            "description": "The Eformly Edit PDF URL to open in the browser."
          }
        }
      },
      "implementation": "Construct: https://eformly.app/edit-pdf?pdfUrl=<URL-encoded pdf_url> (or https://eformly.app/edit-pdf with no parameters)"
    }
  ]
}