{"openapi":"3.1.0","info":{"version":"2.0.0","title":"ScrapeGraphAI API","description":"ScrapeGraphAI v2 HTTP API."},"servers":[{"url":"/"}],"x-service-info":{"categories":["web-scraping","data-extraction","search"],"docs":{"homepage":"https://scrapegraphai.com","apiReference":"https://docs.scrapegraphai.com","llms":"https://docs.scrapegraphai.com/llms.txt"}},"components":{"schemas":{"ServiceCard":{"type":"object","properties":{"service":{"type":"string"},"docs":{"type":"string"},"openapi":{"type":"string"},"protocols":{"type":"string"},"odp":{"type":"string"},"aep":{"type":"string"}},"required":["service","docs","openapi","protocols"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","example":"validation"},"message":{"type":"string","example":"Validation failed"},"details":{"nullable":true}},"required":["type","message"]}},"required":["error"]},"CreditPackPurchaseResponse":{"type":"object","properties":{"pack":{"type":"string","example":"small"},"credits":{"type":"number","example":1000},"remaining":{"type":"number","example":1500}},"required":["pack","credits","remaining"]},"AgentProtocolsResponse":{"type":"object","properties":{"service":{"type":"string"},"payment":{"type":"object","properties":{"protocol":{"type":"string"},"scheme":{"type":"string"},"methods":{"type":"array","items":{"type":"string"}},"currency":{"type":"string"}},"required":["protocol","scheme","methods","currency"]},"access":{"type":"object","additionalProperties":{"type":"object","properties":{"method":{"type":"string"},"endpoint":{"type":"string"},"description":{"type":"string"}},"required":["method","endpoint","description"]}},"packs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"priceUsdc":{"type":"number"},"credits":{"type":"number"}},"required":["id","name","priceUsdc","credits"]}},"subscriptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"planId":{"type":"string","enum":["starter","growth","pro"]},"name":{"type":"string"},"billingPeriod":{"type":"string","enum":["monthly","yearly"]},"priceUsdc":{"type":"string"},"creditsPerMonth":{"type":"number"},"creditsPerPeriod":{"type":"number"},"endpoint":{"type":"string"}},"required":["id","planId","name","billingPeriod","priceUsdc","creditsPerMonth","creditsPerPeriod","endpoint"]}},"docs":{"type":"object","properties":{"apiReference":{"type":"string"},"openapi":{"type":"string"}},"required":["apiReference","openapi"]}},"required":["service","payment","access","packs","subscriptions","docs"]},"AgentAccessResponse":{"type":"object","properties":{"apiKey":{"type":"string","example":"sgai-1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"},"pack":{"type":"string","example":"small"},"credits":{"type":"number","example":1000},"remaining":{"type":"number","example":1000},"account":{"type":"string","enum":["created","existing"],"example":"created"}},"required":["apiKey","pack","credits","remaining","account"]},"AgentSubscriptionResponse":{"type":"object","properties":{"apiKey":{"type":"string","example":"sgai-1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"},"subscriptionId":{"type":"string"},"plan":{"type":"string","enum":["starter","growth","pro"],"example":"starter"},"billingPeriod":{"type":"string","enum":["monthly","yearly"]},"creditsPerMonth":{"type":"number","example":10000},"creditsPerPeriod":{"type":"number","example":120000},"remaining":{"type":"number","example":10000},"renewed":{"type":"boolean"},"paidThrough":{"type":"string","nullable":true}},"required":["apiKey","subscriptionId","plan","billingPeriod","creditsPerMonth","creditsPerPeriod","remaining","renewed","paidThrough"]},"AepDocument":{"type":"object","properties":{"aep_version":{"type":"string"}},"required":["aep_version"]},"DidDocument":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}},"parameters":{},"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"SGAI-APIKEY","x-aep-authentication-method":"api-key"}}},"paths":{"/":{"get":{"tags":["agent"],"summary":"Service card","description":"Where to find the docs, OpenAPI, and agent discovery documents.","responses":{"200":{"description":"Service card","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceCard"}}}}}}},"/api/jobs/monitor":{"post":{"tags":["internal"],"summary":"Internal: monitor tick worker","description":"Invoked by QStash per-cron schedule. Authenticated via X-Internal-Secret or Upstash-Signature.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"cronId":{"type":"string"},"prevId":{"type":"string","nullable":true},"userId":{"type":"string"},"workspaceId":{"type":"string"},"apiKeyId":{"type":"string","nullable":true},"config":{"type":"object","properties":{"url":{"type":"string"},"name":{"type":"string","maxLength":200},"formats":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["markdown"]}},"required":["type"]},{"type":"object","properties":{"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["html"]}},"required":["type"]},{"type":"object","properties":{"fullPage":{"type":"boolean","default":false},"width":{"type":"integer","minimum":320,"maximum":3840,"default":1440},"height":{"type":"integer","minimum":200,"maximum":2160,"default":900},"quality":{"type":"integer","minimum":1,"maximum":100,"default":80},"type":{"type":"string","enum":["screenshot"]}},"required":["type"]},{"type":"object","properties":{"prompt":{"type":"string","maxLength":10000,"default":""},"schema":{"type":"object","additionalProperties":{"nullable":true}},"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["json"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["links"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["images"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["summary"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["branding"]}},"required":["type"]}]},"minItems":1,"default":[{"type":"markdown","mode":"normal"}]},"webhookUrl":{"type":"string"},"interval":{"type":"string","minLength":1,"maxLength":100},"fetchConfig":{"type":"object","properties":{"mode":{"type":"string","enum":["auto","fast","js"],"default":"auto"},"stealth":{"type":"boolean","default":false},"shadowDom":{"type":"boolean","default":true},"timeout":{"type":"integer","minimum":1000,"maximum":300000,"default":60000},"wait":{"type":"integer","minimum":0,"maximum":30000,"default":0},"headers":{"type":"object","additionalProperties":{"type":"string"}},"cookies":{"type":"object","additionalProperties":{"type":"string"}},"country":{"type":"string","minLength":2,"maxLength":2},"scrolls":{"type":"integer","minimum":0,"maximum":100,"default":0}},"default":{}}},"required":["url","interval"]}},"required":["cronId","prevId","userId","workspaceId","apiKeyId","config"]}}}},"responses":{"200":{"description":"Tick processed","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"changed":{"type":"boolean"},"reason":{"type":"string"},"error":{"type":"string"}},"required":["ok"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/jobs/crawl":{"post":{"tags":["internal"],"summary":"Internal: crawl batch worker","description":"Invoked by QStash or our internal worker loop. Authenticated via X-Internal-Secret or Upstash-Signature.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"crawlId":{"type":"string"},"urls":{"type":"array","items":{"type":"string"}},"depth":{"type":"integer"},"parentUrl":{"type":"string","nullable":true},"config":{"type":"object","properties":{"url":{"type":"string"},"formats":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["markdown"]}},"required":["type"]},{"type":"object","properties":{"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["html"]}},"required":["type"]},{"type":"object","properties":{"fullPage":{"type":"boolean","default":false},"width":{"type":"integer","minimum":320,"maximum":3840,"default":1440},"height":{"type":"integer","minimum":200,"maximum":2160,"default":900},"quality":{"type":"integer","minimum":1,"maximum":100,"default":80},"type":{"type":"string","enum":["screenshot"]}},"required":["type"]},{"type":"object","properties":{"prompt":{"type":"string","maxLength":10000,"default":""},"schema":{"type":"object","additionalProperties":{"nullable":true}},"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["json"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["links"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["images"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["summary"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["branding"]}},"required":["type"]}]},"minItems":1,"default":[{"type":"markdown","mode":"normal"}]},"maxDepth":{"type":"integer","nullable":true,"minimum":0,"default":2},"maxPages":{"type":"integer","minimum":1,"maximum":1000,"default":50},"maxLinksPerPage":{"type":"integer","minimum":1,"default":10},"allowExternal":{"type":"boolean","default":false},"includePatterns":{"type":"array","items":{"type":"string"}},"excludePatterns":{"type":"array","items":{"type":"string"}},"allowedTypes":{"type":"array","items":{"type":"string","enum":["text/html","application/json","text/markdown","text/plain","text/csv","application/x-latex","application/pdf","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.presentationml.presentation","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","image/jpeg","image/png","image/webp","image/gif","image/avif","image/tiff","image/heic","image/bmp","application/epub+zip","application/rtf","application/vnd.oasis.opendocument.text"]},"minItems":1,"default":["text/html","application/json","text/markdown","text/plain","text/csv","application/x-latex","application/pdf","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.presentationml.presentation","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","image/jpeg","image/png","image/webp","image/gif","image/avif","image/tiff","image/heic","image/bmp","application/epub+zip","application/rtf","application/vnd.oasis.opendocument.text"]},"processors":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["pdf"]},"maxPages":{"anyOf":[{"type":"number","enum":[-1]},{"type":"integer","minimum":1,"maximum":500}],"default":25}},"required":["type"]},"minItems":1,"default":[{"type":"pdf","maxPages":25}]},"fetchConfig":{"type":"object","properties":{"mode":{"type":"string","enum":["auto","fast","js"],"default":"auto"},"stealth":{"type":"boolean","default":false},"shadowDom":{"type":"boolean","default":true},"timeout":{"type":"integer","minimum":1000,"maximum":300000,"default":60000},"wait":{"type":"integer","minimum":0,"maximum":30000,"default":0},"headers":{"type":"object","additionalProperties":{"type":"string"}},"cookies":{"type":"object","additionalProperties":{"type":"string"}},"country":{"type":"string","minLength":2,"maxLength":2},"scrolls":{"type":"integer","minimum":0,"maximum":100,"default":0}},"default":{}}},"required":["url"]},"userId":{"type":"string"},"workspaceId":{"type":"string"},"apiKeyId":{"type":"string","nullable":true},"sessionId":{"type":"string","minLength":1,"maxLength":128}},"required":["crawlId","urls","depth","parentUrl","config","userId","workspaceId","apiKeyId"]}}}},"responses":{"200":{"description":"Batch processed (may include reason=not_running | credits_limit)","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"reason":{"type":"string"}},"required":["ok"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/scrape":{"post":{"tags":["scrape"],"summary":"Scrape a URL","description":"Fetches a URL and returns the requested format(s): markdown, html, links, images, summary, json, branding, screenshot.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":128},"required":false,"name":"SGAI-Session-Id","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"contentType":{"type":"string","enum":["text/html","application/json","text/markdown","text/plain","text/csv","application/x-latex","application/pdf","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.presentationml.presentation","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","image/jpeg","image/png","image/webp","image/gif","image/avif","image/tiff","image/heic","image/bmp","application/epub+zip","application/rtf","application/vnd.oasis.opendocument.text"]},"allowedTypes":{"type":"array","items":{"type":"string","enum":["text/html","application/json","text/markdown","text/plain","text/csv","application/x-latex","application/pdf","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.presentationml.presentation","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","image/jpeg","image/png","image/webp","image/gif","image/avif","image/tiff","image/heic","image/bmp","application/epub+zip","application/rtf","application/vnd.oasis.opendocument.text"]},"minItems":1,"default":["text/html","application/json","text/markdown","text/plain","text/csv","application/x-latex","application/pdf","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.presentationml.presentation","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","image/jpeg","image/png","image/webp","image/gif","image/avif","image/tiff","image/heic","image/bmp","application/epub+zip","application/rtf","application/vnd.oasis.opendocument.text"]},"processors":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["pdf"]},"maxPages":{"anyOf":[{"type":"number","enum":[-1]},{"type":"integer","minimum":1,"maximum":500}],"default":25}},"required":["type"]},"minItems":1,"default":[{"type":"pdf","maxPages":25}]},"fetchConfig":{"type":"object","properties":{"mode":{"type":"string","enum":["auto","fast","js"],"default":"auto"},"stealth":{"type":"boolean","default":false},"shadowDom":{"type":"boolean","default":true},"timeout":{"type":"integer","minimum":1000,"maximum":300000,"default":60000},"wait":{"type":"integer","minimum":0,"maximum":30000,"default":0},"headers":{"type":"object","additionalProperties":{"type":"string"}},"cookies":{"type":"object","additionalProperties":{"type":"string"}},"country":{"type":"string","minLength":2,"maxLength":2},"scrolls":{"type":"integer","minimum":0,"maximum":100,"default":0}},"default":{}},"formats":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["markdown"]}},"required":["type"]},{"type":"object","properties":{"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["html"]}},"required":["type"]},{"type":"object","properties":{"fullPage":{"type":"boolean","default":false},"width":{"type":"integer","minimum":320,"maximum":3840,"default":1440},"height":{"type":"integer","minimum":200,"maximum":2160,"default":900},"quality":{"type":"integer","minimum":1,"maximum":100,"default":80},"type":{"type":"string","enum":["screenshot"]}},"required":["type"]},{"type":"object","properties":{"prompt":{"type":"string","maxLength":10000,"default":""},"schema":{"type":"object","additionalProperties":{"nullable":true}},"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["json"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["links"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["images"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["summary"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["branding"]}},"required":["type"]}]},"minItems":1,"default":[{"type":"markdown","mode":"normal"}]}},"required":["url"]}}}},"responses":{"200":{"description":"Scrape result","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","properties":{"markdown":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","properties":{}}},"required":["data"]},"html":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","properties":{}}},"required":["data"]},"links":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","properties":{"count":{"type":"integer"}},"required":["count"]}},"required":["data"]},"images":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","properties":{"count":{"type":"integer"}},"required":["count"]}},"required":["data"]},"summary":{"type":"object","properties":{"data":{"type":"string"},"metadata":{"type":"object","properties":{"chunker":{"type":"object","properties":{"chunks":{"type":"array","items":{"type":"object","properties":{"size":{"type":"integer","minimum":0}},"required":["size"]}}},"required":["chunks"]}}}},"required":["data"]},"json":{"type":"object","properties":{"data":{"nullable":true},"metadata":{"type":"object","properties":{"chunker":{"type":"object","properties":{"chunks":{"type":"array","items":{"type":"object","properties":{"size":{"type":"integer","minimum":0}},"required":["size"]}}},"required":["chunks"]},"raw":{"type":"string","nullable":true}},"required":["chunker"]}}},"branding":{"type":"object","properties":{"data":{"type":"object","properties":{"colorScheme":{"type":"string","enum":["light","dark"]},"fonts":{"type":"array","items":{"type":"object","properties":{"family":{"type":"string"},"role":{"type":"string","enum":["heading","body"]}},"required":["family","role"]}},"colors":{"type":"object","properties":{"primary":{"type":"string"},"accent":{"type":"string"},"background":{"type":"string"},"textPrimary":{"type":"string"},"link":{"type":"string"}},"required":["primary","accent","background","textPrimary","link"]},"typography":{"type":"object","properties":{"fontFamilies":{"type":"object","properties":{"primary":{"type":"string"},"heading":{"type":"string"}},"required":["primary","heading"]},"fontStacks":{"type":"object","properties":{"heading":{"type":"array","items":{"type":"string"}},"body":{"type":"array","items":{"type":"string"}},"paragraph":{"type":"array","items":{"type":"string"}}},"required":["heading","body","paragraph"]},"fontSizes":{"type":"object","additionalProperties":{"type":"string"}}},"required":["fontFamilies","fontStacks","fontSizes"]},"spacing":{"type":"object","properties":{"baseUnit":{"type":"number"},"borderRadius":{"type":"string"}},"required":["baseUnit","borderRadius"]},"components":{"type":"object","properties":{"input":{"type":"object","properties":{"borderColor":{"type":"string"},"borderRadius":{"type":"string"}},"required":["borderColor","borderRadius"]},"buttonPrimary":{"type":"object","properties":{"background":{"type":"string"},"textColor":{"type":"string"},"borderRadius":{"type":"string"},"shadow":{"type":"string"}},"required":["background","textColor","borderRadius","shadow"]},"buttonSecondary":{"type":"object","properties":{"background":{"type":"string"},"textColor":{"type":"string"},"borderRadius":{"type":"string"},"shadow":{"type":"string"}},"required":["background","textColor","borderRadius","shadow"]}},"required":["input","buttonPrimary","buttonSecondary"]},"images":{"type":"object","properties":{"logo":{"type":"string"},"favicon":{"type":"string"},"ogImage":{"type":"string"}},"required":["logo","favicon","ogImage"]},"frameworkHints":{"type":"array","items":{"type":"string"}},"buttonReasoning":{"type":"object","properties":{"primary":{"type":"object","properties":{"index":{"type":"integer"},"text":{"type":"string"},"reasoning":{"type":"string"}},"required":["index","text","reasoning"]},"secondary":{"type":"object","properties":{"index":{"type":"integer"},"text":{"type":"string"},"reasoning":{"type":"string"}},"required":["index","text","reasoning"]},"confidence":{"type":"number"}},"required":["primary","secondary","confidence"]},"logoReasoning":{"type":"object","properties":{"selectedIndex":{"type":"integer"},"reasoning":{"type":"string"},"confidence":{"type":"number"}},"required":["selectedIndex","reasoning","confidence"]},"personality":{"type":"object","properties":{"tone":{"type":"string"},"energy":{"type":"string","enum":["high","medium","low"]},"targetAudience":{"type":"string"}},"required":["tone","energy","targetAudience"]},"designSystem":{"type":"object","properties":{"framework":{"type":"string","nullable":true},"componentLibrary":{"type":"string","nullable":true}},"required":["framework","componentLibrary"]},"confidence":{"type":"object","properties":{"colors":{"type":"number"},"buttons":{"type":"number"},"logo":{"type":"number"},"fonts":{"type":"number"},"components":{"type":"number"},"overall":{"type":"number"}},"required":["colors","buttons","logo","fonts","components","overall"]}},"required":["colorScheme","fonts","colors","typography","spacing","components","images","frameworkHints","buttonReasoning","logoReasoning","personality","designSystem","confidence"]},"metadata":{"type":"object","properties":{"branding":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"favicon":{"type":"string"},"language":{"type":"string"},"themeColor":{"type":"string"},"ogTitle":{"type":"string"},"ogDescription":{"type":"string"},"ogImage":{"type":"string"},"ogUrl":{"type":"string"}},"required":["title","description","favicon","language","themeColor","ogTitle","ogDescription","ogImage","ogUrl"]}},"required":["branding"]}},"required":["data"]},"screenshot":{"type":"object","properties":{"data":{"type":"object","properties":{"url":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"}},"required":["url","width","height"]},"metadata":{"type":"object","properties":{"contentType":{"type":"string"},"provider":{"type":"string"}},"required":["contentType"]}},"required":["data"]}}},"metadata":{"type":"object","properties":{"provider":{"type":"string"},"contentType":{"type":"string"},"elapsedMs":{"type":"number"},"warnings":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","enum":["too_short","empty","bot_blocked","spa_shell","soft_404"]},"provider":{"type":"string"}},"required":["reason"]}},"ocr":{"type":"object","properties":{"model":{"type":"string"},"pagesProcessed":{"type":"integer"},"pages":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"images":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"topLeftX":{"type":"number"},"topLeftY":{"type":"number"},"bottomRightX":{"type":"number"},"bottomRightY":{"type":"number"}},"required":["id","topLeftX","topLeftY","bottomRightX","bottomRightY"]}},"tables":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"content":{"type":"string"},"format":{"type":"string"}},"required":["id","content","format"]}},"hyperlinks":{"type":"array","items":{"type":"string"}},"dimensions":{"type":"object","properties":{"dpi":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"}},"required":["dpi","height","width"]}},"required":["index","images","tables","hyperlinks","dimensions"]}}},"required":["model","pagesProcessed","pages"]}},"required":["contentType"]},"errors":{"type":"object","properties":{"markdown":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"html":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"links":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"images":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"summary":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"json":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"branding":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"screenshot":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]}}}},"required":["results","metadata"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (captcha, plan limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited or max jobs exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream fetch or processing failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Upstream timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"apiKey":[]}]}},"/api/extract":{"post":{"tags":["extract"],"summary":"Extract structured JSON","description":"LLM-driven extraction from a URL, HTML, or markdown input with a prompt+schema.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":128},"required":false,"name":"SGAI-Session-Id","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"html":{"type":"string"},"markdown":{"type":"string"},"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"prompt":{"type":"string","minLength":1,"maxLength":10000},"schema":{"type":"object","additionalProperties":{"nullable":true}},"contentType":{"type":"string","enum":["text/html","application/json","text/markdown","text/plain","text/csv","application/x-latex","application/pdf","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.presentationml.presentation","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","image/jpeg","image/png","image/webp","image/gif","image/avif","image/tiff","image/heic","image/bmp","application/epub+zip","application/rtf","application/vnd.oasis.opendocument.text"]},"allowedTypes":{"type":"array","items":{"type":"string","enum":["text/html","application/json","text/markdown","text/plain","text/csv","application/x-latex","application/pdf","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.presentationml.presentation","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","image/jpeg","image/png","image/webp","image/gif","image/avif","image/tiff","image/heic","image/bmp","application/epub+zip","application/rtf","application/vnd.oasis.opendocument.text"]},"minItems":1,"default":["text/html","application/json","text/markdown","text/plain","text/csv","application/x-latex","application/pdf","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.presentationml.presentation","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","image/jpeg","image/png","image/webp","image/gif","image/avif","image/tiff","image/heic","image/bmp","application/epub+zip","application/rtf","application/vnd.oasis.opendocument.text"]},"processors":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["pdf"]},"maxPages":{"anyOf":[{"type":"number","enum":[-1]},{"type":"integer","minimum":1,"maximum":500}],"default":25}},"required":["type"]},"minItems":1,"default":[{"type":"pdf","maxPages":25}]},"fetchConfig":{"type":"object","properties":{"mode":{"type":"string","enum":["auto","fast","js"],"default":"auto"},"stealth":{"type":"boolean","default":false},"shadowDom":{"type":"boolean","default":true},"timeout":{"type":"integer","minimum":1000,"maximum":300000,"default":60000},"wait":{"type":"integer","minimum":0,"maximum":30000,"default":0},"headers":{"type":"object","additionalProperties":{"type":"string"}},"cookies":{"type":"object","additionalProperties":{"type":"string"}},"country":{"type":"string","minLength":2,"maxLength":2},"scrolls":{"type":"integer","minimum":0,"maximum":100,"default":0}},"default":{}}},"required":["prompt"]}}}},"responses":{"200":{"description":"Extract result","content":{"application/json":{"schema":{"type":"object","properties":{"raw":{"type":"string","nullable":true},"json":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"usage":{"type":"object","properties":{"promptTokens":{"type":"integer","minimum":0},"completionTokens":{"type":"integer","minimum":0}},"required":["promptTokens","completionTokens"]},"metadata":{"type":"object","properties":{"chunker":{"type":"object","properties":{"chunks":{"type":"array","items":{"type":"object","properties":{"size":{"type":"integer","minimum":0}},"required":["size"]}}},"required":["chunks"]},"fetch":{"type":"object","properties":{"provider":{"type":"string"},"contentType":{"type":"string","enum":["text/html","application/json","text/markdown","text/plain","text/csv","application/x-latex","application/pdf","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.presentationml.presentation","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","image/jpeg","image/png","image/webp","image/gif","image/avif","image/tiff","image/heic","image/bmp","application/epub+zip","application/rtf","application/vnd.oasis.opendocument.text"]},"pagesProcessed":{"type":"integer","minimum":0}}}},"required":["chunker"]}},"required":["raw","json","usage","metadata"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (captcha, plan limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited or max jobs exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream fetch or processing failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Upstream timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"apiKey":[]}]}},"/api/search":{"post":{"tags":["search"],"summary":"Search + scrape top results","description":"Runs a search, scrapes the top N result URLs, optionally runs LLM extraction with prompt+schema.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":128},"required":false,"name":"SGAI-Session-Id","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":500},"numResults":{"type":"integer","minimum":1,"maximum":20,"default":3},"format":{"type":"string","enum":["html","markdown"],"default":"markdown"},"mode":{"type":"string","enum":["normal","reader","prune"],"default":"prune"},"allowedTypes":{"type":"array","items":{"type":"string","enum":["text/html","application/json","text/markdown","text/plain","text/csv","application/x-latex","application/pdf","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.presentationml.presentation","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","image/jpeg","image/png","image/webp","image/gif","image/avif","image/tiff","image/heic","image/bmp","application/epub+zip","application/rtf","application/vnd.oasis.opendocument.text"]},"minItems":1,"default":["text/html","application/json","text/markdown","text/plain","text/csv","application/x-latex","application/pdf","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.presentationml.presentation","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","image/jpeg","image/png","image/webp","image/gif","image/avif","image/tiff","image/heic","image/bmp","application/epub+zip","application/rtf","application/vnd.oasis.opendocument.text"]},"processors":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["pdf"]},"maxPages":{"anyOf":[{"type":"number","enum":[-1]},{"type":"integer","minimum":1,"maximum":500}],"default":25}},"required":["type"]},"minItems":1,"default":[{"type":"pdf","maxPages":25}]},"fetchConfig":{"type":"object","properties":{"mode":{"type":"string","enum":["auto","fast","js"],"default":"auto"},"stealth":{"type":"boolean","default":false},"shadowDom":{"type":"boolean","default":true},"timeout":{"type":"integer","minimum":1000,"maximum":300000,"default":60000},"wait":{"type":"integer","minimum":0,"maximum":30000,"default":0},"headers":{"type":"object","additionalProperties":{"type":"string"}},"cookies":{"type":"object","additionalProperties":{"type":"string"}},"country":{"type":"string","minLength":2,"maxLength":2},"scrolls":{"type":"integer","minimum":0,"maximum":100,"default":0}},"default":{}},"prompt":{"type":"string","minLength":1,"maxLength":10000},"schema":{"type":"object","additionalProperties":{"nullable":true}},"locationGeoCode":{"type":"string","maxLength":10},"timeRange":{"type":"string","enum":["past_hour","past_24_hours","past_week","past_month","past_year"]}},"required":["query"]}}}},"responses":{"200":{"description":"Search result","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"content":{"type":"string"},"provider":{"type":"string"},"metadata":{"type":"object","properties":{"contentType":{"type":"string","enum":["text/html","application/json","text/markdown","text/plain","text/csv","application/x-latex","application/pdf","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.presentationml.presentation","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","image/jpeg","image/png","image/webp","image/gif","image/avif","image/tiff","image/heic","image/bmp","application/epub+zip","application/rtf","application/vnd.oasis.opendocument.text"]},"ocr":{"type":"object","properties":{"pagesProcessed":{"type":"integer","minimum":0}},"required":["pagesProcessed"]}},"required":["contentType"]}},"required":["url","title","content"]}},"json":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"raw":{"type":"string","nullable":true},"usage":{"type":"object","properties":{"promptTokens":{"type":"integer","minimum":0},"completionTokens":{"type":"integer","minimum":0}},"required":["promptTokens","completionTokens"]},"metadata":{"type":"object","properties":{"search":{"type":"object","properties":{"provider":{"type":"string"}}},"pages":{"type":"object","properties":{"requested":{"type":"integer"},"scraped":{"type":"integer"}},"required":["requested","scraped"]},"pdf":{"type":"object","properties":{"pagesProcessed":{"type":"integer","minimum":0}},"required":["pagesProcessed"]},"chunker":{"type":"object","properties":{"chunks":{"type":"array","items":{"type":"object","properties":{"size":{"type":"integer","minimum":0}},"required":["size"]}}},"required":["chunks"]}},"required":["search","pages"]}},"required":["results","metadata"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (captcha, plan limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited or max jobs exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream fetch or processing failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Upstream timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"apiKey":[]}]}},"/api/history":{"get":{"tags":["history"],"summary":"List request history","description":"Session ID filters use case-insensitive partial matching.","parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["scrape","extract","search","monitor","crawl"]},"required":false,"name":"service","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":false,"name":"sessionId","in":"query"}],"responses":{"200":{"description":"Paginated history","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"service":{"type":"string"},"status":{"type":"string","enum":["completed","failed","running","paused","deleted","processing"]},"error":{"nullable":true},"elapsedMs":{"type":"number","nullable":true},"createdAt":{"type":"string"},"requestParentId":{"type":"string","nullable":true},"sessionId":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"params":{"nullable":true},"result":{"nullable":true}},"required":["id","service","status"],"additionalProperties":{"nullable":true}}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"}},"required":["page","limit","total"]}},"required":["data","pagination"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"apiKey":[]}]}},"/api/history/{id}":{"get":{"tags":["history"],"summary":"Get a history entry","parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"History entry","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"service":{"type":"string"},"status":{"type":"string","enum":["completed","failed","running","paused","deleted","processing"]},"error":{"nullable":true},"elapsedMs":{"type":"number","nullable":true},"createdAt":{"type":"string"},"requestParentId":{"type":"string","nullable":true},"sessionId":{"type":"string","nullable":true,"minLength":1,"maxLength":128},"params":{"nullable":true},"result":{"nullable":true}},"required":["id","service","status"],"additionalProperties":{"nullable":true}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"apiKey":[]}]}},"/api/monitor":{"post":{"tags":["monitor"],"summary":"Create a monitor","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"name":{"type":"string","maxLength":200},"formats":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["markdown"]}},"required":["type"]},{"type":"object","properties":{"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["html"]}},"required":["type"]},{"type":"object","properties":{"fullPage":{"type":"boolean","default":false},"width":{"type":"integer","minimum":320,"maximum":3840,"default":1440},"height":{"type":"integer","minimum":200,"maximum":2160,"default":900},"quality":{"type":"integer","minimum":1,"maximum":100,"default":80},"type":{"type":"string","enum":["screenshot"]}},"required":["type"]},{"type":"object","properties":{"prompt":{"type":"string","maxLength":10000,"default":""},"schema":{"type":"object","additionalProperties":{"nullable":true}},"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["json"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["links"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["images"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["summary"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["branding"]}},"required":["type"]}]},"minItems":1,"default":[{"type":"markdown","mode":"normal"}]},"webhookUrl":{"type":"string"},"interval":{"type":"string","minLength":1,"maxLength":100},"fetchConfig":{"type":"object","properties":{"mode":{"type":"string","enum":["auto","fast","js"],"default":"auto"},"stealth":{"type":"boolean","default":false},"shadowDom":{"type":"boolean","default":true},"timeout":{"type":"integer","minimum":1000,"maximum":300000,"default":60000},"wait":{"type":"integer","minimum":0,"maximum":30000,"default":0},"headers":{"type":"object","additionalProperties":{"type":"string"}},"cookies":{"type":"object","additionalProperties":{"type":"string"}},"country":{"type":"string","minLength":2,"maxLength":2},"scrolls":{"type":"integer","minimum":0,"maximum":100,"default":0}},"default":{}}},"required":["url","interval"]}}}},"responses":{"201":{"description":"Monitor created","content":{"application/json":{"schema":{"type":"object","properties":{"cronId":{"type":"string"},"scheduleId":{"type":"string"},"interval":{"type":"string"},"status":{"type":"string","enum":["active","paused"]},"reason":{"type":"string","nullable":true},"consecutiveFailures":{"type":"integer"},"config":{"type":"object","properties":{"url":{"type":"string"},"name":{"type":"string","maxLength":200},"formats":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["markdown"]}},"required":["type"]},{"type":"object","properties":{"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["html"]}},"required":["type"]},{"type":"object","properties":{"fullPage":{"type":"boolean","default":false},"width":{"type":"integer","minimum":320,"maximum":3840,"default":1440},"height":{"type":"integer","minimum":200,"maximum":2160,"default":900},"quality":{"type":"integer","minimum":1,"maximum":100,"default":80},"type":{"type":"string","enum":["screenshot"]}},"required":["type"]},{"type":"object","properties":{"prompt":{"type":"string","maxLength":10000,"default":""},"schema":{"type":"object","additionalProperties":{"nullable":true}},"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["json"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["links"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["images"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["summary"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["branding"]}},"required":["type"]}]},"minItems":1,"default":[{"type":"markdown","mode":"normal"}]},"webhookUrl":{"type":"string"},"interval":{"type":"string","minLength":1,"maxLength":100},"fetchConfig":{"type":"object","properties":{"mode":{"type":"string","enum":["auto","fast","js"],"default":"auto"},"stealth":{"type":"boolean","default":false},"shadowDom":{"type":"boolean","default":true},"timeout":{"type":"integer","minimum":1000,"maximum":300000,"default":60000},"wait":{"type":"integer","minimum":0,"maximum":30000,"default":0},"headers":{"type":"object","additionalProperties":{"type":"string"}},"cookies":{"type":"object","additionalProperties":{"type":"string"}},"country":{"type":"string","minLength":2,"maxLength":2},"scrolls":{"type":"integer","minimum":0,"maximum":100,"default":0}},"default":{}}},"required":["url","interval"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["cronId","scheduleId","interval","status","reason","consecutiveFailures","config","createdAt","updatedAt"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (captcha, plan limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited or max jobs exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"apiKey":[]}]},"get":{"tags":["monitor"],"summary":"List monitors","responses":{"200":{"description":"List of monitors","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"cronId":{"type":"string"},"scheduleId":{"type":"string"},"interval":{"type":"string"},"status":{"type":"string","enum":["active","paused"]},"reason":{"type":"string","nullable":true},"consecutiveFailures":{"type":"integer"},"config":{"type":"object","properties":{"url":{"type":"string"},"name":{"type":"string","maxLength":200},"formats":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["markdown"]}},"required":["type"]},{"type":"object","properties":{"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["html"]}},"required":["type"]},{"type":"object","properties":{"fullPage":{"type":"boolean","default":false},"width":{"type":"integer","minimum":320,"maximum":3840,"default":1440},"height":{"type":"integer","minimum":200,"maximum":2160,"default":900},"quality":{"type":"integer","minimum":1,"maximum":100,"default":80},"type":{"type":"string","enum":["screenshot"]}},"required":["type"]},{"type":"object","properties":{"prompt":{"type":"string","maxLength":10000,"default":""},"schema":{"type":"object","additionalProperties":{"nullable":true}},"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["json"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["links"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["images"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["summary"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["branding"]}},"required":["type"]}]},"minItems":1,"default":[{"type":"markdown","mode":"normal"}]},"webhookUrl":{"type":"string"},"interval":{"type":"string","minLength":1,"maxLength":100},"fetchConfig":{"type":"object","properties":{"mode":{"type":"string","enum":["auto","fast","js"],"default":"auto"},"stealth":{"type":"boolean","default":false},"shadowDom":{"type":"boolean","default":true},"timeout":{"type":"integer","minimum":1000,"maximum":300000,"default":60000},"wait":{"type":"integer","minimum":0,"maximum":30000,"default":0},"headers":{"type":"object","additionalProperties":{"type":"string"}},"cookies":{"type":"object","additionalProperties":{"type":"string"}},"country":{"type":"string","minLength":2,"maxLength":2},"scrolls":{"type":"integer","minimum":0,"maximum":100,"default":0}},"default":{}}},"required":["url","interval"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["cronId","scheduleId","interval","status","reason","consecutiveFailures","config","createdAt","updatedAt"]}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"apiKey":[]}]}},"/api/monitor/{id}":{"get":{"tags":["monitor"],"summary":"Get a monitor","parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Monitor","content":{"application/json":{"schema":{"type":"object","properties":{"cronId":{"type":"string"},"scheduleId":{"type":"string"},"interval":{"type":"string"},"status":{"type":"string","enum":["active","paused"]},"reason":{"type":"string","nullable":true},"consecutiveFailures":{"type":"integer"},"config":{"type":"object","properties":{"url":{"type":"string"},"name":{"type":"string","maxLength":200},"formats":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["markdown"]}},"required":["type"]},{"type":"object","properties":{"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["html"]}},"required":["type"]},{"type":"object","properties":{"fullPage":{"type":"boolean","default":false},"width":{"type":"integer","minimum":320,"maximum":3840,"default":1440},"height":{"type":"integer","minimum":200,"maximum":2160,"default":900},"quality":{"type":"integer","minimum":1,"maximum":100,"default":80},"type":{"type":"string","enum":["screenshot"]}},"required":["type"]},{"type":"object","properties":{"prompt":{"type":"string","maxLength":10000,"default":""},"schema":{"type":"object","additionalProperties":{"nullable":true}},"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["json"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["links"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["images"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["summary"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["branding"]}},"required":["type"]}]},"minItems":1,"default":[{"type":"markdown","mode":"normal"}]},"webhookUrl":{"type":"string"},"interval":{"type":"string","minLength":1,"maxLength":100},"fetchConfig":{"type":"object","properties":{"mode":{"type":"string","enum":["auto","fast","js"],"default":"auto"},"stealth":{"type":"boolean","default":false},"shadowDom":{"type":"boolean","default":true},"timeout":{"type":"integer","minimum":1000,"maximum":300000,"default":60000},"wait":{"type":"integer","minimum":0,"maximum":30000,"default":0},"headers":{"type":"object","additionalProperties":{"type":"string"}},"cookies":{"type":"object","additionalProperties":{"type":"string"}},"country":{"type":"string","minLength":2,"maxLength":2},"scrolls":{"type":"integer","minimum":0,"maximum":100,"default":0}},"default":{}}},"required":["url","interval"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["cronId","scheduleId","interval","status","reason","consecutiveFailures","config","createdAt","updatedAt"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"apiKey":[]}]},"patch":{"tags":["monitor"],"summary":"Update a monitor","parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"formats":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["markdown"]}},"required":["type"]},{"type":"object","properties":{"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["html"]}},"required":["type"]},{"type":"object","properties":{"fullPage":{"type":"boolean","default":false},"width":{"type":"integer","minimum":320,"maximum":3840,"default":1440},"height":{"type":"integer","minimum":200,"maximum":2160,"default":900},"quality":{"type":"integer","minimum":1,"maximum":100,"default":80},"type":{"type":"string","enum":["screenshot"]}},"required":["type"]},{"type":"object","properties":{"prompt":{"type":"string","maxLength":10000,"default":""},"schema":{"type":"object","additionalProperties":{"nullable":true}},"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["json"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["links"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["images"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["summary"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["branding"]}},"required":["type"]}]},"minItems":1},"webhookUrl":{"type":"string","nullable":true},"interval":{"type":"string","minLength":1,"maxLength":100},"fetchConfig":{"type":"object","properties":{"mode":{"type":"string","enum":["auto","fast","js"],"default":"auto"},"stealth":{"type":"boolean","default":false},"shadowDom":{"type":"boolean","default":true},"timeout":{"type":"integer","minimum":1000,"maximum":300000,"default":60000},"wait":{"type":"integer","minimum":0,"maximum":30000,"default":0},"headers":{"type":"object","additionalProperties":{"type":"string"}},"cookies":{"type":"object","additionalProperties":{"type":"string"}},"country":{"type":"string","minLength":2,"maxLength":2},"scrolls":{"type":"integer","minimum":0,"maximum":100,"default":0}}}}}}}},"responses":{"200":{"description":"Monitor updated","content":{"application/json":{"schema":{"type":"object","properties":{"cronId":{"type":"string"},"scheduleId":{"type":"string"},"interval":{"type":"string"},"status":{"type":"string","enum":["active","paused"]},"reason":{"type":"string","nullable":true},"consecutiveFailures":{"type":"integer"},"config":{"type":"object","properties":{"url":{"type":"string"},"name":{"type":"string","maxLength":200},"formats":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["markdown"]}},"required":["type"]},{"type":"object","properties":{"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["html"]}},"required":["type"]},{"type":"object","properties":{"fullPage":{"type":"boolean","default":false},"width":{"type":"integer","minimum":320,"maximum":3840,"default":1440},"height":{"type":"integer","minimum":200,"maximum":2160,"default":900},"quality":{"type":"integer","minimum":1,"maximum":100,"default":80},"type":{"type":"string","enum":["screenshot"]}},"required":["type"]},{"type":"object","properties":{"prompt":{"type":"string","maxLength":10000,"default":""},"schema":{"type":"object","additionalProperties":{"nullable":true}},"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["json"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["links"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["images"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["summary"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["branding"]}},"required":["type"]}]},"minItems":1,"default":[{"type":"markdown","mode":"normal"}]},"webhookUrl":{"type":"string"},"interval":{"type":"string","minLength":1,"maxLength":100},"fetchConfig":{"type":"object","properties":{"mode":{"type":"string","enum":["auto","fast","js"],"default":"auto"},"stealth":{"type":"boolean","default":false},"shadowDom":{"type":"boolean","default":true},"timeout":{"type":"integer","minimum":1000,"maximum":300000,"default":60000},"wait":{"type":"integer","minimum":0,"maximum":30000,"default":0},"headers":{"type":"object","additionalProperties":{"type":"string"}},"cookies":{"type":"object","additionalProperties":{"type":"string"}},"country":{"type":"string","minLength":2,"maxLength":2},"scrolls":{"type":"integer","minimum":0,"maximum":100,"default":0}},"default":{}}},"required":["url","interval"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["cronId","scheduleId","interval","status","reason","consecutiveFailures","config","createdAt","updatedAt"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"apiKey":[]}]},"delete":{"tags":["monitor"],"summary":"Delete a monitor","parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Monitor deleted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"apiKey":[]}]}},"/api/monitor/{id}/activity":{"get":{"tags":["monitor"],"summary":"Get monitor tick activity","parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Paginated tick activity","content":{"application/json":{"schema":{"type":"object","properties":{"ticks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["completed","failed","paused","running"]},"createdAt":{"type":"string","format":"date-time"},"elapsedMs":{"type":"number"},"changed":{"type":"boolean"},"diffs":{"type":"object","properties":{"markdown":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["added","removed"]},"line":{"type":"integer"},"content":{"type":"string"}},"required":["type","line","content"]}},"html":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["added","removed"]},"line":{"type":"integer"},"content":{"type":"string"}},"required":["type","line","content"]}},"json":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"old":{"nullable":true},"new":{"nullable":true}},"required":["path"]}},"screenshot":{"type":"object","properties":{"size":{"type":"number"},"changed":{"type":"number"},"mask":{"type":"string"}},"required":["size","changed"]},"links":{"type":"object","properties":{"added":{"type":"array","items":{"type":"string"}},"removed":{"type":"array","items":{"type":"string"}}},"required":["added","removed"]},"images":{"type":"object","properties":{"added":{"type":"array","items":{"type":"string"}},"removed":{"type":"array","items":{"type":"string"}}},"required":["added","removed"]},"summary":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["added","removed"]},"line":{"type":"integer"},"content":{"type":"string"}},"required":["type","line","content"]}},"branding":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"old":{"nullable":true},"new":{"nullable":true}},"required":["path"]}}}},"error":{"type":"string"}},"required":["id","status","createdAt","elapsedMs","changed","diffs"]}},"nextCursor":{"type":"string","nullable":true}},"required":["ticks","nextCursor"]},"example":{"ticks":[{"id":"550e8400-e29b-41d4-a716-446655440000","status":"completed","createdAt":"2026-04-30T08:00:00.000Z","elapsedMs":1240,"changed":true,"diffs":{"markdown":[{"type":"added","line":42,"content":"New enterprise pricing tier is available."}],"links":{"added":["https://example.com/pricing"],"removed":[]}}}],"nextCursor":null}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"apiKey":[]}]}},"/api/monitor/{id}/pause":{"post":{"tags":["monitor"],"summary":"Pause a monitor","parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Monitor paused","content":{"application/json":{"schema":{"type":"object","properties":{"cronId":{"type":"string"},"scheduleId":{"type":"string"},"interval":{"type":"string"},"status":{"type":"string","enum":["active","paused"]},"reason":{"type":"string","nullable":true},"consecutiveFailures":{"type":"integer"},"config":{"type":"object","properties":{"url":{"type":"string"},"name":{"type":"string","maxLength":200},"formats":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["markdown"]}},"required":["type"]},{"type":"object","properties":{"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["html"]}},"required":["type"]},{"type":"object","properties":{"fullPage":{"type":"boolean","default":false},"width":{"type":"integer","minimum":320,"maximum":3840,"default":1440},"height":{"type":"integer","minimum":200,"maximum":2160,"default":900},"quality":{"type":"integer","minimum":1,"maximum":100,"default":80},"type":{"type":"string","enum":["screenshot"]}},"required":["type"]},{"type":"object","properties":{"prompt":{"type":"string","maxLength":10000,"default":""},"schema":{"type":"object","additionalProperties":{"nullable":true}},"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["json"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["links"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["images"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["summary"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["branding"]}},"required":["type"]}]},"minItems":1,"default":[{"type":"markdown","mode":"normal"}]},"webhookUrl":{"type":"string"},"interval":{"type":"string","minLength":1,"maxLength":100},"fetchConfig":{"type":"object","properties":{"mode":{"type":"string","enum":["auto","fast","js"],"default":"auto"},"stealth":{"type":"boolean","default":false},"shadowDom":{"type":"boolean","default":true},"timeout":{"type":"integer","minimum":1000,"maximum":300000,"default":60000},"wait":{"type":"integer","minimum":0,"maximum":30000,"default":0},"headers":{"type":"object","additionalProperties":{"type":"string"}},"cookies":{"type":"object","additionalProperties":{"type":"string"}},"country":{"type":"string","minLength":2,"maxLength":2},"scrolls":{"type":"integer","minimum":0,"maximum":100,"default":0}},"default":{}}},"required":["url","interval"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["cronId","scheduleId","interval","status","reason","consecutiveFailures","config","createdAt","updatedAt"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"apiKey":[]}]}},"/api/monitor/{id}/resume":{"post":{"tags":["monitor"],"summary":"Resume a monitor","parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Monitor resumed","content":{"application/json":{"schema":{"type":"object","properties":{"cronId":{"type":"string"},"scheduleId":{"type":"string"},"interval":{"type":"string"},"status":{"type":"string","enum":["active","paused"]},"reason":{"type":"string","nullable":true},"consecutiveFailures":{"type":"integer"},"config":{"type":"object","properties":{"url":{"type":"string"},"name":{"type":"string","maxLength":200},"formats":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["markdown"]}},"required":["type"]},{"type":"object","properties":{"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["html"]}},"required":["type"]},{"type":"object","properties":{"fullPage":{"type":"boolean","default":false},"width":{"type":"integer","minimum":320,"maximum":3840,"default":1440},"height":{"type":"integer","minimum":200,"maximum":2160,"default":900},"quality":{"type":"integer","minimum":1,"maximum":100,"default":80},"type":{"type":"string","enum":["screenshot"]}},"required":["type"]},{"type":"object","properties":{"prompt":{"type":"string","maxLength":10000,"default":""},"schema":{"type":"object","additionalProperties":{"nullable":true}},"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["json"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["links"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["images"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["summary"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["branding"]}},"required":["type"]}]},"minItems":1,"default":[{"type":"markdown","mode":"normal"}]},"webhookUrl":{"type":"string"},"interval":{"type":"string","minLength":1,"maxLength":100},"fetchConfig":{"type":"object","properties":{"mode":{"type":"string","enum":["auto","fast","js"],"default":"auto"},"stealth":{"type":"boolean","default":false},"shadowDom":{"type":"boolean","default":true},"timeout":{"type":"integer","minimum":1000,"maximum":300000,"default":60000},"wait":{"type":"integer","minimum":0,"maximum":30000,"default":0},"headers":{"type":"object","additionalProperties":{"type":"string"}},"cookies":{"type":"object","additionalProperties":{"type":"string"}},"country":{"type":"string","minLength":2,"maxLength":2},"scrolls":{"type":"integer","minimum":0,"maximum":100,"default":0}},"default":{}}},"required":["url","interval"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["cronId","scheduleId","interval","status","reason","consecutiveFailures","config","createdAt","updatedAt"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"apiKey":[]}]}},"/api/crawl":{"post":{"tags":["crawl"],"summary":"Start a crawl","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":128},"required":false,"name":"SGAI-Session-Id","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"formats":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["markdown"]}},"required":["type"]},{"type":"object","properties":{"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["html"]}},"required":["type"]},{"type":"object","properties":{"fullPage":{"type":"boolean","default":false},"width":{"type":"integer","minimum":320,"maximum":3840,"default":1440},"height":{"type":"integer","minimum":200,"maximum":2160,"default":900},"quality":{"type":"integer","minimum":1,"maximum":100,"default":80},"type":{"type":"string","enum":["screenshot"]}},"required":["type"]},{"type":"object","properties":{"prompt":{"type":"string","maxLength":10000,"default":""},"schema":{"type":"object","additionalProperties":{"nullable":true}},"mode":{"type":"string","enum":["normal","reader","prune"],"default":"normal"},"type":{"type":"string","enum":["json"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["links"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["images"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["summary"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["branding"]}},"required":["type"]}]},"minItems":1,"default":[{"type":"markdown","mode":"normal"}]},"maxDepth":{"type":"integer","nullable":true,"minimum":0,"default":2},"maxPages":{"type":"integer","minimum":1,"maximum":1000,"default":50},"maxLinksPerPage":{"type":"integer","minimum":1,"default":10},"allowExternal":{"type":"boolean","default":false},"includePatterns":{"type":"array","items":{"type":"string"}},"excludePatterns":{"type":"array","items":{"type":"string"}},"allowedTypes":{"type":"array","items":{"type":"string","enum":["text/html","application/json","text/markdown","text/plain","text/csv","application/x-latex","application/pdf","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.presentationml.presentation","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","image/jpeg","image/png","image/webp","image/gif","image/avif","image/tiff","image/heic","image/bmp","application/epub+zip","application/rtf","application/vnd.oasis.opendocument.text"]},"minItems":1,"default":["text/html","application/json","text/markdown","text/plain","text/csv","application/x-latex","application/pdf","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.presentationml.presentation","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","image/jpeg","image/png","image/webp","image/gif","image/avif","image/tiff","image/heic","image/bmp","application/epub+zip","application/rtf","application/vnd.oasis.opendocument.text"]},"processors":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["pdf"]},"maxPages":{"anyOf":[{"type":"number","enum":[-1]},{"type":"integer","minimum":1,"maximum":500}],"default":25}},"required":["type"]},"minItems":1,"default":[{"type":"pdf","maxPages":25}]},"fetchConfig":{"type":"object","properties":{"mode":{"type":"string","enum":["auto","fast","js"],"default":"auto"},"stealth":{"type":"boolean","default":false},"shadowDom":{"type":"boolean","default":true},"timeout":{"type":"integer","minimum":1000,"maximum":300000,"default":60000},"wait":{"type":"integer","minimum":0,"maximum":30000,"default":0},"headers":{"type":"object","additionalProperties":{"type":"string"}},"cookies":{"type":"object","additionalProperties":{"type":"string"}},"country":{"type":"string","minLength":2,"maxLength":2},"scrolls":{"type":"integer","minimum":0,"maximum":100,"default":0}},"default":{}}},"required":["url"]}}}},"responses":{"200":{"description":"Crawl started","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["running","completed","failed","paused","deleted"]},"reason":{"type":"string"},"total":{"type":"integer"},"finished":{"type":"integer"},"pages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"status":{"type":"string","enum":["completed","failed","skipped"]},"depth":{"type":"integer"},"parentUrl":{"type":"string","nullable":true},"links":{"type":"array","items":{"type":"string"}},"scrapeRefId":{"type":"string"},"title":{"type":"string"},"contentType":{"type":"string"},"screenshotUrl":{"type":"string"},"reason":{"type":"string"},"error":{"type":"string"},"scrape":{"type":"object","properties":{"results":{"type":"object","properties":{"markdown":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","properties":{}}},"required":["data"]},"html":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","properties":{}}},"required":["data"]},"links":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","properties":{"count":{"type":"integer"}},"required":["count"]}},"required":["data"]},"images":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","properties":{"count":{"type":"integer"}},"required":["count"]}},"required":["data"]},"summary":{"type":"object","properties":{"data":{"type":"string"},"metadata":{"type":"object","properties":{"chunker":{"type":"object","properties":{"chunks":{"type":"array","items":{"type":"object","properties":{"size":{"type":"integer","minimum":0}},"required":["size"]}}},"required":["chunks"]}}}},"required":["data"]},"json":{"type":"object","properties":{"data":{"nullable":true},"metadata":{"type":"object","properties":{"chunker":{"type":"object","properties":{"chunks":{"type":"array","items":{"type":"object","properties":{"size":{"type":"integer","minimum":0}},"required":["size"]}}},"required":["chunks"]},"raw":{"type":"string","nullable":true}},"required":["chunker"]}}},"branding":{"type":"object","properties":{"data":{"type":"object","properties":{"colorScheme":{"type":"string","enum":["light","dark"]},"fonts":{"type":"array","items":{"type":"object","properties":{"family":{"type":"string"},"role":{"type":"string","enum":["heading","body"]}},"required":["family","role"]}},"colors":{"type":"object","properties":{"primary":{"type":"string"},"accent":{"type":"string"},"background":{"type":"string"},"textPrimary":{"type":"string"},"link":{"type":"string"}},"required":["primary","accent","background","textPrimary","link"]},"typography":{"type":"object","properties":{"fontFamilies":{"type":"object","properties":{"primary":{"type":"string"},"heading":{"type":"string"}},"required":["primary","heading"]},"fontStacks":{"type":"object","properties":{"heading":{"type":"array","items":{"type":"string"}},"body":{"type":"array","items":{"type":"string"}},"paragraph":{"type":"array","items":{"type":"string"}}},"required":["heading","body","paragraph"]},"fontSizes":{"type":"object","additionalProperties":{"type":"string"}}},"required":["fontFamilies","fontStacks","fontSizes"]},"spacing":{"type":"object","properties":{"baseUnit":{"type":"number"},"borderRadius":{"type":"string"}},"required":["baseUnit","borderRadius"]},"components":{"type":"object","properties":{"input":{"type":"object","properties":{"borderColor":{"type":"string"},"borderRadius":{"type":"string"}},"required":["borderColor","borderRadius"]},"buttonPrimary":{"type":"object","properties":{"background":{"type":"string"},"textColor":{"type":"string"},"borderRadius":{"type":"string"},"shadow":{"type":"string"}},"required":["background","textColor","borderRadius","shadow"]},"buttonSecondary":{"type":"object","properties":{"background":{"type":"string"},"textColor":{"type":"string"},"borderRadius":{"type":"string"},"shadow":{"type":"string"}},"required":["background","textColor","borderRadius","shadow"]}},"required":["input","buttonPrimary","buttonSecondary"]},"images":{"type":"object","properties":{"logo":{"type":"string"},"favicon":{"type":"string"},"ogImage":{"type":"string"}},"required":["logo","favicon","ogImage"]},"frameworkHints":{"type":"array","items":{"type":"string"}},"buttonReasoning":{"type":"object","properties":{"primary":{"type":"object","properties":{"index":{"type":"integer"},"text":{"type":"string"},"reasoning":{"type":"string"}},"required":["index","text","reasoning"]},"secondary":{"type":"object","properties":{"index":{"type":"integer"},"text":{"type":"string"},"reasoning":{"type":"string"}},"required":["index","text","reasoning"]},"confidence":{"type":"number"}},"required":["primary","secondary","confidence"]},"logoReasoning":{"type":"object","properties":{"selectedIndex":{"type":"integer"},"reasoning":{"type":"string"},"confidence":{"type":"number"}},"required":["selectedIndex","reasoning","confidence"]},"personality":{"type":"object","properties":{"tone":{"type":"string"},"energy":{"type":"string","enum":["high","medium","low"]},"targetAudience":{"type":"string"}},"required":["tone","energy","targetAudience"]},"designSystem":{"type":"object","properties":{"framework":{"type":"string","nullable":true},"componentLibrary":{"type":"string","nullable":true}},"required":["framework","componentLibrary"]},"confidence":{"type":"object","properties":{"colors":{"type":"number"},"buttons":{"type":"number"},"logo":{"type":"number"},"fonts":{"type":"number"},"components":{"type":"number"},"overall":{"type":"number"}},"required":["colors","buttons","logo","fonts","components","overall"]}},"required":["colorScheme","fonts","colors","typography","spacing","components","images","frameworkHints","buttonReasoning","logoReasoning","personality","designSystem","confidence"]},"metadata":{"type":"object","properties":{"branding":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"favicon":{"type":"string"},"language":{"type":"string"},"themeColor":{"type":"string"},"ogTitle":{"type":"string"},"ogDescription":{"type":"string"},"ogImage":{"type":"string"},"ogUrl":{"type":"string"}},"required":["title","description","favicon","language","themeColor","ogTitle","ogDescription","ogImage","ogUrl"]}},"required":["branding"]}},"required":["data"]},"screenshot":{"type":"object","properties":{"data":{"type":"object","properties":{"url":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"}},"required":["url","width","height"]},"metadata":{"type":"object","properties":{"contentType":{"type":"string"},"provider":{"type":"string"}},"required":["contentType"]}},"required":["data"]}}},"metadata":{"type":"object","properties":{"provider":{"type":"string"},"contentType":{"type":"string"},"elapsedMs":{"type":"number"},"warnings":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","enum":["too_short","empty","bot_blocked","spa_shell","soft_404"]},"provider":{"type":"string"}},"required":["reason"]}},"ocr":{"type":"object","properties":{"model":{"type":"string"},"pagesProcessed":{"type":"integer"},"pages":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"images":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"topLeftX":{"type":"number"},"topLeftY":{"type":"number"},"bottomRightX":{"type":"number"},"bottomRightY":{"type":"number"}},"required":["id","topLeftX","topLeftY","bottomRightX","bottomRightY"]}},"tables":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"content":{"type":"string"},"format":{"type":"string"}},"required":["id","content","format"]}},"hyperlinks":{"type":"array","items":{"type":"string"}},"dimensions":{"type":"object","properties":{"dpi":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"}},"required":["dpi","height","width"]}},"required":["index","images","tables","hyperlinks","dimensions"]}}},"required":["model","pagesProcessed","pages"]}},"required":["contentType"]},"errors":{"type":"object","properties":{"markdown":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"html":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"links":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"images":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"summary":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"json":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"branding":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"screenshot":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]}}}},"required":["results","metadata"]}},"required":["url","status","depth","parentUrl","links","scrapeRefId","title","contentType"]}},"id":{"type":"string"}},"required":["status","total","finished","pages","id"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited or max jobs exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"apiKey":[]}]}},"/api/crawl/{id}":{"get":{"tags":["crawl"],"summary":"Get crawl status and pages","parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Crawl status","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["running","completed","failed","paused","deleted"]},"reason":{"type":"string"},"total":{"type":"integer"},"finished":{"type":"integer"},"pages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"status":{"type":"string","enum":["completed","failed","skipped"]},"depth":{"type":"integer"},"parentUrl":{"type":"string","nullable":true},"links":{"type":"array","items":{"type":"string"}},"scrapeRefId":{"type":"string"},"title":{"type":"string"},"contentType":{"type":"string"},"screenshotUrl":{"type":"string"},"reason":{"type":"string"},"error":{"type":"string"},"scrape":{"type":"object","properties":{"results":{"type":"object","properties":{"markdown":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","properties":{}}},"required":["data"]},"html":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","properties":{}}},"required":["data"]},"links":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","properties":{"count":{"type":"integer"}},"required":["count"]}},"required":["data"]},"images":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","properties":{"count":{"type":"integer"}},"required":["count"]}},"required":["data"]},"summary":{"type":"object","properties":{"data":{"type":"string"},"metadata":{"type":"object","properties":{"chunker":{"type":"object","properties":{"chunks":{"type":"array","items":{"type":"object","properties":{"size":{"type":"integer","minimum":0}},"required":["size"]}}},"required":["chunks"]}}}},"required":["data"]},"json":{"type":"object","properties":{"data":{"nullable":true},"metadata":{"type":"object","properties":{"chunker":{"type":"object","properties":{"chunks":{"type":"array","items":{"type":"object","properties":{"size":{"type":"integer","minimum":0}},"required":["size"]}}},"required":["chunks"]},"raw":{"type":"string","nullable":true}},"required":["chunker"]}}},"branding":{"type":"object","properties":{"data":{"type":"object","properties":{"colorScheme":{"type":"string","enum":["light","dark"]},"fonts":{"type":"array","items":{"type":"object","properties":{"family":{"type":"string"},"role":{"type":"string","enum":["heading","body"]}},"required":["family","role"]}},"colors":{"type":"object","properties":{"primary":{"type":"string"},"accent":{"type":"string"},"background":{"type":"string"},"textPrimary":{"type":"string"},"link":{"type":"string"}},"required":["primary","accent","background","textPrimary","link"]},"typography":{"type":"object","properties":{"fontFamilies":{"type":"object","properties":{"primary":{"type":"string"},"heading":{"type":"string"}},"required":["primary","heading"]},"fontStacks":{"type":"object","properties":{"heading":{"type":"array","items":{"type":"string"}},"body":{"type":"array","items":{"type":"string"}},"paragraph":{"type":"array","items":{"type":"string"}}},"required":["heading","body","paragraph"]},"fontSizes":{"type":"object","additionalProperties":{"type":"string"}}},"required":["fontFamilies","fontStacks","fontSizes"]},"spacing":{"type":"object","properties":{"baseUnit":{"type":"number"},"borderRadius":{"type":"string"}},"required":["baseUnit","borderRadius"]},"components":{"type":"object","properties":{"input":{"type":"object","properties":{"borderColor":{"type":"string"},"borderRadius":{"type":"string"}},"required":["borderColor","borderRadius"]},"buttonPrimary":{"type":"object","properties":{"background":{"type":"string"},"textColor":{"type":"string"},"borderRadius":{"type":"string"},"shadow":{"type":"string"}},"required":["background","textColor","borderRadius","shadow"]},"buttonSecondary":{"type":"object","properties":{"background":{"type":"string"},"textColor":{"type":"string"},"borderRadius":{"type":"string"},"shadow":{"type":"string"}},"required":["background","textColor","borderRadius","shadow"]}},"required":["input","buttonPrimary","buttonSecondary"]},"images":{"type":"object","properties":{"logo":{"type":"string"},"favicon":{"type":"string"},"ogImage":{"type":"string"}},"required":["logo","favicon","ogImage"]},"frameworkHints":{"type":"array","items":{"type":"string"}},"buttonReasoning":{"type":"object","properties":{"primary":{"type":"object","properties":{"index":{"type":"integer"},"text":{"type":"string"},"reasoning":{"type":"string"}},"required":["index","text","reasoning"]},"secondary":{"type":"object","properties":{"index":{"type":"integer"},"text":{"type":"string"},"reasoning":{"type":"string"}},"required":["index","text","reasoning"]},"confidence":{"type":"number"}},"required":["primary","secondary","confidence"]},"logoReasoning":{"type":"object","properties":{"selectedIndex":{"type":"integer"},"reasoning":{"type":"string"},"confidence":{"type":"number"}},"required":["selectedIndex","reasoning","confidence"]},"personality":{"type":"object","properties":{"tone":{"type":"string"},"energy":{"type":"string","enum":["high","medium","low"]},"targetAudience":{"type":"string"}},"required":["tone","energy","targetAudience"]},"designSystem":{"type":"object","properties":{"framework":{"type":"string","nullable":true},"componentLibrary":{"type":"string","nullable":true}},"required":["framework","componentLibrary"]},"confidence":{"type":"object","properties":{"colors":{"type":"number"},"buttons":{"type":"number"},"logo":{"type":"number"},"fonts":{"type":"number"},"components":{"type":"number"},"overall":{"type":"number"}},"required":["colors","buttons","logo","fonts","components","overall"]}},"required":["colorScheme","fonts","colors","typography","spacing","components","images","frameworkHints","buttonReasoning","logoReasoning","personality","designSystem","confidence"]},"metadata":{"type":"object","properties":{"branding":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"favicon":{"type":"string"},"language":{"type":"string"},"themeColor":{"type":"string"},"ogTitle":{"type":"string"},"ogDescription":{"type":"string"},"ogImage":{"type":"string"},"ogUrl":{"type":"string"}},"required":["title","description","favicon","language","themeColor","ogTitle","ogDescription","ogImage","ogUrl"]}},"required":["branding"]}},"required":["data"]},"screenshot":{"type":"object","properties":{"data":{"type":"object","properties":{"url":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"}},"required":["url","width","height"]},"metadata":{"type":"object","properties":{"contentType":{"type":"string"},"provider":{"type":"string"}},"required":["contentType"]}},"required":["data"]}}},"metadata":{"type":"object","properties":{"provider":{"type":"string"},"contentType":{"type":"string"},"elapsedMs":{"type":"number"},"warnings":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","enum":["too_short","empty","bot_blocked","spa_shell","soft_404"]},"provider":{"type":"string"}},"required":["reason"]}},"ocr":{"type":"object","properties":{"model":{"type":"string"},"pagesProcessed":{"type":"integer"},"pages":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"images":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"topLeftX":{"type":"number"},"topLeftY":{"type":"number"},"bottomRightX":{"type":"number"},"bottomRightY":{"type":"number"}},"required":["id","topLeftX","topLeftY","bottomRightX","bottomRightY"]}},"tables":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"content":{"type":"string"},"format":{"type":"string"}},"required":["id","content","format"]}},"hyperlinks":{"type":"array","items":{"type":"string"}},"dimensions":{"type":"object","properties":{"dpi":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"}},"required":["dpi","height","width"]}},"required":["index","images","tables","hyperlinks","dimensions"]}}},"required":["model","pagesProcessed","pages"]}},"required":["contentType"]},"errors":{"type":"object","properties":{"markdown":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"html":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"links":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"images":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"summary":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"json":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"branding":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"screenshot":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]}}}},"required":["results","metadata"]}},"required":["url","status","depth","parentUrl","links","scrapeRefId","title","contentType"]}},"id":{"type":"string"}},"required":["status","total","finished","pages","id"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"Resource gone (session expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"apiKey":[]}]},"delete":{"tags":["crawl"],"summary":"Delete a crawl","parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Crawl deleted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"apiKey":[]}]}},"/api/crawl/{id}/pages":{"get":{"tags":["crawl"],"summary":"Get paginated crawl pages","parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Paginated crawl pages","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"status":{"type":"string","enum":["completed","failed","skipped"]},"depth":{"type":"integer"},"parentUrl":{"type":"string","nullable":true},"links":{"type":"array","items":{"type":"string"}},"scrapeRefId":{"type":"string"},"title":{"type":"string"},"contentType":{"type":"string"},"screenshotUrl":{"type":"string"},"reason":{"type":"string"},"error":{"type":"string"},"scrape":{"type":"object","properties":{"results":{"type":"object","properties":{"markdown":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","properties":{}}},"required":["data"]},"html":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","properties":{}}},"required":["data"]},"links":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","properties":{"count":{"type":"integer"}},"required":["count"]}},"required":["data"]},"images":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","properties":{"count":{"type":"integer"}},"required":["count"]}},"required":["data"]},"summary":{"type":"object","properties":{"data":{"type":"string"},"metadata":{"type":"object","properties":{"chunker":{"type":"object","properties":{"chunks":{"type":"array","items":{"type":"object","properties":{"size":{"type":"integer","minimum":0}},"required":["size"]}}},"required":["chunks"]}}}},"required":["data"]},"json":{"type":"object","properties":{"data":{"nullable":true},"metadata":{"type":"object","properties":{"chunker":{"type":"object","properties":{"chunks":{"type":"array","items":{"type":"object","properties":{"size":{"type":"integer","minimum":0}},"required":["size"]}}},"required":["chunks"]},"raw":{"type":"string","nullable":true}},"required":["chunker"]}}},"branding":{"type":"object","properties":{"data":{"type":"object","properties":{"colorScheme":{"type":"string","enum":["light","dark"]},"fonts":{"type":"array","items":{"type":"object","properties":{"family":{"type":"string"},"role":{"type":"string","enum":["heading","body"]}},"required":["family","role"]}},"colors":{"type":"object","properties":{"primary":{"type":"string"},"accent":{"type":"string"},"background":{"type":"string"},"textPrimary":{"type":"string"},"link":{"type":"string"}},"required":["primary","accent","background","textPrimary","link"]},"typography":{"type":"object","properties":{"fontFamilies":{"type":"object","properties":{"primary":{"type":"string"},"heading":{"type":"string"}},"required":["primary","heading"]},"fontStacks":{"type":"object","properties":{"heading":{"type":"array","items":{"type":"string"}},"body":{"type":"array","items":{"type":"string"}},"paragraph":{"type":"array","items":{"type":"string"}}},"required":["heading","body","paragraph"]},"fontSizes":{"type":"object","additionalProperties":{"type":"string"}}},"required":["fontFamilies","fontStacks","fontSizes"]},"spacing":{"type":"object","properties":{"baseUnit":{"type":"number"},"borderRadius":{"type":"string"}},"required":["baseUnit","borderRadius"]},"components":{"type":"object","properties":{"input":{"type":"object","properties":{"borderColor":{"type":"string"},"borderRadius":{"type":"string"}},"required":["borderColor","borderRadius"]},"buttonPrimary":{"type":"object","properties":{"background":{"type":"string"},"textColor":{"type":"string"},"borderRadius":{"type":"string"},"shadow":{"type":"string"}},"required":["background","textColor","borderRadius","shadow"]},"buttonSecondary":{"type":"object","properties":{"background":{"type":"string"},"textColor":{"type":"string"},"borderRadius":{"type":"string"},"shadow":{"type":"string"}},"required":["background","textColor","borderRadius","shadow"]}},"required":["input","buttonPrimary","buttonSecondary"]},"images":{"type":"object","properties":{"logo":{"type":"string"},"favicon":{"type":"string"},"ogImage":{"type":"string"}},"required":["logo","favicon","ogImage"]},"frameworkHints":{"type":"array","items":{"type":"string"}},"buttonReasoning":{"type":"object","properties":{"primary":{"type":"object","properties":{"index":{"type":"integer"},"text":{"type":"string"},"reasoning":{"type":"string"}},"required":["index","text","reasoning"]},"secondary":{"type":"object","properties":{"index":{"type":"integer"},"text":{"type":"string"},"reasoning":{"type":"string"}},"required":["index","text","reasoning"]},"confidence":{"type":"number"}},"required":["primary","secondary","confidence"]},"logoReasoning":{"type":"object","properties":{"selectedIndex":{"type":"integer"},"reasoning":{"type":"string"},"confidence":{"type":"number"}},"required":["selectedIndex","reasoning","confidence"]},"personality":{"type":"object","properties":{"tone":{"type":"string"},"energy":{"type":"string","enum":["high","medium","low"]},"targetAudience":{"type":"string"}},"required":["tone","energy","targetAudience"]},"designSystem":{"type":"object","properties":{"framework":{"type":"string","nullable":true},"componentLibrary":{"type":"string","nullable":true}},"required":["framework","componentLibrary"]},"confidence":{"type":"object","properties":{"colors":{"type":"number"},"buttons":{"type":"number"},"logo":{"type":"number"},"fonts":{"type":"number"},"components":{"type":"number"},"overall":{"type":"number"}},"required":["colors","buttons","logo","fonts","components","overall"]}},"required":["colorScheme","fonts","colors","typography","spacing","components","images","frameworkHints","buttonReasoning","logoReasoning","personality","designSystem","confidence"]},"metadata":{"type":"object","properties":{"branding":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"favicon":{"type":"string"},"language":{"type":"string"},"themeColor":{"type":"string"},"ogTitle":{"type":"string"},"ogDescription":{"type":"string"},"ogImage":{"type":"string"},"ogUrl":{"type":"string"}},"required":["title","description","favicon","language","themeColor","ogTitle","ogDescription","ogImage","ogUrl"]}},"required":["branding"]}},"required":["data"]},"screenshot":{"type":"object","properties":{"data":{"type":"object","properties":{"url":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"}},"required":["url","width","height"]},"metadata":{"type":"object","properties":{"contentType":{"type":"string"},"provider":{"type":"string"}},"required":["contentType"]}},"required":["data"]}}},"metadata":{"type":"object","properties":{"provider":{"type":"string"},"contentType":{"type":"string"},"elapsedMs":{"type":"number"},"warnings":{"type":"array","items":{"type":"object","properties":{"reason":{"type":"string","enum":["too_short","empty","bot_blocked","spa_shell","soft_404"]},"provider":{"type":"string"}},"required":["reason"]}},"ocr":{"type":"object","properties":{"model":{"type":"string"},"pagesProcessed":{"type":"integer"},"pages":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"images":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"topLeftX":{"type":"number"},"topLeftY":{"type":"number"},"bottomRightX":{"type":"number"},"bottomRightY":{"type":"number"}},"required":["id","topLeftX","topLeftY","bottomRightX","bottomRightY"]}},"tables":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"content":{"type":"string"},"format":{"type":"string"}},"required":["id","content","format"]}},"hyperlinks":{"type":"array","items":{"type":"string"}},"dimensions":{"type":"object","properties":{"dpi":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"}},"required":["dpi","height","width"]}},"required":["index","images","tables","hyperlinks","dimensions"]}}},"required":["model","pagesProcessed","pages"]}},"required":["contentType"]},"errors":{"type":"object","properties":{"markdown":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"html":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"links":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"images":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"summary":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"json":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"branding":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]},"screenshot":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"}},"required":["code","error"]}}}},"required":["results","metadata"]}},"required":["url","status","depth","parentUrl","links","scrapeRefId","title","contentType"]}},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"nextCursor":{"type":"string","nullable":true}},"required":["limit","nextCursor"]}},"required":["data","pagination"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"Resource gone (session expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"apiKey":[]}]}},"/api/crawl/{id}/stop":{"post":{"tags":["crawl"],"summary":"Stop a running crawl","parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Crawl stopped","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"Resource gone (session expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"apiKey":[]}]}},"/api/crawl/{id}/resume":{"post":{"tags":["crawl"],"summary":"Resume a paused crawl","parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Crawl resumed","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"Resource gone (session expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"apiKey":[]}]}},"/api/credits/purchase/{pack}":{"post":{"tags":["credits"],"summary":"Buy a credit pack with USDC","description":"Purchase a credit pack by paying USDC over the Machine Payments Protocol (MPP). An unpaid request returns 402 with a `WWW-Authenticate: Payment` challenge; pay it and retry with `Authorization: Payment <credential>` to receive credits and a `Payment-Receipt` header.","x-payment-info":{"offers":[{"amount":"5","currency":"USDC","method":"inflow","intent":"charge","description":"1000 ScrapeGraphAI credits (small pack)"},{"amount":"40","currency":"USDC","method":"inflow","intent":"charge","description":"10000 ScrapeGraphAI credits (medium pack)"},{"amount":"150","currency":"USDC","method":"inflow","intent":"charge","description":"50000 ScrapeGraphAI credits (large pack)"}]},"parameters":[{"schema":{"type":"string","enum":["small","medium","large"],"example":"small"},"required":true,"name":"pack","in":"path"}],"responses":{"200":{"description":"Payment verified, credits added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditPackPurchaseResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"apiKey":[]}]}},"/api/credits":{"get":{"tags":["credits"],"summary":"Get credits balance","description":"Returns remaining credits, usage, plan, and job slot usage.","responses":{"200":{"description":"Credits info","content":{"application/json":{"schema":{"type":"object","properties":{"remaining":{"type":"integer"},"used":{"type":"integer"},"plan":{"type":"string"},"jobs":{"type":"object","properties":{"crawl":{"type":"object","properties":{"used":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":0}},"required":["used","limit"]},"monitor":{"type":"object","properties":{"used":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":0}},"required":["used","limit"]}},"required":["crawl","monitor"]}},"required":["remaining","used","plan","jobs"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"apiKey":[]}]}},"/api/agent/subscription":{"get":{"tags":["agent"],"summary":"Get your agent subscription","description":"Requires SGAI-APIKEY. Returns Inflow status, paid-through date, and remaining subscription and top-up credits.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Agent subscription and paid-period access","content":{"application/json":{"schema":{"type":"object","properties":{"subscriptionId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["ACTIVE","CANCELLED","EXPIRED","FAILED","PAST_DUE","PENDING","REVOKED"]},"plan":{"type":"string"},"accountPlan":{"type":"string"},"billingPeriod":{"type":"string","enum":["monthly","yearly"]},"paidThrough":{"type":"string","nullable":true},"cancelledAt":{"type":"string","nullable":true},"renewsAutomatically":{"type":"boolean"},"subscriptionCredits":{"type":"number"},"topUpCredits":{"type":"number"},"remaining":{"type":"number"}},"required":["subscriptionId","status","plan","accountPlan","billingPeriod","paidThrough","cancelledAt","renewsAutomatically","subscriptionCredits","topUpCredits","remaining"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited or max jobs exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["agent"],"summary":"Cancel your agent subscription","description":"Requires SGAI-APIKEY. Stops future Inflow billing immediately. Paid access and subscription credits remain until paidThrough; top-ups and the API key do not expire with the subscription. Idempotent; no automatic refund.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Agent subscription and paid-period access","content":{"application/json":{"schema":{"type":"object","properties":{"subscriptionId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["ACTIVE","CANCELLED","EXPIRED","FAILED","PAST_DUE","PENDING","REVOKED"]},"plan":{"type":"string"},"accountPlan":{"type":"string"},"billingPeriod":{"type":"string","enum":["monthly","yearly"]},"paidThrough":{"type":"string","nullable":true},"cancelledAt":{"type":"string","nullable":true},"renewsAutomatically":{"type":"boolean"},"subscriptionCredits":{"type":"number"},"topUpCredits":{"type":"number"},"remaining":{"type":"number"}},"required":["subscriptionId","status","plan","accountPlan","billingPeriod","paidThrough","cancelledAt","renewsAutomatically","subscriptionCredits","topUpCredits","remaining"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited or max jobs exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/agent/protocols":{"get":{"tags":["agent"],"summary":"Discover agent payments, credit packs, and subscriptions","description":"Free, unauthenticated discovery: which payment protocols this API accepts, the credit packs and monthly/yearly subscriptions on sale, and the endpoints a keyless agent uses to buy access.","responses":{"200":{"description":"Supported protocols, packs, and endpoints","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentProtocolsResponse"}}}}}}},"/api/agent/mpp/access/{pack}":{"post":{"tags":["agent"],"summary":"Keyless: pay USDC to mint an account, API key, and credits","description":"No credentials required. An unpaid request returns 402 with a `WWW-Authenticate: Payment` challenge (MPP); pay it and retry with `Authorization: Payment <credential>` to receive an API key plus the pack's credits. Save the returned key; payment retries return the same key. Refills go through `POST /api/credits/purchase/{pack}` with the key; paying this route again mints a separate fresh account.","x-payment-info":{"offers":[{"amount":"5","currency":"USDC","method":"inflow","intent":"charge","description":"1000 ScrapeGraphAI credits + a fresh API key (small pack)"},{"amount":"40","currency":"USDC","method":"inflow","intent":"charge","description":"10000 ScrapeGraphAI credits + a fresh API key (medium pack)"},{"amount":"150","currency":"USDC","method":"inflow","intent":"charge","description":"50000 ScrapeGraphAI credits + a fresh API key (large pack)"}]},"parameters":[{"schema":{"type":"string","enum":["small","medium","large"],"example":"small"},"required":true,"name":"pack","in":"path"}],"responses":{"200":{"description":"Payment verified — account minted (or re-delivered on replay)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentAccessResponse"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/agent/mpp/subscription/{plan}":{"post":{"tags":["agent"],"summary":"Keyless: subscribe through InFlow MPP","description":"Creates or renews a monthly InFlow MPP subscription (legacy monthly endpoint). The first unpaid request returns 402 with an `inflow/subscription` challenge. A successful activation returns a stable API key for a separate agent account. Each paid period grants its full credit allowance upfront; yearly billing grants twelve months of credits at once. Replays do not grant more credits.","x-payment-info":{"offers":[{"amount":"20.00","currency":"USDC","method":"inflow","intent":"subscription","periodUnit":"month","periodCount":1,"description":"Starter Plan: 10000 credits upfront, billed monthly"},{"amount":"100.00","currency":"USDC","method":"inflow","intent":"subscription","periodUnit":"month","periodCount":1,"description":"Growth Plan: 100000 credits upfront, billed monthly"},{"amount":"500.00","currency":"USDC","method":"inflow","intent":"subscription","periodUnit":"month","periodCount":1,"description":"Pro Plan: 750000 credits upfront, billed monthly"}]},"parameters":[{"schema":{"type":"string","enum":["starter","growth","pro"],"example":"starter"},"required":true,"name":"plan","in":"path"}],"responses":{"200":{"description":"Subscription active and account provisioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSubscriptionResponse"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/agent/mpp/subscription/{plan}/{billingPeriod}":{"post":{"tags":["agent"],"summary":"Keyless: subscribe through InFlow MPP","description":"Creates or renews a monthly or yearly InFlow MPP subscription. The first unpaid request returns 402 with an `inflow/subscription` challenge. A successful activation returns a stable API key for a separate agent account. Each paid period grants its full credit allowance upfront; yearly billing grants twelve months of credits at once. Replays do not grant more credits.","x-payment-info":{"offers":[{"amount":"20.00","currency":"USDC","method":"inflow","intent":"subscription","periodUnit":"month","periodCount":1,"description":"Starter Plan: 10000 credits upfront, billed monthly"},{"amount":"204.00","currency":"USDC","method":"inflow","intent":"subscription","periodUnit":"year","periodCount":1,"description":"Starter Plan: 120000 credits upfront, billed yearly"},{"amount":"100.00","currency":"USDC","method":"inflow","intent":"subscription","periodUnit":"month","periodCount":1,"description":"Growth Plan: 100000 credits upfront, billed monthly"},{"amount":"1020.00","currency":"USDC","method":"inflow","intent":"subscription","periodUnit":"year","periodCount":1,"description":"Growth Plan: 1200000 credits upfront, billed yearly"},{"amount":"500.00","currency":"USDC","method":"inflow","intent":"subscription","periodUnit":"month","periodCount":1,"description":"Pro Plan: 750000 credits upfront, billed monthly"},{"amount":"5100.00","currency":"USDC","method":"inflow","intent":"subscription","periodUnit":"year","periodCount":1,"description":"Pro Plan: 9000000 credits upfront, billed yearly"}]},"parameters":[{"schema":{"type":"string","enum":["starter","growth","pro"],"example":"starter"},"required":true,"name":"plan","in":"path"},{"schema":{"type":"string","enum":["monthly","yearly"]},"required":true,"name":"billingPeriod","in":"path"}],"responses":{"200":{"description":"Subscription active and account provisioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSubscriptionResponse"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/agent/x402/access/{pack}":{"post":{"tags":["agent"],"summary":"Keyless (x402): pay USDC on Base to mint an account, API key, and credits","description":"No credentials required. An unpaid request returns 402 with an x402 payment challenge; pay it with an x402/EVM wallet and retry with the `PAYMENT-SIGNATURE` header to receive an API key plus the pack's credits. Save the returned key; payment retries return the same key. Refills go through `POST /api/credits/purchase/{pack}` with the key. Only present when the x402 rail is enabled.","parameters":[{"schema":{"type":"string","enum":["small","medium","large"],"example":"small"},"required":true,"name":"pack","in":"path"}],"responses":{"200":{"description":"Payment verified — account minted (or re-delivered on replay)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentAccessResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Payment belongs to another purchase","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream fetch or processing failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/validate":{"get":{"tags":["auth"],"summary":"Validate API key","description":"Returns the email of the user owning the provided API key.","responses":{"200":{"description":"API key is valid","content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"}},"required":["email"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"apiKey":[]}]}},"/api/health":{"get":{"tags":["health"],"summary":"Health check","description":"Returns ok if Redis and DB are reachable, degraded otherwise.","responses":{"200":{"description":"Service healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"]},"uptime":{"type":"integer","minimum":0},"services":{"type":"object","properties":{"redis":{"type":"string","enum":["ok","down"]},"db":{"type":"string","enum":["ok","down"]}},"required":["redis","db"]}},"required":["status","uptime"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service degraded","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"]},"uptime":{"type":"integer","minimum":0},"services":{"type":"object","properties":{"redis":{"type":"string","enum":["ok","down"]},"db":{"type":"string","enum":["ok","down"]}},"required":["redis","db"]}},"required":["status","uptime"]}}}}}}},"/.well-known/odp":{"get":{"summary":"Get the ODP service document","tags":["agent"],"description":"Requires Accept: application/odp+json. Uses the ODP 1.0 response format.","responses":{"200":{"description":"Get the ODP service document","content":{"application/odp+json":{"schema":{"type":"object"}}}},"404":{"description":"Offering or collection not found"},"406":{"description":"Accept header must include application/odp+json"}}}},"/api/agent/odp/offerings":{"get":{"summary":"List credit packs and subscriptions","tags":["agent"],"description":"Requires Accept: application/odp+json. Uses the ODP 1.0 response format.","responses":{"200":{"description":"List credit packs and subscriptions","content":{"application/odp+json":{"schema":{"type":"object"}}}},"404":{"description":"Offering or collection not found"},"406":{"description":"Accept header must include application/odp+json"}}}},"/api/agent/odp/offerings/{id}":{"get":{"summary":"Get an offering","tags":["agent"],"description":"Requires Accept: application/odp+json. Uses the ODP 1.0 response format.","parameters":[{"schema":{"type":"string","example":"small"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Get an offering","content":{"application/odp+json":{"schema":{"type":"object"}}}},"404":{"description":"Offering or collection not found"},"406":{"description":"Accept header must include application/odp+json"}}}},"/api/agent/odp/collections":{"get":{"summary":"List offering collections","tags":["agent"],"description":"Requires Accept: application/odp+json. Uses the ODP 1.0 response format.","responses":{"200":{"description":"List offering collections","content":{"application/odp+json":{"schema":{"type":"object"}}}},"404":{"description":"Offering or collection not found"},"406":{"description":"Accept header must include application/odp+json"}}}},"/api/agent/odp/collections/{id}":{"get":{"summary":"Get a collection","tags":["agent"],"description":"Requires Accept: application/odp+json. Uses the ODP 1.0 response format.","parameters":[{"schema":{"type":"string","example":"small"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Get a collection","content":{"application/odp+json":{"schema":{"type":"object"}}}},"404":{"description":"Offering or collection not found"},"406":{"description":"Accept header must include application/odp+json"}}}},"/api/agent/odp/collections/{id}/offerings":{"get":{"summary":"List offerings in a collection","tags":["agent"],"description":"Requires Accept: application/odp+json. Uses the ODP 1.0 response format.","parameters":[{"schema":{"type":"string","example":"small"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"List offerings in a collection","content":{"application/odp+json":{"schema":{"type":"object"}}}},"404":{"description":"Offering or collection not found"},"406":{"description":"Accept header must include application/odp+json"}}}},"/api/agent/odp/schemas/subscription.json":{"get":{"tags":["agent"],"summary":"Get the subscription attribute schema","responses":{"200":{"description":"JSON Schema for subscription terms","content":{"application/schema+json":{"schema":{"type":"object"}}}}}}},"/.well-known/aep":{"get":{"tags":["agent"],"summary":"AEP inspect document","description":"Agent enrollment entrypoint: identity methods, grant types, and command URLs.","responses":{"200":{"description":"Inspect document","content":{"application/aep+json":{"schema":{"$ref":"#/components/schemas/AepDocument"}}}},"401":{"description":"AEP Problem Details (application/problem+json)"},"404":{"description":"AEP Problem Details (application/problem+json)"},"409":{"description":"AEP Problem Details (application/problem+json)"}}}},"/.well-known/did.json":{"get":{"tags":["agent"],"summary":"Service DID document","description":"The did:web document for did:web:sgai-api-v2.onrender.com. Carries no keys; agents check it matches the origin.","responses":{"200":{"description":"DID document","content":{"application/did+json":{"schema":{"$ref":"#/components/schemas/DidDocument"}}}},"401":{"description":"AEP Problem Details (application/problem+json)"},"404":{"description":"AEP Problem Details (application/problem+json)"},"409":{"description":"AEP Problem Details (application/problem+json)"}}}},"/aep/enroll":{"post":{"tags":["agent"],"summary":"AEP: enroll an agent","description":"Registers the agent's did:web identity and provisions a free-plan account. Requires an `Authorization: AEP <client assertion>` signed by the agent's did:web key.","responses":{"200":{"description":"Enrollment state","content":{"application/aep+json":{"schema":{"$ref":"#/components/schemas/AepDocument"}}}},"401":{"description":"AEP Problem Details (application/problem+json)"},"404":{"description":"AEP Problem Details (application/problem+json)"},"409":{"description":"AEP Problem Details (application/problem+json)"}}}},"/aep/status":{"get":{"tags":["agent"],"summary":"AEP: enrollment status","description":"Current enrollment state for the calling agent. Requires an `Authorization: AEP <client assertion>` signed by the agent's did:web key.","responses":{"200":{"description":"Enrollment state","content":{"application/aep+json":{"schema":{"$ref":"#/components/schemas/AepDocument"}}}},"401":{"description":"AEP Problem Details (application/problem+json)"},"404":{"description":"AEP Problem Details (application/problem+json)"},"409":{"description":"AEP Problem Details (application/problem+json)"}}}},"/aep/grant":{"post":{"tags":["agent"],"summary":"AEP: issue an API key","description":"Issues an SGAI-APIKEY session credential for the enrolled agent. Requires an `Authorization: AEP <client assertion>` signed by the agent's did:web key.","responses":{"200":{"description":"Credential","content":{"application/aep+json":{"schema":{"$ref":"#/components/schemas/AepDocument"}}}},"401":{"description":"AEP Problem Details (application/problem+json)"},"404":{"description":"AEP Problem Details (application/problem+json)"},"409":{"description":"AEP Problem Details (application/problem+json)"}}}},"/aep/revoke":{"post":{"tags":["agent"],"summary":"AEP: revoke credentials","description":"Revokes one credential or every api-key credential; the API key is deleted. Requires an `Authorization: AEP <client assertion>` signed by the agent's did:web key.","responses":{"200":{"description":"Revocation result","content":{"application/aep+json":{"schema":{"$ref":"#/components/schemas/AepDocument"}}}},"401":{"description":"AEP Problem Details (application/problem+json)"},"404":{"description":"AEP Problem Details (application/problem+json)"},"409":{"description":"AEP Problem Details (application/problem+json)"}}}}}}