{ "components": { "schemas": { "AccountResponse": { "properties": { "data": { "properties": { "createdAt": { "format": "date-time", "type": "string" }, "credits": { "type": "integer" }, "email": { "format": "email", "type": "string" }, "id": { "type": "string" }, "lifetimeSpendUsd": { "type": "number" }, "plan": { "properties": { "concurrency": { "type": "integer" }, "id": { "type": "string" }, "name": { "type": "string" }, "queueLimit": { "type": "integer" }, "rateLimitPerMinute": { "type": "integer" } }, "required": [ "id", "name", "rateLimitPerMinute", "concurrency", "queueLimit" ], "type": "object" }, "queue": { "properties": { "active": { "type": "integer" }, "waiting": { "type": "integer" } }, "required": [ "active", "waiting" ], "type": "object" } }, "required": [ "id", "email", "credits", "plan", "queue", "lifetimeSpendUsd", "createdAt" ], "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "ActionDto": { "properties": { "amount": { "maximum": 10000, "minimum": 0, "type": "number" }, "direction": { "enum": [ "up", "down" ], "type": "string" }, "key": { "maxLength": 64, "type": "string" }, "milliseconds": { "maximum": 10000, "minimum": 0, "type": "number" }, "selector": { "maxLength": 2048, "type": "string" }, "text": { "maxLength": 10000, "type": "string" }, "type": { "enum": [ "wait", "click", "write", "press", "scroll", "scrape", "screenshot", "pdf" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, "AgentConfigDto": { "properties": { "mode": { "default": "default", "description": "Model routing mode. \"default\" uses the fast default model; \"smart\" uses the higher-latency reasoning model.", "enum": [ "default", "smart" ], "type": "string" }, "model": { "default": "deepseek/deepseek-v4-flash", "description": "Explicit AI model to use. Omit for the configured default, or set \"smart\" to use the configured smart model.", "example": "deepseek/deepseek-v4-flash", "type": "string" } }, "type": "object" }, "BrandAsset": { "properties": { "height": { "type": "integer" }, "theme": { "type": "string" }, "type": { "type": "string" }, "url": { "format": "uri", "type": "string" }, "width": { "type": "integer" } }, "required": [ "url", "type" ], "type": "object" }, "BrandComponentStyle": { "properties": { "background": { "type": "string" }, "borderColor": { "type": "string" }, "borderRadius": { "type": "string" }, "shadow": { "type": "string" }, "textColor": { "type": "string" } }, "type": "object" }, "BrandDesignSystem": { "properties": { "colors": { "properties": { "accent": { "type": "string" }, "background": { "type": "string" }, "link": { "type": "string" }, "primary": { "type": "string" }, "secondary": { "type": "string" }, "textPrimary": { "type": "string" } }, "type": "object" }, "colorScheme": { "enum": [ "light", "dark" ], "type": "string" }, "components": { "properties": { "buttonPrimary": { "$ref": "#/components/schemas/BrandComponentStyle" }, "buttonSecondary": { "$ref": "#/components/schemas/BrandComponentStyle" }, "input": { "$ref": "#/components/schemas/BrandComponentStyle" } }, "type": "object" }, "images": { "properties": { "favicon": { "format": "uri", "type": "string" }, "logo": { "format": "uri", "type": "string" }, "ogImage": { "format": "uri", "type": "string" } }, "type": "object" }, "spacing": { "properties": { "baseUnit": { "type": "number" }, "borderRadius": { "type": "string" } }, "required": [ "baseUnit" ], "type": "object" }, "typography": { "properties": { "fontFamilies": { "properties": { "heading": { "type": "string" }, "primary": { "type": "string" } }, "type": "object" }, "fontSizes": { "properties": { "body": { "type": "string" }, "h1": { "type": "string" }, "h2": { "type": "string" } }, "type": "object" }, "fontStacks": { "properties": { "body": { "items": { "type": "string" }, "type": "array" }, "heading": { "items": { "type": "string" }, "type": "array" }, "paragraph": { "items": { "type": "string" }, "type": "array" } }, "required": [ "heading", "body", "paragraph" ], "type": "object" } }, "required": [ "fontFamilies", "fontStacks", "fontSizes" ], "type": "object" } }, "required": [ "colorScheme", "colors", "typography", "spacing", "components", "images" ], "type": "object" }, "BrandDto": { "properties": { "refresh": { "default": false, "description": "Ignore a cached profile and fetch the website again", "type": "boolean" }, "timeout": { "default": 30000, "description": "Maximum time to spend building the profile, in milliseconds", "maximum": 120000, "minimum": 1000, "type": "number" }, "url": { "description": "The public website whose brand profile should be extracted", "example": "https://stripe.com", "type": "string" } }, "required": [ "url" ], "type": "object" }, "BrandProfile": { "properties": { "branding": { "$ref": "#/components/schemas/BrandDesignSystem" }, "colors": { "items": { "properties": { "hex": { "type": "string" }, "name": { "type": "string" } }, "required": [ "hex" ], "type": "object" }, "type": "array" }, "description": { "type": "string" }, "domain": { "type": "string" }, "fonts": { "items": { "properties": { "family": { "type": "string" }, "weights": { "items": { "type": "string" }, "type": "array" } }, "required": [ "family" ], "type": "object" }, "type": "array" }, "images": { "items": { "$ref": "#/components/schemas/BrandAsset" }, "type": "array" }, "language": { "nullable": true, "type": "string" }, "logos": { "items": { "$ref": "#/components/schemas/BrandAsset" }, "type": "array" }, "name": { "type": "string" }, "socials": { "items": { "properties": { "network": { "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "network", "url" ], "type": "object" }, "type": "array" }, "tagline": { "type": "string" } }, "required": [ "name", "domain", "logos", "images", "colors", "fonts", "socials" ], "type": "object" }, "BrandResponse": { "properties": { "data": { "properties": { "brand": { "$ref": "#/components/schemas/BrandProfile" }, "meta": { "properties": { "cached": { "type": "boolean" }, "creditsUsed": { "type": "integer" }, "fetchedAt": { "format": "date-time", "type": "string" }, "sourceUrl": { "format": "uri", "type": "string" } }, "required": [ "sourceUrl", "fetchedAt", "cached", "creditsUsed" ], "type": "object" } }, "required": [ "brand", "meta" ], "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "CancelJobResponse": { "properties": { "data": { "properties": { "id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "status" ], "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "ChangeTrackingFormatDto": { "properties": { "modes": { "description": "Change detection modes", "example": [ "text", "visual", "structure" ], "items": { "type": "string" }, "type": "array" }, "schema": { "description": "Schema for structured change tracking", "type": "object" }, "tag": { "description": "Tag to identify this tracking session", "type": "string" }, "type": { "description": "Format type", "enum": [ "changeTracking" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, "CrawlDto": { "properties": { "allowExternalLinks": { "default": false, "description": "Whether to allow crawling external domains", "type": "boolean" }, "allowSubdomains": { "default": false, "description": "Whether to allow crawling subdomains", "type": "boolean" }, "crawlEntireDomain": { "default": false, "description": "Whether to crawl entire domain or just subtree", "type": "boolean" }, "deduplicateSimilarURLs": { "default": false, "description": "Deduplicate similar URLs using intelligent matching", "type": "boolean" }, "delay": { "default": 0, "description": "Delay between page scrapes in milliseconds", "type": "number" }, "excludePaths": { "description": "Regex patterns to exclude paths", "example": [ "^/admin", "^/private" ], "items": { "type": "string" }, "type": "array" }, "ignoreQueryParameters": { "default": false, "description": "Ignore query parameters when deduplicating URLs", "type": "boolean" }, "includePaths": { "description": "Regex patterns to include paths", "example": [ "^/blog", "^/docs" ], "items": { "type": "string" }, "type": "array" }, "limit": { "default": 10000, "description": "Maximum number of pages to crawl", "type": "number" }, "maxConcurrency": { "description": "Maximum number of concurrent scrapes for this crawl", "type": "number" }, "maxDiscoveryDepth": { "default": 10, "description": "Maximum depth for URL discovery", "type": "number" }, "prompt": { "description": "Natural language instructions for crawl configuration", "type": "string" }, "scrapeOptions": { "description": "Scrape options to apply to each page. actions accepts at most 25 bounded browser actions. zeroDataRetention: true is currently rejected with 400 ZERO_DATA_RETENTION_NOT_SUPPORTED.", "type": "object" }, "sitemap": { "default": "include", "description": "Sitemap handling strategy", "enum": [ "include", "skip", "only" ], "type": "string" }, "url": { "description": "Starting URL to crawl", "example": "https://example.com", "type": "string" }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/WebhookConfigDto" } ], "description": "Webhook configuration" }, "zeroDataRetention": { "default": false, "description": "Reserved for a future zero-data-retention mode. true is currently rejected with 400 ZERO_DATA_RETENTION_NOT_SUPPORTED; omit or use false.", "type": "boolean" } }, "required": [ "url" ], "type": "object" }, "CreateWebhookDto": { "properties": { "events": { "description": "Event types to subscribe to", "example": [ "crawl.completed", "extract.failed" ], "items": { "type": "string" }, "type": "array" }, "url": { "description": "Webhook URL to send events to", "example": "https://api.example.com/webhooks", "type": "string" } }, "required": [ "url", "events" ], "type": "object" }, "ExtractDto": { "properties": { "agent": { "allOf": [ { "$ref": "#/components/schemas/AgentConfigDto" } ], "description": "Agent configuration" }, "enableWebSearch": { "default": false, "description": "Enable web search for URL discovery", "type": "boolean" }, "ignoreInvalidURLs": { "default": true, "description": "Ignore invalid URLs and process remaining valid ones", "type": "boolean" }, "ignoreSitemap": { "default": false, "description": "Ignore sitemap during URL discovery", "type": "boolean" }, "includeSubdomains": { "default": true, "description": "Include subdomains in extraction", "type": "boolean" }, "prompt": { "description": "Natural language prompt describing what to extract. Maximum 16384 UTF-8 bytes.", "example": "Extract all product names, prices, and descriptions from these pages", "type": "string" }, "schema": { "description": "JSON Schema for structured output. Serialized schema is limited to 65536 UTF-8 bytes.", "example": { "properties": { "products": { "items": { "properties": { "description": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "number" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "object" }, "scrapeOptions": { "description": "Scrape options for each URL. zeroDataRetention: true is currently rejected with 400 ZERO_DATA_RETENTION_NOT_SUPPORTED.", "type": "object" }, "showSources": { "default": false, "description": "Include source citations in response", "type": "boolean" }, "urls": { "description": "1–20 unique public HTTP(S) URLs. May be omitted only when enableWebSearch is true. Each URL is limited to 2048 UTF-8 bytes.", "example": [ "https://example.com/page1", "https://example.com/page2" ], "items": { "type": "string" }, "maxItems": 20, "minItems": 1, "type": "array", "uniqueItems": true }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/ExtractWebhookConfigDto" } ], "description": "Webhook configuration" } }, "required": [ "prompt" ], "type": "object" }, "ExtractWebhookConfigDto": { "properties": { "events": { "description": "Events to subscribe to", "example": [ "extract.completed", "extract.failed" ], "items": { "type": "string" }, "type": "array" }, "metadata": { "description": "Custom metadata", "example": { "jobName": "supplier-extract" }, "type": "object" }, "secret": { "description": "Optional secret used to sign direct webhook deliveries", "type": "string" }, "url": { "description": "Webhook URL", "example": "https://example.com/webhook", "type": "string" } }, "required": [ "url" ], "type": "object" }, "JobCreatedResponse": { "properties": { "id": { "type": "string" }, "invalidURLs": { "items": { "type": "string" }, "type": "array" }, "success": { "type": "boolean" }, "url": { "type": "string" } }, "required": [ "success", "id", "url" ], "type": "object" }, "JobResponse": { "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/JobSummary" }, { "properties": { "errors": { "items": { "properties": { "error": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "type": "array" }, "result": {}, "resultPagination": { "$ref": "#/components/schemas/Pagination" }, "results": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } }, "required": [ "results", "errors", "resultPagination" ], "type": "object" } ] }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "JobSummary": { "properties": { "completed": { "nullable": true, "type": "integer" }, "completedAt": { "format": "date-time", "nullable": true, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "creditsUsed": { "type": "integer" }, "error": { "nullable": true, "type": "string" }, "failed": { "nullable": true, "type": "integer" }, "id": { "type": "string" }, "startedAt": { "format": "date-time", "nullable": true, "type": "string" }, "status": { "type": "string" }, "total": { "type": "integer" }, "type": { "enum": [ "crawl", "extract" ], "type": "string" } }, "required": [ "id", "type", "status", "total", "creditsUsed", "createdAt" ], "type": "object" }, "JsonFormatDto": { "properties": { "prompt": { "description": "Natural language prompt for extraction guidance", "type": "string" }, "schema": { "description": "JSON schema for structured extraction", "type": "object" }, "type": { "description": "Format type", "enum": [ "json" ], "type": "string" } }, "required": [ "type", "schema" ], "type": "object" }, "ListJobsResponse": { "properties": { "data": { "properties": { "jobs": { "items": { "$ref": "#/components/schemas/JobSummary" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "jobs", "pagination" ], "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "ListWebhooksResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Webhook" }, "type": "array" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "LocationDto": { "properties": { "country": { "type": "string" }, "languages": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "MapDto": { "properties": { "ignoreQueryParameters": { "default": true, "description": "Ignore query parameters when discovering URLs", "type": "boolean" }, "includeSubdomains": { "default": true, "description": "Include subdomains in the map", "type": "boolean" }, "limit": { "default": 100, "description": "Maximum number of URLs to return", "maximum": 1000, "minimum": 1, "type": "number" }, "location": { "allOf": [ { "$ref": "#/components/schemas/LocationDto" } ], "description": "Location configuration" }, "search": { "description": "Search filter for URLs", "example": "blog", "type": "string" }, "sitemap": { "default": "include", "description": "How to handle sitemaps", "enum": [ "include", "skip", "only" ], "type": "string" }, "timeout": { "description": "Timeout for map operation in milliseconds", "maximum": 300000, "minimum": 1000, "type": "number" }, "url": { "description": "URL to map", "example": "https://example.com", "type": "string" } }, "required": [ "url" ], "type": "object" }, "MapLink": { "properties": { "description": { "type": "string" }, "title": { "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "url" ], "type": "object" }, "MapResponse": { "properties": { "creditsUsed": { "type": "integer" }, "links": { "items": { "$ref": "#/components/schemas/MapLink" }, "type": "array" }, "success": { "type": "boolean" }, "total": { "type": "integer" } }, "required": [ "success", "total", "creditsUsed", "links" ], "type": "object" }, "MessageResponse": { "properties": { "message": { "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success", "message" ], "type": "object" }, "Pagination": { "properties": { "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "required": [ "page", "limit", "total" ], "type": "object" }, "ParseDto": { "properties": { "timeout": { "default": 30000, "maximum": 120000, "minimum": 1000, "type": "number" }, "url": { "description": "Public PDF, Word document, or spreadsheet URL", "example": "https://example.com/report.pdf", "type": "string" } }, "required": [ "url" ], "type": "object" }, "ScrapeDto": { "properties": { "actions": { "description": "Browser actions to execute", "items": { "$ref": "#/components/schemas/ActionDto" }, "maxItems": 25, "type": "array" }, "blockAds": { "default": true, "description": "Enable ad-blocking and cookie popup blocking", "type": "boolean" }, "domain": { "description": "Domain to scrape. Normalized to https://domain when url is omitted.", "example": "example.com", "type": "string" }, "excludeTags": { "description": "CSS selectors to exclude", "example": [ ".ad", ".sidebar" ], "items": { "type": "string" }, "type": "array" }, "extractionSchema": { "description": "Schema for structured data extraction (used with json format)", "example": { "description": "string", "price": "number", "title": "string" }, "type": "object" }, "formats": { "default": [ "markdown" ], "description": "Output formats - can be simple strings or format objects with options", "example": [ "markdown", "html", "links" ], "items": { "oneOf": [ { "enum": [ "markdown", "html", "rawhtml", "links", "images", "summary", "json", "changeTracking" ], "type": "string" }, { "$ref": "#/components/schemas/JsonFormatDto" }, { "$ref": "#/components/schemas/SummaryFormatDto" }, { "$ref": "#/components/schemas/ChangeTrackingFormatDto" } ] }, "type": "array" }, "headers": { "description": "Custom headers", "type": "object" }, "includeTags": { "description": "CSS selectors to include", "example": [ "article", ".content" ], "items": { "type": "string" }, "type": "array" }, "location": { "allOf": [ { "$ref": "#/components/schemas/LocationDto" } ], "description": "Location settings" }, "maxAge": { "default": 172800000, "description": "Cache max age in milliseconds", "type": "number" }, "mobile": { "default": false, "description": "Emulate mobile device for scraping", "type": "boolean" }, "onlyMainContent": { "default": true, "description": "Extract only main content", "type": "boolean" }, "proxy": { "default": "auto", "description": "Proxy mode. auto starts direct and escalates only when blocked. basic is an alias for none.", "enum": [ "none", "basic", "datacenter", "residential", "stealth", "auto" ], "type": "string" }, "removeBase64Images": { "default": true, "description": "Remove base64 images from output (keeps alt text)", "type": "boolean" }, "screenshotAsBase64": { "default": false, "description": "Return screenshot/PDF output inline as a base64 data URL instead of an uploaded CDN URL. Default false (a CDN URL is returned).", "type": "boolean" }, "skipTlsVerification": { "default": false, "description": "Skip TLS certificate verification", "type": "boolean" }, "storeInCache": { "default": true, "description": "Store result in cache", "type": "boolean" }, "timeout": { "default": 30000, "description": "Request timeout in milliseconds", "type": "number" }, "url": { "description": "URL to scrape. Either url or domain is required.", "example": "https://example.com", "type": "string" }, "waitFor": { "default": 0, "description": "Wait time before scraping (ms)", "type": "number" }, "zeroDataRetention": { "default": false, "description": "Reserved for a future zero-data-retention mode. true is currently rejected with 400 ZERO_DATA_RETENTION_NOT_SUPPORTED; omit or use false.", "type": "boolean" } }, "type": "object" }, "ScrapeMetadata": { "properties": { "authorName": { "type": "string" }, "authorUrl": { "format": "uri", "type": "string" }, "contentType": { "type": "string" }, "durationSeconds": { "nullable": true, "type": "integer" }, "durationText": { "nullable": true, "type": "string" }, "language": { "type": "string" }, "source": { "type": "string" }, "statusCode": { "type": "integer" }, "thumbnailUrl": { "format": "uri", "type": "string" }, "timestamp": { "format": "date-time", "type": "string" }, "title": { "type": "string" }, "url": { "format": "uri", "type": "string" }, "videoId": { "type": "string" } }, "required": [ "url", "timestamp" ], "type": "object" }, "ScrapeResponse": { "properties": { "credits": { "properties": { "used": { "type": "integer" } }, "required": [ "used" ], "type": "object" }, "data": { "additionalProperties": true, "type": "object" }, "error": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/ScrapeMetadata" }, "success": { "type": "boolean" } }, "required": [ "success", "metadata", "credits" ], "type": "object" }, "ScreenshotClipDto": { "properties": { "height": { "example": 600, "maximum": 50000, "minimum": 1, "type": "number" }, "width": { "example": 800, "maximum": 3840, "minimum": 1, "type": "number" }, "x": { "example": 0, "minimum": 0, "type": "number" }, "y": { "example": 0, "minimum": 0, "type": "number" } }, "required": [ "x", "y", "width", "height" ], "type": "object" }, "ScreenshotCookieDto": { "properties": { "domain": { "example": ".example.com", "type": "string" }, "httpOnly": { "type": "boolean" }, "name": { "example": "session", "type": "string" }, "path": { "default": "/", "type": "string" }, "sameSite": { "enum": [ "Strict", "Lax", "None" ], "type": "string" }, "secure": { "type": "boolean" }, "value": { "example": "signed-session-value", "type": "string" } }, "required": [ "name", "value" ], "type": "object" }, "ScreenshotDto": { "properties": { "blockAds": { "default": true, "description": "Block common advertising and analytics requests", "type": "boolean" }, "clickSelector": { "description": "Click this CSS selector before capture", "type": "string" }, "clip": { "allOf": [ { "$ref": "#/components/schemas/ScreenshotClipDto" } ], "description": "Capture an exact pixel rectangle instead of the page" }, "colorScheme": { "enum": [ "light", "dark" ], "type": "string" }, "cookies": { "description": "Cookies to set before loading the page", "items": { "$ref": "#/components/schemas/ScreenshotCookieDto" }, "type": "array" }, "delay": { "default": 0, "description": "Extra settling time after the page is ready, in milliseconds", "maximum": 30000, "minimum": 0, "type": "number" }, "device": { "default": "desktop", "description": "Named viewport preset", "enum": [ "desktop", "desktop-hd", "tablet", "iphone-15", "pixel-8" ], "type": "string" }, "disableAnimations": { "default": true, "type": "boolean" }, "format": { "default": "png", "enum": [ "png", "jpeg", "webp" ], "type": "string" }, "fullPage": { "default": true, "description": "Capture the complete page instead of only the viewport", "type": "boolean" }, "fullPageAlgorithm": { "default": "auto", "description": "auto uses native capture for normal pages and stitched slices for very tall pages", "enum": [ "auto", "native", "stitch" ], "type": "string" }, "headers": { "description": "Headers sent while loading the page", "example": { "X-Preview-Token": "token" }, "type": "object" }, "hideFixedElements": { "default": true, "description": "Show fixed/sticky UI once instead of repeating it in stitched captures", "type": "boolean" }, "hideSelectors": { "description": "Hide matching elements before capture", "example": [ ".announcement-bar", "#debug-panel" ], "items": { "type": "string" }, "type": "array" }, "location": { "$ref": "#/components/schemas/ScreenshotLocationDto" }, "maskColor": { "default": "#000000", "example": "#111111", "type": "string" }, "maskSelectors": { "description": "Cover matching elements with a solid privacy mask", "example": [ ".customer-email", "[data-private]" ], "items": { "type": "string" }, "type": "array" }, "maxHeight": { "default": 30000, "description": "Maximum full-page height. Prevents endless captures on infinite pages.", "maximum": 50000, "minimum": 1000, "type": "number" }, "omitBackground": { "default": false, "description": "Use a transparent background where the page allows it", "type": "boolean" }, "proxy": { "default": "auto", "description": "Proxy mode", "enum": [ "none", "basic", "datacenter", "residential", "stealth", "auto" ], "type": "string" }, "quality": { "default": 85, "description": "JPEG or WebP quality", "maximum": 100, "minimum": 1, "type": "number" }, "reducedMotion": { "default": true, "type": "boolean" }, "removeChatWidgets": { "default": true, "description": "Hide common support and chat widgets", "type": "boolean" }, "removeCookieBanners": { "default": true, "description": "Accept known consent dialogs, hide remaining cookie banners, and restore page scrolling", "type": "boolean" }, "removeOverlays": { "default": true, "description": "Remove newsletter gates, modal backdrops, and blocking overlays", "type": "boolean" }, "responseFormat": { "default": "url", "description": "Return a CDN URL or an inline data URL", "enum": [ "url", "base64" ], "type": "string" }, "scale": { "default": "css", "description": "Capture at CSS pixel size or the emulated device pixel ratio", "enum": [ "css", "device" ], "type": "string" }, "scrollDelay": { "default": 250, "description": "Pause between lazy-load scroll steps, in milliseconds", "maximum": 2000, "minimum": 50, "type": "number" }, "scrollPage": { "default": true, "description": "Scroll through the page first so lazy content is loaded", "type": "boolean" }, "selector": { "description": "Capture one element instead of the page", "example": "#pricing", "type": "string" }, "styles": { "description": "CSS rules to apply before capture", "items": { "type": "string" }, "type": "array" }, "timeout": { "default": 30000, "maximum": 120000, "minimum": 1000, "type": "number" }, "url": { "description": "Public webpage URL to capture", "example": "https://example.com", "type": "string" }, "viewport": { "allOf": [ { "$ref": "#/components/schemas/ScreenshotViewportDto" } ], "description": "Custom viewport. Overrides the named device dimensions." }, "waitForSelector": { "description": "Wait for this CSS selector before capture", "type": "string" }, "waitUntil": { "default": "networkidle", "description": "Page readiness milestone used before capture", "enum": [ "domcontentloaded", "load", "networkidle" ], "type": "string" } }, "required": [ "url" ], "type": "object" }, "ScreenshotLocationDto": { "properties": { "country": { "example": "us", "type": "string" }, "languages": { "example": [ "en-US" ], "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "ScreenshotViewportDto": { "properties": { "height": { "example": 900, "maximum": 2160, "minimum": 240, "type": "number" }, "width": { "example": 1440, "maximum": 3840, "minimum": 320, "type": "number" } }, "required": [ "width", "height" ], "type": "object" }, "SearchDto": { "properties": { "categories": { "description": "Category filters", "example": [ "github", "research", "pdf" ], "items": { "type": "string" }, "type": "array" }, "country": { "default": "US", "description": "Country code", "example": "US", "type": "string" }, "limit": { "default": 10, "description": "Maximum number of results", "maximum": 10, "minimum": 1, "type": "number" }, "location": { "description": "Location for geo-targeting", "example": "New York, NY", "type": "string" }, "query": { "description": "Search query", "example": "machine learning tutorials", "type": "string" }, "sources": { "default": [ "web" ], "description": "Source types to search", "example": [ "web", "images", "news" ], "items": { "type": "string" }, "type": "array" }, "tbs": { "description": "Time-based filter (e.g., qdr:d for past day)", "example": "qdr:w", "type": "string" }, "timeout": { "default": 60000, "description": "Timeout for search operation in milliseconds", "maximum": 300000, "minimum": 1000, "type": "number" } }, "required": [ "query" ], "type": "object" }, "SearchResponse": { "properties": { "creditsUsed": { "type": "integer" }, "data": { "items": { "$ref": "#/components/schemas/SearchResult" }, "type": "array" }, "query": { "type": "string" }, "success": { "type": "boolean" }, "total": { "type": "integer" } }, "required": [ "success", "query", "total", "creditsUsed", "data" ], "type": "object" }, "SearchResult": { "properties": { "publishedDate": { "nullable": true, "type": "string" }, "snippet": { "type": "string" }, "source": { "type": "string" }, "title": { "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "title", "url", "snippet", "source" ], "type": "object" }, "SummaryFormatDto": { "properties": { "query": { "description": "Specific query for focused summarization", "type": "string" }, "type": { "description": "Format type", "enum": [ "summary" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, "TestWebhookDto": { "properties": { "event": { "description": "Event type to test", "example": "crawl.completed", "type": "string" }, "payload": { "description": "Optional custom payload for testing", "example": { "jobId": "test_123", "status": "completed" }, "type": "object" } }, "required": [ "event" ], "type": "object" }, "TestWebhookResponse": { "properties": { "event": { "type": "string" }, "message": { "type": "string" }, "payload": { "additionalProperties": true, "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "message", "event", "payload" ], "type": "object" }, "UpdateWebhookDto": { "properties": { "events": { "description": "Event types to subscribe to", "example": [ "crawl.completed", "extract.failed" ], "items": { "type": "string" }, "type": "array" }, "isActive": { "description": "Enable or disable webhook", "example": true, "type": "boolean" }, "url": { "description": "Webhook URL to send events to", "example": "https://api.example.com/webhooks", "type": "string" } }, "type": "object" }, "Webhook": { "properties": { "createdAt": { "format": "date-time", "type": "string" }, "events": { "items": { "type": "string" }, "type": "array" }, "id": { "type": "string" }, "isActive": { "type": "boolean" }, "recentDeliveries": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "secret": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "id", "url", "events", "isActive" ], "type": "object" }, "WebhookConfigDto": { "properties": { "events": { "description": "Events to subscribe to", "example": [ "crawl.page", "crawl.completed" ], "items": { "type": "string" }, "type": "array" }, "metadata": { "description": "Additional metadata", "type": "object" }, "secret": { "description": "Optional secret used to sign direct webhook deliveries", "type": "string" }, "url": { "description": "Webhook URL", "type": "string" } }, "required": [ "url", "events" ], "type": "object" }, "WebhookResponse": { "properties": { "data": { "$ref": "#/components/schemas/Webhook" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "YouTubeTranscriptDto": { "properties": { "formats": { "default": [ "markdown" ], "description": "Output formats - can be simple strings or format objects with options", "example": [ "markdown", "html", "links" ], "items": { "oneOf": [ { "enum": [ "markdown", "html", "rawhtml", "links", "images", "summary", "json", "changeTracking" ], "type": "string" }, { "$ref": "#/components/schemas/JsonFormatDto" }, { "$ref": "#/components/schemas/SummaryFormatDto" }, { "$ref": "#/components/schemas/ChangeTrackingFormatDto" } ] }, "type": "array" }, "timeout": { "default": 30000, "description": "Request timeout in milliseconds", "type": "number" }, "url": { "description": "A YouTube URL that identifies one video. Watch, Shorts, live, embed, and youtu.be URLs are supported.", "example": "https://www.youtube.com/watch?v=aircAruvnKk", "type": "string" } }, "required": [ "url" ], "type": "object" } }, "securitySchemes": { "api-key": { "bearerFormat": "API Key", "description": "Enter your API key with the bc_ prefix", "in": "header", "name": "Authorization", "scheme": "bearer", "type": "http" } } }, "info": { "contact": {}, "description": "Curated Berrycrawl API surface for AI agents: setup, scraping, YouTube transcripts, crawling, search, extraction, and brand intelligence.", "title": "Berrycrawl Agent API", "version": "1.0" }, "openapi": "3.0.0", "paths": { "/account": { "get": { "operationId": "accountGet", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponse" } } }, "description": "" } }, "security": [ { "api-key": [] } ], "summary": "Get credits, plan, limits, and scrape queue usage", "tags": [ "Account" ], "x-fern-sdk-group-name": "account", "x-fern-sdk-method-name": "get" } }, "/brand": { "post": { "description": "Send one website URL. BerryCrawl returns the brand identity found on that site.", "operationId": "brandRetrieve", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandDto" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandResponse" } } }, "description": "Brand profile retrieved successfully" }, "400": { "description": "Invalid website URL or insufficient credits" }, "401": { "description": "Invalid API key" }, "404": { "description": "Website could not be loaded" } }, "security": [ { "api-key": [] } ], "summary": "Get the complete public brand profile for a website", "tags": [ "Brand" ], "x-fern-sdk-group-name": "brand", "x-fern-sdk-method-name": "retrieve" } }, "/crawl": { "post": { "operationId": "crawl", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlDto" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreatedResponse" } } }, "description": "Crawl job created. Use /jobs/:id to follow it." }, "400": { "description": "Invalid request or ZERO_DATA_RETENTION_NOT_SUPPORTED. No job is created for rejected requests." }, "401": { "description": "Invalid API key" } }, "security": [ { "api-key": [] } ], "summary": "Start a website crawl", "tags": [ "Crawl" ], "x-fern-sdk-method-name": "crawl" } }, "/extract": { "post": { "operationId": "extract", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractDto" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreatedResponse" } } }, "description": "Extraction job created. Use /jobs/:id to follow it." }, "400": { "description": "Invalid request or ZERO_DATA_RETENTION_NOT_SUPPORTED. No job is created for rejected requests." }, "401": { "description": "Invalid API key" } }, "security": [ { "api-key": [] } ], "summary": "Start a structured data extraction job", "tags": [ "Extract" ], "x-fern-sdk-method-name": "extract" } }, "/jobs": { "get": { "operationId": "jobsList", "parameters": [ { "in": "query", "name": "type", "required": false, "schema": { "enum": [ "crawl", "extract" ], "type": "string" } }, { "in": "query", "name": "status", "required": false, "schema": { "enum": [ "PENDING", "RUNNING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" } }, { "in": "query", "name": "page", "required": false, "schema": { "default": 1, "minimum": 1, "type": "number" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "maximum": 100, "minimum": 1, "type": "number" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListJobsResponse" } } }, "description": "" } }, "security": [ { "api-key": [] } ], "summary": "List crawl and extraction jobs", "tags": [ "Jobs" ], "x-fern-sdk-group-name": "jobs", "x-fern-sdk-method-name": "list" } }, "/jobs/{id}": { "delete": { "operationId": "jobsCancel", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelJobResponse" } } }, "description": "" } }, "security": [ { "api-key": [] } ], "summary": "Cancel any pending or running job", "tags": [ "Jobs" ], "x-fern-sdk-group-name": "jobs", "x-fern-sdk-method-name": "cancel" }, "get": { "operationId": "jobsGet", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "page", "required": false, "schema": { "default": 1, "minimum": 1, "type": "number" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "number" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } }, "description": "" } }, "security": [ { "api-key": [] } ], "summary": "Get any job, including results and errors", "tags": [ "Jobs" ], "x-fern-sdk-group-name": "jobs", "x-fern-sdk-method-name": "get" } }, "/map": { "post": { "operationId": "map", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MapDto" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MapResponse" } } }, "description": "URLs discovered successfully" }, "401": { "description": "Unauthorized - Invalid API key" } }, "security": [ { "api-key": [] } ], "summary": "Map a website and discover URLs", "tags": [ "Map" ], "x-fern-sdk-method-name": "map" } }, "/parse": { "post": { "operationId": "parse", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParseDto" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScrapeResponse" } } }, "description": "Document parsed successfully" }, "502": { "description": "Upstream document fetch failed" }, "503": { "description": "Required provider unavailable" }, "504": { "description": "Document fetch timed out" } }, "security": [ { "api-key": [] } ], "summary": "Parse a PDF, Word document, or spreadsheet", "tags": [ "Parse" ], "x-fern-sdk-method-name": "parse" } }, "/scrape": { "post": { "description": "YouTube video URLs return the timestamped transcript through the normal text formats. Every successful YouTube transcript scrape costs 5 credits.", "operationId": "scrape", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScrapeDto" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScrapeResponse" } } }, "description": "Page scraped successfully" }, "400": { "description": "Invalid request or insufficient credits" }, "401": { "description": "Invalid API key" }, "404": { "description": "YouTube transcript unavailable" }, "429": { "description": "Rate or concurrency limit exceeded" }, "502": { "description": "Upstream page or proxy failed" }, "503": { "description": "Proxy provider unavailable" }, "504": { "description": "Scrape timed out" } }, "security": [ { "api-key": [] } ], "summary": "Scrape one web page", "tags": [ "Scrape" ], "x-fern-sdk-method-name": "scrape" } }, "/screenshot": { "post": { "description": "Cookie banners, blocking overlays, chat widgets, and lazy loading are handled by default. Every cleanup pass can be controlled per request.", "operationId": "screenshot", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScreenshotDto" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScrapeResponse" } } }, "description": "Screenshot captured successfully" }, "502": { "description": "Upstream page or proxy failed" }, "503": { "description": "Proxy provider unavailable" }, "504": { "description": "Screenshot timed out" } }, "security": [ { "api-key": [] } ], "summary": "Capture a clean screenshot of one web page", "tags": [ "Screenshot" ], "x-fern-sdk-method-name": "screenshot" } }, "/search": { "post": { "operationId": "search", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchDto" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } }, "description": "Search results returned successfully" }, "401": { "description": "Unauthorized - Invalid API key" } }, "security": [ { "api-key": [] } ], "summary": "Perform web search with advanced operators", "tags": [ "Search" ], "x-fern-sdk-method-name": "search" } }, "/webhooks": { "get": { "operationId": "webhooksList", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWebhooksResponse" } } }, "description": "" } }, "security": [ { "api-key": [] } ], "summary": "List webhooks", "tags": [ "Webhooks" ], "x-fern-sdk-group-name": "webhooks", "x-fern-sdk-method-name": "list" }, "post": { "operationId": "webhooksCreate", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookDto" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } }, "description": "" } }, "security": [ { "api-key": [] } ], "summary": "Create a webhook", "tags": [ "Webhooks" ], "x-fern-sdk-group-name": "webhooks", "x-fern-sdk-method-name": "create" } }, "/webhooks/{id}": { "delete": { "operationId": "webhooksDelete", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } }, "description": "" } }, "security": [ { "api-key": [] } ], "summary": "Delete a webhook", "tags": [ "Webhooks" ], "x-fern-sdk-group-name": "webhooks", "x-fern-sdk-method-name": "delete" }, "get": { "operationId": "webhooksGet", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } }, "description": "" } }, "security": [ { "api-key": [] } ], "summary": "Get a webhook and its recent deliveries", "tags": [ "Webhooks" ], "x-fern-sdk-group-name": "webhooks", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "webhooksUpdate", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookDto" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } }, "description": "" } }, "security": [ { "api-key": [] } ], "summary": "Update a webhook", "tags": [ "Webhooks" ], "x-fern-sdk-group-name": "webhooks", "x-fern-sdk-method-name": "update" } }, "/webhooks/{id}/test": { "post": { "operationId": "webhooksTest", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestWebhookDto" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestWebhookResponse" } } }, "description": "" } }, "security": [ { "api-key": [] } ], "summary": "Send a test webhook delivery", "tags": [ "Webhooks" ], "x-fern-sdk-group-name": "webhooks", "x-fern-sdk-method-name": "test" } }, "/youtube/transcript": { "post": { "description": "Returns a YouTube video transcript through the standard scrape response shape. Every successful response costs 5 credits. Failed requests are not charged.", "operationId": "youtubeTranscript", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/YouTubeTranscriptDto" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScrapeResponse" } } }, "description": "YouTube transcript returned successfully" }, "400": { "description": "Invalid request, unsupported URL, or insufficient credits" }, "401": { "description": "Invalid API key" }, "404": { "description": "Transcript unavailable" }, "429": { "description": "Rate limit exceeded" }, "502": { "description": "Transcript provider failed" }, "503": { "description": "Transcript provider unavailable" }, "504": { "description": "Transcript request timed out" } }, "security": [ { "api-key": [] } ], "summary": "Get a timestamped YouTube transcript", "tags": [ "YouTube" ], "x-fern-sdk-group-name": "youtube", "x-fern-sdk-method-name": "transcript" } } }, "servers": [ { "description": "Production", "url": "https://api.berrycrawl.com/api/v1" } ], "tags": [ { "description": "Get the complete public brand for a website", "name": "Brand" }, { "description": "Scrape one web page", "name": "Scrape" }, { "description": "Get timestamped transcripts from YouTube videos", "name": "YouTube" }, { "description": "Web search endpoints", "name": "Search" }, { "description": "Crawl a website in the background", "name": "Crawl" }, { "description": "AI-powered data extraction", "name": "Extract" }, { "description": "Website mapping and URL discovery", "name": "Map" }, { "description": "Capture a clean page image with default-on cookie cleanup, lazy loading, and tall-page stitching", "name": "Screenshot" }, { "description": "Parse a PDF, Word document, or spreadsheet", "name": "Parse" }, { "description": "Follow and cancel background work", "name": "Jobs" }, { "description": "Manage webhook destinations", "name": "Webhooks" }, { "description": "Credits, plan, and limits", "name": "Account" } ] }