{ "openapi": "3.0.1", "info": { "title": "HTML to JSON Smart Parser", "description": "Convert any HTML page, pasted HTML, or HTML file into clean structured JSON. Works without an API key via smart heuristics; optional AI mode for schema-driven extraction. Returns titles, headings, links, images, tables, emails, and custom fields.", "version": "1.0", "x-build-id": "n4S7c4j7iCk2CXlgD" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/muhammadafzal~html-to-json-smart-parser/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-muhammadafzal-html-to-json-smart-parser", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/muhammadafzal~html-to-json-smart-parser/runs": { "post": { "operationId": "runs-sync-muhammadafzal-html-to-json-smart-parser", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/muhammadafzal~html-to-json-smart-parser/run-sync": { "post": { "operationId": "run-sync-muhammadafzal-html-to-json-smart-parser", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "startUrls": { "title": "Page URLs", "type": "array", "description": "Web page URLs to fetch and parse into JSON. Use this when the user provides specific pages (products, articles, listings, documents). Each URL is fetched and parsed; one structured JSON record is returned per page. Leave empty if pasting HTML or uploading files.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "htmlContent": { "title": "HTML Content (Paste)", "type": "string", "description": "Raw HTML to convert to JSON, pasted directly into this field. Use this when the HTML is not publicly reachable (emails, local files, authenticated pages). Takes precedence over nothing — it is processed in addition to any URLs. Leave empty if using URLs or file URLs." }, "htmlFileUrls": { "title": "HTML File URLs", "type": "array", "description": "URLs of HTML files to fetch and parse (e.g., exported HTML archives or static files). You can upload files in the Apify Console using the file upload button, or provide direct download URLs. Leave empty if using page URLs or pasted HTML.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "fieldsToExtract": { "title": "Fields to Extract", "type": "string", "description": "Comma-separated list of custom fields to pull out of the HTML, e.g. 'title, price, author, availability'. Each field is extracted heuristically using common selectors (itemprop, meta tags, data attributes, class names). Leave empty to auto-detect all important fields. AI mode uses these names as the extraction contract.", "default": "" }, "outputSchema": { "title": "Output JSON Schema (AI Mode)", "type": "string", "description": "A JSON schema or sample object that the AI should return in AI mode, e.g. {\"title\": \"string\", \"price\": \"number\", \"inStock\": \"boolean\"}. Only used when mode is 'ai' or an OpenAI API key is provided. When set, the AI restructures the page into exactly this shape. Ignored in heuristic mode.", "default": "" }, "mode": { "title": "Extraction Mode", "enum": [ "auto", "heuristic", "ai" ], "type": "string", "description": "How to extract data. 'auto' uses AI when an OpenAI API key is provided, otherwise falls back to heuristics. 'heuristic' always uses the fast, free rule-based engine. 'ai' always calls the LLM to restructure the page into your fieldsToExtract or outputSchema.", "default": "auto" }, "openaiApiKey": { "title": "OpenAI API Key (Optional)", "type": "string", "description": "Your OpenAI API key, used only when mode is 'ai' or 'auto'. Without it, extraction is heuristic and free. Get a key at https://platform.openai.com/api-keys. The key is stored securely as a secret and never returned in results." }, "model": { "title": "AI Model", "enum": [ "gpt-4o-mini", "gpt-4o", "gpt-4-turbo", "gpt-4", "gpt-3.5-turbo" ], "type": "string", "description": "The OpenAI model used for AI-mode extraction. Defaults to gpt-4o-mini, the best cost/quality balance for HTML extraction. Use a stronger model (e.g. gpt-4o) for complex or ambiguous documents.", "default": "gpt-4o-mini" }, "systemPrompt": { "title": "System Prompt (Optional)", "type": "string", "description": "Custom instructions that override the default AI extraction prompt. Use to add domain rules (e.g. 'extract prices in EUR only', 'normalize dates to YYYY-MM-DD'). Only used in AI mode. Leave empty to use the smart default prompt.", "default": "" }, "maxContentChars": { "title": "Max Content Characters (AI Mode)", "minimum": 1000, "maximum": 60000, "type": "integer", "description": "How much of the page text to send to the AI model in AI mode. Larger pages are truncated to this limit to control token cost. Heuristic mode ignores this.", "default": 20000 }, "maxResults": { "title": "Max Results", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Maximum number of JSON records to produce across all sources (cost control). One record is produced per URL, pasted HTML block, or HTML file.", "default": 100 }, "proxyConfiguration": { "title": "Proxy Configuration", "type": "object", "description": "Proxy settings for fetching page and file URLs. Datacenter proxy is enabled by default; switch to residential for sites that block datacenter IPs. Not used for pasted HTML content.", "default": { "useApifyProxy": true } } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } }