{ "openapi": "3.1.0", "info": { "title": "url2llm API draft", "version": "0.1.0-draft", "description": "Draft scrape request and response contract with simple JPEG screenshots. Not implemented by the current backend. No server is configured and requests must not be sent to the existing API." }, "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Scrape", "description": "Read a single public page." } ], "paths": { "/v1/scrape": { "post": { "operationId": "scrapePage", "tags": [ "Scrape" ], "summary": "Scrape a page", "description": "Draft contract. Select outputs with formats, shared browser settings with sharedParams, and optional output-specific settings. Caching is off by default. No branding output or provider-routing diagnostics.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScrapeRequest" }, "examples": { "markdown": { "summary": "Markdown", "value": { "url": "https://example.com", "formats": { "markdown": true } } }, "screenshot": { "summary": "Full-page screenshot", "value": { "url": "https://example.com", "formats": { "screenshot": true }, "screenshotParams": { "fullPage": true } } } } } } }, "responses": { "200": { "description": "Validated requested outputs. Partial success is possible only when explicitly requested; see is_partial and output_errors. Example credit values are illustrative, not a price quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScrapeResponse" }, "examples": { "complete": { "value": { "success": true, "request_id": "example-request", "data": { "metadata": { "source_url": "https://example.com", "final_url": "https://example.com", "status_code": 200, "credits_used": 0, "from_cache": false }, "markdown": "# Example Domain", "is_partial": false } } }, "partial": { "value": { "success": true, "request_id": "example-request", "data": { "metadata": { "source_url": "https://example.com", "final_url": "https://example.com", "status_code": 200, "credits_used": 0, "from_cache": false }, "markdown": "# Example Domain", "is_partial": true, "output_errors": { "screenshot": { "code": "CAPTURE_FAILED", "message": "The requested screenshot was not produced." } } } } } } } } }, "400": { "description": "Invalid or incompatible inputs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Insufficient credits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Permission or access policy denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid request shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; respect Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 0 } } } }, "502": { "description": "Requested content or outputs could not be produced.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Overall request deadline exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "url2llm API key with scrape scope." } }, "schemas": { "ScrapeFormats": { "type": "object", "additionalProperties": false, "properties": { "html": { "type": "boolean", "default": false }, "markdown": { "type": "boolean", "default": false }, "screenshot": { "type": "boolean", "default": false }, "images": { "type": "boolean", "default": false }, "bytes": { "type": "boolean", "default": false }, "parse": { "type": "boolean", "default": false }, "highlights": { "type": "boolean", "default": false }, "json": { "type": "boolean", "default": false }, "product": { "type": "boolean", "default": false }, "rawHtml": { "type": "boolean", "default": false }, "links": { "type": "boolean", "default": false }, "assets": { "type": "boolean", "default": false } }, "anyOf": [ { "required": [ "html" ], "properties": { "html": { "const": true } } }, { "required": [ "markdown" ], "properties": { "markdown": { "const": true } } }, { "required": [ "screenshot" ], "properties": { "screenshot": { "const": true } } }, { "required": [ "images" ], "properties": { "images": { "const": true } } }, { "required": [ "bytes" ], "properties": { "bytes": { "const": true } } }, { "required": [ "parse" ], "properties": { "parse": { "const": true } } }, { "required": [ "highlights" ], "properties": { "highlights": { "const": true } } }, { "required": [ "json" ], "properties": { "json": { "const": true } } }, { "required": [ "product" ], "properties": { "product": { "const": true } } }, { "required": [ "rawHtml" ], "properties": { "rawHtml": { "const": true } } }, { "required": [ "links" ], "properties": { "links": { "const": true } } }, { "required": [ "assets" ], "properties": { "assets": { "const": true } } } ] }, "ScrapeMarkdownParams": { "type": "object", "additionalProperties": false, "properties": { "includeLinks": { "type": "boolean", "default": true }, "includeImages": { "type": "boolean", "default": false }, "inlineImages": { "type": "string", "enum": [ "placeholder", "preserve" ] }, "sourcePreference": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "html-conversion", "markdown-direct" ] }, "default": [ "html-conversion", "markdown-direct" ] } }, "allOf": [ { "if": { "required": [ "inlineImages" ] }, "then": { "required": [ "includeImages" ], "properties": { "includeImages": { "const": true } } } }, { "if": { "required": [ "sourcePreference" ], "properties": { "sourcePreference": { "items": { "not": { "enum": [ "html-conversion" ] } } } } }, "then": { "properties": { "includeLinks": { "not": {} }, "includeImages": { "not": {} }, "inlineImages": { "not": {} } } } } ] }, "ScrapeScreenshotParams": { "type": "object", "additionalProperties": false, "properties": { "fullPage": { "type": "boolean", "default": false }, "quality": { "type": "integer", "minimum": 1, "maximum": 100, "default": 80 } }, "description": "JPEG screenshot. Viewport by default; fullPage captures the full page. Viewport dimensions belong in sharedParams.viewport." }, "ScrapeImageParams": { "type": "object", "additionalProperties": false, "properties": { "enrich": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "items": { "type": "string", "enum": [ "dimensions", "classification", "file" ] } }, "dedupe": { "type": "string", "enum": [ "none", "visual" ], "default": "none" } } }, "ScrapeParseParams": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "const": "custom", "default": "custom" }, "rules": { "$ref": "#/components/schemas/ScrapeParseRules" } }, "required": [ "rules" ] }, { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "const": "prebuilt" }, "parser": { "type": "string", "enum": [ "google-maps", "google-maps-reviews", "google-play", "google-play-reviews", "app-store", "app-store-reviews", "g2-reviews", "instagram-profile", "instagram-post", "instagram-feed", "tiktok-profile", "tiktok-video", "tiktok-feed", "tiktok-comments", "tiktok-followers", "tiktok-following", "tiktok-user-search", "emails", "phone-numbers", "links" ] }, "sort": { "type": "string", "enum": [ "newest", "oldest", "relevant", "highest", "lowest" ], "default": "newest" }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, "required": [ "type", "parser" ] } ] }, "ScrapeParseRules": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2048 }, { "type": "object", "properties": { "selector": { "type": "string", "minLength": 1, "maxLength": 2048 }, "type": { "type": "string", "enum": [ "item", "list" ] }, "output": { "anyOf": [ { "type": "string", "enum": [ "text", "html" ] }, { "type": "string", "pattern": "^@.*$" }, { "$ref": "#/components/schemas/ScrapeParseRules" } ] } }, "required": [ "selector" ], "additionalProperties": false } ] }, "minProperties": 1 }, "ScrapeHighlightsParams": { "type": "object", "additionalProperties": false, "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 2000 }, "maxCharacters": { "type": "integer", "minimum": 100, "maximum": 20000, "default": 4000 } }, "required": [ "query" ] }, "ScrapeJsonParams": { "type": "object", "additionalProperties": false, "properties": { "schema": { "type": "object", "additionalProperties": true }, "instructions": { "type": "string", "maxLength": 2000 } }, "required": [ "schema" ] }, "ScrapeProductParams": { "type": "object", "additionalProperties": false, "properties": { "dedupeImages": { "type": "boolean", "default": false } } }, "ScrapeSharedParams": { "type": "object", "additionalProperties": false, "properties": { "profile": { "$ref": "#/components/schemas/ScrapeProfile" }, "country": { "type": "string", "pattern": "^[A-Za-z]{2}$", "description": "Supported ISO country for network egress; omission does not imply a country or change languages." }, "headers": { "type": "object", "propertyNames": { "pattern": "^[!#$%&'*+.^_`|~0-9A-Za-z-]+$", "not": { "pattern": "^(?:[Hh][Oo][Ss][Tt]|[Cc][Oo][Nn][Tt][Ee][Nn][Tt]-[Ll][Ee][Nn][Gg][Tt][Hh]|[Cc][Oo][Nn][Nn][Ee][Cc][Tt][Ii][Oo][Nn]|[Kk][Ee][Ee][Pp]-[Aa][Ll][Ii][Vv][Ee]|[Pp][Rr][Oo][Xx][Yy]-[Aa][Uu][Tt][Hh][Ee][Nn][Tt][Ii][Cc][Aa][Tt][Ee]|[Pp][Rr][Oo][Xx][Yy]-[Aa][Uu][Tt][Hh][Oo][Rr][Ii][Zz][Aa][Tt][Ii][Oo][Nn]|[Pp][Rr][Oo][Xx][Yy]-[Cc][Oo][Nn][Nn][Ee][Cc][Tt][Ii][Oo][Nn]|[Tt][Ee]|[Tt][Rr][Aa][Ii][Ll][Ee][Rr]|[Tt][Rr][Aa][Nn][Ss][Ff][Ee][Rr]-[Ee][Nn][Cc][Oo][Dd][Ii][Nn][Gg]|[Uu][Pp][Gg][Rr][Aa][Dd][Ee]|[Ee][Xx][Pp][Ee][Cc][Tt])$" }, "maxLength": 256 }, "additionalProperties": { "type": "string", "maxLength": 8192, "pattern": "^[^\\r\\n]*$" }, "maxProperties": 50 }, "viewport": { "type": "object", "additionalProperties": false, "properties": { "width": { "type": "integer", "minimum": 240, "maximum": 7680 }, "height": { "type": "integer", "minimum": 240, "maximum": 4320 } }, "required": [ "width", "height" ], "description": "Shared viewport for navigation and screenshots; omit for desktop 1920x1080 or mobile 412x915." }, "theme": { "type": "string", "enum": [ "light", "dark" ] }, "dismissCookies": { "type": "boolean", "default": false }, "dismissPopups": { "type": "boolean", "default": false }, "actions": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "$ref": "#/components/schemas/ScrapeAction" } }, "waitFor": { "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 30000 }, { "type": "string", "pattern": "\\S", "maxLength": 2048 } ], "default": 0 }, "settleAnimations": { "type": "boolean", "default": false }, "mainContentOnly": { "type": "boolean", "default": true }, "includeSelectors": { "type": "array", "minItems": 1, "maxItems": 50, "uniqueItems": true, "items": { "type": "string", "pattern": "\\S", "maxLength": 2048 } }, "excludeSelectors": { "type": "array", "minItems": 1, "maxItems": 50, "uniqueItems": true, "items": { "type": "string", "pattern": "\\S", "maxLength": 2048 } }, "includeFrames": { "type": "boolean", "default": false }, "parsers": { "type": "object", "additionalProperties": false, "properties": { "pdf": { "$ref": "#/components/schemas/ScrapePdfOptions" } } }, "renderJs": { "type": "boolean", "default": true, "description": "Render with JavaScript by default. False selects the explicit HTTP path." }, "mobile": { "type": "boolean", "default": false, "description": "Mobile viewport, touch and user-agent emulation; does not request a mobile carrier IP." }, "blockAds": { "type": "boolean", "default": true, "description": "Existing resource filtering; separate from accepting cookie banners or dismissing popups." }, "languages": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 63 }, "minItems": 1, "maxItems": 10, "uniqueItems": true, "description": "Ordered BCP 47 language preferences, independent of country. Validate actual tags at runtime." } } }, "ScrapeProfile": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "const": "existing" }, "profileId": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "type", "profileId" ] }, { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "const": "new" }, "identifier": { "type": "string", "minLength": 1, "maxLength": 1024 }, "password": { "type": "string", "minLength": 1, "maxLength": 4096, "writeOnly": true }, "description": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "type", "identifier", "password" ] } ] }, "ScrapeAction": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "perform" ] }, "action": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "type", "action" ] }, { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "scroll" ] }, "direction": { "type": "string", "enum": [ "down", "up", "left", "right" ], "default": "down" }, "amount": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 100000 }, { "type": "string", "enum": [ "viewport", "max" ] } ], "default": "viewport" }, "selector": { "type": "string", "pattern": "\\S", "maxLength": 2000, "minLength": 1 }, "maxScrolls": { "type": "integer", "minimum": 1, "maximum": 50, "default": 1 } }, "required": [ "type" ] }, { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "wait" ] }, "milliseconds": { "type": "integer", "minimum": 0, "maximum": 30000 } }, "required": [ "type", "milliseconds" ] }, { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "waitFor" ] }, "selector": { "type": "string", "pattern": "\\S", "maxLength": 2048, "minLength": 1 } }, "required": [ "type", "selector" ] } ] }, "ScrapePdfOptions": { "type": "object", "additionalProperties": false, "properties": { "startPage": { "type": "integer", "minimum": 1 }, "endPage": { "type": "integer", "minimum": 1 }, "ocr": { "type": "string", "enum": [ "off", "auto" ], "default": "off" } } }, "ScrapeTimeout": { "type": "object", "properties": { "milliseconds": { "type": "integer", "minimum": 1, "maximum": 120000 }, "behavior": { "type": "string", "enum": [ "fail", "return-partial" ], "default": "fail" } }, "required": [ "milliseconds" ], "additionalProperties": false, "allOf": [ { "if": { "required": [ "behavior" ], "properties": { "behavior": { "const": "return-partial" } } }, "then": { "properties": { "milliseconds": { "minimum": 5000 } } } } ] }, "RequestTags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 50 }, "maxItems": 20 }, "ScrapeRequest": { "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https?://" }, "formats": { "$ref": "#/components/schemas/ScrapeFormats" }, "markdownParams": { "$ref": "#/components/schemas/ScrapeMarkdownParams" }, "screenshotParams": { "$ref": "#/components/schemas/ScrapeScreenshotParams" }, "imageParams": { "$ref": "#/components/schemas/ScrapeImageParams" }, "parseParams": { "$ref": "#/components/schemas/ScrapeParseParams" }, "highlightsParams": { "$ref": "#/components/schemas/ScrapeHighlightsParams" }, "jsonParams": { "$ref": "#/components/schemas/ScrapeJsonParams" }, "productParams": { "$ref": "#/components/schemas/ScrapeProductParams" }, "sharedParams": { "$ref": "#/components/schemas/ScrapeSharedParams" }, "maxAgeMs": { "type": "integer", "minimum": 0, "maximum": 31536000000, "default": 0 }, "zdr": { "type": "string", "enum": [ "enabled", "disabled" ], "default": "disabled" }, "timeoutOpts": { "$ref": "#/components/schemas/ScrapeTimeout", "default": { "milliseconds": 30000, "behavior": "fail" } }, "tags": { "$ref": "#/components/schemas/RequestTags" }, "storeInCache": { "type": "boolean", "default": false } }, "required": [ "url", "formats" ], "allOf": [ { "if": { "required": [ "markdownParams" ] }, "then": { "properties": { "formats": { "required": [ "markdown" ], "properties": { "markdown": { "const": true } } } } } }, { "if": { "required": [ "screenshotParams" ] }, "then": { "properties": { "formats": { "required": [ "screenshot" ], "properties": { "screenshot": { "const": true } } } } } }, { "if": { "required": [ "imageParams" ] }, "then": { "properties": { "formats": { "required": [ "images" ], "properties": { "images": { "const": true } } } } } }, { "if": { "required": [ "parseParams" ] }, "then": { "properties": { "formats": { "required": [ "parse" ], "properties": { "parse": { "const": true } } } } } }, { "if": { "properties": { "formats": { "required": [ "parse" ], "properties": { "parse": { "const": true } } } } }, "then": { "required": [ "parseParams" ] } }, { "if": { "required": [ "highlightsParams" ] }, "then": { "properties": { "formats": { "required": [ "highlights" ], "properties": { "highlights": { "const": true } } } } } }, { "if": { "properties": { "formats": { "required": [ "highlights" ], "properties": { "highlights": { "const": true } } } } }, "then": { "required": [ "highlightsParams" ] } }, { "if": { "required": [ "jsonParams" ] }, "then": { "properties": { "formats": { "required": [ "json" ], "properties": { "json": { "const": true } } } } } }, { "if": { "properties": { "formats": { "required": [ "json" ], "properties": { "json": { "const": true } } } } }, "then": { "required": [ "jsonParams" ] } }, { "if": { "required": [ "productParams" ] }, "then": { "properties": { "formats": { "required": [ "product" ], "properties": { "product": { "const": true } } } } } }, { "if": { "required": [ "sharedParams" ], "properties": { "sharedParams": { "anyOf": [ { "required": [ "actions" ] }, { "required": [ "profile" ] }, { "required": [ "headers" ] } ] } } }, "then": { "properties": { "maxAgeMs": { "const": 0 }, "storeInCache": { "const": false } } } }, { "if": { "required": [ "sharedParams" ], "properties": { "sharedParams": { "required": [ "profile" ] } } }, "then": { "properties": { "url": { "pattern": "^https://" }, "zdr": { "const": "disabled" }, "formats": { "properties": { "bytes": { "const": false } } }, "sharedParams": { "not": { "required": [ "headers" ] } } } } }, { "if": { "required": [ "zdr" ], "properties": { "zdr": { "const": "enabled" } } }, "then": { "properties": { "maxAgeMs": { "const": 0 }, "storeInCache": { "const": false }, "sharedParams": { "not": { "required": [ "profile" ] } } } } }, { "if": { "required": [ "sharedParams" ], "properties": { "sharedParams": { "required": [ "renderJs" ], "properties": { "renderJs": { "const": false } } } } }, "then": { "properties": { "formats": { "properties": { "screenshot": { "const": false }, "assets": { "const": false } } }, "sharedParams": { "properties": { "waitFor": { "const": 0 }, "includeFrames": { "const": false }, "dismissCookies": { "const": false }, "dismissPopups": { "const": false }, "settleAnimations": { "const": false } }, "not": { "anyOf": [ { "required": [ "actions" ] }, { "required": [ "profile" ] }, { "required": [ "viewport" ] }, { "required": [ "theme" ] } ] } } } } } ], "title": "url2llm proposed scrape request", "description": "Draft scrape request with shared browser settings and output-specific options. Not the live endpoint schema.", "x-status": "proposed", "examples": [ { "url": "https://example.com", "formats": { "markdown": true } }, { "url": "https://example.com", "formats": { "screenshot": true } }, { "url": "https://example.com", "formats": { "markdown": true, "screenshot": true }, "screenshotParams": { "fullPage": true }, "sharedParams": { "languages": [ "de-DE" ], "country": "DE" } }, { "url": "https://example.com", "formats": { "json": true }, "jsonParams": { "schema": { "type": "object", "properties": { "title": { "type": "string" } } } } } ] }, "AssetMetadata": { "description": "What is known about one asset beyond its URL. Keys differ by asset_type.", "properties": { "width": { "default": 0, "title": "Width", "type": "integer" }, "height": { "default": 0, "title": "Height", "type": "integer" }, "alt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Images only", "title": "Alt" }, "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Videos only: html5, youtube or vimeo", "title": "Provider" }, "poster_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "html5 video only", "title": "Poster Url" } }, "title": "AssetMetadata", "type": "object" }, "BrandAsset": { "description": "One image or video the page references, as produced by render.assets.", "properties": { "url": { "title": "Url", "type": "string" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Derived from the title or alt text", "title": "Filename" }, "title": { "default": "", "title": "Title", "type": "string" }, "asset_type": { "description": "image or video", "title": "Asset Type", "type": "string" }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Images only: page or product_gallery", "title": "Context" }, "mimetype": { "title": "Mimetype", "type": "string" }, "metadata": { "$ref": "#/components/schemas/AssetMetadata" } }, "required": [ "url", "asset_type", "mimetype" ], "title": "BrandAsset", "type": "object" }, "Link": { "description": "One anchor on the page, as produced by render.links.", "properties": { "url": { "title": "Url", "type": "string" }, "normalized_url": { "title": "Normalized Url", "type": "string" }, "type": { "title": "Type", "type": "string" }, "text": { "default": "", "title": "Text", "type": "string" }, "title": { "default": "", "title": "Title", "type": "string" }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Image Url" }, "internal": { "default": false, "title": "Internal", "type": "boolean" } }, "required": [ "url", "normalized_url", "type" ], "title": "Link", "type": "object" }, "ScrapeMetadata": { "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Title" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Author" }, "published_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Published At" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Language" }, "source_url": { "title": "Source Url", "type": "string" }, "final_url": { "title": "Final Url", "type": "string" }, "status_code": { "title": "Status Code", "type": "integer" }, "from_cache": { "default": false, "title": "From Cache", "type": "boolean" }, "credits_used": { "default": 0, "description": "Credits this request charged. Zero on a re-read or an unbilled failure", "title": "Credits Used", "type": "integer", "minimum": 0 } }, "required": [ "source_url", "final_url", "status_code", "credits_used", "from_cache" ], "title": "ScrapeMetadata", "type": "object" }, "ApiError": { "properties": { "code": { "title": "Code", "type": "string" }, "message": { "title": "Message", "type": "string" }, "details": { "anyOf": [ {}, { "type": "null" } ], "default": null, "title": "Details" } }, "required": [ "code", "message" ], "title": "ApiError", "type": "object" }, "ErrorResponse": { "properties": { "success": { "type": "boolean", "const": false }, "error": { "$ref": "#/components/schemas/ApiError" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Request Id" } }, "required": [ "success", "error" ], "title": "ErrorResult", "type": "object" }, "ScrapeImage": { "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "pattern": "^(https?://|data:image/)" }, "alt": { "type": [ "string", "null" ] }, "width": { "type": "integer", "minimum": 1 }, "height": { "type": "integer", "minimum": 1 }, "classification": { "type": "string", "enum": [ "photography", "illustration", "logo", "wordmark", "icon", "pattern", "graphic", "other" ] }, "fileUrl": { "type": "string", "format": "uri", "pattern": "^https?://" } }, "required": [ "url", "alt" ] }, "ScrapeProductResult": { "type": "object", "additionalProperties": false, "properties": { "isProductPage": { "type": "boolean" }, "product": { "oneOf": [ { "$ref": "#/components/schemas/ScrapeProduct" }, { "type": "null" } ] } }, "required": [ "isProductPage", "product" ] }, "ScrapeProduct": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "brand": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "null" ] }, "regularPrice": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "availability": { "type": [ "string", "null" ], "enum": [ "in_stock", "out_of_stock", "limited_availability", "preorder", "backorder", "made_to_order", "discontinued", null ] }, "category": { "type": [ "string", "null" ] }, "imageUrl": { "type": [ "string", "null" ], "format": "uri" }, "images": { "type": "array", "items": { "type": "string", "format": "uri" } }, "dimensions": { "type": "array", "items": { "type": "string" } }, "features": { "type": "array", "items": { "type": "string" } }, "targetAudience": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "variants": { "$ref": "#/components/schemas/ProductVariants" } }, "required": [ "name", "description", "brand", "sku", "price", "regularPrice", "currency", "availability", "category", "imageUrl", "images", "dimensions", "features", "targetAudience", "tags", "variants" ] }, "ProductVariants": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "attributes": { "type": "object", "additionalProperties": { "type": "string" } }, "url": { "type": [ "string", "null" ] }, "images": { "type": "array", "items": { "type": "string" } } }, "required": [ "sku", "attributes", "url", "images" ] } }, "OutputError": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } } }, "ScrapeResult": { "description": "Requested outputs only. In fail mode every requested output must validate. In return-partial mode return successful outputs and errors for failed outputs; if none succeed return an error response. Partial billing remains an activation gate.", "properties": { "metadata": { "$ref": "#/components/schemas/ScrapeMetadata" }, "markdown": { "type": "string", "title": "Markdown" }, "html": { "type": "string", "title": "Html" }, "raw_html": { "type": "string", "title": "Raw Html" }, "links": { "items": { "$ref": "#/components/schemas/Link" }, "type": "array", "title": "Links" }, "screenshot": { "type": "string", "format": "uri", "pattern": "^https://", "description": "URL of the JPEG screenshot. Artifact access and retention must be finalized before activation." }, "json": { "additionalProperties": true, "type": "object", "title": "Json" }, "assets": { "items": { "$ref": "#/components/schemas/BrandAsset" }, "type": "array", "title": "Assets" }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/ScrapeImage" } }, "bytes": { "type": "object", "additionalProperties": false, "properties": { "contentType": { "type": "string" }, "base64": { "type": "string", "contentEncoding": "base64", "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$" } }, "required": [ "contentType", "base64" ] }, "parsed": { "type": "object", "additionalProperties": true }, "highlights": { "type": "array", "items": { "type": "string" } }, "product": { "$ref": "#/components/schemas/ScrapeProductResult" }, "profile": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "description": "Present for new and existing profile requests; reuse id as sharedParams.profile.profileId. Omitted when no profile is requested." }, "is_partial": { "type": "boolean", "default": false, "description": "True only when at least one requested output succeeded and at least one failed in return-partial mode." }, "output_errors": { "type": "object", "propertyNames": { "enum": [ "assets", "bytes", "highlights", "html", "images", "json", "links", "markdown", "parsed", "product", "raw_html", "screenshot" ] }, "additionalProperties": { "$ref": "#/components/schemas/OutputError" }, "default": {} } }, "required": [ "metadata", "is_partial" ], "type": "object", "additionalProperties": false, "anyOf": [ { "required": [ "assets" ] }, { "required": [ "bytes" ] }, { "required": [ "highlights" ] }, { "required": [ "html" ] }, { "required": [ "images" ] }, { "required": [ "json" ] }, { "required": [ "links" ] }, { "required": [ "markdown" ] }, { "required": [ "parsed" ] }, { "required": [ "product" ] }, { "required": [ "raw_html" ] }, { "required": [ "screenshot" ] } ], "allOf": [ { "if": { "properties": { "is_partial": { "const": true } } }, "then": { "required": [ "output_errors" ], "properties": { "output_errors": { "minProperties": 1 } } }, "else": { "properties": { "output_errors": { "maxProperties": 0 } } } }, { "if": { "required": [ "output_errors" ], "properties": { "output_errors": { "required": [ "assets" ] } } }, "then": { "not": { "required": [ "assets" ] } } }, { "if": { "required": [ "output_errors" ], "properties": { "output_errors": { "required": [ "bytes" ] } } }, "then": { "not": { "required": [ "bytes" ] } } }, { "if": { "required": [ "output_errors" ], "properties": { "output_errors": { "required": [ "highlights" ] } } }, "then": { "not": { "required": [ "highlights" ] } } }, { "if": { "required": [ "output_errors" ], "properties": { "output_errors": { "required": [ "html" ] } } }, "then": { "not": { "required": [ "html" ] } } }, { "if": { "required": [ "output_errors" ], "properties": { "output_errors": { "required": [ "images" ] } } }, "then": { "not": { "required": [ "images" ] } } }, { "if": { "required": [ "output_errors" ], "properties": { "output_errors": { "required": [ "json" ] } } }, "then": { "not": { "required": [ "json" ] } } }, { "if": { "required": [ "output_errors" ], "properties": { "output_errors": { "required": [ "links" ] } } }, "then": { "not": { "required": [ "links" ] } } }, { "if": { "required": [ "output_errors" ], "properties": { "output_errors": { "required": [ "markdown" ] } } }, "then": { "not": { "required": [ "markdown" ] } } }, { "if": { "required": [ "output_errors" ], "properties": { "output_errors": { "required": [ "parsed" ] } } }, "then": { "not": { "required": [ "parsed" ] } } }, { "if": { "required": [ "output_errors" ], "properties": { "output_errors": { "required": [ "product" ] } } }, "then": { "not": { "required": [ "product" ] } } }, { "if": { "required": [ "output_errors" ], "properties": { "output_errors": { "required": [ "raw_html" ] } } }, "then": { "not": { "required": [ "raw_html" ] } } }, { "if": { "required": [ "output_errors" ], "properties": { "output_errors": { "required": [ "screenshot" ] } } }, "then": { "not": { "required": [ "screenshot" ] } } } ] }, "ScrapeResponse": { "type": "object", "additionalProperties": false, "required": [ "success", "data", "request_id" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/ScrapeResult" }, "request_id": { "type": "string", "minLength": 1 } } } } } }