{ "openapi": "3.1.0", "info": { "title": "Web2MD: web pages to clean Markdown for AI apps", "version": "0.1.0", "description": "Turn any web page into clean Markdown, plain text, or heading-aware, token-counted chunks ready for RAG and LLM apps." }, "paths": { "/v1/read": { "post": { "summary": "Fetch a URL and return its main content", "operationId": "Read Page", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadRequest" }, "example": { "format": "markdown", "url": "https://en.wikipedia.org/wiki/Markdown" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "summary": "Fetch a URL and return its main content (query-string form)", "operationId": "Read Page (GET)", "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 2048, "title": "Url" }, "example": "https://en.wikipedia.org/wiki/Markdown" }, { "name": "format", "in": "query", "required": false, "schema": { "enum": [ "markdown", "text", "json" ], "type": "string", "default": "markdown", "title": "Format" } }, { "name": "include_links", "in": "query", "required": false, "schema": { "type": "boolean", "default": true, "title": "Include Links" } }, { "name": "include_images", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Images" } }, { "name": "include_tables", "in": "query", "required": false, "schema": { "type": "boolean", "default": true, "title": "Include Tables" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/convert": { "post": { "summary": "Convert HTML you already have (nothing is fetched)", "operationId": "Convert HTML", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertRequest" }, "example": { "format": "markdown", "html": "

Hello

Web2MD turns this HTML into clean Markdown for AI apps.

", "url": "https://example.com/post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/chunks": { "post": { "summary": "Split a page into heading-aware, token-bounded chunks for RAG", "operationId": "Chunk Page", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChunksRequest" }, "example": { "max_tokens": 512, "overlap_tokens": 50, "url": "https://en.wikipedia.org/wiki/Markdown" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChunksOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/metadata": { "post": { "summary": "Title, author, date, language, canonical URL, image and word count", "operationId": "Page Metadata", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataRequest" }, "example": { "url": "https://en.wikipedia.org/wiki/Markdown" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "ChunkOut": { "properties": { "id": { "type": "integer", "title": "Id" }, "heading_path": { "items": { "type": "string" }, "type": "array", "title": "Heading Path" }, "text": { "type": "string", "title": "Text" }, "tokens": { "type": "integer", "title": "Tokens" } }, "type": "object", "required": [ "id", "heading_path", "text", "tokens" ], "title": "ChunkOut" }, "ChunksOut": { "properties": { "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lang" }, "published": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Published" }, "chunks": { "items": { "$ref": "#/components/schemas/ChunkOut" }, "type": "array", "title": "Chunks" }, "total_tokens": { "type": "integer", "title": "Total Tokens" }, "cached": { "type": "boolean", "title": "Cached" } }, "type": "object", "required": [ "chunks", "total_tokens", "cached" ], "title": "ChunksOut" }, "ChunksRequest": { "properties": { "include_links": { "type": "boolean", "title": "Include Links", "description": "Keep links as [text](absolute-url).", "default": true }, "include_images": { "type": "boolean", "title": "Include Images", "description": "Keep images as ![alt](absolute-url).", "default": false }, "include_tables": { "type": "boolean", "title": "Include Tables", "description": "Keep tables as Markdown tables.", "default": true }, "url": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "title": "Url", "examples": [ "https://en.wikipedia.org/wiki/Markdown" ] }, "html": { "anyOf": [ { "type": "string", "maxLength": 5000000 }, { "type": "null" } ], "title": "Html" }, "max_tokens": { "type": "integer", "maximum": 8192.0, "minimum": 64.0, "title": "Max Tokens", "default": 512 }, "overlap_tokens": { "type": "integer", "maximum": 1024.0, "minimum": 0.0, "title": "Overlap Tokens", "default": 50 } }, "type": "object", "title": "ChunksRequest", "examples": [ { "max_tokens": 512, "overlap_tokens": 50, "url": "https://en.wikipedia.org/wiki/Markdown" } ] }, "ConvertRequest": { "properties": { "include_links": { "type": "boolean", "title": "Include Links", "description": "Keep links as [text](absolute-url).", "default": true }, "include_images": { "type": "boolean", "title": "Include Images", "description": "Keep images as ![alt](absolute-url).", "default": false }, "include_tables": { "type": "boolean", "title": "Include Tables", "description": "Keep tables as Markdown tables.", "default": true }, "html": { "type": "string", "maxLength": 5000000, "minLength": 1, "title": "Html" }, "url": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "title": "Url", "description": "Base URL for relative links. Never fetched." }, "format": { "type": "string", "enum": [ "markdown", "text", "json" ], "title": "Format", "default": "markdown" } }, "type": "object", "required": [ "html" ], "title": "ConvertRequest", "examples": [ { "format": "markdown", "html": "

Hello

Web2MD turns this HTML into clean Markdown for AI apps.

", "url": "https://example.com/post" } ] }, "DocumentOut": { "properties": { "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "format": { "type": "string", "enum": [ "markdown", "text", "json" ], "title": "Format" }, "markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Markdown" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text" }, "metadata": { "$ref": "#/components/schemas/MetadataOut" }, "word_count": { "type": "integer", "title": "Word Count" }, "tokens": { "type": "integer", "title": "Tokens" }, "cached": { "type": "boolean", "title": "Cached" }, "rendered": { "type": "boolean", "title": "Rendered" } }, "type": "object", "required": [ "format", "metadata", "word_count", "tokens", "cached", "rendered" ], "title": "DocumentOut" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "MetadataOut": { "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author" }, "published": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Published" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "site_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Site Name" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "canonical_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Canonical Url" }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Image" }, "word_count": { "type": "integer", "title": "Word Count" }, "reading_time_min": { "type": "integer", "title": "Reading Time Min" } }, "type": "object", "required": [ "word_count", "reading_time_min" ], "title": "MetadataOut" }, "MetadataRequest": { "properties": { "url": { "type": "string", "maxLength": 2048, "title": "Url", "examples": [ "https://en.wikipedia.org/wiki/Markdown" ] } }, "type": "object", "required": [ "url" ], "title": "MetadataRequest", "examples": [ { "url": "https://en.wikipedia.org/wiki/Markdown" } ] }, "MetadataResponse": { "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author" }, "published": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Published" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "site_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Site Name" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" }, "canonical_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Canonical Url" }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Image" }, "word_count": { "type": "integer", "title": "Word Count" }, "reading_time_min": { "type": "integer", "title": "Reading Time Min" }, "url": { "type": "string", "title": "Url" }, "cached": { "type": "boolean", "title": "Cached" } }, "type": "object", "required": [ "word_count", "reading_time_min", "url", "cached" ], "title": "MetadataResponse" }, "ReadRequest": { "properties": { "include_links": { "type": "boolean", "title": "Include Links", "description": "Keep links as [text](absolute-url).", "default": true }, "include_images": { "type": "boolean", "title": "Include Images", "description": "Keep images as ![alt](absolute-url).", "default": false }, "include_tables": { "type": "boolean", "title": "Include Tables", "description": "Keep tables as Markdown tables.", "default": true }, "url": { "type": "string", "maxLength": 2048, "title": "Url", "examples": [ "https://en.wikipedia.org/wiki/Markdown" ] }, "format": { "type": "string", "enum": [ "markdown", "text", "json" ], "title": "Format", "description": "markdown, text, or json (both).", "default": "markdown" } }, "type": "object", "required": [ "url" ], "title": "ReadRequest", "examples": [ { "format": "markdown", "url": "https://en.wikipedia.org/wiki/Markdown" } ] }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } }