{ "openapi": "3.1.1", "info": { "title": "sample-pdf.com API", "description": "REST API for generating and downloading PDF files. Supports custom-size PDF generation (1 KB – 50 MB), HTML-to-PDF conversion via headless Chrome, and pre-built sample file downloads. Compatible with ChatGPT Actions.", "contact": { "name": "sample-pdf.com", "url": "https://sample-pdf.com" }, "version": "v1" }, "servers": [ { "url": "http://sample-pdf.com/" } ], "paths": { "/api/generate-pdf": { "post": { "tags": [ "PdfApi" ], "summary": "Generate a PDF file of a specified size.", "description": "Generates a valid PDF document padded to the requested size.\nThe file contains sample content. Minimum 1 KB, maximum 51200 KB (50 MB).", "requestBody": { "description": "Target size in kilobytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneratePdfRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/GeneratePdfRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/GeneratePdfRequest" } } }, "required": true }, "responses": { "200": { "description": "Returns the generated PDF binary.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/FileContentResult" } }, "application/json": { "schema": { "$ref": "#/components/schemas/FileContentResult" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FileContentResult" } } } }, "400": { "description": "Invalid request body.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/html-to-pdf": { "post": { "tags": [ "PdfApi" ], "summary": "Convert an HTML string to a PDF file.", "description": "Accepts raw HTML, sanitizes it (scripts and event handlers are removed),\nrenders it using a headless Chrome browser, and returns the resulting PDF.\nSupports inline CSS, <style> blocks, and base64-encoded images.", "requestBody": { "description": "HTML string to convert.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HtmlToPdfApiRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/HtmlToPdfApiRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/HtmlToPdfApiRequest" } } }, "required": true }, "responses": { "200": { "description": "Returns the converted PDF binary.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/FileContentResult" } }, "application/json": { "schema": { "$ref": "#/components/schemas/FileContentResult" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FileContentResult" } } } }, "400": { "description": "HTML content is missing or empty.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Chrome browser not found or conversion failed.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/sample/{size}": { "get": { "tags": [ "PdfApi" ], "summary": "Download a pre-generated sample PDF file.", "description": "Returns one of four pre-built sample PDF files generated at application startup.\nValid size values: `10kb`, `1mb`, `10mb`, `20mb`.", "parameters": [ { "name": "size", "in": "path", "description": "Size identifier: 10kb, 1mb, 10mb, or 20mb.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the requested sample PDF binary.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/FileContentResult" } }, "application/json": { "schema": { "$ref": "#/components/schemas/FileContentResult" } }, "text/json": { "schema": { "$ref": "#/components/schemas/FileContentResult" } } } }, "400": { "description": "Invalid size identifier.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Sample file not found on disk.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/health": { "get": { "tags": [ "PdfApi" ], "summary": "Health check — reports Chrome browser status and environment.", "description": "Returns diagnostic information useful for debugging conversion failures on the server:\nOS, PUPPETEER_EXECUTABLE_PATH value, resolved Chrome path, and whether the browser is running.", "responses": { "200": { "description": "Diagnostics object.", "content": { "application/json": { } } } } } }, "/api/pdf-to-markdown": { "post": { "tags": [ "PdfApi" ], "summary": "Convert a PDF file to Markdown text.", "description": "Upload a PDF file (multipart/form-data). The service extracts text using PdfPig,\ndetects headings (H1/H2/H3) based on relative font size, and separates pages with `---`.\nReturns a plain Markdown string (text/markdown). Maximum file size: 20 MB.", "requestBody": { "description": "The PDF file to convert.", "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "$ref": "#/components/schemas/IFormFile" } } } } }, "required": true }, "responses": { "200": { "description": "Returns the Markdown string.", "content": { "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "No file uploaded, wrong format, or file too large.", "content": { "text/markdown": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Conversion failed.", "content": { "text/markdown": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } } }, "components": { "schemas": { "EntityTagHeaderValue": { "type": "object", "properties": { "tag": { "$ref": "#/components/schemas/StringSegment" }, "isWeak": { "type": "boolean" } } }, "FileContentResult": { "type": "object", "properties": { "fileContents": { "type": "string", "format": "byte" }, "contentType": { "type": [ "null", "string" ] }, "fileDownloadName": { "type": [ "null", "string" ] }, "lastModified": { "type": [ "null", "string" ], "format": "date-time" }, "entityTag": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EntityTagHeaderValue" } ] }, "enableRangeProcessing": { "type": "boolean" } } }, "GeneratePdfRequest": { "type": "object", "properties": { "sizeKb": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Target size of the generated PDF in kilobytes. Min: 1, Max: 51200 (50 MB).", "format": "int32", "example": 1024 } }, "description": "Request body for `POST /api/generate-pdf`." }, "HtmlToPdfApiRequest": { "type": "object", "properties": { "html": { "type": "string", "description": "Raw HTML string to convert to PDF. Will be sanitized before conversion (scripts removed).\nSupports inline CSS, <style> blocks, and base64-encoded images.", "example": "<h1>Hello World</h1><p style=\"color:red\">Sample paragraph.</p>" } }, "description": "Request body for `POST /api/html-to-pdf`." }, "IFormFile": { "type": "string", "format": "binary" }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": [ "null", "string" ] }, "title": { "type": [ "null", "string" ] }, "status": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "detail": { "type": [ "null", "string" ] }, "instance": { "type": [ "null", "string" ] } } }, "StringSegment": { "type": "object", "properties": { "buffer": { "type": [ "null", "string" ] }, "offset": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "length": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "value": { "type": [ "null", "string" ] }, "hasValue": { "type": "boolean" } } } } }, "tags": [ { "name": "PdfApi" } ] }