{ "openapi": "3.1.1", "info": { "title": "gugudata.io API", "version": "1.0.0", "description": "Official OpenAPI definition for the public gugudata.io API endpoints." }, "servers": [ { "url": "https://api.gugudata.io", "description": "Production API server" } ], "paths": { "/ai/knowledge-bases/{knowledge_base_id}/chat/completions": { "post": { "operationId": "postKnowledgeChat", "tags": [ "ai" ], "summary": "AI RAG Knowledge Base Chat API", "description": "Answer questions from private documents with source citations. Clients send the complete message history on each request; thread_id is a correlation identifier and does not restore server-side history.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.", "schema": { "type": "string", "default": "YOUR_APPKEY" } }, { "name": "knowledge_base_id", "in": "path", "required": true, "description": "Knowledge base identifier in the URL path", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "default": "default" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeChatCompletion" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/KnowledgeChatStream" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "502": { "$ref": "#/components/responses/Http502" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeChatRequest" } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/ai/knowledge-bases/{knowledge_base_id}/documents": { "post": { "operationId": "postKnowledgeChat1", "tags": [ "ai" ], "summary": "Upload Knowledge Base Documents", "description": "Upload documents and build a private knowledge base.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" } }, { "name": "knowledge_base_id", "in": "path", "required": true, "description": "Knowledge base identifier; default may be used", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeUploadResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "413": { "$ref": "#/components/responses/Http413" }, "422": { "$ref": "#/components/responses/Http422" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "502": { "$ref": "#/components/responses/Http502" }, "503": { "$ref": "#/components/responses/Http503" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "PDF, TXT, Markdown, HTML, or DOCX documents; up to 5 files and 20 MB per file" }, "tenant_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "description": "Customer-defined business grouping; defaults to default" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Customer-defined metadata as a JSON object, up to 8 KiB" }, "replace_existing": { "type": "boolean", "description": "Replace an existing document with the same name when true" } }, "required": [ "files" ] } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/ai/knowledge-bases/{knowledge_base_id}/documents/{document_id}": { "delete": { "operationId": "deleteKnowledgeBaseDocument", "tags": [ "ai" ], "summary": "Delete a Knowledge Base Document", "description": "Delete one document and its indexed content from a private knowledge base.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication.", "schema": { "type": "string" } }, { "name": "knowledge_base_id", "in": "path", "required": true, "description": "Knowledge base identifier.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" } }, { "name": "document_id", "in": "path", "required": true, "description": "Document identifier returned by the upload operation.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" } }, { "name": "tenant_id", "in": "query", "required": false, "description": "Customer-defined tenant grouping used during upload.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "default": "default" } } ], "responses": { "204": { "description": "Document deleted successfully." }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "404": { "$ref": "#/components/responses/Http404" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/article/extract": { "post": { "operationId": "postArticleExtract", "tags": [ "websitetools" ], "summary": "Article Extractor", "description": "Turn a public article URL or raw HTML document into a structured content record with the title, description, author, publication date, readable body, links, images, source, and estimated reading time. Ideal for research ingestion, monitoring, archiving, and editorial automation.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleExtractSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]?://", "maxLength": 2048, "description": "Public HTTP or HTTPS article URL." }, "parserOptions": { "$ref": "#/components/schemas/ArticleParserOptions" }, "fetchOptions": { "$ref": "#/components/schemas/ArticleFetchOptions" } }, "additionalProperties": false, "required": [ "url" ] } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/article/extractFromHtml": { "post": { "operationId": "postArticleExtractFromHtml", "tags": [ "websitetools" ], "summary": "Extract Article from HTML", "description": "Extract article content and metadata from a raw HTML document. An optional public source URL can be supplied to resolve relative links and identify the source.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleExtractSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "422": { "description": "The supplied HTML does not contain extractable article content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "html": { "type": "string", "minLength": 1, "description": "Raw HTML document. The service enforces a 10 MiB UTF-8 payload limit." }, "url": { "type": "string", "format": "uri", "pattern": "^https?://", "maxLength": 2048, "description": "Optional public HTTP or HTTPS source URL." }, "parserOptions": { "$ref": "#/components/schemas/ArticleParserOptions" } }, "additionalProperties": false, "required": [ "html" ] } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/barcode": { "post": { "operationId": "postBarcode", "tags": [ "qrcode_barcode" ], "summary": "General Barcode Generation", "description": "Generate scan-ready one-dimensional barcode images across 40 retail, logistics, postal, publishing, and pharmaceutical symbologies. Configure output dimensions and receive a reusable HTTPS image URL for labels, documents, inventory, and fulfillment workflows.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BarcodeSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "One-dimensional barcode symbology.", "default": "CODE128", "enum": [ "UPCA", "UPCE", "UPCSupplemental2Digit", "UPCSupplemental5Digit", "EAN13", "EAN8", "Interleaved2Of5", "Interleaved2Of5Mod10", "Standard2Of5", "Standard2Of5Mod10", "Industrial2Of5", "Industrial2Of5Mod10", "Code39", "Code39Extended", "Code39Mod43", "Codabar", "PostNet", "Bookland", "ISBN", "JAN13", "MsiMod10", "Msi2Mod10", "MsiMod11", "MsiMod11Mod10", "ModifiedPlessey", "Code11", "Usd8", "Code32", "Ucc12", "Ucc13", "Logmars", "Code128", "Code128A", "Code128B", "Code128C", "Itf14", "Code93", "Telepen", "Fim", "Pharmacode" ] }, "content": { "type": "string", "description": "Primary text content processed by the endpoint.", "default": "123456789012", "minLength": 1, "maxLength": 512 }, "width": { "type": "integer", "format": "int32", "description": "Output width in pixels. Use 1 only for legacy default sizing.", "oneOf": [ { "const": 1 }, { "minimum": 64, "maximum": 2048 } ], "default": 290 }, "height": { "type": "integer", "format": "int32", "description": "Output height in pixels. Use 1 only for legacy default sizing.", "oneOf": [ { "const": 1 }, { "minimum": 32, "maximum": 2048 } ], "default": 120 } }, "required": [ "type", "content", "width", "height" ] } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/barcode/qrcode/decode": { "post": { "operationId": "postQrcodeDecode", "tags": [ "qrcode_barcode" ], "summary": "Decode QR Code from Image", "description": "Read one QR code from an uploaded image or public image URL. Select the first decodable code in top-to-bottom, then left-to-right order. Text is returned unchanged; decoded links are not visited.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key supplied in the query string.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrDecodeSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "413": { "description": "Image exceeds size or pixel limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid, unsupported or undecodable image.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "502": { "description": "Image download or decoding failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "$ref": "#/components/responses/Http503" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "PNG, JPEG, static WebP or BMP: up to 10 MiB, 8192 pixels per side and 16 million pixels." }, "file_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Public HTTP(S) image URL; mutually exclusive with file.", "pattern": "^https?://" } }, "oneOf": [ { "required": [ "file" ], "not": { "required": [ "file_url" ] } }, { "required": [ "file_url" ], "not": { "required": [ "file" ] } } ] } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/education/us/institutions/search": { "get": { "operationId": "getUsCollegeInstitutions", "tags": [ "metadata" ], "summary": "US College Institutions Data API", "description": "Search US colleges by name, location, ownership and degree level. Results use business code 100 and include the matching total, including beyond the last page. Text filters use NFKC normalization, trimming and a 100-character limit; control characters are rejected. This reference dataset is not a real-time admissions or tuition guarantee.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Required application key in the query string.", "schema": { "type": "string", "default": "YOUR_APPKEY" } }, { "name": "name", "in": "query", "required": false, "description": "Name filter used by the endpoint dataset.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "state", "in": "query", "required": false, "description": "US state abbreviation, such as CA or MA", "schema": { "type": "string", "maxLength": 100 } }, { "name": "city", "in": "query", "required": false, "description": "City filter used by the endpoint dataset.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "ownership", "in": "query", "required": false, "description": "Ownership filter, such as public or private", "schema": { "type": "string", "maxLength": 100 } }, { "name": "degreeLevel", "in": "query", "required": false, "description": "Degree level keyword", "schema": { "type": "string", "maxLength": 100 } }, { "name": "minAdmissionRate", "in": "query", "required": false, "description": "Minimum admission rate", "schema": { "type": "number", "format": "double", "minimum": 0, "maximum": 1 } }, { "name": "maxTuition", "in": "query", "required": false, "description": "Maximum in-state tuition", "schema": { "type": "number", "format": "double", "minimum": 0 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort expression in the format documented by the endpoint.", "schema": { "type": "string", "default": "institutionName|asc", "maxLength": 100 } }, { "name": "pageIndex", "in": "query", "required": false, "description": "Default 1; values below 1 use 1 for compatibility.", "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "Default 10; values below 1 use 10, values above 100 use 100.", "schema": { "type": "integer", "format": "int32", "default": 10 } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstitutionSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/education/us/programs/search": { "get": { "operationId": "getUsCollegePrograms", "tags": [ "metadata" ], "summary": "US College Programs Data API", "description": "Search US college programs by keyword, CIP prefix, state and credential level, with optional earnings and debt filters. Business code 100 denotes success. Empty pages retain the matching total. Text uses NFKC normalization and trimming with a 100-character limit and no controls. Reference figures are not an employment, earnings or financial-aid guarantee.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Required application key in query.", "schema": { "type": "string", "default": "YOUR_APPKEY" } }, { "name": "keyword", "in": "query", "required": false, "description": "Keyword for program, CIP title, or institution name", "schema": { "type": "string", "maxLength": 100 } }, { "name": "cipCode", "in": "query", "required": false, "description": "Numeric CIP prefix or code: 1-6 digits, or two digits followed by a dot and 0-4 digits. Empty means no filter.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "state", "in": "query", "required": false, "description": "US state abbreviation", "schema": { "type": "string", "maxLength": 100 } }, { "name": "credentialLevel", "in": "query", "required": false, "description": "Credential level keyword", "schema": { "type": "string", "maxLength": 100 } }, { "name": "minEarnings", "in": "query", "required": false, "description": "Minimum median earnings", "schema": { "type": "number", "format": "double", "minimum": 0 } }, { "name": "maxDebt", "in": "query", "required": false, "description": "Maximum median debt", "schema": { "type": "number", "format": "double", "minimum": 0 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort expression in the format documented by the endpoint.", "schema": { "type": "string", "default": "institutionName|asc", "maxLength": 100 } }, { "name": "pageIndex", "in": "query", "required": false, "description": "Default 1; values below 1 use 1 for compatibility.", "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "Default 10; values below 1 use 10, values above 100 use 100.", "schema": { "type": "integer", "format": "int32", "default": 10 } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/image/image-compress": { "post": { "operationId": "postImageCompress", "tags": [ "imagerecognition" ], "summary": "Image Compression", "description": "Compress and optionally resize a JPEG, PNG, or WebP upload or public image URL, then return optimized image bytes in the selected format. Reduce storage and delivery costs, standardize media dimensions, and prepare images for websites, apps, archives, and content pipelines.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Compressed image binary. The response MIME type and filename extension identify the selected output format.", "headers": { "Content-Disposition": { "description": "Safe attachment filename for the compressed image.", "schema": { "type": "string", "example": "attachment; filename=\"compressed-image.jpg\"" } } }, "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "422": { "$ref": "#/components/responses/Http422" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "502": { "$ref": "#/components/responses/Http502" }, "503": { "$ref": "#/components/responses/Http503" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ImageCompressMultipartRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ImageCompressUrlRequest" } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/imagerecognition/html2pdf": { "post": { "operationId": "postHtml2pdf", "tags": [ "imagerecognition" ], "summary": "HTML/URL to PDF", "description": "Convert raw HTML or a public webpage into an A4 PDF in portrait or landscape orientation and receive a downloadable HTTPS file. Generate invoices, receipts, reports, archives, approvals, and print-ready documents from application content.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HtmlToPdfSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "422": { "description": "The supplied HTML or URL could not be rendered as a PDF.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/Http429" }, "502": { "description": "The PDF rendering provider timed out or was temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The PDF rendering or storage capability is not configured or temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "html", "url" ], "description": "Input mode. Values are case-insensitive.", "example": "html" }, "content": { "type": "string", "description": "HTML content up to 5 MiB when type is html, or a complete public HTTP/HTTPS URL up to 2048 characters when type is url.", "example": "

Quarterly report

Prepared for review.

" }, "landscape": { "type": "integer", "format": "int32", "enum": [ 0, 1 ], "description": "Set to 1 for landscape orientation or 0 for portrait orientation.", "default": 0, "example": 0 } }, "required": [ "type", "content" ] } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/imagerecognition/html2word": { "post": { "operationId": "postHtml2word", "tags": [ "imagerecognition" ], "summary": "Convert HTML to Word", "description": "Convert raw HTML or a public webpage into an editable DOCX document that preserves readable headings, paragraphs, lists, tables, links, and supported images. Build exports for reports, archives, CMS workflows, publishing, and business document automation.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HtmlToWordSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "422": { "$ref": "#/components/responses/Http422" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "502": { "$ref": "#/components/responses/Http502" }, "503": { "$ref": "#/components/responses/Http503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HtmlToWordRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/HtmlToWordRequest" } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/imagerecognition/markdown2pdf": { "post": { "operationId": "postMarkdown2pdf", "tags": [ "imagerecognition" ], "summary": "Markdown to PDF Converter", "description": "Convert Markdown into a downloadable PDF while preserving headings, paragraphs, lists, tables, quotations, links, and code blocks for reports, documentation, handouts, and archives.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Markdown converted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkdownToPdfSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "422": { "$ref": "#/components/responses/MarkdownToPdfHttp422" }, "429": { "$ref": "#/components/responses/Http429" }, "503": { "$ref": "#/components/responses/Http503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkdownToPdfRequest" } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/imagerecognition/ocr": { "post": { "operationId": "postOcr", "tags": [ "imagerecognition" ], "summary": "Image OCR Extraction API", "description": "Extract English text from JPEG, PNG, WebP, TIFF, and BMP images up to 10 MiB. Receive recognized lines and joined plain text for document intake, searchable archives, data entry, indexing, and automation workflows.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OcrSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "413": { "description": "The uploaded image exceeds the 10 MiB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "The uploaded file is not a supported image type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "$ref": "#/components/responses/Http422" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "502": { "$ref": "#/components/responses/Http502" }, "503": { "$ref": "#/components/responses/Http503" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "imagefile": { "type": "string", "format": "binary", "description": "A JPEG, PNG, WebP, TIFF, or BMP image no larger than 10 MiB." } }, "required": [ "imagefile" ] } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/imagerecognition/ocr2word": { "post": { "operationId": "postOcr2word", "tags": [ "imagerecognition" ], "summary": "Image OCR to Word API", "description": "Convert English text in JPEG, PNG, WebP, TIFF, or BMP images into downloadable Word documents for review, editing, document intake, and archive workflows.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "A Word document was generated from recognized image text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OcrToWordSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "413": { "$ref": "#/components/responses/Http413" }, "415": { "description": "The uploaded file is not a supported JPEG, PNG, WebP, TIFF, or BMP image.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "$ref": "#/components/responses/Http422" }, "429": { "$ref": "#/components/responses/Http429" }, "502": { "$ref": "#/components/responses/Http502" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "imagefile": { "type": "string", "format": "binary", "description": "JPEG, PNG, WebP, TIFF, or BMP image. Maximum size: 10 MiB. Maximum dimensions: 8,192 pixels per side and 40 million pixels total." }, "filename": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Optional safe output name. The .docx extension is appended when omitted, and whitespace is normalized to hyphens.", "default": "ocr-result.docx", "example": "receipt-notes.docx" } }, "required": [ "imagefile" ] } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/imagerecognition/pdf-splitter": { "post": { "operationId": "postPdfSplitter", "tags": [ "imagerecognition" ], "summary": "PDF Splitting", "description": "Split a PDF into page-based files, return individual files or a ZIP, and optionally keep the output private.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfSplitterSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "413": { "$ref": "#/components/responses/Http413" }, "422": { "$ref": "#/components/responses/Http422" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "502": { "$ref": "#/components/responses/Http502" }, "503": { "$ref": "#/components/responses/Http503" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "page_size": { "type": "integer", "format": "int32", "description": "Number of pages per split output file.", "minimum": 1, "maximum": 100, "default": 100 }, "is_zip": { "type": "boolean", "description": "Whether the split PDF output should be packaged as a ZIP archive.", "default": true }, "file": { "type": "string", "format": "binary", "description": "PDF upload, up to 20 MiB and 100 pages. Use either file or file_url." }, "file_url": { "type": "string", "format": "uri", "pattern": "^https?://", "maxLength": 2048, "description": "Public HTTP or HTTPS PDF URL. Use either file_url or file." }, "storage": { "type": "string", "enum": ["public", "private"], "default": "public", "description": "Public returns download URLs. Private returns file references for the signing operation." } }, "oneOf": [ { "required": ["file"] }, { "required": ["file_url"] } ] } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/private-files/{file_id}:sign": { "post": { "operationId": "signPrivateFile", "tags": ["imagerecognition"], "summary": "Create a private file download link", "description": "Create a short-lived HTTPS download URL for a private file owned by the authenticated account.", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "appkey", "in": "query", "required": true, "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivateFileSignRequest" } } } }, "responses": { "200": { "description": "A short-lived download URL was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivateFileSignSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "404": { "$ref": "#/components/responses/Http404" }, "429": { "$ref": "#/components/responses/Http429" }, "503": { "$ref": "#/components/responses/Http503" } }, "security": [{ "AppKeyAuth": [] }] } }, "/v1/imagerecognition/pdf-summary": { "post": { "operationId": "postPdfSummary", "tags": [ "imagerecognition" ], "summary": "PDF AI Summary", "description": "Upload a PDF and receive a concise AI-generated summary in your chosen language. Turn reports, research papers, manuals, and long-form documents into faster briefings for support, operations, study, and knowledge workflows.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Local file uploaded as multipart form data." }, "lang": { "type": "string", "description": "Language code used by the summarization workflow.", "default": "en" } }, "required": [ "file" ] } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/imagerecognition/pdf2format": { "post": { "operationId": "postPdf2format", "tags": [ "imagerecognition" ], "summary": "PDF Parsing and Formatted Output", "description": "Extract readable PDF text as HTML, plain text, Markdown, or a JSON string. Up to 20 MiB and 100 pages. No OCR, image extraction, or layout reconstruction.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Readable PDF content converted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfFormatSuccessResponse" } } } }, "400": { "description": "Invalid parameters or restricted URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "413": { "description": "PDF exceeds 20 MiB or 100 pages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid, encrypted, unreadable PDF or output exceeds 20 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "502": { "description": "Remote download failed or conversion response invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Conversion service temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PdfFormatRequest" } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/imagerecognition/pdf2html": { "post": { "operationId": "postPdf2html", "tags": [ "imagerecognition" ], "summary": "Convert PDF to HTML", "description": "Convert PDF text into a public UTF-8 HTML download. Preserves page order and line breaks, not images, complex layouts, or OCR.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key supplied as a query parameter.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfHtmlSuccessResponse" } } } }, "400": { "description": "Invalid parameters; business code 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfHtmlErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "413": { "description": "PDF exceeds 20 MiB or 100 pages; business code 500.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfHtmlErrorResponse" } } } }, "422": { "description": "Invalid, encrypted or textless PDF, or output exceeds 20 MiB; business code 500.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfHtmlErrorResponse" } } } }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "502": { "description": "Remote PDF retrieval or conversion response failed; business code 500.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfHtmlErrorResponse" } } } }, "503": { "description": "Conversion or storage is temporarily unavailable; business code 500.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfHtmlErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PdfHtmlRequest" } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/imagerecognition/pdf2text": { "post": { "operationId": "postPdf2text", "tags": [ "imagerecognition" ], "summary": "PDF OCR to Text API", "description": "Extract searchable text from scanned PDFs. Returns page-ordered text and combined text. English is the default; Chinese and mixed-language options are available. Recognition depends on scan quality.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key supplied as a query parameter.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfOcrSuccessResponse" } } } }, "400": { "description": "Invalid input; business code 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfOcrErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "413": { "description": "PDF exceeds 20 MiB or 50 pages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfOcrErrorResponse" } } } }, "422": { "description": "Invalid, encrypted, unreadable PDF or rendering limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfOcrErrorResponse" } } } }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "502": { "description": "Download, OCR timeout or invalid conversion response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfOcrErrorResponse" } } } }, "503": { "description": "OCR capacity or service unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfOcrErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PdfOcrRequest" } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/imagerecognition/pdf2word": { "post": { "operationId": "postPdf2word", "tags": [ "imagerecognition" ], "summary": "PDF OCR to Word API", "description": "Turn scanned PDFs into editable Word documents. Choose English, Simplified Chinese, Traditional Chinese, or English with either Chinese option. Text follows source page order with page breaks and line breaks; blank page positions are preserved. Original layout, images, table structure, handwriting recognition, and identical Word pagination are not guaranteed. Upload at most 20 MiB and 50 pages. Entirely unrecognizable documents fail explicitly.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key supplied as a query parameter.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfWordSuccessResponse" } } } }, "400": { "description": "Invalid input, language, or output filename.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfWordErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "413": { "description": "PDF exceeds 20 MiB or 50 pages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfWordErrorResponse" } } } }, "422": { "description": "Invalid, encrypted, unrecognizable PDF, excessive rendering size, or invalid Word output.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfWordErrorResponse" } } } }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "502": { "description": "Remote download, processing timeout, or invalid conversion response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfWordErrorResponse" } } } }, "503": { "description": "Conversion or storage is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfWordErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PdfWordRequest" } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/imagerecognition/ppt-to-images": { "post": { "operationId": "postPpt2images", "tags": [ "imagerecognition" ], "summary": "Convert PPT to Images", "description": "Convert PPT/PPTX slides into ordered static PNG images. Maximum 20 MiB and 50 slides; animations and transitions are not preserved.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key supplied in the query string.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PptImagesSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" }, "413": { "description": "Presentation exceeds 20 MiB or 50 slides.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PptImagesErrorResponse" } } } }, "422": { "description": "Invalid, encrypted, unsupported presentation or excessive rendering/output size.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PptImagesErrorResponse" } } } }, "502": { "description": "Remote download, processing timeout, or invalid conversion response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PptImagesErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PptImagesRequest" } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/imagerecognition/ppt-to-pdf": { "post": { "operationId": "postPpt2pdf", "tags": [ "imagerecognition" ], "summary": "Convert PPT to PDF", "description": "Convert PPT/PPTX slides into a static PDF. Hidden slides are excluded by default; blank selected slides retain their position. Layout may vary with fonts and complex effects.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key. Send only in the query string.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PptPdfSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "413": { "description": "Input exceeds 20 MiB or 50 source slides.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid, encrypted, unsupported or unrenderable presentation; no selected slides or PDF exceeds 20 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "502": { "description": "Download failed, conversion timed out, or invalid conversion response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "$ref": "#/components/responses/Http503" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "PPT or PPTX; maximum 20 MiB and 50 slides including hidden slides." }, "file_url": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^[Hh][Tt][Tt][Pp][Ss]?://", "description": "Public HTTP(S) presentation URL; provide instead of file." }, "include_hidden_slides": { "type": "boolean", "default": false, "description": "Export hidden slides as well as visible slides." } }, "oneOf": [ { "required": [ "file" ], "not": { "required": [ "file_url" ] } }, { "required": [ "file_url" ], "not": { "required": [ "file" ] } } ] } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/imagerecognition/word-to-html": { "post": { "operationId": "postWord2html", "tags": [ "imagerecognition" ], "summary": "Convert Word to HTML", "description": "Convert DOC or DOCX files up to 20 MiB into readable HTML with embedded images. Complex layout may differ. Active content is not retained. Result links are public; save files you need to keep.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key supplied in the query string.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WordHtmlSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "413": { "description": "Word file exceeds 20 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid, encrypted or unsupported document, or HTML output exceeds limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "502": { "description": "Conversion timed out or returned an invalid response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Conversion capacity or storage is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "DOC or DOCX document, maximum 20 MiB. Encrypted or damaged files are rejected." } }, "required": [ "file" ] } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/location/coordinateconverter": { "get": { "operationId": "getCoordinateconverter", "tags": [ "websitetools" ], "summary": "Geographic Coordinate System Converter", "description": "Convert longitude and latitude pairs between WGS84, GCJ-02, and BD-09 with a consistent coordinate response. Normalize location data across international maps, China map providers, geocoding, navigation, and mobility workflows.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.", "schema": { "type": "string", "default": "YOUR_APPKEY" } }, { "name": "from", "in": "query", "required": true, "description": "Source coordinate system. Supported values are `WGS84`, `GCJ02`, and `BD09`.", "schema": { "type": "string", "enum": [ "WGS84", "GCJ02", "BD09" ], "example": "WGS84" } }, { "name": "to", "in": "query", "required": true, "description": "Target coordinate system. Supported values are `WGS84`, `GCJ02`, and `BD09`.", "schema": { "type": "string", "enum": [ "WGS84", "GCJ02", "BD09" ], "example": "GCJ02" } }, { "name": "value", "in": "query", "required": true, "description": "Coordinate pair in `[longitude,latitude]` format, for example `[120.54,32.74]`.", "schema": { "type": "string", "example": "[120.54,32.74]" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoordinateConverterSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/location/ip": { "get": { "operationId": "getLocationIp", "tags": [ "websitetools" ], "summary": "IP Geolocation and Log Enrichment API", "description": "Look up IP geolocation metadata for log enrichment, security review, dashboards, and network analysis workflows.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.", "schema": { "type": "string", "default": "YOUR_APPKEY" } }, { "name": "ip", "in": "query", "required": true, "description": "Public IPv4 or IPv6 address to look up. Private, loopback, link-local, reserved, multicast, and hostname inputs are rejected.", "schema": { "type": "string", "maxLength": 45, "examples": [ "8.8.8.8", "2001:4860:4860::8888" ] } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IpLocationSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/metadata/global-university": { "get": { "operationId": "getGlobalUniversity", "tags": [ "metadata" ], "summary": "Global University Data", "description": "Query the global university dataset with filters for name, country, region, city, sorting, and pagination.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key supplied in the query string.", "schema": { "type": "string", "default": "YOUR_APPKEY" } }, { "name": "name", "in": "query", "required": false, "description": "Name filter used by the endpoint dataset.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "country", "in": "query", "required": false, "description": "Country filter used by the endpoint dataset.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "region", "in": "query", "required": false, "description": "Macro-region filter from the QS dataset, for example `North America`. For US state-level matching, omit `region` and use `country` with `city`.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "city", "in": "query", "required": false, "description": "City filter used by the endpoint dataset.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort expression in `field|direction` format, for example `rank|asc`.", "schema": { "type": "string", "default": "rank|asc", "maxLength": 100 } }, { "name": "pageIndex", "in": "query", "required": false, "description": "One-based page index for pagination.", "schema": { "type": "integer", "format": "int32", "default": 1, "minimum": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "Number of records returned per page. Zero uses the default; values above 20 are capped at 20.", "schema": { "type": "integer", "format": "int32", "default": 10, "minimum": 0 } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalUniversitySuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/metadata/qs-global-university-ranking": { "get": { "operationId": "getQsGlobalUniversityRanking", "tags": [ "metadata" ], "summary": "Global QS World University Rankings", "description": "Query the global QS university ranking dataset with name filtering and pagination support.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key supplied in the query string.", "schema": { "type": "string", "default": "YOUR_APPKEY" } }, { "name": "name", "in": "query", "required": false, "description": "Name filter used by the endpoint dataset.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "pageIndex", "in": "query", "required": false, "description": "One-based page index for pagination.", "schema": { "type": "integer", "format": "int32", "default": 1, "minimum": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "Number of records returned per page. Zero uses the default; values above 20 are capped at 20.", "schema": { "type": "integer", "format": "int32", "default": 10, "minimum": 0 } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalUniversityRankingSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/qrcode": { "post": { "operationId": "postQrcode", "tags": [ "qrcode_barcode" ], "summary": "Universal QR Code Generator", "description": "Create a PNG QR code from text or a URL, encoded exactly as supplied. Download and retain the public result file; permanent hosting is not guaranteed.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key supplied in the query string.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrCodeSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrCodeRequest" }, "example": { "content": "https://gugudata.io/", "size": 200 } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/shortLinks": { "post": { "operationId": "postShortlink", "tags": [ "websitetools" ], "summary": "Short Link API", "description": "Create short URLs on guguurl.com, manage destination URLs and expiration times, disable links when needed, and track total clicks through a simple REST API.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Paid application key supplied in the query string.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShortLinkSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "409": { "description": "The requested short-link ID is already in use.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}} }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "longUrl": { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]?://", "maxLength": 8192, "description": "Destination URL. Must use HTTP or HTTPS.", "default": "https://example.com/page" }, "shortLinkId": { "type": "string", "minLength": 4, "maxLength": 32, "pattern": "^[A-Za-z0-9_-]+$", "description": "Optional custom short link ID. Use 4 to 32 letters, numbers, underscores, or hyphens.", "default": "campaign01" }, "expireTime": { "type": "string", "format": "date-time", "description": "Optional expiration time.", "default": "2026-12-31T23:59:59Z" } }, "required": [ "longUrl" ] } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/shortLinks/{code}": { "parameters": [{ "name": "code", "in": "path", "required": true, "description": "Short-link ID.", "schema": {"type": "string", "minLength": 4, "maxLength": 32, "pattern": "^[A-Za-z0-9_-]+$"} }], "get": { "operationId": "getShortLink", "tags": ["websitetools"], "summary": "Get a Short Link", "description": "Read one short link owned by the paid AppKey account.", "parameters": [{"name": "appkey", "in": "query", "required": true, "schema": {"type": "string"}}], "responses": { "200": {"description": "Short link returned.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ShortLinkSuccessResponse"}}}}, "400": {"$ref": "#/components/responses/Http400"}, "401": {"$ref": "#/components/responses/Http401"}, "403": {"$ref": "#/components/responses/Http403"}, "404": {"description": "Short link not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, "429": {"$ref": "#/components/responses/Http429"}, "500": {"$ref": "#/components/responses/Http500"} }, "security": [{"AppKeyAuth": []}] }, "patch": { "operationId": "updateShortLink", "tags": ["websitetools"], "summary": "Update a Short Link", "description": "Change the destination, expiration time, or state of an owned short link.", "parameters": [{"name": "appkey", "in": "query", "required": true, "schema": {"type": "string"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "longUrl": {"type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]?://", "maxLength": 8192}, "expireTime": {"type": "string", "format": "date-time"}, "state": {"type": "string", "enum": ["ACTIVE", "DISABLED"]} } }}}}, "responses": { "200": {"description": "Short link updated.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ShortLinkSuccessResponse"}}}}, "400": {"$ref": "#/components/responses/Http400"}, "401": {"$ref": "#/components/responses/Http401"}, "403": {"$ref": "#/components/responses/Http403"}, "404": {"description": "Short link not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, "429": {"$ref": "#/components/responses/Http429"}, "500": {"$ref": "#/components/responses/Http500"} }, "security": [{"AppKeyAuth": []}] } }, "/v1/shortLinks/{code}:redirect": { "get": { "operationId": "redirectShortLink", "tags": ["websitetools"], "summary": "Redirect a Short Link", "description": "Redirect an active, unexpired short link and increment its total click count.", "parameters": [{ "name": "code", "in": "path", "required": true, "schema": {"type": "string", "minLength": 4, "maxLength": 32, "pattern": "^[A-Za-z0-9_-]+$"} }], "responses": { "302": {"description": "Redirect to the destination URL.", "headers": {"Location": {"schema": {"type": "string", "format": "uri"}}}}, "400": {"$ref": "#/components/responses/Http400"}, "404": {"description": "Short link not found.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, "410": {"description": "Short link is disabled or expired.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, "500": {"$ref": "#/components/responses/Http500"} } } }, "/v1/stock/hk/symbols": { "get": { "operationId": "getHkStockSymbols", "tags": [ "metadata" ], "summary": "HK Stock Symbols Directory", "description": "Search active Hong Kong-listed securities by five-digit symbol, exchange English short name, or Chinese display name. Add reliable security selectors, symbol validation, portfolio enrichment, and reference-data search with stable paginated results.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.", "schema": { "type": "string", "default": "YOUR_APPKEY" } }, { "name": "query", "in": "query", "required": false, "description": "Optional case-insensitive substring matched against the five-digit symbol, English short name, and Chinese display name. The service applies Unicode NFKC normalization and trims surrounding whitespace.", "schema": { "type": "string", "maxLength": 100, "examples": [ "00700" ] } }, { "name": "pageIndex", "in": "query", "required": false, "description": "One-based page index for pagination.", "schema": { "type": "integer", "format": "int32", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "Number of records returned per page. Omitted or zero uses 20; values above 20 are reduced to 20.", "schema": { "type": "integer", "format": "int32", "minimum": 0, "default": 20 } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HkStockSymbolsSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/stock/us/symbols": { "get": { "operationId": "getUsStockSymbols", "tags": [ "metadata" ], "summary": "US Stock Symbols Directory", "description": "Search active US stock symbols and company names with case-insensitive substring matching and symbol-ordered pages. Empty pages are successful. dataTotalCount is the matching dataset total, including when the requested page is beyond the last page. This directory does not provide live prices or trading eligibility.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key supplied in the query string.", "schema": { "type": "string", "default": "YOUR_APPKEY" } }, { "name": "query", "in": "query", "required": false, "description": "Optional substring, normalized with Unicode NFKC and trimmed. At most 100 Unicode code points; no control characters. Empty input lists all active records.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "pageIndex", "in": "query", "required": false, "description": "One-based page index for pagination.", "schema": { "type": "integer", "format": "int32", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "Results per page. Missing or zero uses 20; 1-20 is preserved; values above 20 use 20. Negative values fail.", "schema": { "type": "integer", "format": "int32", "minimum": 0, "default": 20 } } ], "responses": { "200": { "description": "Successful directory lookup, preserving business statusCode 100.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsStockSymbolsSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/text/chinese-poem": { "get": { "operationId": "getChinesepoem", "tags": [ "metadata" ], "summary": "Chinese Classical Poetry Database", "description": "Search nearly 400,000 works of Chinese classical poetry, including Tang poems, Song poems, and Song lyrics, by title, author, or content. Build literature search, education, language-learning, and cultural research experiences with structured paginated results.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.", "schema": { "type": "string", "default": "YOUR_APPKEY" } }, { "name": "keywords", "in": "query", "required": false, "description": "Literal keyword matched against the selected search scope. Simplified Chinese keywords also match traditional Chinese poem content.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "pagesize", "in": "query", "required": false, "description": "Number of records returned per page.", "schema": { "type": "integer", "format": "int32", "default": 10, "minimum": 1, "maximum": 20 } }, { "name": "pagenumber", "in": "query", "required": false, "description": "One-based page number for pagination.", "schema": { "type": "integer", "format": "int32", "default": 1, "minimum": 1 } }, { "name": "type", "in": "query", "required": false, "description": "Poetry type filter. Canonical values are `tang`, `song`, and `ci`; the Chinese aliases `唐诗`, `宋诗`, and `宋词` are also accepted.", "schema": { "type": "string", "enum": [ "tang", "song", "ci", "唐诗", "宋诗", "宋词" ] } }, { "name": "searchtype", "in": "query", "required": false, "description": "Field scope used for literal keyword matching.", "schema": { "type": "string", "default": "all", "enum": [ "all", "author", "title", "content" ] } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChinesePoemSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/text/detectlanguage": { "post": { "operationId": "postNlpdetectlanguage", "tags": [ "text" ], "summary": "Detect Text Language", "description": "Detect the most likely language of a text snippet and return ranked language candidates with confidence scores.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LanguageDetectionSuccessResponse" }, "example": { "dataStatus": { "requestParameter": "content_chars=72,content_bytes=73", "statusCode": 200, "status": "SUCCESS", "statusDescription": "successfully", "responseDateTime": "2026-09-05 05:30:00+0000", "dataTotalCount": 1 }, "data": [ { "Language": "French", "LanguageAbbr": "fr", "Probability": 0.999996 } ] } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "422": { "$ref": "#/components/responses/Http422" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "502": { "$ref": "#/components/responses/Http502" }, "503": { "$ref": "#/components/responses/Http503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LanguageDetectionRequest" }, "example": { "content": "Bonjour, ceci est un exemple stable pour identifier la langue française." } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/text/isbn": { "get": { "operationId": "getIsbn", "tags": [ "text" ], "summary": "ISBN Book Metadata Lookup", "description": "Look up books by ISBN or title keywords and retrieve structured publishing metadata, including title, author, translator, publisher, publication date, page count, binding, introductions, and cover image when available. Ideal for catalogs, bookstores, libraries, education, and content enrichment.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.", "schema": { "type": "string", "default": "YOUR_APPKEY" } }, { "name": "isbn", "in": "query", "required": false, "description": "ISBN number for an exact book lookup", "schema": { "type": "string" } }, { "name": "keywords", "in": "query", "required": false, "description": "Keyword used for fuzzy matching against the searchable text fields supported by this endpoint.", "schema": { "type": "string" } }, { "name": "pageIndex", "in": "query", "required": false, "description": "One-based page index for pagination.", "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "Number of records returned per page.", "schema": { "type": "integer", "format": "int32", "default": 10 } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/text/similarity": { "post": { "operationId": "postTextsimilarity", "tags": [ "text" ], "summary": "Text Similarity Calculator", "description": "Compare the meaning of two texts. Scores are decimal strings from 0.00 to 1.00, not guarantees of equivalence. Input spacing is preserved. Inspect dataStatus.statusCode: 100 indicates success; -1 indicates processing failure under the existing HTTP 200 contract.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key supplied in the query string.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Inspect the business status: 100 with a score, or -1 with null data.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TextSimilaritySuccessResponse" }, { "$ref": "#/components/schemas/TextSimilarityFailureResponse" } ] } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextSimilarityRequest" } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/text/stconvert": { "post": { "operationId": "postStconvert", "tags": [ "text" ], "summary": "Simplified and Traditional Chinese Converter", "description": "Convert Chinese text between Simplified (s) and Traditional (t) scripts. Same-mode conversion preserves the input. This is script conversion, not translation or regional terminology localization.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value in the query string.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/STConvertSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/STConvertRequest" } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/websitetools/dns-lookup": { "get": { "operationId": "getDnslookup", "tags": [ "websitetools" ], "summary": "DNS Lookup and Troubleshooting API", "description": "Resolve complete A, AAAA, MX, TXT, NS, CNAME, SRV, and SOA records from a domain or HTTP(S) URL in one structured response. Use it for launch checks, email configuration, incident diagnosis, monitoring, service discovery, and domain security reviews.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.", "schema": { "type": "string", "default": "YOUR_APPKEY" } }, { "name": "domain", "in": "query", "required": true, "description": "Domain name or HTTP(S) URL to inspect. Paths, letter case, a trailing dot, and internationalized domain names are normalized before lookup. IP addresses and non-HTTP(S) URL schemes are not accepted.", "schema": { "type": "string", "default": "https://gugudata.io/docs" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DnsLookupSuccessResponse" }, "examples": { "records": { "summary": "Structured DNS records", "value": { "dataStatus": { "statusCode": 200, "status": "SUCCESS", "statusDescription": "successfully", "responseDateTime": "2026-08-25 00:00:00+0000", "dataTotalCount": 1, "requestParameter": "domain=gugudata.io" }, "data": { "A": [ { "domain": "gugudata.io.", "ttl": "300", "class": "IN", "type": "A", "value": "104.21.28.29" } ], "MX": [ { "domain": "gugudata.io.", "ttl": "300", "class": "IN", "type": "MX", "value": "11 route3.mx.cloudflare.net." } ], "TXT": [ { "domain": "gugudata.io.", "ttl": "300", "class": "IN", "type": "TXT", "value": "v=spf1 include:_spf.mx.cloudflare.net ~all" } ], "SOA": [ { "domain": "gugudata.io.", "ttl": "1800", "class": "IN", "type": "SOA", "value": "iris.ns.cloudflare.com. dns.cloudflare.com. 2412527907 10000 2400 604800 1800" } ] } } }, "nxdomain": { "summary": "Valid domain with no DNS name", "value": { "dataStatus": { "statusCode": 200, "status": "SUCCESS", "statusDescription": "successfully", "responseDateTime": "2026-08-25 00:00:00+0000", "dataTotalCount": 1, "requestParameter": "domain=postman-ci.invalid" }, "data": {} } } } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/websitetools/favicon": { "get": { "operationId": "getFavicon", "tags": [ "websitetools" ], "summary": "Website Metadata and Favicon API", "description": "Turn any public website into a clean metadata record with its page title, verified favicon URL, description, and keywords. Build richer bookmarks, link previews, company profiles, directories, and enrichment workflows while handling sites without a usable icon predictably.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.", "schema": { "type": "string", "default": "YOUR_APPKEY" } }, { "name": "url", "in": "query", "required": true, "description": "Public HTTP or HTTPS webpage URL or domain. Domains without a scheme use HTTPS.", "schema": { "type": "string", "format": "uri-reference", "example": "https://gugudata.io/" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaviconSuccessResponse" }, "examples": { "withIcon": { "summary": "Website metadata with a verified favicon", "value": { "dataStatus": { "requestParameter": "url=https://gugudata.io/", "statusCode": 200, "status": "SUCCESS", "statusDescription": "successfully", "responseDateTime": "2026-08-25 08:00:00+0000", "dataTotalCount": 1 }, "data": { "title": "GuGuData.io - Unlimited API Marketplace", "favicon": "https://gugudata.io/favicon.ico", "description": "Production-ready APIs for data, documents, websites, and automation.", "keywords": "API marketplace, developer APIs" } } }, "withoutIcon": { "summary": "Website metadata without a usable favicon", "value": { "dataStatus": { "requestParameter": "url=https://example.com/no-icon", "statusCode": 200, "status": "SUCCESS", "statusDescription": "successfully", "responseDateTime": "2026-08-25 08:00:00+0000", "dataTotalCount": 1 }, "data": { "title": "Example Page", "favicon": null, "description": "Example page without a usable favicon.", "keywords": "" } } } } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "502": { "$ref": "#/components/responses/FaviconHttp502" }, "503": { "$ref": "#/components/responses/FaviconHttp503" } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/websitetools/fetchcontent": { "post": { "operationId": "postFetchcontent", "tags": [ "websitetools" ], "summary": "LLM-ready Article Content Extraction API", "description": "Turn a public article URL into LLM-ready content with readable HTML, paragraph-preserving text, the final URL, article metadata, primary image, ordered image candidates, author, publication time, and source. Built for RAG, search, monitoring, content analysis, and automation.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FetchContentSuccessResponse" }, "example": { "dataStatus": { "requestParameter": "url_host=gugudata.github.io&url_path=/gugudata-io/guides/article-content-extraction-api-seo-guide/", "statusCode": 200, "status": "SUCCESS", "statusDescription": "successfully", "responseDateTime": "2026-08-25 13:00:00+0000", "dataTotalCount": 1 }, "data": { "url": "https://gugudata.github.io/gugudata-io/guides/article-content-extraction-api-seo-guide/", "title": "Article Content Extraction API Guide", "description": "Extract readable article content and metadata from public webpages.", "content": "

Article Content Extraction API Guide

Extract readable content for search and AI workflows.

", "contentText": "Article Content Extraction API Guide\nExtract readable content for search and AI workflows.", "image": "", "images": [], "author": "GuGuData", "published": "2026-08-25 13:00", "source": "gugudata.github.io" } } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "422": { "description": "The target is not HTML, has no extractable article body, is too large, or redirects too many times.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/Http429" }, "502": { "description": "The target website timed out, failed at the network layer, or returned a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The article extraction service is temporarily unavailable or not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Complete public HTTP or HTTPS article URL.", "example": "https://gugudata.github.io/gugudata-io/guides/article-content-extraction-api-seo-guide/" } }, "required": [ "url" ] } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/websitetools/fetchcontentimages": { "post": { "operationId": "postFetchcontentimages", "tags": [ "websitetools" ], "summary": "Extract Images from Article URL API", "description": "Extract ordered, deduplicated image candidates from the readable area of a public article. Receive the final page URL plus absolute image URLs, alt text, and available dimensions for SEO audits, media inventories, research, AI ingestion, and editorial automation.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FetchContentImagesSuccessResponse" }, "examples": { "withImages": { "summary": "Ordered article image candidates", "value": { "dataStatus": { "requestParameter": "url_host=gugudata.github.io&url_path=/gugudata-io/guides/extract-images-from-article-url-api-seo-guide/", "statusCode": 200, "status": "SUCCESS", "statusDescription": "successfully", "responseDateTime": "2026-08-26 08:00:00+0000", "dataTotalCount": 1 }, "data": { "url": "https://gugudata.github.io/gugudata-io/guides/extract-images-from-article-url-api-seo-guide/", "images": [ { "src": "https://cdn.gugudata.io/api-covers/api-covers_fetchcontentimages.jpg", "absoluteUrl": "https://cdn.gugudata.io/api-covers/api-covers_fetchcontentimages.jpg", "alt": "Article image extraction API workflow", "width": null, "height": null } ] } } }, "withoutImages": { "summary": "Readable article without image candidates", "value": { "dataStatus": { "requestParameter": "url_host=example.com&url_path=/article-without-images", "statusCode": 200, "status": "SUCCESS", "statusDescription": "successfully", "responseDateTime": "2026-08-26 08:00:00+0000", "dataTotalCount": 1 }, "data": { "url": "https://example.com/article-without-images", "images": [] } } } } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "422": { "description": "The target is not HTML, has no extractable article body, is too large, or redirects too many times.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "502": { "description": "The target website timed out, failed at the network layer, or returned a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The article extraction service is temporarily unavailable or not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Complete public HTTP or HTTPS article URL.", "default": "https://gugudata.github.io/gugudata-io/guides/extract-images-from-article-url-api-seo-guide/" } }, "required": [ "url" ] } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/websitetools/international-phone-format": { "get": { "operationId": "getInternationalPhoneFormat", "tags": [ "websitetools" ], "summary": "International Phone Number Validation and Correction", "description": "Validate an international phone number against numbering-plan rules and return a normalized E.164 value when valid. This endpoint checks format and number-plan validity; it does not confirm reachability, ownership, or current carrier status.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.", "schema": { "type": "string", "default": "APPKEY" } }, { "name": "phone", "in": "query", "required": true, "description": "International phone number beginning with +. Spaces, hyphens, periods, and parentheses are accepted.", "schema": { "type": "string", "minLength": 2, "maxLength": 64, "pattern": "^\\+.*$", "default": "+1 (817) 569-8900", "examples": [ "+1 (817) 569-8900", "+44 20 7946 0018", "+86 138 0013 8000" ] }, "allowEmptyValue": false } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternationalPhoneFormatSuccessResponse" }, "examples": { "validNumber": { "summary": "Valid US number normalized to E.164", "value": { "dataStatus": { "requestParameter": "phone=+1******8900", "statusCode": 200, "status": "SUCCESS", "statusDescription": "successfully", "responseDateTime": "2026-08-31 09:30:00.000", "dataTotalCount": 1 }, "data": { "isValid": true, "correctedMobileNumber": "+18175698900", "countryCode": "+1", "countryCode2": "US", "countryCode3": "USA" } } }, "invalidNumber": { "summary": "Well-formed but invalid number", "value": { "dataStatus": { "requestParameter": "phone=+1***5501", "statusCode": 200, "status": "SUCCESS", "statusDescription": "successfully", "responseDateTime": "2026-08-31 09:30:00.000", "dataTotalCount": 1 }, "data": { "isValid": false, "correctedMobileNumber": "", "countryCode": "+1", "countryCode2": "", "countryCode3": "" } } } } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/websitetools/pagespeed-score": { "get": { "operationId": "getPagespeedScore", "tags": [ "websitetools" ], "summary": "Technical SEO Diagnostics API", "description": "Run a real-browser laboratory audit for a public webpage. Compare mobile and desktop profiles, return requested performance, accessibility, best-practice, and SEO scores, inspect loading metrics, and receive prioritized opportunities without treating laboratory results as real-user field data or a search-ranking guarantee.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.", "schema": { "type": "string", "default": "YOUR_APPKEY" } }, { "name": "url", "in": "query", "required": true, "description": "Complete public HTTP or HTTPS webpage URL, up to 2,048 characters. Credentials, IP addresses, private targets, and non-standard ports are not accepted.", "schema": { "type": "string", "format": "uri", "maxLength": 2048, "default": "https://gugudata.github.io/gugudata-io/guides/pagespeed-and-seo-score-api-guide/" } }, { "name": "strategy", "in": "query", "required": false, "description": "Browser profile used for the laboratory audit.", "schema": { "type": "string", "enum": ["desktop", "mobile"], "default": "desktop" } }, { "name": "locale", "in": "query", "required": false, "description": "BCP 47-style locale used for audit labels.", "schema": { "type": "string", "maxLength": 35, "pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$", "default": "en" } }, { "name": "categories", "in": "query", "required": false, "description": "Comma-separated subset of performance, accessibility, best-practices, and seo.", "schema": { "type": "string", "default": "performance,accessibility,best-practices,seo" } }, { "name": "forceRefresh", "in": "query", "required": false, "description": "Bypass a cached result and replace it with a fresh browser audit when true.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageSpeedScoreSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "422": { "$ref": "#/components/responses/Http422" }, "502": { "$ref": "#/components/responses/Http502" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/websitetools/readability": { "post": { "operationId": "postReadability", "tags": [ "websitetools" ], "summary": "Webpage Readable Content Extraction", "description": "Extract reader-friendly article HTML and plain text from exactly one public HTTP(S) URL or raw HTML input. HTML is limited to 1 MiB in UTF-8. Results depend on the page structure; pages without readable article text return HTTP 422.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key supplied in the query string.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadabilitySuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "413": { "$ref": "#/components/responses/Http413" }, "422": { "$ref": "#/components/responses/Http422" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "502": { "$ref": "#/components/responses/Http502" }, "503": { "$ref": "#/components/responses/Http503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadabilityRequest" }, "example": { "html": "Sample article

Readable article text.

" } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/websitetools/search-visibility": { "post": { "operationId": "postSearchVisibility", "tags": [ "websitetools" ], "summary": "Keyword Rank Visibility API", "description": "Check sampled organic search visibility for a domain. Inspect data.searchMetadata.status: UPSTREAM_UNAVAILABLE indicates an incomplete check with no credits consumed, not a zero-rank observation. Rankings vary by time, location and language.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key supplied in the query string.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchVisibilitySuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Keyword or search phrase to observe after Unicode normalization.", "maxLength": 1000, "default": "search visibility api" }, "domain": { "type": "string", "description": "Target domain or HTTP(S) URL, including internationalized domain names.", "maxLength": 2048, "default": "gugudata.io" }, "source": { "type": "string", "description": "Search source. Supported values: `google_web` and `baidu_web`. `bing_web` can be enabled separately.", "default": "google_web" }, "maxRank": { "type": "integer", "format": "int32", "description": "Maximum organic rank depth to observe. Supported values are `10`, `20`, and `50`.", "enum": [10, 20, 50], "default": 20 }, "locale": { "type": "string", "description": "Language preference for the observation.", "maxLength": 35, "default": "en" }, "region": { "type": "string", "description": "Search region preference.", "maxLength": 100, "default": "United States" }, "competitors": { "type": "array", "items": { "type": "string" }, "description": "Optional competitor domains to compare, up to 10 domains.", "maxItems": 10 } }, "required": [ "query", "domain" ] } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/websitetools/sslcertinfo": { "get": { "operationId": "getSslcertinfo", "tags": [ "websitetools" ], "summary": "SSL Certificate Audit API", "description": "Inspect the certificate chain presented by a valid HTTPS domain. Certificate identity, issuer, validity dates and cryptographic details are returned in chain order. Invalid or untrusted TLS certificates fail the lookup; this is not a complete TLS security scan.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.", "schema": { "type": "string", "default": "YOUR_APPKEY" } }, { "name": "domain", "in": "query", "required": true, "description": "Bare domain or HTTPS URL. Internationalized domains are supported; path, query and fragment are ignored. Credentials, IP literals and nonstandard ports are not accepted.", "schema": { "type": "string", "maxLength": 2048, "example": "https://example.com" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SslCertificateSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/websitetools/url2html": { "post": { "operationId": "postUrl2html", "tags": [ "websitetools" ], "summary": "URL to Static HTML Converter", "description": "Save a webpage as a downloadable HTML document. Static resources may be embedded; JavaScript-dependent content is not rendered. Save the public result file yourself for long-term retention.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key supplied as a query parameter.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "type": "object", "required": [ "dataStatus", "data" ], "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "type": "object", "required": [ "url" ], "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "Public HTTPS download address for the generated HTML document." } } } } } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "minLength": 1, "maxLength": 2048, "description": "Complete public HTTP or HTTPS webpage URL. Credentials, IP addresses and nonstandard ports are not accepted.", "example": "https://gugudata.io/" } }, "required": [ "url" ] } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/websitetools/url2image": { "get": { "operationId": "getUrl2image", "tags": [ "websitetools" ], "summary": "Webpage to Image Rendering", "description": "Render a public webpage as a PNG image with configurable output and viewport dimensions.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value in the query string.", "schema": { "type": "string", "default": "YOUR_APPKEY" } }, { "name": "url", "in": "query", "required": true, "description": "Public HTTP or HTTPS webpage URL, up to 2,048 characters. Credentials, IP literals, private targets and non-standard ports are rejected.", "schema": { "type": "string", "format": "uri", "maxLength": 2048 } }, { "name": "isFullPage", "in": "query", "required": false, "description": "Whether the renderer should capture the full page height.", "schema": { "type": "boolean", "default": false } }, { "name": "width", "in": "query", "required": false, "description": "Output width in pixels.", "schema": { "type": "integer", "format": "int32", "default": 250, "minimum": 1, "maximum": 4096 } }, { "name": "height", "in": "query", "required": false, "description": "Output height in pixels.", "schema": { "type": "integer", "format": "int32", "default": 250, "minimum": 1, "maximum": 4096 } }, { "name": "viewportWidth", "in": "query", "required": false, "description": "Viewport width in pixels used during page rendering.", "schema": { "type": "integer", "format": "int32", "default": 1080, "minimum": 320, "maximum": 4096 } }, { "name": "viewportHeight", "in": "query", "required": false, "description": "Viewport height in pixels used during page rendering.", "schema": { "type": "integer", "format": "int32", "default": 1080, "minimum": 200, "maximum": 4096 } }, { "name": "forceReload", "in": "query", "required": false, "description": "Whether the renderer should bypass cached page content before capture.", "schema": { "type": "boolean", "default": false } }, { "name": "isMobile", "in": "query", "required": false, "description": "Whether the renderer should emulate a mobile device viewport.", "schema": { "type": "boolean", "default": false } }, { "name": "isDarkMode", "in": "query", "required": false, "description": "Whether the renderer should emulate dark mode when rendering the target page.", "schema": { "type": "boolean", "default": false } }, { "name": "deviceScaleFactor", "in": "query", "required": false, "description": "Device scale factor used during page rendering.", "schema": { "type": "integer", "format": "int32", "default": 1, "minimum": 1, "maximum": 4 } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/websitetools/url2json": { "post": { "operationId": "postUrl2json", "tags": [ "websitetools" ], "summary": "AI Structured Web Data Extraction API", "description": "Extract structured fields from a webpage using a natural-language instruction. Missing or malformed extraction results fail with 502; empty objects fail with 422. Explicit empty lists remain valid successful results.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key supplied as a query parameter.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Url2JsonSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "422": { "description": "No structured content could be extracted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "502": { "description": "Extraction failed, timed out, or returned an invalid result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Extraction is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]?://", "maxLength": 2048, "description": "Public HTTP(S) webpage URL using port 80 or 443. Credentials and IP-address targets are not accepted.", "example": "https://example.com" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 100000, "description": "Natural-language extraction instruction, up to 100,000 Unicode characters and 512 KiB as UTF-8.", "example": "Extract the page title as title." } }, "required": [ "url", "prompt" ] } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/websitetools/url2links": { "get": { "operationId": "getUrl2links", "tags": [ "websitetools" ], "summary": "Extract Links from URL", "description": "Extract link strings from a public HTTP or HTTPS webpage. Source order and duplicates are preserved; an empty list is a successful result. Extraction failure returns HTTP 503 with business code 500, never substitute links. Returned strings are not visited or verified for availability.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key supplied in the query string.", "schema": { "type": "string", "default": "YOUR_APPKEY" } }, { "name": "url", "in": "query", "required": true, "description": "Complete public HTTP or HTTPS URL, without credentials or non-standard ports.", "schema": { "type": "string", "maxLength": 2048, "example": "https://gugudata.io/" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebpageLinksSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/websitetools/url2markdown": { "post": { "operationId": "postUrl2markdown", "tags": [ "websitetools" ], "summary": "Convert Webpage to Markdown", "description": "Convert a public HTTP or HTTPS webpage into Markdown for documentation, knowledge bases, and content processing. Returns non-empty text in data.result; conversion failure returns HTTP 503 with business code 500, not substitute content. Page structure and access restrictions can affect conversion quality.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key supplied only in the query string; send url in the JSON body.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebpageMarkdownSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Complete public HTTP or HTTPS URL, without credentials or non-standard ports.", "maxLength": 2048, "example": "https://gugudata.io/" } }, "required": [ "url" ] } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/websitetools/url2snapshot": { "post": { "operationId": "postUrl2snapshot", "tags": [ "websitetools" ], "summary": "Webpage Screenshot Capture", "description": "Capture a webpage as a PNG image with rendered HTML. Choose Base64 output or a public image URL, a full-page capture or a viewport, and desktop or mobile settings. Viewport width × height × scale² must not exceed 64000000 pixels. Full-page captures remain subject to output limits.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key supplied as a query parameter.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebpageSnapshotSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "description": "Complete public HTTP or HTTPS URL without credentials, literal IP addresses or non-standard ports." }, "responseFormat": { "type": "string", "description": "Use url for a public PNG URL or base64 for PNG Base64 text. For compatibility, other values also use Base64 output.", "default": "base64" }, "fullPage": { "type": "boolean", "description": "Whether the capture should include the full page height instead of the visible viewport only.", "default": true }, "width": { "type": "integer", "format": "int32", "description": "Viewport width in CSS pixels before device scaling.", "minimum": 1, "maximum": 8192, "default": 1920 }, "height": { "type": "integer", "format": "int32", "description": "Viewport height in CSS pixels; full-page output may be taller.", "minimum": 1, "maximum": 8192, "default": 1080 }, "deviceScaleFactor": { "type": "integer", "format": "int32", "description": "Device scale factor used during page rendering.", "minimum": 1, "maximum": 3, "default": 1 }, "userAgent": { "type": "string", "description": "Optional user agent string, without control characters.", "maxLength": 1024, "default": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36" }, "isMobile": { "type": "boolean", "description": "Whether the renderer should emulate a mobile device viewport.", "default": false } }, "required": [ "url" ] } } } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/websitetools/whois": { "get": { "operationId": "getWhois", "tags": [ "websitetools" ], "summary": "Domain WHOIS Monitoring API", "description": "Look up available domain registration details. Records may be incomplete or privacy-redacted; they do not verify current ownership or registration availability.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.", "schema": { "type": "string", "default": "YOUR_APPKEY" } }, { "name": "domain", "in": "query", "required": true, "description": "Domain name only, not a URL or IP address. Trim surrounding whitespace and lowercase letters. Each label is at most 63 characters; the normalized domain is at most 253 characters.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhoisSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "security": [ { "AppKeyAuth": [] } ] } }, "/v1/wifi-qrcode": { "post": { "operationId": "postWifiqrcode", "tags": [ "qrcode_barcode" ], "summary": "Wi-Fi Wireless Network QR Code Generation", "description": "Create a QR code for joining a Wi-Fi network. The PNG contains the supplied credentials: share the image and its public download link only with intended users. Scanning support depends on the device. Enterprise configuration beyond the authentication token is not provided.", "parameters": [ { "name": "appkey", "in": "query", "required": true, "description": "Application key used for request authentication. Supply the value in the query string.", "schema": { "type": "string", "default": "YOUR_APPKEY" } } ], "responses": { "200": { "description": "A PNG image was generated and stored successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WifiQrSuccessResponse" } } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" }, "403": { "$ref": "#/components/responses/Http403" }, "429": { "$ref": "#/components/responses/Http429" }, "500": { "$ref": "#/components/responses/Http500" }, "503": { "$ref": "#/components/responses/Http503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ssid": { "type": "string", "description": "Required network name. Whitespace and Unicode are preserved. Combined SSID, password and authentication input must not exceed 32768 UTF-8 bytes; dense content may require a larger image.", "minLength": 1, "example": "Guest Network" }, "password": { "type": "string", "description": "Network password, preserved exactly. Optional for an open network. Anyone with the image can read this value.", "example": "guest-password" }, "authentication": { "type": "string", "description": "Case-insensitive WPA, WEP, nopass or legacy WPA2-EAP token. Missing or empty means nopass. The legacy enterprise token does not supply EAP identity or method settings.", "default": "nopass", "example": "WPA" }, "isHiddenSSID": { "type": "boolean", "description": "Whether the Wi-Fi network is hidden.", "default": false }, "isShowWifiIcon": { "type": "boolean", "description": "Include a Wi-Fi symbol below the code, without covering it. The image remains square.", "default": false }, "size": { "type": "integer", "format": "int32", "description": "Square PNG size in pixels. Too-small images for the supplied content return 400; increase size or shorten the input.", "minimum": 64, "maximum": 2048, "default": 500 } }, "required": [ "ssid" ] } } } }, "security": [ { "AppKeyAuth": [] } ] } } }, "components": { "securitySchemes": { "AppKeyAuth": { "type": "apiKey", "in": "query", "name": "appkey", "description": "Application key used for request authentication." } }, "schemas": { "WordHtmlSuccessResponse": { "type": "object", "required": ["dataStatus", "data"], "properties": { "dataStatus": {"$ref": "#/components/schemas/DataStatus"}, "data": { "type": "object", "required": ["html_url"], "additionalProperties": false, "properties": { "html_url": {"type": "string", "format": "uri", "pattern": "^https://", "description": "Public HTML download URL. Save the file if you need to retain it."}, "html_content": {"type": "string", "minLength": 1, "description": "Converted HTML, when present. Maximum 20 MiB in UTF-8. Layout may differ from the source document."} } } } }, "WifiQrSuccessResponse": { "type": "object", "required": ["dataStatus", "data"], "properties": { "dataStatus": {"$ref": "#/components/schemas/DataStatus"}, "data": { "type": "object", "required": ["url"], "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "Public PNG download URL. Save and share responsibly; the image contains network credentials. Permanent hosting is not guaranteed." } } } } }, "WhoisSuccessResponse": { "type": "object", "required": ["dataStatus", "data"], "properties": { "dataStatus": {"$ref": "#/components/schemas/DataStatus"}, "data": {"$ref": "#/components/schemas/WhoisData"} } }, "WhoisData": { "type": "object", "additionalProperties": false, "description": "Available registration fields. Partial records are valid; missing values may be null or empty. Entirely empty lookups are unavailable, not successful registration records.", "properties": { "address": {"$ref": "#/components/schemas/WhoisStringList"}, "city": {"$ref": "#/components/schemas/WhoisStringList"}, "creation_date": {"$ref": "#/components/schemas/WhoisStringList"}, "domain_name": {"$ref": "#/components/schemas/WhoisStringList"}, "emails": {"$ref": "#/components/schemas/WhoisStringList"}, "expiration_date": {"$ref": "#/components/schemas/WhoisStringList"}, "name": {"$ref": "#/components/schemas/WhoisStringList"}, "name_servers": {"$ref": "#/components/schemas/WhoisStringList"}, "status": {"$ref": "#/components/schemas/WhoisStringList"}, "updated_date": {"$ref": "#/components/schemas/WhoisStringList"}, "country": {"type": ["string", "null"]}, "dnssec": {"type": ["string", "null"]}, "org": {"type": ["string", "null"]}, "referral_url": {"type": ["string", "null"]}, "registrant_postal_code": {"type": ["string", "null"]}, "registrar": {"type": ["string", "null"]}, "state": {"type": ["string", "null"]} } }, "WhoisStringList": { "type": ["array", "null"], "items": {"type": "string"} }, "ProgramSuccessResponse": { "type": "object", "required": [ "dataStatus", "data" ], "properties": { "dataStatus": { "type": "object", "required": [ "requestParameter", "statusCode", "status", "statusDescription", "responseDateTime", "dataTotalCount" ], "properties": { "requestParameter": { "type": [ "string", "null" ] }, "statusCode": { "type": "integer", "const": 100 }, "status": { "type": "string", "const": "SUCCESS" }, "statusDescription": { "type": "string" }, "responseDateTime": { "type": "string", "example": "2026-09-08 10:00:00.123" }, "dataTotalCount": { "type": "integer", "minimum": 0 } } }, "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "institutionName", "city", "state", "cipCode", "cipTitle", "programName", "credentialLevel", "source", "sourceUpdatedAt", "unitId", "graduates", "sourceYear", "tuitionInState", "medianEarnings", "medianDebt", "debtToEarnings" ], "properties": { "institutionName": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "cipCode": { "type": "string" }, "cipTitle": { "type": "string" }, "programName": { "type": "string" }, "credentialLevel": { "type": "string" }, "source": { "type": "string" }, "sourceUpdatedAt": { "type": "string" }, "unitId": { "type": [ "integer", "null" ] }, "graduates": { "type": [ "integer", "null" ] }, "sourceYear": { "type": [ "integer", "null" ] }, "tuitionInState": { "type": [ "number", "null" ] }, "medianEarnings": { "type": [ "number", "null" ] }, "medianDebt": { "type": [ "number", "null" ] }, "debtToEarnings": { "type": [ "number", "null" ] } } } } } }, "InstitutionSuccessResponse": { "type": "object", "required": [ "dataStatus", "data" ], "properties": { "dataStatus": { "type": "object", "required": [ "requestParameter", "statusCode", "status", "statusDescription", "responseDateTime", "dataTotalCount" ], "properties": { "requestParameter": { "type": [ "string", "null" ] }, "statusCode": { "type": "integer", "const": 100 }, "status": { "type": "string", "const": "SUCCESS" }, "statusDescription": { "type": "string" }, "responseDateTime": { "type": "string", "example": "2026-09-08 10:00:00.123" }, "dataTotalCount": { "type": "integer", "minimum": 0 } } }, "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "opeId", "scorecardId", "institutionName", "city", "state", "zip", "website", "ownership", "degreeLevel", "institutionType", "source", "sourceUpdatedAt", "unitId", "studentSize", "sourceYear", "admissionRate", "tuitionInState", "tuitionOutOfState", "netPricePublic", "netPricePrivate", "completionRate" ], "properties": { "opeId": { "type": "string" }, "scorecardId": { "type": "string" }, "institutionName": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "website": { "type": "string" }, "ownership": { "type": "string" }, "degreeLevel": { "type": "string" }, "institutionType": { "type": "string" }, "source": { "type": "string" }, "sourceUpdatedAt": { "type": "string" }, "unitId": { "type": [ "integer", "null" ] }, "studentSize": { "type": [ "integer", "null" ] }, "sourceYear": { "type": [ "integer", "null" ] }, "admissionRate": { "type": [ "number", "null" ] }, "tuitionInState": { "type": [ "number", "null" ] }, "tuitionOutOfState": { "type": [ "number", "null" ] }, "netPricePublic": { "type": [ "number", "null" ] }, "netPricePrivate": { "type": [ "number", "null" ] }, "completionRate": { "type": [ "number", "null" ] } } } } } }, "UsStockSymbolsSuccessResponse": { "type": "object", "required": ["dataStatus", "data"], "properties": { "dataStatus": { "type": "object", "required": ["requestParameter", "statusCode", "statusDescription", "responseDateTime", "dataTotalCount"], "properties": { "requestParameter": { "type": "string", "description": "Normalized search and pagination values, without AppKey." }, "statusCode": { "type": "integer", "const": 100 }, "statusDescription": { "type": "string" }, "responseDateTime": { "type": "string", "example": "2026-09-08 10:00:00.123" }, "dataTotalCount": { "type": "integer", "minimum": 0, "description": "All matching records, not the number of rows on this page." } } }, "data": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": ["symbol", "stockName"], "properties": { "symbol": { "type": ["string", "null"], "example": "AAPL" }, "stockName": { "type": ["string", "null"], "example": "Apple Inc." } }, "additionalProperties": false } } } }, "WebpageSnapshotSuccessResponse": { "type": "object", "required": ["dataStatus", "data"], "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "type": "object", "additionalProperties": false, "required": ["image", "content"], "properties": { "image": { "type": "string", "minLength": 1, "description": "PNG Base64 text by default, or a public image URL when responseFormat is url. Save downloaded files yourself; permanent hosting is not guaranteed." }, "content": { "type": "string", "description": "Rendered page HTML, or an empty string if none was returned. Treat it as untrusted content, not sanitized HTML." } } } } }, "WebpageLinksSuccessResponse": { "type": "object", "additionalProperties": false, "required": ["dataStatus", "data"], "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "type": "object", "additionalProperties": false, "required": ["result", "count", "requestParameter"], "properties": { "result": { "type": "array", "items": { "type": "string" }, "description": "Extracted strings in returned order, including duplicate and non-HTTP links. Empty arrays are valid." }, "count": { "type": "integer", "minimum": 0, "description": "Number of entries in result." }, "requestParameter": { "type": "string", "description": "Source host and path, without query parameters or credentials." } } } } }, "WebpageMarkdownSuccessResponse": { "type": "object", "additionalProperties": false, "required": ["dataStatus", "data"], "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "type": "object", "additionalProperties": false, "required": ["result"], "properties": { "result": { "type": "string", "minLength": 1, "description": "Converted Markdown, preserving the returned text and whitespace." } } } } }, "TextSimilarityRequest": { "type": "object", "required": [ "content1", "content2" ], "properties": { "content1": { "type": "string", "minLength": 1, "maxLength": 5000, "pattern": "\\S", "description": "Nonblank text, at most 5,000 Unicode code points. Original spacing is preserved." }, "content2": { "type": "string", "minLength": 1, "maxLength": 5000, "pattern": "\\S", "description": "Nonblank text, at most 5,000 Unicode code points. Original spacing is preserved." } } }, "TextSimilaritySuccessResponse": { "type": "object", "required": [ "dataStatus", "data" ], "properties": { "dataStatus": { "type": "object", "required": [ "requestParameter", "statusCode", "statusDescription", "responseDateTime", "dataTotalCount" ], "properties": { "requestParameter": { "type": "string", "description": "Only input character counts; no input text or AppKey.", "example": "content1Length=5&content2Length=6" }, "statusCode": { "type": "integer", "const": 100 }, "statusDescription": { "type": "string", "const": "Request successful." }, "responseDateTime": { "type": "string", "description": "Existing yyyy-MM-dd HH:mm:ss.SSS timestamp." }, "dataTotalCount": { "type": "integer", "const": 1 } } }, "data": { "type": "object", "required": [ "similarity" ], "additionalProperties": false, "properties": { "similarity": { "type": "string", "pattern": "^(?:0\\.[0-9]{2}|1\\.00)$", "example": "0.85" } } } } }, "TextSimilarityFailureResponse": { "type": "object", "required": [ "dataStatus", "data" ], "properties": { "dataStatus": { "type": "object", "required": [ "requestParameter", "statusCode", "statusDescription", "responseDateTime", "dataTotalCount" ], "properties": { "requestParameter": { "type": "string", "description": "Only input character counts; no input text or AppKey.", "example": "content1Length=5&content2Length=6" }, "statusCode": { "type": "integer", "const": -1 }, "statusDescription": { "type": "string", "const": "Request failed. Please try again later." }, "responseDateTime": { "type": "string", "description": "Existing yyyy-MM-dd HH:mm:ss.SSS timestamp." }, "dataTotalCount": { "type": "integer", "const": 0 } } }, "data": { "type": "null" } } }, "ReadabilityRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://", "description": "Complete public HTTP(S) page URL." }, "html": { "type": "string", "minLength": 1, "maxLength": 1048576, "description": "Raw HTML, maximum 1 MiB in UTF-8. Scripts and embedded resources are not executed." } }, "oneOf": [ { "required": [ "url" ], "not": { "required": [ "html" ] } }, { "required": [ "html" ], "not": { "required": [ "url" ] } } ] }, "ReadabilityData": { "type": "object", "properties": { "title": { "type": "string" }, "content": { "type": "string", "description": "Clean article HTML." }, "textContent": { "type": "string", "description": "Extracted plain text." }, "length": { "type": "integer", "minimum": 0, "description": "Length of extracted text." }, "byline": { "type": [ "string", "null" ] }, "dir": { "type": [ "string", "null" ] }, "lang": { "type": [ "string", "null" ] }, "excerpt": { "type": [ "string", "null" ] }, "siteName": { "type": [ "string", "null" ] }, "publishedTime": { "type": [ "string", "null" ] } }, "required": [ "title", "content", "textContent", "length" ] }, "ReadabilitySuccessResponse": { "type": "object", "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "$ref": "#/components/schemas/ReadabilityData" } }, "required": [ "dataStatus", "data" ] }, "ShortLinkSuccessResponse": { "type": "object", "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "$ref": "#/components/schemas/ShortLinkData" } }, "required": ["dataStatus", "data"] }, "ShortLinkData": { "type": "object", "properties": { "name": { "type": "string", "example": "shortLinks/abc1234" }, "shortLinkId": { "type": "string" }, "shortUrl": { "type": "string", "format": "uri" }, "longUrl": { "type": "string", "format": "uri", "maxLength": 8192 }, "state": { "type": "string", "enum": ["ACTIVE", "DISABLED"] }, "expireTime": { "$ref": "#/components/schemas/ShortLinkTimestamp" }, "clickCount": { "type": ["integer", "null"], "minimum": 0, "description": "Redirect requests, not unique visitors." }, "lastAccessTime": { "$ref": "#/components/schemas/ShortLinkTimestamp" }, "createTime": { "$ref": "#/components/schemas/ShortLinkTimestamp" }, "updateTime": { "$ref": "#/components/schemas/ShortLinkTimestamp" } }, "required": ["name", "shortLinkId", "shortUrl", "longUrl", "state"] }, "ShortLinkTimestamp": { "type": ["string", "integer", "null"], "description": "Existing date serialization: epoch milliseconds or a formatted date string; null when unavailable." }, "SearchVisibilityData": { "type": "object", "properties": { "query": { "type": "string" }, "domain": { "type": "string" }, "source": { "type": "string", "enum": ["google_web", "bing_web", "baidu_web"] }, "maxRank": { "type": "integer", "enum": [10, 20, 50] }, "checkedAt": { "type": "string", "format": "date-time" }, "creditCost": { "type": "integer", "minimum": 0 }, "remainingCredits": { "type": ["integer", "null"], "minimum": 0 }, "observedItems": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer", "minimum": 1, "maximum": 50 }, "title": { "type": "string" }, "url": { "type": "string" }, "domain": { "type": "string" }, "snippet": { "type": "string" } }, "required": ["rank", "title", "url", "domain", "snippet"] } }, "brandMatches": { "type": "array", "items": { "$ref": "#/components/schemas/SearchVisibilityMatch" } }, "competitorMatches": { "type": "array", "items": { "$ref": "#/components/schemas/SearchVisibilityMatch" } }, "metrics": { "type": "object", "properties": { "visible": { "type": "boolean" }, "bestRank": { "type": ["integer", "null"] }, "top10": { "type": "boolean" }, "top20": { "type": "boolean" }, "visibilityScore": { "type": "number", "minimum": 0, "maximum": 100 }, "matchedCount": { "type": "integer", "minimum": 0 } }, "required": ["visible", "top10", "top20", "visibilityScore", "matchedCount"] }, "searchMetadata": { "type": "object", "properties": { "status": { "type": ["string", "null"] }, "statusDescription": { "type": ["string", "null"] }, "totalResults": { "type": ["integer", "null"] }, "itemCount": { "type": "integer", "minimum": 0 }, "itemTypes": { "type": "array", "items": { "type": "string" } }, "checkUrl": { "type": ["string", "null"] } }, "required": ["itemCount", "itemTypes"] } }, "required": ["query", "domain", "source", "maxRank", "checkedAt", "creditCost", "observedItems", "brandMatches", "competitorMatches", "metrics", "searchMetadata"] }, "SearchVisibilityMatch": { "type": "object", "properties": { "domain": { "type": "string" }, "bestRank": { "type": ["integer", "null"] }, "matchCount": { "type": "integer", "minimum": 0 } }, "required": ["domain", "matchCount"] }, "SearchVisibilitySuccessResponse": { "type": "object", "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "$ref": "#/components/schemas/SearchVisibilityData" } }, "required": ["dataStatus", "data"] }, "QrDecodeData": { "type": "object", "additionalProperties": false, "required": [ "format", "parsed", "points", "raw", "type" ], "properties": { "format": { "type": "string", "const": "QR_CODE" }, "parsed": { "type": "string", "description": "Exact decoded text; identical to raw." }, "raw": { "type": "string" }, "type": { "type": "string", "enum": [ "URI", "WIFI", "EMAIL", "TEXT" ] }, "points": { "type": "array", "description": "Four corners in image pixels: top-left, top-right, bottom-right, bottom-left; empty when reliable corners are unavailable.", "items": { "type": "array", "items": { "type": "number", "minimum": 0 }, "minItems": 2, "maxItems": 2 }, "oneOf": [ { "maxItems": 0 }, { "minItems": 4, "maxItems": 4 } ] } } }, "QrDecodeSuccessResponse": { "type": "object", "required": [ "dataStatus", "data" ], "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "$ref": "#/components/schemas/QrDecodeData" } } }, "QrCodeRequest": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "minLength": 1, "pattern": "[^\\u0009-\\u000d\\u001c-\\u0020\\u1680\\u2000-\\u2006\\u2008-\\u200a\\u2028\\u2029\\u205f\\u3000]", "x-maxUtf8Bytes": 32768, "description": "Nonblank text preserved exactly. At most 32768 UTF-8 bytes before encoding; actual QR capacity and image size impose smaller limits. Shorten content or increase size when it cannot fit." }, "size": { "type": "integer", "minimum": 64, "maximum": 2048, "default": 200, "description": "Width and height in pixels. Fractions, strings and null are rejected." } } }, "QrCodeData": { "type": "object", "required": [ "url" ], "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "Public HTTPS PNG URL. Download and save the file." } } }, "QrCodeDataStatus": { "type": "object", "required": [ "statusCode", "requestParameter", "responseDateTime" ], "properties": { "statusCode": { "type": "integer", "const": 200 }, "statusDescription": { "type": "string" }, "status": { "type": "string" }, "requestParameter": { "type": "string", "description": "Character count, UTF-8 byte count and size; never submitted text." }, "dataTotalCount": { "type": "integer" }, "responseDateTime": { "type": "string" } } }, "QrCodeSuccessResponse": { "type": "object", "required": [ "dataStatus", "data" ], "properties": { "dataStatus": { "$ref": "#/components/schemas/QrCodeDataStatus" }, "data": { "$ref": "#/components/schemas/QrCodeData" } } }, "UniversityDataStatus": { "type": "object", "additionalProperties": false, "required": ["requestParameter", "statusCode", "status", "statusDescription", "responseDateTime", "dataTotalCount"], "properties": { "requestParameter": {"type": "string"}, "statusCode": {"type": "integer", "const": 200}, "status": {"type": "string", "const": "SUCCESS"}, "statusDescription": {"type": "string"}, "responseDateTime": {"type": "string"}, "dataTotalCount": {"type": "integer", "minimum": 0} } }, "GlobalUniversityProgramme": { "type": "object", "additionalProperties": false, "required": ["programmeId", "programmeName", "studyLevel"], "properties": { "programmeId": {"type": ["string", "null"]}, "programmeName": {"type": ["string", "null"]}, "studyLevel": {"type": ["string", "null"]} } }, "GlobalUniversityRecord": { "type": "object", "additionalProperties": false, "required": ["rank", "website", "universityName", "universityChineseName", "logo", "region", "country", "city", "internationalStudents", "subjectCount", "programmeCount", "programmeDataAvailable", "programmes", "schoolUUID", "institutionType"], "properties": { "rank": {"type": ["integer", "null"]}, "website": {"type": ["string", "null"]}, "universityName": {"type": ["string", "null"]}, "universityChineseName": {"type": ["string", "null"]}, "logo": {"type": ["string", "null"]}, "region": {"type": ["string", "null"]}, "country": {"type": ["string", "null"]}, "city": {"type": ["string", "null"]}, "internationalStudents": {"type": ["integer", "null"]}, "subjectCount": {"type": ["integer", "null"]}, "programmeCount": {"type": ["integer", "null"], "minimum": 0}, "programmeDataAvailable": {"type": ["boolean", "null"]}, "programmes": {"type": ["array", "null"], "items": {"$ref": "#/components/schemas/GlobalUniversityProgramme"}}, "schoolUUID": {"type": ["string", "null"]}, "institutionType": {"type": ["string", "null"]} } }, "GlobalUniversitySuccessResponse": { "type": "object", "additionalProperties": false, "required": ["dataStatus", "data"], "properties": { "dataStatus": {"$ref": "#/components/schemas/UniversityDataStatus"}, "data": {"type": "array", "items": {"$ref": "#/components/schemas/GlobalUniversityRecord"}} } }, "GlobalUniversityRankingRecord": { "type": "object", "additionalProperties": false, "required": ["id", "universityName", "region", "country", "city", "logoUrl", "rank", "academicReputationRank", "academicReputationScore", "citationsPerFacultyRank", "citationsPerFacultyScore", "facultyStudentRatioRank", "facultyStudentRatioScore", "employerReputationRank", "employerReputationScore", "employmentOutcomesRank", "employmentOutcomesScore", "internationalStudentRatioRank", "internationalStudentRatioScore", "internationalResearchNetworkRank", "internationalResearchNetworkScore", "internationalFacultyRatioRank", "internationalFacultyRatioScore", "sustainabilityRank", "sustainabilityScore"], "properties": { "id": {"type": ["string", "null"]}, "universityName": {"type": ["string", "null"]}, "region": {"type": ["string", "null"]}, "country": {"type": ["string", "null"]}, "city": {"type": ["string", "null"]}, "logoUrl": {"type": ["string", "null"]}, "rank": {"type": ["string", "null"]}, "academicReputationRank": {"type": ["string", "null"]}, "academicReputationScore": {"type": ["string", "null"]}, "citationsPerFacultyRank": {"type": ["string", "null"]}, "citationsPerFacultyScore": {"type": ["string", "null"]}, "facultyStudentRatioRank": {"type": ["string", "null"]}, "facultyStudentRatioScore": {"type": ["string", "null"]}, "employerReputationRank": {"type": ["string", "null"]}, "employerReputationScore": {"type": ["string", "null"]}, "employmentOutcomesRank": {"type": ["string", "null"]}, "employmentOutcomesScore": {"type": ["string", "null"]}, "internationalStudentRatioRank": {"type": ["string", "null"]}, "internationalStudentRatioScore": {"type": ["string", "null"]}, "internationalResearchNetworkRank": {"type": ["string", "null"]}, "internationalResearchNetworkScore": {"type": ["string", "null"]}, "internationalFacultyRatioRank": {"type": ["string", "null"]}, "internationalFacultyRatioScore": {"type": ["string", "null"]}, "sustainabilityRank": {"type": ["string", "null"]}, "sustainabilityScore": {"type": ["string", "null"]} } }, "GlobalUniversityRankingSuccessResponse": { "type": "object", "additionalProperties": false, "required": ["dataStatus", "data"], "properties": { "dataStatus": {"$ref": "#/components/schemas/UniversityDataStatus"}, "data": {"type": "array", "items": {"$ref": "#/components/schemas/GlobalUniversityRankingRecord"}} } }, "Url2JsonSuccessResponse": { "type": "object", "required": ["dataStatus", "data"], "properties": { "dataStatus": {"$ref": "#/components/schemas/DataStatus"}, "data": { "type": "object", "additionalProperties": true, "description": "Fields depend on the extraction instruction. Article arrays are wrapped in articles; other arrays in items. Explicit empty lists are valid. Example fields are not required for every request.", "examples": [{"title": "Example Domain"}, {"items": []}] } } }, "PptPdfSuccessResponse": { "type": "object", "required": [ "dataStatus", "data" ], "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "type": "object", "required": [ "pdfPath" ], "properties": { "pdfPath": { "type": "string", "format": "uri", "pattern": "^https://", "description": "Public PDF download URL. Save the file; permanent hosting is not guaranteed." } } } } }, "PdfWordRequest": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "PDF upload, maximum 20 MiB and 50 pages." }, "file_url": { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]?://", "maxLength": 2048, "description": "Public HTTP(S) PDF URL. Supply file or file_url, not both." }, "lang": { "type": "string", "enum": [ "en", "zh-CN", "zh-TW", "en+zh-CN", "en+zh-TW" ], "default": "en" }, "filename": { "type": "string", "maxLength": 128, "default": "result.docx", "description": "Optional filename normalized to .docx, at most 128 characters including suffix. Paths and unsafe names are rejected." } }, "oneOf": [ { "required": [ "file" ], "not": { "required": [ "file_url" ] } }, { "required": [ "file_url" ], "not": { "required": [ "file" ] } } ] }, "PdfWordData": { "type": "object", "required": [ "wordPath" ], "additionalProperties": false, "properties": { "wordPath": { "type": "string", "format": "uri", "pattern": "^https://", "description": "Public HTTPS DOCX download URL. Save the file; permanent hosting is not guaranteed." } } }, "PdfWordDataStatus": { "type": "object", "required": [ "requestParameter", "statusCode", "statusDescription", "responseDateTime", "dataTotalCount" ], "properties": { "requestParameter": { "type": "string", "example": "source=upload&lang=en&bytes=25476&pages=2" }, "statusCode": { "type": "integer", "const": 200 }, "status": { "type": "string", "const": "SUCCESS" }, "statusDescription": { "type": "string" }, "responseDateTime": { "type": "string", "example": "2026-09-06 06:34:26+0000" }, "dataTotalCount": { "type": "integer", "minimum": 1, "maximum": 50 } } }, "PdfWordErrorResponse": { "type": "object", "required": [ "dataStatus", "data" ], "properties": { "data": { "type": "null" }, "dataStatus": { "type": "object", "required": [ "statusCode", "statusDescription" ], "properties": { "statusCode": { "type": "integer", "enum": [ 400, 500 ] }, "status": { "type": "string" }, "statusDescription": { "type": "string" }, "requestParameter": { "type": "string" }, "responseDateTime": { "type": "string" }, "dataTotalCount": { "type": "integer", "const": 0 } } } } }, "PdfWordSuccessResponse": { "type": "object", "required": [ "dataStatus", "data" ], "properties": { "dataStatus": { "$ref": "#/components/schemas/PdfWordDataStatus" }, "data": { "$ref": "#/components/schemas/PdfWordData" } } }, "PdfOcrRequest": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "PDF upload, maximum 20 MiB and 50 pages." }, "file_url": { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]?://", "maxLength": 2048, "description": "Public HTTP(S) PDF URL. Supply file or file_url, not both." }, "lang": { "type": "string", "enum": [ "en", "zh-CN", "zh-TW", "en+zh-CN", "en+zh-TW" ], "default": "en" } }, "oneOf": [ { "required": [ "file" ], "not": { "required": [ "file_url" ] } }, { "required": [ "file_url" ], "not": { "required": [ "file" ] } } ] }, "PdfOcrData": { "type": "object", "additionalProperties": false, "required": [ "resultText", "text" ], "properties": { "resultText": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string" }, "description": "One entry per page; blank pages retain empty strings." }, "text": { "type": "string", "description": "Nonempty page text joined by two newline characters." } } }, "PdfOcrDataStatus": { "type": "object", "required": [ "requestParameter", "statusCode", "statusDescription", "responseDateTime", "dataTotalCount" ], "properties": { "requestParameter": { "type": "string", "example": "source=url&bytes=25476&pages=2&lang=en" }, "statusCode": { "type": "integer", "const": 200 }, "status": { "type": "string", "const": "SUCCESS" }, "statusDescription": { "type": "string" }, "responseDateTime": { "type": "string", "example": "2026-09-06 06:34:26+0000" }, "dataTotalCount": { "type": "integer", "const": 1 } } }, "PdfOcrErrorResponse": { "type": "object", "required": [ "dataStatus", "data" ], "properties": { "data": { "type": "null" }, "dataStatus": { "type": "object", "required": [ "statusCode", "statusDescription" ], "properties": { "statusCode": { "type": "integer", "enum": [ 400, 500 ] }, "status": { "type": "string" }, "statusDescription": { "type": "string" }, "requestParameter": { "type": "string" }, "responseDateTime": { "type": "string" }, "dataTotalCount": { "type": "integer", "const": 0 } } } } }, "PdfOcrSuccessResponse": { "type": "object", "required": [ "dataStatus", "data" ], "properties": { "dataStatus": { "$ref": "#/components/schemas/PdfOcrDataStatus" }, "data": { "$ref": "#/components/schemas/PdfOcrData" } } }, "PdfHtmlRequest": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "PDF up to 20 MiB and 100 pages. Supply file or file_url, not both." }, "file_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Public HTTP/HTTPS PDF URL, supplied instead of file.", "pattern": "^[Hh][Tt][Tt][Pp][Ss]?://", "example": "https://storage.gugudata.io/pdf/demo.pdf" } }, "oneOf": [ { "required": [ "file" ], "not": { "required": [ "file_url" ] } }, { "required": [ "file_url" ], "not": { "required": [ "file" ] } } ] }, "PdfHtmlData": { "type": "object", "required": [ "htmlUrl" ], "additionalProperties": false, "properties": { "htmlUrl": { "type": "string", "format": "uri", "pattern": "^https://", "description": "Public HTTPS URL of readable UTF-8 HTML. Retain your own copy; permanent availability is not guaranteed." } } }, "PdfHtmlSuccessResponse": { "type": "object", "required": [ "dataStatus", "data" ], "properties": { "dataStatus": { "$ref": "#/components/schemas/PdfHtmlDataStatus" }, "data": { "$ref": "#/components/schemas/PdfHtmlData" } } }, "PdfHtmlDataStatus": { "type": "object", "required": [ "requestParameter", "statusCode", "statusDescription", "responseDateTime", "dataTotalCount" ], "properties": { "requestParameter": { "type": "string", "description": "Input source, byte count and page count; Demo identifies its public PDF fixture." }, "statusCode": { "type": "integer", "const": 200 }, "status": { "type": "string", "const": "SUCCESS" }, "statusDescription": { "type": "string" }, "responseDateTime": { "type": "string", "example": "2026-09-06 06:34:26+0000" }, "dataTotalCount": { "type": "integer", "const": 1 } } }, "PdfHtmlErrorResponse": { "type": "object", "required": [ "dataStatus", "data" ], "properties": { "data": { "type": "null" }, "dataStatus": { "type": "object", "required": [ "statusCode", "statusDescription" ], "properties": { "statusCode": { "type": "integer", "enum": [ 400, 500 ] }, "status": { "type": "string" }, "statusDescription": { "type": "string" }, "requestParameter": { "type": "string" }, "responseDateTime": { "type": "string" }, "dataTotalCount": { "type": "integer", "const": 0 } } } } }, "DataStatus": { "type": "object", "properties": { "requestParameter": { "type": "string" }, "statusCode": { "type": "integer", "format": "int32" }, "status": { "type": "string" }, "statusDescription": { "type": "string" }, "responseDateTime": { "type": "string" }, "dataTotalCount": { "type": "integer", "format": "int32" } }, "required": [ "statusCode", "statusDescription", "responseDateTime", "dataTotalCount" ] }, "PdfSplitterSuccessResponse": { "type": "object", "additionalProperties": false, "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "$ref": "#/components/schemas/PdfSplitterData" } }, "required": ["dataStatus", "data"] }, "PdfSplitterData": { "oneOf": [ { "$ref": "#/components/schemas/PdfSplitterPublicData" }, { "$ref": "#/components/schemas/PdfSplitterPrivateData" } ] }, "PdfSplitterPublicData": { "type": "object", "additionalProperties": false, "properties": { "uuid": { "type": "string", "format": "uuid" }, "num_files": { "type": "integer", "minimum": 1, "description": "Number of logical PDF parts before optional ZIP packaging." }, "pdf_files": { "type": "array", "minItems": 1, "items": { "type": "string", "format": "uri" } } }, "required": ["uuid", "num_files", "pdf_files"] }, "PdfSplitterPrivateData": { "type": "object", "additionalProperties": false, "properties": { "uuid": { "type": "string", "format": "uuid" }, "num_files": { "type": "integer", "minimum": 1, "description": "Number of logical PDF parts before optional ZIP packaging." }, "pdf_files": { "type": "array", "maxItems": 0, "items": { "type": "string", "format": "uri" } }, "storage": { "type": "string", "const": "private" }, "files": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/PrivateFileReference" } } }, "required": ["uuid", "num_files", "pdf_files", "storage", "files"] }, "PrivateFileReference": { "type": "object", "additionalProperties": false, "properties": { "file_id": { "type": "string", "format": "uuid" }, "file_name": { "type": "string" }, "content_type": { "type": "string", "enum": ["application/pdf", "application/zip"] }, "size_bytes": { "type": "integer", "format": "int64", "minimum": 1 }, "index": { "type": "integer", "minimum": 1 } }, "required": ["file_id", "file_name", "content_type", "size_bytes", "index"] }, "PrivateFileSignRequest": { "type": "object", "additionalProperties": false, "properties": { "secret": { "type": "string", "minLength": 1, "writeOnly": true }, "expires_seconds": { "type": "integer", "minimum": 1, "maximum": 3600, "default": 600 } }, "required": ["secret"] }, "PrivateFileSignSuccessResponse": { "type": "object", "additionalProperties": false, "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "type": "object", "additionalProperties": false, "properties": { "file_id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": ["file_id", "url", "expires_at"] } }, "required": ["dataStatus", "data"] }, "PageSpeedScoreSuccessResponse": { "type": "object", "additionalProperties": false, "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "$ref": "#/components/schemas/PageSpeedScoreData" } }, "required": ["dataStatus", "data"] }, "PageSpeedScoreData": { "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "description": "Final audited URL after redirects." }, "strategy": { "type": "string", "enum": ["desktop", "mobile"] }, "locale": { "type": "string" }, "checkedAt": { "type": "string", "format": "date-time" }, "coreMetrics": { "$ref": "#/components/schemas/PageSpeedCoreMetrics" }, "scores": { "$ref": "#/components/schemas/PageSpeedScores" }, "audits": { "type": "array", "items": { "$ref": "#/components/schemas/PageSpeedAudit" } }, "opportunities": { "type": "array", "items": { "$ref": "#/components/schemas/PageSpeedOpportunity" } } }, "required": ["url", "strategy", "locale", "checkedAt", "coreMetrics", "scores", "audits", "opportunities"] }, "PageSpeedCoreMetrics": { "type": "object", "additionalProperties": false, "properties": { "statusCode": { "type": "integer", "format": "int32" }, "fetchTimeMs": { "type": ["integer", "null"], "format": "int64" }, "contentBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "contentType": { "type": "string" }, "compressed": { "type": "boolean" }, "imageCount": { "type": "integer", "format": "int32", "minimum": 0 }, "missingImageAlt": { "type": "integer", "format": "int32", "minimum": 0 }, "scriptCount": { "type": "integer", "format": "int32", "minimum": 0 }, "url": { "type": "string", "format": "uri" }, "firstContentfulPaintMs": { "type": ["integer", "null"], "format": "int64" }, "largestContentfulPaintMs": { "type": ["integer", "null"], "format": "int64" }, "totalBlockingTimeMs": { "type": ["integer", "null"], "format": "int64" }, "cumulativeLayoutShift": { "type": ["number", "null"], "format": "double" }, "speedIndexMs": { "type": ["integer", "null"], "format": "int64" }, "interactiveMs": { "type": ["integer", "null"], "format": "int64" } }, "required": ["statusCode", "fetchTimeMs", "contentBytes", "contentType", "compressed", "imageCount", "missingImageAlt", "scriptCount", "url", "firstContentfulPaintMs", "largestContentfulPaintMs", "totalBlockingTimeMs", "cumulativeLayoutShift", "speedIndexMs", "interactiveMs"] }, "PageSpeedScores": { "type": "object", "additionalProperties": false, "description": "Only requested categories are returned.", "properties": { "performance": { "type": "integer", "minimum": 0, "maximum": 100 }, "accessibility": { "type": "integer", "minimum": 0, "maximum": 100 }, "bestPractices": { "type": "integer", "minimum": 0, "maximum": 100 }, "seo": { "type": "integer", "minimum": 0, "maximum": 100 } } }, "PageSpeedAudit": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "passed": { "type": ["boolean", "null"] }, "value": { "type": "string" } }, "required": ["id", "title", "passed", "value"] }, "PageSpeedOpportunity": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "recommendation": { "type": "string" } }, "required": ["id", "title", "recommendation"] }, "LanguageDetectionRequest": { "type": "object", "additionalProperties": false, "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 100000, "description": "Text to analyze, limited to 100,000 Unicode characters and 512 KiB of UTF-8 data. Short or mixed-language text may produce lower-confidence results." } }, "required": ["content"] }, "LanguageDetectionCandidate": { "type": "object", "additionalProperties": false, "properties": { "Language": { "type": "string", "description": "English language name.", "example": "French" }, "LanguageAbbr": { "type": "string", "pattern": "^[a-z]{2}$", "description": "Two-letter language code.", "example": "fr" }, "Probability": { "type": "number", "format": "double", "minimum": 0, "maximum": 1, "description": "Relative confidence score for this candidate.", "example": 0.999996 } }, "required": ["Language", "LanguageAbbr", "Probability"] }, "LanguageDetectionDataStatus": { "allOf": [ { "$ref": "#/components/schemas/DataStatus" }, { "type": "object", "properties": { "requestParameter": { "type": "string", "description": "Text length metadata. The submitted text is never echoed.", "example": "content_chars=72,content_bytes=73" } } } ] }, "LanguageDetectionSuccessResponse": { "type": "object", "additionalProperties": false, "properties": { "dataStatus": { "$ref": "#/components/schemas/LanguageDetectionDataStatus" }, "data": { "type": "array", "description": "Language candidates ordered by descending probability.", "items": { "$ref": "#/components/schemas/LanguageDetectionCandidate" }, "minItems": 1 } }, "required": ["dataStatus", "data"] }, "SslCertificateData": { "type": "object", "additionalProperties": false, "properties": { "subjectDN": { "type": [ "string", "null" ] }, "issuerDN": { "type": [ "string", "null" ] }, "serialNumber": { "type": [ "string", "null" ] }, "validFrom": { "type": [ "string", "null" ] }, "validTo": { "type": [ "string", "null" ] }, "signatureAlgorithm": { "type": [ "string", "null" ] }, "publicKey": { "type": [ "string", "null" ] }, "extendedKeyUsage": { "type": [ "string", "null" ] }, "basicConstraints": { "type": [ "string", "null" ] }, "subjectAlternativeNames": { "type": [ "string", "null" ] }, "issuerAlternativeNames": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "signature": { "type": [ "string", "null" ] }, "publicKeyAlgorithm": { "type": [ "string", "null" ] }, "extensions": { "type": [ "string", "null" ] }, "keyUsage": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "description": "One certificate from the presented chain. Dates preserve the existing textual representation, not ISO 8601. Optional extension fields may be null." }, "SslCertificateSuccessResponse": { "type": "object", "required": [ "dataStatus", "data" ], "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/SslCertificateData" } } } }, "STConvertRequest": { "type": "object", "required": [ "content", "from", "to" ], "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 100000, "description": "Nonblank text, at most 100,000 Unicode code points and 512 KiB UTF-8. Spacing and Unicode presentation are not normalized.", "example": "简体中文" }, "from": { "type": "string", "enum": [ "s", "t" ], "description": "Source script. Send the canonical lowercase value s or t." }, "to": { "type": "string", "enum": [ "s", "t" ], "description": "Target script. Same source and target returns the original input." } } }, "STConvertSuccessResponse": { "type": "object", "required": [ "dataStatus", "data" ], "properties": { "dataStatus": { "type": "object", "required": [ "requestParameter", "statusCode", "statusDescription", "responseDateTime", "dataTotalCount" ], "properties": { "requestParameter": { "type": "string", "example": "contentLength=4&from=s&to=t" }, "statusCode": { "type": "integer", "const": 100 }, "statusDescription": { "type": "string", "example": "请求成功。" }, "responseDateTime": { "type": "string", "description": "Existing yyyy-MM-dd HH:mm:ss.SSS timestamp." }, "dataTotalCount": { "type": "integer", "const": 1 } } }, "data": { "type": "object", "required": [ "convertedContent" ], "additionalProperties": false, "properties": { "convertedContent": { "type": "string", "example": "簡體中文" } } } } }, "JsonSuccessResponse": { "type": "object", "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "description": "Primary response payload returned by the endpoint." } }, "required": [ "dataStatus", "data" ] }, "KnowledgeChatMessage": { "type": "object", "additionalProperties": false, "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant" ] }, "content": { "type": "string", "minLength": 1, "maxLength": 8000 } }, "required": [ "role", "content" ] }, "KnowledgeChatRequest": { "type": "object", "additionalProperties": false, "properties": { "model": { "type": "string", "const": "gugudata-knowledge-chat", "default": "gugudata-knowledge-chat" }, "messages": { "type": "array", "minItems": 1, "maxItems": 20, "description": "Complete client-managed conversation history. At least one user message is required, and total content is limited to 32,000 characters.", "items": { "$ref": "#/components/schemas/KnowledgeChatMessage" } }, "tenant_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "default": "default" }, "thread_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "description": "Optional request correlation identifier. It does not restore conversation history." }, "stream": { "type": "boolean", "default": false, "description": "Return incremental Server-Sent Events when true." }, "top_k": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 12, "default": 6 } }, "required": [ "messages" ], "example": { "model": "gugudata-knowledge-chat", "messages": [ { "role": "user", "content": "What is the refund period in the uploaded policy?" } ], "tenant_id": "default", "stream": false, "top_k": 6 } }, "KnowledgeSource": { "type": "object", "properties": { "document_id": { "type": "string" }, "source_name": { "type": "string" }, "location": { "type": "string" }, "score": { "type": "number", "format": "double" }, "text": { "type": "string" } }, "required": [ "document_id", "source_name", "location", "score", "text" ] }, "KnowledgeUsage": { "type": "object", "properties": { "top_k": { "type": "integer", "format": "int32" }, "source_count": { "type": "integer", "format": "int32" } }, "required": [ "top_k", "source_count" ] }, "KnowledgeChatChoice": { "type": "object", "properties": { "index": { "type": "integer", "format": "int32" }, "message": { "$ref": "#/components/schemas/KnowledgeChatMessage" }, "finish_reason": { "type": "string", "const": "stop" } }, "required": [ "index", "message", "finish_reason" ] }, "KnowledgeChatCompletion": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "chat.completion" }, "created": { "type": "integer", "format": "int64" }, "model": { "type": "string", "const": "gugudata-knowledge-chat" }, "choices": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeChatChoice" } }, "usage": { "$ref": "#/components/schemas/KnowledgeUsage" }, "thread_id": { "type": "string" }, "message_id": { "type": "string" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeSource" } } }, "required": [ "id", "object", "created", "model", "choices", "usage", "thread_id", "message_id", "sources" ] }, "KnowledgeChatStreamChunk": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "chat.completion.chunk" }, "created": { "type": "integer", "format": "int64" }, "model": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object" } }, "thread_id": { "type": "string" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeSource" } }, "usage": { "$ref": "#/components/schemas/KnowledgeUsage" } }, "required": [ "id", "object", "created", "model", "choices" ] }, "KnowledgeChatStream": { "type": "string", "description": "A sequence of data events containing KnowledgeChatStreamChunk objects. The final chunk includes thread_id, sources, usage, and finish_reason stop, followed by data: [DONE]." }, "KnowledgeDocumentResult": { "type": "object", "properties": { "document_id": { "type": "string" }, "file_name": { "type": "string" }, "status": { "type": "string", "enum": [ "ready", "duplicated" ] }, "chunk_count": { "type": "integer", "format": "int32" } }, "required": [ "document_id", "file_name", "status", "chunk_count" ] }, "KnowledgeUploadResponse": { "type": "object", "properties": { "knowledge_base_id": { "type": "string" }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeDocumentResult" } }, "ready_count": { "type": "integer", "format": "int32" }, "failed_count": { "type": "integer", "format": "int32" } }, "required": [ "knowledge_base_id", "documents", "ready_count", "failed_count" ] }, "InternationalPhoneFormatDataStatus": { "type": "object", "properties": { "requestParameter": { "type": "string", "description": "Privacy-masked phone parameter recorded for the request.", "pattern": "^phone=(\\+[0-9]+\\*+[0-9]{4}|\\[invalid\\])$", "example": "phone=+1******8900" }, "statusCode": { "type": "integer", "format": "int32", "const": 200 }, "status": { "type": "string", "const": "SUCCESS" }, "statusDescription": { "type": "string", "example": "successfully" }, "responseDateTime": { "type": "string", "description": "Response timestamp generated by the API.", "example": "2026-08-31 09:30:00.000" }, "dataTotalCount": { "type": "integer", "format": "int32", "const": 1 } }, "required": [ "requestParameter", "statusCode", "status", "statusDescription", "responseDateTime", "dataTotalCount" ], "additionalProperties": false }, "InternationalPhoneFormatData": { "type": "object", "description": "Phone format and numbering-plan validation result.", "properties": { "isValid": { "type": "boolean", "description": "Whether the number is valid under the applicable numbering plan.", "example": true }, "correctedMobileNumber": { "type": "string", "description": "Validated number in E.164 format, or an empty string when invalid.", "pattern": "^(\\+[1-9][0-9]{1,14})?$", "example": "+18175698900" }, "countryCode": { "type": "string", "description": "International calling code, including the leading plus sign, when determinable.", "pattern": "^(\\+[1-9][0-9]{0,2})?$", "example": "+1" }, "countryCode2": { "type": "string", "description": "ISO 3166-1 alpha-2 region code, or an empty string for invalid or non-geographic numbers.", "pattern": "^([A-Z]{2})?$", "example": "US" }, "countryCode3": { "type": "string", "description": "ISO 3166-1 alpha-3 region code, or an empty string for invalid or non-geographic numbers.", "pattern": "^([A-Z]{3})?$", "example": "USA" } }, "required": [ "isValid", "correctedMobileNumber", "countryCode", "countryCode2", "countryCode3" ], "additionalProperties": false }, "InternationalPhoneFormatSuccessResponse": { "type": "object", "properties": { "dataStatus": { "$ref": "#/components/schemas/InternationalPhoneFormatDataStatus" }, "data": { "$ref": "#/components/schemas/InternationalPhoneFormatData" } }, "required": [ "dataStatus", "data" ], "additionalProperties": false }, "IpLocationDataStatus": { "type": "object", "properties": { "requestParameter": { "type": "string", "description": "Privacy-masked address for authenticated requests, or the public fixture address for the Demo.", "examples": [ "ip=8.8.*.*", "ip=2001:4860:4860:0000::/64", "ip=8.8.8.8" ] }, "statusCode": { "type": "integer", "format": "int32", "const": 200 }, "status": { "type": "string", "const": "SUCCESS" }, "statusDescription": { "type": "string", "example": "successfully" }, "responseDateTime": { "type": "string", "description": "Response timestamp generated by the API.", "example": "2026-08-31 13:22:04+0000" }, "dataTotalCount": { "type": "integer", "format": "int32", "const": 1 } }, "required": [ "requestParameter", "statusCode", "status", "statusDescription", "responseDateTime", "dataTotalCount" ], "additionalProperties": false }, "IpLocationData": { "type": "object", "description": "Approximate network geolocation. Every field is null when a valid public address has no record in the current dataset.", "properties": { "countryCode": { "type": ["string", "null"], "description": "ISO 3166-1 alpha-2 country code when available.", "pattern": "^[A-Z]{2}$", "example": "US" }, "state": { "type": ["string", "null"], "description": "English first-level administrative area name when available.", "example": "California" }, "city": { "type": ["string", "null"], "description": "English city name when available.", "example": "Mountain View" }, "latitude": { "type": ["number", "null"], "format": "double", "minimum": -90, "maximum": 90, "description": "Approximate latitude when available.", "example": 37.386 }, "longitude": { "type": ["number", "null"], "format": "double", "minimum": -180, "maximum": 180, "description": "Approximate longitude when available.", "example": -122.0838 } }, "required": [ "countryCode", "state", "city", "latitude", "longitude" ], "additionalProperties": false }, "IpLocationSuccessResponse": { "type": "object", "properties": { "dataStatus": { "$ref": "#/components/schemas/IpLocationDataStatus" }, "data": { "$ref": "#/components/schemas/IpLocationData" } }, "required": ["dataStatus", "data"], "additionalProperties": false }, "FetchContentImage": { "type": "object", "properties": { "src": { "type": "string", "description": "Image source as it appeared in extracted metadata or readable content." }, "absoluteUrl": { "type": "string", "format": "uri", "description": "Final absolute HTTP or HTTPS image URL resolved against the final article URL." }, "alt": { "type": "string", "description": "Image alternative text, or an empty string when unavailable." }, "width": { "type": [ "string", "null" ], "description": "Declared image width retained as a string, or null when unavailable." }, "height": { "type": [ "string", "null" ], "description": "Declared image height retained as a string, or null when unavailable." } }, "required": [ "src", "absoluteUrl", "alt", "width", "height" ], "additionalProperties": false }, "FetchContentData": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Final article URL after HTTP redirects." }, "title": { "type": "string", "description": "Article title, or an empty string when unavailable." }, "description": { "type": "string", "description": "Article description, or an empty string when unavailable." }, "content": { "type": "string", "description": "Cleaned readable article HTML." }, "contentText": { "type": "string", "description": "Plain article text with paragraph boundaries represented by line breaks." }, "image": { "type": "string", "description": "Primary absolute image URL, or an empty string when unavailable." }, "images": { "type": "array", "description": "Deduplicated image candidates ordered by primary image, extracted metadata, and readable content.", "items": { "$ref": "#/components/schemas/FetchContentImage" } }, "author": { "type": "string", "description": "Article author, or an empty string when unavailable." }, "published": { "type": "string", "description": "Normalized publication time when available, typically YYYY-MM-DD HH:mm." }, "source": { "type": "string", "description": "Final article hostname." } }, "required": [ "url", "title", "description", "content", "contentText", "image", "images", "author", "published", "source" ], "additionalProperties": false }, "FetchContentSuccessResponse": { "type": "object", "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "$ref": "#/components/schemas/FetchContentData" } }, "required": [ "dataStatus", "data" ], "additionalProperties": false }, "FetchContentImagesImage": { "type": "object", "properties": { "src": { "type": "string", "description": "Selected image source from article metadata or readable content." }, "absoluteUrl": { "type": "string", "format": "uri", "description": "Absolute HTTP or HTTPS image URL resolved against the final article URL." }, "alt": { "type": "string", "description": "Image alternative text, or an empty string when unavailable." }, "width": { "type": [ "string", "null" ], "description": "Declared image width retained as a string, or null when unavailable." }, "height": { "type": [ "string", "null" ], "description": "Declared image height retained as a string, or null when unavailable." } }, "required": [ "src", "absoluteUrl", "alt", "width", "height" ], "additionalProperties": false }, "FetchContentImagesData": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Final article URL after HTTP redirects." }, "images": { "type": "array", "description": "Deduplicated image candidates ordered by primary image and readable article DOM order. The array is empty when extraction succeeds without image candidates.", "items": { "$ref": "#/components/schemas/FetchContentImagesImage" } } }, "required": [ "url", "images" ], "additionalProperties": false }, "FetchContentImagesSuccessResponse": { "type": "object", "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "$ref": "#/components/schemas/FetchContentImagesData" } }, "required": [ "dataStatus", "data" ], "additionalProperties": false }, "HkStockSymbolsDataStatus": { "type": "object", "properties": { "requestParameter": { "type": "string", "description": "Normalized search and pagination parameters without the application key.", "examples": [ "query=00700&pageindex=1&pagesize=20" ] }, "statusCode": { "type": "integer", "format": "int32", "description": "Application-level response code.", "examples": [ 100 ] }, "statusDescription": { "type": "string", "description": "Application-level response description.", "examples": [ "Request succeeded" ] }, "responseDateTime": { "type": "string", "description": "Response timestamp in server local time with milliseconds.", "pattern": "^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}\\.\\d{3}$", "examples": [ "2026-08-27 10:57:00.000" ] }, "dataTotalCount": { "type": "integer", "format": "int64", "minimum": 0, "description": "Total number of active records matching the normalized query." } }, "required": [ "requestParameter", "statusCode", "statusDescription", "responseDateTime", "dataTotalCount" ], "additionalProperties": false }, "HkStockSymbol": { "type": "object", "properties": { "symbol": { "type": "string", "pattern": "^\\d{5}$", "description": "Five-digit Hong Kong-listed security symbol.", "examples": [ "00700" ] }, "stockName": { "type": "string", "description": "Exchange English short name.", "examples": [ "TENCENT" ] }, "stockChineseName": { "type": "string", "description": "Chinese display name.", "examples": [ "腾讯控股" ] } }, "required": [ "symbol", "stockName", "stockChineseName" ], "additionalProperties": false }, "HkStockSymbolsSuccessResponse": { "type": "object", "properties": { "dataStatus": { "$ref": "#/components/schemas/HkStockSymbolsDataStatus" }, "data": { "type": "array", "description": "Active Hong Kong-listed security records ordered by symbol. The array is empty when no records match.", "items": { "$ref": "#/components/schemas/HkStockSymbol" } } }, "required": [ "dataStatus", "data" ], "additionalProperties": false }, "FaviconData": { "type": "object", "properties": { "title": { "type": "string", "description": "Website title, or an empty string when the page does not provide one." }, "favicon": { "type": [ "string", "null" ], "format": "uri", "description": "Verified public favicon URL, or null when no usable website icon is available." }, "description": { "type": "string", "description": "Website meta description, or an empty string when unavailable." }, "keywords": { "type": "string", "description": "Website meta keywords, or an empty string when unavailable." } }, "required": [ "title", "favicon", "description", "keywords" ], "additionalProperties": false }, "FaviconSuccessResponse": { "type": "object", "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "$ref": "#/components/schemas/FaviconData" } }, "required": [ "dataStatus", "data" ], "additionalProperties": false }, "DnsRecord": { "type": "object", "description": "One DNS resource record.", "properties": { "domain": { "type": "string", "description": "Absolute owner name of the record.", "example": "gugudata.io." }, "ttl": { "type": "string", "pattern": "^\\d+$", "description": "Record time to live in seconds, returned as a string for compatibility.", "example": "300" }, "class": { "type": "string", "description": "DNS record class.", "example": "IN" }, "type": { "type": "string", "description": "DNS record type.", "enum": [ "A", "AAAA", "MX", "TXT", "NS", "CNAME", "SRV", "SOA" ] }, "value": { "type": "string", "description": "Complete record value. Multi-field MX, SRV, and SOA records retain every field, and multi-part TXT values are joined in their original order.", "example": "11 route3.mx.cloudflare.net." } }, "required": [ "domain", "ttl", "class", "type", "value" ], "additionalProperties": false }, "DnsLookupRecordGroups": { "type": "object", "description": "DNS records grouped by record type. Groups without records are omitted; a valid nonexistent domain returns an empty object.", "propertyNames": { "enum": [ "A", "AAAA", "MX", "TXT", "NS", "CNAME", "SRV", "SOA" ] }, "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/DnsRecord" } } }, "DnsLookupSuccessResponse": { "type": "object", "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "$ref": "#/components/schemas/DnsLookupRecordGroups" } }, "required": [ "dataStatus", "data" ], "additionalProperties": false }, "CoordinateConverterData": { "type": "object", "properties": { "coordinateFrom": { "type": "string", "description": "Normalized source coordinate system.", "enum": [ "WGS84", "GCJ02", "BD09" ] }, "coordinateTo": { "type": "string", "description": "Normalized target coordinate system.", "enum": [ "WGS84", "GCJ02", "BD09" ] }, "coordinateSourceValue": { "type": "string", "description": "Source coordinate pair supplied by the caller.", "example": "[120.54,32.74]" }, "coordinateDestinationValue": { "type": "string", "description": "Converted coordinate pair in longitude-latitude order with six decimal places.", "pattern": "^\\[-?\\d+\\.\\d{6},-?\\d+\\.\\d{6}\\]$", "example": "[120.544394,32.737947]" } }, "required": [ "coordinateFrom", "coordinateTo", "coordinateSourceValue", "coordinateDestinationValue" ], "additionalProperties": false }, "CoordinateConverterSuccessResponse": { "type": "object", "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "$ref": "#/components/schemas/CoordinateConverterData" } }, "required": [ "dataStatus", "data" ], "additionalProperties": false }, "BarcodeData": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "CDN URL of the generated PNG barcode image." } }, "required": [ "url" ], "additionalProperties": false }, "BarcodeSuccessResponse": { "type": "object", "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "$ref": "#/components/schemas/BarcodeData" } }, "required": [ "dataStatus", "data" ] }, "ChinesePoemData": { "type": "object", "properties": { "title": { "type": "string", "description": "Title of the poem or rhythmic title of the lyric." }, "author": { "type": "string", "description": "Author name." }, "content": { "type": "array", "description": "Poem or lyric content split into lines.", "items": { "type": "string" } }, "type": { "type": "string", "description": "Dataset type returned as a Chinese label.", "enum": [ "唐诗", "宋诗", "宋词" ] } }, "required": [ "title", "author", "content", "type" ], "additionalProperties": false }, "ChinesePoemSuccessResponse": { "type": "object", "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChinesePoemData" } } }, "required": [ "dataStatus", "data" ] }, "ArticleParserOptions": { "type": "object", "properties": { "wordsPerMinute": { "type": "integer", "minimum": 50, "maximum": 1000 }, "descriptionTruncateLen": { "type": "integer", "minimum": 1, "maximum": 2000 }, "descriptionLengthThreshold": { "type": "integer", "minimum": 0, "maximum": 2000 }, "contentLengthThreshold": { "type": "integer", "minimum": 1, "maximum": 100000 } }, "additionalProperties": false }, "ArticleFetchOptions": { "type": "object", "properties": { "timeoutMs": { "type": "integer", "minimum": 1000, "maximum": 30000 }, "headers": { "type": "object", "description": "Optional safe request headers forwarded to the public article URL.", "properties": { "user-agent": { "type": "string", "maxLength": 512 }, "accept": { "type": "string", "maxLength": 512 }, "accept-language": { "type": "string", "maxLength": 512 } }, "additionalProperties": false } }, "additionalProperties": false }, "ArticleExtractData": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "links": { "type": "array", "items": { "type": "string" } }, "image": { "type": "string" }, "content": { "type": "string" }, "author": { "type": "string" }, "favicon": { "type": "string" }, "source": { "type": "string" }, "published": { "type": "string" }, "ttr": { "type": "integer" }, "type": { "type": "string" } }, "required": [ "url", "title", "content" ] }, "ArticleExtractSuccessResponse": { "type": "object", "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "$ref": "#/components/schemas/ArticleExtractData" } }, "required": [ "dataStatus", "data" ] }, "ImageCompressOptions": { "type": "object", "properties": { "targetWidth": { "type": "integer", "minimum": 1, "maximum": 8192, "description": "Optional width bound in pixels. Aspect ratio is preserved and smaller sources are not enlarged." }, "targetHeight": { "type": "integer", "minimum": 1, "maximum": 8192, "description": "Optional height bound in pixels. Aspect ratio is preserved and smaller sources are not enlarged." }, "maxWidth": { "type": "integer", "minimum": 1, "maximum": 8192, "description": "Maximum output width in pixels while preserving aspect ratio." }, "maxHeight": { "type": "integer", "minimum": 1, "maximum": 8192, "description": "Maximum output height in pixels while preserving aspect ratio." }, "quality": { "type": "integer", "minimum": 1, "maximum": 95, "default": 85, "description": "JPEG or WebP output quality. PNG output remains lossless." }, "format": { "type": "string", "enum": [ "jpeg", "jpg", "png", "webp" ], "description": "Optional output format. When omitted, the supported source format is retained." } } }, "ImageCompressMultipartRequest": { "unevaluatedProperties": false, "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ImageCompressOptions" }, { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "JPEG, PNG, or WebP file up to 10 MiB." } }, "required": [ "file" ] } ] }, { "allOf": [ { "$ref": "#/components/schemas/ImageCompressUrlRequest" } ] } ] }, "ImageCompressUrlRequest": { "unevaluatedProperties": false, "allOf": [ { "$ref": "#/components/schemas/ImageCompressOptions" }, { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Complete public HTTP or HTTPS URL of a JPEG, PNG, or WebP image.", "example": "https://cdn.gugudata.io/api-fixtures/image-compress-source.jpg" } }, "required": [ "image_url" ] } ] }, "HtmlToWordRequest": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "html", "url" ], "description": "Input mode. Use html for HTML markup or url for a complete public HTTP/HTTPS page URL.", "example": "html" }, "content": { "type": "string", "description": "HTML markup up to 5 MiB when type is html, or a complete public HTTP/HTTPS URL up to 2048 characters when type is url.", "example": "

Quarterly report

Prepared for review.

" }, "filename": { "type": "string", "maxLength": 128, "pattern": "^[^/\\\\\\u0000-\\u001F\\u007F]+(?:\\.docx)?$", "description": "Optional output filename. The .docx extension is added when omitted.", "example": "quarterly-report.docx" } }, "required": [ "type", "content" ] }, "HtmlToWordData": { "type": "object", "additionalProperties": false, "properties": { "wordPath": { "type": "string", "format": "uri", "description": "Public HTTPS URL of the generated DOCX file.", "example": "https://storage.gugudata.io/html2word/6ae8b0dd-66bb-4bfc-b685-06746b76145d-quarterly-report.docx" } }, "required": [ "wordPath" ] }, "HtmlToWordSuccessResponse": { "type": "object", "additionalProperties": false, "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "$ref": "#/components/schemas/HtmlToWordData" } }, "required": [ "dataStatus", "data" ] }, "HtmlToPdfData": { "type": "object", "additionalProperties": false, "properties": { "pdfPath": { "type": "string", "format": "uri", "description": "Public HTTPS URL of the generated PDF file.", "example": "https://storage.gugudata.io/pdf/86bb28cb-0e7d-4105-a080-6c5c2fe4c451.pdf" } }, "required": [ "pdfPath" ] }, "HtmlToPdfSuccessResponse": { "type": "object", "additionalProperties": false, "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "$ref": "#/components/schemas/HtmlToPdfData" } }, "required": [ "dataStatus", "data" ] }, "MarkdownToPdfRequest": { "type": "object", "additionalProperties": false, "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 100000, "description": "Markdown source. UTF-8 input must not exceed 512 KiB.", "example": "# Quarterly update\n\n- Revenue increased\n- Support response time improved\n\n| Metric | Result |\n| --- | --- |\n| Availability | 99.95% |" } }, "required": [ "content" ] }, "MarkdownToPdfData": { "type": "object", "additionalProperties": false, "properties": { "pdfPath": { "type": "string", "format": "uri", "description": "Public HTTPS URL of the generated PDF file.", "example": "https://storage.gugudata.io/markdown2pdf/86bb28cb-0e7d-4105-a080-6c5c2fe4c451.pdf" } }, "required": [ "pdfPath" ] }, "MarkdownToPdfSuccessResponse": { "type": "object", "additionalProperties": false, "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "$ref": "#/components/schemas/MarkdownToPdfData" } }, "required": [ "dataStatus", "data" ] }, "OcrData": { "type": "object", "additionalProperties": false, "properties": { "resultText": { "type": "array", "description": "Recognized non-empty text lines in reading order.", "items": { "type": "string" }, "example": [ "GUGUDATA", "DATA PAY LESS" ] }, "text": { "type": "string", "description": "Recognized text joined as plain text. An image without recognized text returns an empty string.", "example": "GUGUDATA\nDATA PAY LESS" } }, "required": [ "resultText", "text" ] }, "OcrSuccessResponse": { "type": "object", "additionalProperties": false, "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "$ref": "#/components/schemas/OcrData" } }, "required": [ "dataStatus", "data" ] }, "OcrToWordData": { "type": "object", "additionalProperties": false, "properties": { "wordPath": { "type": "string", "format": "uri", "description": "Public HTTPS URL of the generated Word document.", "example": "https://storage.gugudata.io/ocr2word/55a4346b-receipt-notes.docx" } }, "required": [ "wordPath" ] }, "OcrToWordSuccessResponse": { "type": "object", "additionalProperties": false, "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "$ref": "#/components/schemas/OcrToWordData" } }, "required": [ "dataStatus", "data" ] }, "ErrorResponse": { "type": "object", "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "type": "null" } }, "required": [ "dataStatus", "data" ] }, "PdfFormatRequest": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "html", "text", "txt", "markdown", "md", "json" ] }, "pdffile": { "type": "string", "format": "binary", "description": "PDF upload. Maximum 20 MiB and 100 pages." }, "file": { "type": "string", "format": "binary", "description": "Legacy alias for pdffile." }, "file_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Public HTTP(S) PDF URL." } }, "oneOf": [ { "required": [ "pdffile" ], "not": { "anyOf": [ { "required": [ "file" ] }, { "required": [ "file_url" ] } ] } }, { "required": [ "file" ], "not": { "anyOf": [ { "required": [ "pdffile" ] }, { "required": [ "file_url" ] } ] } }, { "required": [ "file_url" ], "not": { "anyOf": [ { "required": [ "file" ] }, { "required": [ "pdffile" ] } ] } } ] }, "PdfFormatSuccessResponse": { "type": "object", "required": [ "dataStatus", "data" ], "properties": { "dataStatus": { "$ref": "#/components/schemas/DataStatus" }, "data": { "type": "object", "required": [ "result" ], "additionalProperties": false, "properties": { "result": { "type": "string", "description": "Inline formatted text. For type=json, parse this string to obtain the pages object." } } } } }, "PptImagesErrorResponse": { "type": "object", "required": [ "dataStatus", "data" ], "properties": { "data": { "type": "null" }, "dataStatus": { "type": "object", "required": [ "statusCode", "statusDescription" ], "properties": { "statusCode": { "type": "integer", "enum": [ 400, 500 ] }, "status": { "type": "string" }, "statusDescription": { "type": "string" }, "requestParameter": { "type": "string" }, "responseDateTime": { "type": "string" }, "dataTotalCount": { "type": "integer", "const": 0 } } } } }, "PptImagesRequest": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "PPT/PPTX, maximum 20 MiB and 50 slides." }, "file_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Public HTTP(S) presentation URL, mutually exclusive with file." }, "scale_factor": { "type": "integer", "default": 1, "description": "Integers below 1 use 1; above 4 use 4. Maximum 8192 pixels per side, 32 million pixels per image, 100 MiB total." } }, "oneOf": [ { "required": [ "file" ], "not": { "required": [ "file_url" ] } }, { "required": [ "file_url" ], "not": { "required": [ "file" ] } } ] }, "PptImagesDataStatus": { "type": "object", "required": [ "requestParameter", "statusCode", "statusDescription", "responseDateTime", "dataTotalCount" ], "properties": { "requestParameter": { "type": "string", "example": "source=upload&scale_factor=1&bytes=33355&slides=4" }, "statusCode": { "type": "integer", "const": 200 }, "status": { "type": "string", "const": "SUCCESS" }, "statusDescription": { "type": "string" }, "responseDateTime": { "type": "string", "example": "2026-09-06 06:34:26+0000" }, "dataTotalCount": { "type": "integer", "const": 1 } } }, "PptImagesSuccessResponse": { "type": "object", "required": [ "dataStatus", "data" ], "properties": { "dataStatus": { "$ref": "#/components/schemas/PptImagesDataStatus" }, "data": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "format": "uri", "pattern": "^https://" }, "description": "Public PNG URLs in source order, including hidden and blank slides. Save files you need to keep." } } } }, "responses": { "FaviconHttp502": { "description": "The target website timed out, refused the request, returned non-HTML content, or returned an invalid response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "dataStatus": { "requestParameter": "url=https://example.com/", "statusCode": 500, "status": "FAILED", "statusDescription": "The target website could not be fetched.", "responseDateTime": "2026-08-25 08:00:00+0000", "dataTotalCount": 0 }, "data": null } } } }, "FaviconHttp503": { "description": "The website metadata capability is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "dataStatus": { "requestParameter": "url=https://example.com/", "statusCode": 500, "status": "FAILED", "statusDescription": "Website metadata service is unavailable.", "responseDateTime": "2026-08-25 08:00:00+0000", "dataTotalCount": 0 }, "data": null } } } }, "Http400": { "description": "Invalid request parameters or request format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "summary": "Invalid request parameters or request format.", "value": { "dataStatus": { "statusCode": 400, "status": "FAILED", "statusDescription": "Invalid request parameters or request format.", "responseDateTime": "2026-04-10 00:00:00+0000", "dataTotalCount": 0, "requestParameter": "" }, "data": null } } } } } }, "Http401": { "description": "Missing or unknown application key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "summary": "Missing or unknown application key.", "value": { "dataStatus": { "statusCode": 401, "status": "FAILED", "statusDescription": "Missing or unknown application key.", "responseDateTime": "2026-04-10 00:00:00+0000", "dataTotalCount": 0, "requestParameter": "" }, "data": null } } } } } }, "Http403": { "description": "The application key is recognized but access is not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "summary": "The application key is recognized but access is not allowed.", "value": { "dataStatus": { "statusCode": 403, "status": "FAILED", "statusDescription": "The application key is recognized but access is not allowed.", "responseDateTime": "2026-04-10 00:00:00+0000", "dataTotalCount": 0, "requestParameter": "" }, "data": null } } } } } }, "Http404": { "description": "The requested resource was not found or is not accessible with the supplied credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "dataStatus": { "statusCode": 404, "status": "FAILED", "statusDescription": "The requested document was not found.", "responseDateTime": "2026-08-31 00:00:00+0000", "dataTotalCount": 0, "requestParameter": "" }, "data": null } } } }, "Http413": { "description": "The request or uploaded file exceeds the supported size.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "dataStatus": { "statusCode": 413, "status": "FAILED", "statusDescription": "The knowledge request exceeds the supported size.", "responseDateTime": "2026-08-31 00:00:00+0000", "dataTotalCount": 0, "requestParameter": "" }, "data": null } } } }, "Http422": { "description": "The input was valid but could not be converted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "dataStatus": { "statusCode": 500, "status": "FAILED", "statusDescription": "The content could not be converted.", "responseDateTime": "2026-08-28 00:00:00+0000", "dataTotalCount": 0, "requestParameter": "type=html&content_length=42" }, "data": null } } } }, "MarkdownToPdfHttp422": { "description": "The Markdown input was accepted but could not be rendered as a valid PDF.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "dataStatus": { "statusCode": 500, "status": "FAILED", "statusDescription": "The Markdown content could not be rendered as a valid PDF.", "responseDateTime": "2026-09-01 00:00:00+0000", "dataTotalCount": 0, "requestParameter": "content_length=133,content_bytes=133" }, "data": null } } } }, "Http429": { "description": "Request rate or trial usage limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "summary": "Request rate or trial usage limit exceeded.", "value": { "dataStatus": { "statusCode": 429, "status": "FAILED", "statusDescription": "Request rate or trial usage limit exceeded.", "responseDateTime": "2026-04-10 00:00:00+0000", "dataTotalCount": 0, "requestParameter": "" }, "data": null } } } } } }, "Http500": { "description": "Internal service error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "summary": "Internal service error.", "value": { "dataStatus": { "statusCode": 500, "status": "FAILED", "statusDescription": "Internal service error.", "responseDateTime": "2026-04-10 00:00:00+0000", "dataTotalCount": 0, "requestParameter": "" }, "data": null } } } } } }, "Http502": { "description": "The requested external resource could not be fetched.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "dataStatus": { "statusCode": 500, "status": "FAILED", "statusDescription": "The source page could not be fetched.", "responseDateTime": "2026-08-28 00:00:00+0000", "dataTotalCount": 0, "requestParameter": "type=url&url_host=example.com&url_path=/article" }, "data": null } } } }, "Http503": { "description": "Upstream service unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "summary": "Upstream service unavailable.", "value": { "dataStatus": { "statusCode": 503, "status": "FAILED", "statusDescription": "Upstream service unavailable.", "responseDateTime": "2026-04-10 00:00:00+0000", "dataTotalCount": 0, "requestParameter": "" }, "data": null } } } } } } } } }