{"success": true, "name": "DOCUMENTS_API", "content": "# EscalateFlow Documents (shared PDFs) \u2014 API & MCP Reference\n\n> Put a PDF (guide, catalogue, menu, price list, lead magnet) online at a link on the website, optionally behind an\n> email form, and see who read it: views, unique readers, downloads, time per page, how far people got.\n\n## Public links (on the website's own domain)\n\n```\nhttps://<site domain>/public/docs/<slug>/            \u2192 viewer (works on phones; pages render as you scroll)\nhttps://<site domain>/public/docs/<slug>/download/   \u2192 download (counted); only when allow_download is true\n```\n\nLink to it from any page, button, email or social post. Readers are measured by the viewer itself (time on each page\nwhile the tab is visible), so bots don't count. With `require_email: true` the reader first leaves an email; the\nemails appear in the document's statistics and CSV export.\n\n## REST API\n\n```\nGET    /api/v1/projects/{project_id}/documents/                 \u2192 list (+ views/downloads of the last 30 days, plan limits, usage)\nPOST   /api/v1/projects/{project_id}/documents/                 \u2192 upload\nGET    /api/v1/projects/{project_id}/documents/{doc_id}/?days=30 \u2192 document + reading statistics (days: 7, 30, 90, 365)\nPATCH  /api/v1/projects/{project_id}/documents/{doc_id}/        \u2192 edit settings\nDELETE /api/v1/projects/{project_id}/documents/{doc_id}/        \u2192 delete (link stops working, statistics removed)\nPOST   /api/v1/projects/{project_id}/documents/{doc_id}/file/   \u2192 replace the file (same link, same statistics)\n```\n\n**Upload** (`POST .../documents/` and `.../file/`), one of:\n- multipart/form-data with a `file` field (up to the plan limit, max 95 MB);\n- JSON `{\"url\": \"https://.../file.pdf\"}` \u2014 EscalateFlow downloads it (public http(s) URLs only);\n- JSON `{\"file_base64\": \"...\", \"filename\": \"menu.pdf\"}` \u2014 up to 25 MB (MCP: 7 MB; use `url` for bigger files).\n\n**Settings** (on upload or PATCH): `title` (default: from the file name), `slug` (lowercase letters, numbers,\ndashes; unique per website), `description`, `allow_download` (default true), `require_email` (default false),\n`is_published` (default true; false = the link answers 404 without deleting anything).\n\n**Response**: `{\"document\": {\"id\", \"title\", \"slug\", \"public_url\", \"download_url\", \"page_count\", \"file_size\",\n\"allow_download\", \"require_email\", \"is_published\", ...}}`.\n\n**Statistics** (`GET .../documents/{doc_id}/`): `views`, `unique_readers`, `downloads`, `emails`, `avg_read_seconds`,\n`avg_pages_read`, `completion_rate` (% of readers who reached the last page), `pages` (for each page: `readers` who\nreached it and `avg_seconds` on it \u2014 shows where people stop reading), `series` (views and downloads per day),\n`referrers` (referring site, or `utm: <source>` for campaign links), `countries`, `devices`, `recent` (latest readers,\nwith the email when the document asks for it).\n\n## Limits (per account, by plan)\n\n| Plan | Documents | Max size per PDF |\n|---|---|---|\n| Free | 5 | 20 MB |\n| Starter | 50 | 50 MB |\n| Growth | 250 | 95 MB |\n| Scale | 1,000 | 95 MB |\n| Enterprise | 9,999 | 95 MB |\n\nDocuments and media share the plan's storage (`max_storage_mb`). Errors say which limit was reached.\n\n## What is refused (security)\n\nOnly plain PDFs are accepted; the bytes are checked, not the file name. Refused: anything that is not a PDF (HTML,\nimages, executables, ZIPs, a PDF with other data glued to it), encrypted / password-protected PDFs, and PDFs with\nactive content: JavaScript, launch actions, embedded files/attachments, XFA forms, rich media, form submission or\nlinks that open other files (also when hidden in compressed object streams). Fix: export the document again as a\nplain PDF (\"Print to PDF\" / \"Save as PDF\").\n\n## MCP tool `documents`\n\n| Tool | Does |\n|---|---|\n| `escalateflow_documents_upload` | `url` (preferred) or `file_base64`, plus the settings above \u2192 document with `public_url` |\n| `escalateflow_documents_list` | documents with 30-day views/downloads, plan limits and usage |\n| `escalateflow_documents_get` | `document_id`, `days` \u2192 document + statistics |\n| `escalateflow_documents_update` | `document_id` + settings |\n| `escalateflow_documents_replace` | `document_id` + `url` or `file_base64` |\n| `escalateflow_documents_delete` | `document_id` |\n\nExample \u2014 a lead magnet:\n1. `escalateflow_documents_upload` with `url`, `title: \"Gu\u00eda de masa madre\"`, `require_email: true`.\n2. Add a button to the home page linking to the returned `public_url`.\n3. Later, `escalateflow_documents_get` to see how many people left their email and on which page they stop reading.\n", "format": "markdown", "data": {"name": "DOCUMENTS_API", "content": "# EscalateFlow Documents (shared PDFs) \u2014 API & MCP Reference\n\n> Put a PDF (guide, catalogue, menu, price list, lead magnet) online at a link on the website, optionally behind an\n> email form, and see who read it: views, unique readers, downloads, time per page, how far people got.\n\n## Public links (on the website's own domain)\n\n```\nhttps://<site domain>/public/docs/<slug>/            \u2192 viewer (works on phones; pages render as you scroll)\nhttps://<site domain>/public/docs/<slug>/download/   \u2192 download (counted); only when allow_download is true\n```\n\nLink to it from any page, button, email or social post. Readers are measured by the viewer itself (time on each page\nwhile the tab is visible), so bots don't count. With `require_email: true` the reader first leaves an email; the\nemails appear in the document's statistics and CSV export.\n\n## REST API\n\n```\nGET    /api/v1/projects/{project_id}/documents/                 \u2192 list (+ views/downloads of the last 30 days, plan limits, usage)\nPOST   /api/v1/projects/{project_id}/documents/                 \u2192 upload\nGET    /api/v1/projects/{project_id}/documents/{doc_id}/?days=30 \u2192 document + reading statistics (days: 7, 30, 90, 365)\nPATCH  /api/v1/projects/{project_id}/documents/{doc_id}/        \u2192 edit settings\nDELETE /api/v1/projects/{project_id}/documents/{doc_id}/        \u2192 delete (link stops working, statistics removed)\nPOST   /api/v1/projects/{project_id}/documents/{doc_id}/file/   \u2192 replace the file (same link, same statistics)\n```\n\n**Upload** (`POST .../documents/` and `.../file/`), one of:\n- multipart/form-data with a `file` field (up to the plan limit, max 95 MB);\n- JSON `{\"url\": \"https://.../file.pdf\"}` \u2014 EscalateFlow downloads it (public http(s) URLs only);\n- JSON `{\"file_base64\": \"...\", \"filename\": \"menu.pdf\"}` \u2014 up to 25 MB (MCP: 7 MB; use `url` for bigger files).\n\n**Settings** (on upload or PATCH): `title` (default: from the file name), `slug` (lowercase letters, numbers,\ndashes; unique per website), `description`, `allow_download` (default true), `require_email` (default false),\n`is_published` (default true; false = the link answers 404 without deleting anything).\n\n**Response**: `{\"document\": {\"id\", \"title\", \"slug\", \"public_url\", \"download_url\", \"page_count\", \"file_size\",\n\"allow_download\", \"require_email\", \"is_published\", ...}}`.\n\n**Statistics** (`GET .../documents/{doc_id}/`): `views`, `unique_readers`, `downloads`, `emails`, `avg_read_seconds`,\n`avg_pages_read`, `completion_rate` (% of readers who reached the last page), `pages` (for each page: `readers` who\nreached it and `avg_seconds` on it \u2014 shows where people stop reading), `series` (views and downloads per day),\n`referrers` (referring site, or `utm: <source>` for campaign links), `countries`, `devices`, `recent` (latest readers,\nwith the email when the document asks for it).\n\n## Limits (per account, by plan)\n\n| Plan | Documents | Max size per PDF |\n|---|---|---|\n| Free | 5 | 20 MB |\n| Starter | 50 | 50 MB |\n| Growth | 250 | 95 MB |\n| Scale | 1,000 | 95 MB |\n| Enterprise | 9,999 | 95 MB |\n\nDocuments and media share the plan's storage (`max_storage_mb`). Errors say which limit was reached.\n\n## What is refused (security)\n\nOnly plain PDFs are accepted; the bytes are checked, not the file name. Refused: anything that is not a PDF (HTML,\nimages, executables, ZIPs, a PDF with other data glued to it), encrypted / password-protected PDFs, and PDFs with\nactive content: JavaScript, launch actions, embedded files/attachments, XFA forms, rich media, form submission or\nlinks that open other files (also when hidden in compressed object streams). Fix: export the document again as a\nplain PDF (\"Print to PDF\" / \"Save as PDF\").\n\n## MCP tool `documents`\n\n| Tool | Does |\n|---|---|\n| `escalateflow_documents_upload` | `url` (preferred) or `file_base64`, plus the settings above \u2192 document with `public_url` |\n| `escalateflow_documents_list` | documents with 30-day views/downloads, plan limits and usage |\n| `escalateflow_documents_get` | `document_id`, `days` \u2192 document + statistics |\n| `escalateflow_documents_update` | `document_id` + settings |\n| `escalateflow_documents_replace` | `document_id` + `url` or `file_base64` |\n| `escalateflow_documents_delete` | `document_id` |\n\nExample \u2014 a lead magnet:\n1. `escalateflow_documents_upload` with `url`, `title: \"Gu\u00eda de masa madre\"`, `require_email: true`.\n2. Add a button to the home page linking to the returned `public_url`.\n3. Later, `escalateflow_documents_get` to see how many people left their email and on which page they stop reading.\n", "format": "markdown"}, "meta": {"request_id": "e81102971492458c"}}