From ac230f179b78122b5c1c604dbf78ed7ee915d979 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Sat, 8 Aug 2026 06:57:04 +0000 Subject: [PATCH 1/3] feat(api): api update --- .stats.yml | 4 +- packages/mcp-server/src/local-docs-search.ts | 18 ++--- src/resources/batch.ts | 18 +++++ src/resources/web.ts | 76 +++++++++++++++++--- 4 files changed, 94 insertions(+), 22 deletions(-) diff --git a/.stats.yml b/.stats.yml index 97db86d..90b5514 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,4 +1,4 @@ configured_endpoints: 40 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/context-dev/context.dev-a0dda03bbb600917cfb9add468cc4c8c84351a8dbbf61644dbc353263ca1748f.yml -openapi_spec_hash: c24264f32a46d9317aac5af9d6a396f7 +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/context-dev/context.dev-1c93116e47cab52ea63490f5bca186ed3acda8bbd7f0ce5a320effb9f5b72b1f.yml +openapi_spec_hash: f56204d55bd4bffb6e4d50d6a5d9471a config_hash: 920678668dd2da6f8966fbf1b8fde4e2 diff --git a/packages/mcp-server/src/local-docs-search.ts b/packages/mcp-server/src/local-docs-search.ts index 8035e0b..aacf645 100644 --- a/packages/mcp-server/src/local-docs-search.ts +++ b/packages/mcp-server/src/local-docs-search.ts @@ -139,9 +139,9 @@ const EMBEDDED_METHODS: MethodEntry[] = [ "zdr?: 'enabled' | 'disabled';", ], response: - "{ html: string; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; success: true; type: string; url: string; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; actionsHtmlStale?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", + "{ html: string; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; success: true; type: string; url: string; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; actionsHtmlStale?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", markdown: - "## web_scrape_html\n\n`client.web.webScrapeHTML(url: string, actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; }[], country?: string, excludeSelectors?: string[], headers?: object, includeFrames?: boolean | 'true' | 'false', includeSelectors?: string[], maxAgeMs?: number, pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }, settleAnimations?: boolean | 'true' | 'false', tags?: string[], timeoutMS?: number, useMainContentOnly?: boolean | 'true' | 'false', waitForMs?: number, zdr?: 'enabled' | 'disabled'): { html: string; metadata: object; success: true; type: string; url: string; actionsApplied?: object[]; actionsHtmlStale?: boolean; key_metadata?: object; }`\n\n**get** `/web/scrape/html`\n\nScrapes the given URL and returns the raw HTML content of the page. The base request costs 1 credit; requests with browser actions cost 2 credits.\n\n### Parameters\n\n- `url: string`\n Full URL to scrape (must include http:// or https:// protocol)\n\n- `actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; }[]`\n Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions.\n\n- `country?: string`\n Fetch the target page through a residential proxy in this country (ISO 3166-1 alpha-2).\n\n- `excludeSelectors?: string[]`\n CSS selectors to remove from the result. Applied after includeSelectors. Exclusion takes precedence: an element matching both is removed. Examples: \"nav\", \"footer\", \".ad-banner\", \"[aria-hidden=true]\".\n\n- `headers?: object`\n Optional outbound HTTP headers forwarded only to the target URL, sent as deep-object query params such as headers[X-Custom]=value. When provided, caching is bypassed: the result is neither read from nor written to cache.\n\n- `includeFrames?: boolean | 'true' | 'false'`\n When true, iframes are rendered inline into the returned HTML.\n\n- `includeSelectors?: string[]`\n CSS selectors. When provided, only matching subtrees (and their descendants) are kept and everything else is dropped. When omitted, the entire document is kept. Examples: \"article.main\", \"#content\", \"[role=main]\".\n\n- `maxAgeMs?: number`\n Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh.\n\n- `pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }`\n PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range.\n - `end?: number`\n Last 1-based PDF page to parse. When omitted, parsing ends at the last page. Must be greater than or equal to start when both are provided.\n - `ocr?: boolean | 'true' | 'false'`\n When true, OCR the selected PDF pages that have no usable text layer (scans), replacing each recovered page's text with the OCR result while pages with a real text layer keep it. Billed at 1 credit per page OCR actually recovered, on top of the base request cost. When false, no OCR runs.\n - `shouldParse?: boolean | 'true' | 'false'`\n When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and a 400 PDF_SKIPPED is returned.\n - `start?: number`\n First 1-based PDF page to parse. When omitted, parsing starts at the first page.\n\n- `settleAnimations?: boolean | 'true' | 'false'`\n When true, waits briefly for CSS and transition animations to settle before extracting HTML. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages.\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n- `useMainContentOnly?: boolean | 'true' | 'false'`\n When true, return only the page's main content in the HTML response, excluding headers, footers, sidebars, and navigation when detectable.\n\n- `waitForMs?: number`\n Optional browser wait time in milliseconds after initial page load. Min: 0. Max: 30000 (30 seconds).\n\n- `zdr?: 'enabled' | 'disabled'`\n Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.\n\n### Returns\n\n- `{ html: string; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; success: true; type: string; url: string; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; actionsHtmlStale?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `html: string`\n - `metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }`\n - `success: true`\n - `type: string`\n - `url: string`\n - `actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]`\n - `actionsHtmlStale?: boolean`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.webScrapeHTML({ url: 'https://example.com' });\n\nconsole.log(response);\n```", + "## web_scrape_html\n\n`client.web.webScrapeHTML(url: string, actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; }[], country?: string, excludeSelectors?: string[], headers?: object, includeFrames?: boolean | 'true' | 'false', includeSelectors?: string[], maxAgeMs?: number, pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }, settleAnimations?: boolean | 'true' | 'false', tags?: string[], timeoutMS?: number, useMainContentOnly?: boolean | 'true' | 'false', waitForMs?: number, zdr?: 'enabled' | 'disabled'): { html: string; metadata: object; success: true; type: string; url: string; actionsApplied?: object[]; actionsHtmlStale?: boolean; key_metadata?: object; }`\n\n**get** `/web/scrape/html`\n\nScrapes the given URL and returns the raw HTML content of the page. The base request costs 1 credit; requests with browser actions cost 2 credits.\n\n### Parameters\n\n- `url: string`\n Full URL to scrape (must include http:// or https:// protocol)\n\n- `actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; }[]`\n Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions.\n\n- `country?: string`\n Fetch the target page through a residential proxy in this country (ISO 3166-1 alpha-2).\n\n- `excludeSelectors?: string[]`\n CSS selectors to remove from the result. Applied after includeSelectors. Exclusion takes precedence: an element matching both is removed. Examples: \"nav\", \"footer\", \".ad-banner\", \"[aria-hidden=true]\".\n\n- `headers?: object`\n Optional outbound HTTP headers forwarded only to the target URL, sent as deep-object query params such as headers[X-Custom]=value. When provided, caching is bypassed: the result is neither read from nor written to cache.\n\n- `includeFrames?: boolean | 'true' | 'false'`\n When true, iframes are rendered inline into the returned HTML.\n\n- `includeSelectors?: string[]`\n CSS selectors. When provided, only matching subtrees (and their descendants) are kept and everything else is dropped. When omitted, the entire document is kept. Examples: \"article.main\", \"#content\", \"[role=main]\".\n\n- `maxAgeMs?: number`\n Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh.\n\n- `pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }`\n PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range.\n - `end?: number`\n Last 1-based PDF page to parse. When omitted, parsing ends at the last page. Must be greater than or equal to start when both are provided.\n - `ocr?: boolean | 'true' | 'false'`\n When true, OCR the selected PDF pages that have no usable text layer (scans), replacing each recovered page's text with the OCR result while pages with a real text layer keep it. Billed at 1 credit per page OCR actually recovered, on top of the base request cost. When false, no OCR runs.\n - `shouldParse?: boolean | 'true' | 'false'`\n When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and a 400 PDF_SKIPPED is returned.\n - `start?: number`\n First 1-based PDF page to parse. When omitted, parsing starts at the first page.\n\n- `settleAnimations?: boolean | 'true' | 'false'`\n When true, waits briefly for CSS and transition animations to settle before extracting HTML. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages.\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n- `useMainContentOnly?: boolean | 'true' | 'false'`\n When true, return only the page's main content in the HTML response, excluding headers, footers, sidebars, and navigation when detectable.\n\n- `waitForMs?: number`\n Optional browser wait time in milliseconds after initial page load. Min: 0. Max: 30000 (30 seconds).\n\n- `zdr?: 'enabled' | 'disabled'`\n Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.\n\n### Returns\n\n- `{ html: string; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; success: true; type: string; url: string; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; actionsHtmlStale?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `html: string`\n - `metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }`\n - `success: true`\n - `type: string`\n - `url: string`\n - `actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]`\n - `actionsHtmlStale?: boolean`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.webScrapeHTML({ url: 'https://example.com' });\n\nconsole.log(response);\n```", perLanguage: { typescript: { method: 'client.web.webScrapeHTML', @@ -185,7 +185,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ httpMethod: 'get', summary: 'Scrape Markdown', description: - 'Scrapes the given URL into LLM usable Markdown. Inspect key_metadata on JSON responses from a recognized API key; use error_code to distinguish stable failure categories.\n\n### YouTube\n\nYouTube URLs return the video or channel itself rather than the surrounding player and navigation chrome. A URL addressing a single video (`/watch`, `youtu.be`, `/shorts`, `/embed`, `/live`) returns its title, channel, duration, view count, keywords, full description, and the transcript when the video has captions that can be retrieved; videos without captions return everything except the transcript. A channel URL (`/channel/UC…`, `/@handle`, `/c/…`, `/user/…`) returns its name, handle, subscriber count, video count, and full description. When `includeImages=true`, video responses also include the thumbnail and channel responses include the avatar. Costs the same as any other scrape.\n\n### Billing & errors\n\n| HTTP status | Billed? | Meaning |\n| --- | --- | --- |\n| 200 | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing |\n| 400 | No | Invalid input, skipped PDF, or the page could not be scraped |\n| 401 / 403 | No | Invalid/disabled key, insufficient permissions, or credits exhausted; inspect error_code |\n| 404 | No | Target page returned or fingerprinted as not found |\n| 408 | No | Request timed out |\n| 413 | No | Target content exceeds the maximum supported size (20 MB) |\n| 415 | No | Unsupported content type |\n| 429 | No | Per-minute rate limit exceeded; honor Retry-After |\n| 500 | No | Internal error |', + 'Scrapes the given URL into LLM usable Markdown. Inspect key_metadata on JSON responses from a recognized API key; use error_code to distinguish stable failure categories.\n\n### YouTube\n\nYouTube URLs return the video or channel itself rather than the surrounding player and navigation chrome. A URL addressing a single video (`/watch`, `youtu.be`, `/shorts`, `/embed`, `/live`) returns its title, channel, duration, view count, keywords, full description, and the transcript when the video has captions that can be retrieved; videos without captions return everything except the transcript. A channel URL (`/channel/UC…`, `/@handle`, `/c/…`, `/user/…`) returns its name, handle, subscriber count, video count, and full description. When `includeImages=true`, video responses also include the thumbnail and channel responses include the avatar. Costs the same as any other scrape.\n\n### Billing & errors\n\n| HTTP status | Billed? | Meaning |\n| --- | --- | --- |\n| 200 | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing |\n| 400 | No | Invalid input, skipped PDF, or the page could not be scraped. error_code WEBSITE_BLOCKED specifically means the site answered with an anti-bot challenge, CAPTCHA wall, or login shell instead of the page (even when the site returned HTTP 200) — retrying later or from another country sometimes succeeds |\n| 401 / 403 | No | Invalid/disabled key, insufficient permissions, or credits exhausted; inspect error_code |\n| 404 | No | Target page returned or fingerprinted as not found |\n| 408 | No | Request timed out |\n| 413 | No | Target content exceeds the maximum supported size (20 MB) |\n| 415 | No | Unsupported content type |\n| 429 | No | Per-minute rate limit exceeded; honor Retry-After |\n| 500 | No | Internal error |', stainlessPath: '(resource) web > (method) web_scrape_md', qualified: 'client.web.webScrapeMd', params: [ @@ -209,9 +209,9 @@ const EMBEDDED_METHODS: MethodEntry[] = [ "zdr?: 'enabled' | 'disabled';", ], response: - "{ contentLength: number; markdown: string; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; success: true; url: string; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; actionsHtmlStale?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", + "{ contentLength: number; markdown: string; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; success: true; url: string; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; actionsHtmlStale?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", markdown: - "## web_scrape_md\n\n`client.web.webScrapeMd(url: string, actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; }[], country?: string, excludeSelectors?: string[], headers?: object, includeFrames?: boolean | 'true' | 'false', includeImages?: boolean | 'true' | 'false', includeLinks?: boolean | 'true' | 'false', includeSelectors?: string[], maxAgeMs?: number, pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }, settleAnimations?: boolean | 'true' | 'false', shortenBase64Images?: boolean | 'true' | 'false', tags?: string[], timeoutMS?: number, useMainContentOnly?: boolean | 'true' | 'false', waitForMs?: number, zdr?: 'enabled' | 'disabled'): { contentLength: number; markdown: string; metadata: object; success: true; url: string; actionsApplied?: object[]; actionsHtmlStale?: boolean; key_metadata?: object; }`\n\n**get** `/web/scrape/markdown`\n\nScrapes the given URL into LLM usable Markdown. Inspect key_metadata on JSON responses from a recognized API key; use error_code to distinguish stable failure categories.\n\n### YouTube\n\nYouTube URLs return the video or channel itself rather than the surrounding player and navigation chrome. A URL addressing a single video (`/watch`, `youtu.be`, `/shorts`, `/embed`, `/live`) returns its title, channel, duration, view count, keywords, full description, and the transcript when the video has captions that can be retrieved; videos without captions return everything except the transcript. A channel URL (`/channel/UC…`, `/@handle`, `/c/…`, `/user/…`) returns its name, handle, subscriber count, video count, and full description. When `includeImages=true`, video responses also include the thumbnail and channel responses include the avatar. Costs the same as any other scrape.\n\n### Billing & errors\n\n| HTTP status | Billed? | Meaning |\n| --- | --- | --- |\n| 200 | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing |\n| 400 | No | Invalid input, skipped PDF, or the page could not be scraped |\n| 401 / 403 | No | Invalid/disabled key, insufficient permissions, or credits exhausted; inspect error_code |\n| 404 | No | Target page returned or fingerprinted as not found |\n| 408 | No | Request timed out |\n| 413 | No | Target content exceeds the maximum supported size (20 MB) |\n| 415 | No | Unsupported content type |\n| 429 | No | Per-minute rate limit exceeded; honor Retry-After |\n| 500 | No | Internal error |\n\n### Parameters\n\n- `url: string`\n Full URL to scrape into LLM usable Markdown (must include http:// or https:// protocol)\n\n- `actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; }[]`\n Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions.\n\n- `country?: string`\n Fetch the target page through a residential proxy in this country (ISO 3166-1 alpha-2).\n\n- `excludeSelectors?: string[]`\n CSS selectors to remove before conversion to Markdown. Applied after includeSelectors. Exclusion takes precedence: an element matching both is removed. Examples: \"nav\", \"footer\", \".ad-banner\", \"[aria-hidden=true]\".\n\n- `headers?: object`\n Optional outbound HTTP headers forwarded only to the target URL, sent as deep-object query params such as headers[X-Custom]=value. When provided, caching is bypassed: the result is neither read from nor written to cache.\n\n- `includeFrames?: boolean | 'true' | 'false'`\n When true, the contents of iframes are rendered to Markdown.\n\n- `includeImages?: boolean | 'true' | 'false'`\n Include image references in Markdown output\n\n- `includeLinks?: boolean | 'true' | 'false'`\n Preserve hyperlinks in Markdown output\n\n- `includeSelectors?: string[]`\n CSS selectors. When provided, only matching HTML subtrees (and their descendants) are kept before conversion to Markdown. When omitted, the entire document is kept. Examples: \"article.main\", \"#content\", \"[role=main]\".\n\n- `maxAgeMs?: number`\n Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh.\n\n- `pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }`\n PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range.\n - `end?: number`\n Last 1-based PDF page to parse. When omitted, parsing ends at the last page. Must be greater than or equal to start when both are provided.\n - `ocr?: boolean | 'true' | 'false'`\n When true, OCR the selected PDF pages that have no usable text layer (scans), replacing each recovered page's text with the OCR result while pages with a real text layer keep it. Billed at 1 credit per page OCR actually recovered, on top of the base request cost. When false, no OCR runs.\n - `shouldParse?: boolean | 'true' | 'false'`\n When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and a 400 PDF_SKIPPED is returned.\n - `start?: number`\n First 1-based PDF page to parse. When omitted, parsing starts at the first page.\n\n- `settleAnimations?: boolean | 'true' | 'false'`\n When true, waits briefly for CSS and transition animations to settle before converting to Markdown. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages.\n\n- `shortenBase64Images?: boolean | 'true' | 'false'`\n Shorten base64-encoded image data in the Markdown output\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n- `useMainContentOnly?: boolean | 'true' | 'false'`\n Extract only the main content of the page, excluding headers, footers, sidebars, and navigation\n\n- `waitForMs?: number`\n Optional browser wait time in milliseconds after initial page load before converting the page to Markdown. Min: 0. Max: 30000 (30 seconds).\n\n- `zdr?: 'enabled' | 'disabled'`\n Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.\n\n### Returns\n\n- `{ contentLength: number; markdown: string; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; success: true; url: string; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; actionsHtmlStale?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `contentLength: number`\n - `markdown: string`\n - `metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }`\n - `success: true`\n - `url: string`\n - `actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]`\n - `actionsHtmlStale?: boolean`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.webScrapeMd({ url: 'https://example.com' });\n\nconsole.log(response);\n```", + "## web_scrape_md\n\n`client.web.webScrapeMd(url: string, actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; }[], country?: string, excludeSelectors?: string[], headers?: object, includeFrames?: boolean | 'true' | 'false', includeImages?: boolean | 'true' | 'false', includeLinks?: boolean | 'true' | 'false', includeSelectors?: string[], maxAgeMs?: number, pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }, settleAnimations?: boolean | 'true' | 'false', shortenBase64Images?: boolean | 'true' | 'false', tags?: string[], timeoutMS?: number, useMainContentOnly?: boolean | 'true' | 'false', waitForMs?: number, zdr?: 'enabled' | 'disabled'): { contentLength: number; markdown: string; metadata: object; success: true; url: string; actionsApplied?: object[]; actionsHtmlStale?: boolean; key_metadata?: object; }`\n\n**get** `/web/scrape/markdown`\n\nScrapes the given URL into LLM usable Markdown. Inspect key_metadata on JSON responses from a recognized API key; use error_code to distinguish stable failure categories.\n\n### YouTube\n\nYouTube URLs return the video or channel itself rather than the surrounding player and navigation chrome. A URL addressing a single video (`/watch`, `youtu.be`, `/shorts`, `/embed`, `/live`) returns its title, channel, duration, view count, keywords, full description, and the transcript when the video has captions that can be retrieved; videos without captions return everything except the transcript. A channel URL (`/channel/UC…`, `/@handle`, `/c/…`, `/user/…`) returns its name, handle, subscriber count, video count, and full description. When `includeImages=true`, video responses also include the thumbnail and channel responses include the avatar. Costs the same as any other scrape.\n\n### Billing & errors\n\n| HTTP status | Billed? | Meaning |\n| --- | --- | --- |\n| 200 | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing |\n| 400 | No | Invalid input, skipped PDF, or the page could not be scraped. error_code WEBSITE_BLOCKED specifically means the site answered with an anti-bot challenge, CAPTCHA wall, or login shell instead of the page (even when the site returned HTTP 200) — retrying later or from another country sometimes succeeds |\n| 401 / 403 | No | Invalid/disabled key, insufficient permissions, or credits exhausted; inspect error_code |\n| 404 | No | Target page returned or fingerprinted as not found |\n| 408 | No | Request timed out |\n| 413 | No | Target content exceeds the maximum supported size (20 MB) |\n| 415 | No | Unsupported content type |\n| 429 | No | Per-minute rate limit exceeded; honor Retry-After |\n| 500 | No | Internal error |\n\n### Parameters\n\n- `url: string`\n Full URL to scrape into LLM usable Markdown (must include http:// or https:// protocol)\n\n- `actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; }[]`\n Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions.\n\n- `country?: string`\n Fetch the target page through a residential proxy in this country (ISO 3166-1 alpha-2).\n\n- `excludeSelectors?: string[]`\n CSS selectors to remove before conversion to Markdown. Applied after includeSelectors. Exclusion takes precedence: an element matching both is removed. Examples: \"nav\", \"footer\", \".ad-banner\", \"[aria-hidden=true]\".\n\n- `headers?: object`\n Optional outbound HTTP headers forwarded only to the target URL, sent as deep-object query params such as headers[X-Custom]=value. When provided, caching is bypassed: the result is neither read from nor written to cache.\n\n- `includeFrames?: boolean | 'true' | 'false'`\n When true, the contents of iframes are rendered to Markdown.\n\n- `includeImages?: boolean | 'true' | 'false'`\n Include image references in Markdown output\n\n- `includeLinks?: boolean | 'true' | 'false'`\n Preserve hyperlinks in Markdown output\n\n- `includeSelectors?: string[]`\n CSS selectors. When provided, only matching HTML subtrees (and their descendants) are kept before conversion to Markdown. When omitted, the entire document is kept. Examples: \"article.main\", \"#content\", \"[role=main]\".\n\n- `maxAgeMs?: number`\n Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh.\n\n- `pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }`\n PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range.\n - `end?: number`\n Last 1-based PDF page to parse. When omitted, parsing ends at the last page. Must be greater than or equal to start when both are provided.\n - `ocr?: boolean | 'true' | 'false'`\n When true, OCR the selected PDF pages that have no usable text layer (scans), replacing each recovered page's text with the OCR result while pages with a real text layer keep it. Billed at 1 credit per page OCR actually recovered, on top of the base request cost. When false, no OCR runs.\n - `shouldParse?: boolean | 'true' | 'false'`\n When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and a 400 PDF_SKIPPED is returned.\n - `start?: number`\n First 1-based PDF page to parse. When omitted, parsing starts at the first page.\n\n- `settleAnimations?: boolean | 'true' | 'false'`\n When true, waits briefly for CSS and transition animations to settle before converting to Markdown. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages.\n\n- `shortenBase64Images?: boolean | 'true' | 'false'`\n Shorten base64-encoded image data in the Markdown output\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n- `useMainContentOnly?: boolean | 'true' | 'false'`\n Extract only the main content of the page, excluding headers, footers, sidebars, and navigation\n\n- `waitForMs?: number`\n Optional browser wait time in milliseconds after initial page load before converting the page to Markdown. Min: 0. Max: 30000 (30 seconds).\n\n- `zdr?: 'enabled' | 'disabled'`\n Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.\n\n### Returns\n\n- `{ contentLength: number; markdown: string; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; success: true; url: string; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; actionsHtmlStale?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `contentLength: number`\n - `markdown: string`\n - `metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }`\n - `success: true`\n - `url: string`\n - `actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]`\n - `actionsHtmlStale?: boolean`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.webScrapeMd({ url: 'https://example.com' });\n\nconsole.log(response);\n```", perLanguage: { typescript: { method: 'client.web.webScrapeMd', @@ -466,9 +466,9 @@ const EMBEDDED_METHODS: MethodEntry[] = [ "zdr?: 'enabled' | 'disabled';", ], response: - '{ metadata: { maxCrawlDepth: number; numFailed: number; numSkipped: number; numSucceeded: number; numUrls: number; }; results: { markdown: string; metadata: { crawlDepth: number; finalUrl: string; sourceUrl: string; statusCode: number; success: boolean; title: string; url: string; additionalMeta?: object; alternates?: object[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; twitter?: object; }; }[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }', + '{ metadata: { maxCrawlDepth: number; numFailed: number; numSkipped: number; numSucceeded: number; numUrls: number; }; results: { markdown: string; metadata: { crawlDepth: number; finalUrl: string; sourceUrl: string; statusCode: number; success: boolean; title: string; url: string; additionalMeta?: object; alternates?: object[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: object[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; twitter?: object; }; }[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }', markdown: - '## web_crawl_md\n\n`client.web.webCrawlMd(url: string, country?: string, excludeSelectors?: string[], followSubdomains?: boolean, includeFrames?: boolean, includeImages?: boolean, includeLinks?: boolean, includeSelectors?: string[], maxAgeMs?: number, maxDepth?: number, maxPages?: number, pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }, settleAnimations?: boolean, shortenBase64Images?: boolean, stopAfterMs?: number, tags?: string[], timeoutMS?: number, urlRegex?: string, useMainContentOnly?: boolean, waitForMs?: number, zdr?: \'enabled\' | \'disabled\'): { metadata: object; results: object[]; key_metadata?: object; }`\n\n**post** `/web/crawl`\n\nPerforms a crawl starting from a given URL, extracts page content as Markdown, and returns results for all crawled pages.\n\n### Parameters\n\n- `url: string`\n The starting URL for the crawl (must include http:// or https:// protocol)\n\n- `country?: string`\n Fetch the target page through a residential proxy in this country (ISO 3166-1 alpha-2).\n\n- `excludeSelectors?: string[]`\n CSS selectors to remove before each crawled page is converted to Markdown. Applied after includeSelectors. Exclusion takes precedence: an element matching both is removed. Examples: "nav", "footer", ".ad-banner", "[aria-hidden=true]".\n\n- `followSubdomains?: boolean`\n When true, follow links on subdomains of the starting URL\'s domain (e.g. docs.example.com when starting from example.com). www and apex are always treated as equivalent.\n\n- `includeFrames?: boolean`\n When true, the contents of iframes are rendered to Markdown for each crawled page.\n\n- `includeImages?: boolean`\n Include image references in the Markdown output\n\n- `includeLinks?: boolean`\n Preserve hyperlinks in the Markdown output\n\n- `includeSelectors?: string[]`\n CSS selectors. When provided, only matching HTML subtrees (and their descendants) are kept before each crawled page is converted to Markdown. When omitted, the entire document is kept. Examples: "article.main", "#content", "[role=main]".\n\n- `maxAgeMs?: number`\n Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh.\n\n- `maxDepth?: number`\n Maximum link depth from the starting URL (0 = only the starting page)\n\n- `maxPages?: number`\n Maximum number of pages to crawl. Hard cap: 500.\n\n- `pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }`\n PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range.\n - `end?: number`\n Last 1-based PDF page to parse. When omitted, parsing ends at the last page. Must be greater than or equal to start when both are provided.\n - `ocr?: boolean`\n When true, OCR the selected PDF pages that have no usable text layer (scans), replacing each recovered page\'s text with the OCR result while pages with a real text layer keep it. Billed at 1 credit per page OCR actually recovered, on top of the base request cost.\n - `shouldParse?: boolean`\n When true, PDF pages are fetched and parsed. When false, PDF pages are skipped entirely (not included in results and not counted as failures).\n - `start?: number`\n First 1-based PDF page to parse. When omitted, parsing starts at the first page.\n\n- `settleAnimations?: boolean`\n When true, waits briefly for CSS and transition animations to settle before extracting each crawled page. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages.\n\n- `shortenBase64Images?: boolean`\n Truncate base64-encoded image data in the Markdown output\n\n- `stopAfterMs?: number`\n Soft time budget for the crawl in milliseconds. After each scrape, the crawler checks the elapsed time and, if exceeded, returns the pages collected so far instead of continuing. Min: 10000 (10s). Max: 110000 (110s). Default: 80000 (80s).\n\n- `tags?: string[]`\n Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n- `urlRegex?: string`\n Regex pattern. Only URLs matching this pattern will be followed and scraped.\n\n- `useMainContentOnly?: boolean`\n Extract only the main content, stripping headers, footers, sidebars, and navigation\n\n- `waitForMs?: number`\n Optional browser wait time in milliseconds after initial page load for each crawled page. Min: 0. Max: 30000 (30 seconds). \n\n- `zdr?: \'enabled\' | \'disabled\'`\n Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.\n\n### Returns\n\n- `{ metadata: { maxCrawlDepth: number; numFailed: number; numSkipped: number; numSucceeded: number; numUrls: number; }; results: { markdown: string; metadata: { crawlDepth: number; finalUrl: string; sourceUrl: string; statusCode: number; success: boolean; title: string; url: string; additionalMeta?: object; alternates?: object[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; twitter?: object; }; }[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `metadata: { maxCrawlDepth: number; numFailed: number; numSkipped: number; numSucceeded: number; numUrls: number; }`\n - `results: { markdown: string; metadata: { crawlDepth: number; finalUrl: string; sourceUrl: string; statusCode: number; success: boolean; title: string; url: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; twitter?: object; }; }[]`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from \'context.dev\';\n\nconst client = new ContextDev();\n\nconst response = await client.web.webCrawlMd({ url: \'https://example.com\' });\n\nconsole.log(response);\n```', + '## web_crawl_md\n\n`client.web.webCrawlMd(url: string, country?: string, excludeSelectors?: string[], followSubdomains?: boolean, includeFrames?: boolean, includeImages?: boolean, includeLinks?: boolean, includeSelectors?: string[], maxAgeMs?: number, maxDepth?: number, maxPages?: number, pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }, settleAnimations?: boolean, shortenBase64Images?: boolean, stopAfterMs?: number, tags?: string[], timeoutMS?: number, urlRegex?: string, useMainContentOnly?: boolean, waitForMs?: number, zdr?: \'enabled\' | \'disabled\'): { metadata: object; results: object[]; key_metadata?: object; }`\n\n**post** `/web/crawl`\n\nPerforms a crawl starting from a given URL, extracts page content as Markdown, and returns results for all crawled pages.\n\n### Parameters\n\n- `url: string`\n The starting URL for the crawl (must include http:// or https:// protocol)\n\n- `country?: string`\n Fetch the target page through a residential proxy in this country (ISO 3166-1 alpha-2).\n\n- `excludeSelectors?: string[]`\n CSS selectors to remove before each crawled page is converted to Markdown. Applied after includeSelectors. Exclusion takes precedence: an element matching both is removed. Examples: "nav", "footer", ".ad-banner", "[aria-hidden=true]".\n\n- `followSubdomains?: boolean`\n When true, follow links on subdomains of the starting URL\'s domain (e.g. docs.example.com when starting from example.com). www and apex are always treated as equivalent.\n\n- `includeFrames?: boolean`\n When true, the contents of iframes are rendered to Markdown for each crawled page.\n\n- `includeImages?: boolean`\n Include image references in the Markdown output\n\n- `includeLinks?: boolean`\n Preserve hyperlinks in the Markdown output\n\n- `includeSelectors?: string[]`\n CSS selectors. When provided, only matching HTML subtrees (and their descendants) are kept before each crawled page is converted to Markdown. When omitted, the entire document is kept. Examples: "article.main", "#content", "[role=main]".\n\n- `maxAgeMs?: number`\n Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh.\n\n- `maxDepth?: number`\n Maximum link depth from the starting URL (0 = only the starting page)\n\n- `maxPages?: number`\n Maximum number of pages to crawl. Hard cap: 500.\n\n- `pdf?: { end?: number; ocr?: boolean; shouldParse?: boolean; start?: number; }`\n PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range.\n - `end?: number`\n Last 1-based PDF page to parse. When omitted, parsing ends at the last page. Must be greater than or equal to start when both are provided.\n - `ocr?: boolean`\n When true, OCR the selected PDF pages that have no usable text layer (scans), replacing each recovered page\'s text with the OCR result while pages with a real text layer keep it. Billed at 1 credit per page OCR actually recovered, on top of the base request cost.\n - `shouldParse?: boolean`\n When true, PDF pages are fetched and parsed. When false, PDF pages are skipped entirely (not included in results and not counted as failures).\n - `start?: number`\n First 1-based PDF page to parse. When omitted, parsing starts at the first page.\n\n- `settleAnimations?: boolean`\n When true, waits briefly for CSS and transition animations to settle before extracting each crawled page. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages.\n\n- `shortenBase64Images?: boolean`\n Truncate base64-encoded image data in the Markdown output\n\n- `stopAfterMs?: number`\n Soft time budget for the crawl in milliseconds. After each scrape, the crawler checks the elapsed time and, if exceeded, returns the pages collected so far instead of continuing. Min: 10000 (10s). Max: 110000 (110s). Default: 80000 (80s).\n\n- `tags?: string[]`\n Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n- `urlRegex?: string`\n Regex pattern. Only URLs matching this pattern will be followed and scraped.\n\n- `useMainContentOnly?: boolean`\n Extract only the main content, stripping headers, footers, sidebars, and navigation\n\n- `waitForMs?: number`\n Optional browser wait time in milliseconds after initial page load for each crawled page. Min: 0. Max: 30000 (30 seconds). \n\n- `zdr?: \'enabled\' | \'disabled\'`\n Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.\n\n### Returns\n\n- `{ metadata: { maxCrawlDepth: number; numFailed: number; numSkipped: number; numSucceeded: number; numUrls: number; }; results: { markdown: string; metadata: { crawlDepth: number; finalUrl: string; sourceUrl: string; statusCode: number; success: boolean; title: string; url: string; additionalMeta?: object; alternates?: object[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: object[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; twitter?: object; }; }[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `metadata: { maxCrawlDepth: number; numFailed: number; numSkipped: number; numSucceeded: number; numUrls: number; }`\n - `results: { markdown: string; metadata: { crawlDepth: number; finalUrl: string; sourceUrl: string; statusCode: number; success: boolean; title: string; url: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; twitter?: object; }; }[]`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from \'context.dev\';\n\nconst client = new ContextDev();\n\nconst response = await client.web.webCrawlMd({ url: \'https://example.com\' });\n\nconsole.log(response);\n```', perLanguage: { typescript: { method: 'client.web.webCrawlMd', @@ -2086,9 +2086,9 @@ const EMBEDDED_METHODS: MethodEntry[] = [ qualified: 'client.batch.getResults', params: ['batch_id: string;', 'cursor?: string;', 'limit?: number;'], response: - "{ data?: { final_url: string; http_status: number; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: object[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; status: 'ok'; url: string; html?: string; itemId?: string; markdown?: string; meta?: object; ocr_pages?: number; } | { error_code: string; message: string; status: 'error'; url: string; itemId?: string; meta?: object; }[]; has_more?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; next_cursor?: string; }", + "{ data?: { final_url: string; http_status: number; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: object[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: object[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; status: 'ok'; url: string; html?: string; itemId?: string; markdown?: string; meta?: object; ocr_pages?: number; } | { error_code: string; message: string; status: 'error'; url: string; itemId?: string; meta?: object; }[]; has_more?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; next_cursor?: string; }", markdown: - "## get_results\n\n`client.batch.getResults(batch_id: string, cursor?: string, limit?: number): { data?: object | object[]; has_more?: boolean; key_metadata?: object; next_cursor?: string; }`\n\n**get** `/batch/{batch_id}/results`\n\nPage through a finished batch's results as JSON instead of downloading the NDJSON files.\n\n### Parameters\n\n- `batch_id: string`\n ID of the batch to retrieve or cancel.\n\n- `cursor?: string`\n next_cursor from the previous page.\n\n- `limit?: number`\n Records per page. Defaults to 25. A page can close early so its payload stays under ~8 MB; rely on next_cursor rather than counting records.\n\n### Returns\n\n- `{ data?: { final_url: string; http_status: number; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: object[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; status: 'ok'; url: string; html?: string; itemId?: string; markdown?: string; meta?: object; ocr_pages?: number; } | { error_code: string; message: string; status: 'error'; url: string; itemId?: string; meta?: object; }[]; has_more?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; next_cursor?: string; }`\n\n - `data?: { final_url: string; http_status: number; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; status: 'ok'; url: string; html?: string; itemId?: string; markdown?: string; meta?: object; ocr_pages?: number; } | { error_code: string; message: string; status: 'error'; url: string; itemId?: string; meta?: object; }[]`\n - `has_more?: boolean`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n - `next_cursor?: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.batch.getResults('batch_9f2c8a');\n\nconsole.log(response);\n```", + "## get_results\n\n`client.batch.getResults(batch_id: string, cursor?: string, limit?: number): { data?: object | object[]; has_more?: boolean; key_metadata?: object; next_cursor?: string; }`\n\n**get** `/batch/{batch_id}/results`\n\nPage through a finished batch's results as JSON instead of downloading the NDJSON files.\n\n### Parameters\n\n- `batch_id: string`\n ID of the batch to retrieve or cancel.\n\n- `cursor?: string`\n next_cursor from the previous page.\n\n- `limit?: number`\n Records per page. Defaults to 25. A page can close early so its payload stays under ~8 MB; rely on next_cursor rather than counting records.\n\n### Returns\n\n- `{ data?: { final_url: string; http_status: number; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: object[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: object[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; status: 'ok'; url: string; html?: string; itemId?: string; markdown?: string; meta?: object; ocr_pages?: number; } | { error_code: string; message: string; status: 'error'; url: string; itemId?: string; meta?: object; }[]; has_more?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; next_cursor?: string; }`\n\n - `data?: { final_url: string; http_status: number; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; status: 'ok'; url: string; html?: string; itemId?: string; markdown?: string; meta?: object; ocr_pages?: number; } | { error_code: string; message: string; status: 'error'; url: string; itemId?: string; meta?: object; }[]`\n - `has_more?: boolean`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n - `next_cursor?: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.batch.getResults('batch_9f2c8a');\n\nconsole.log(response);\n```", perLanguage: { typescript: { method: 'client.batch.getResults', diff --git a/src/resources/batch.ts b/src/resources/batch.ts index 79a9f56..062b78a 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -969,6 +969,12 @@ export namespace BatchGetResultsResponse { */ favicon?: string; + /** + * Page headings (h1–h6) in document order, extracted from the unfiltered document. + * Capped at the first 500 headings. Omitted when the page has none. + */ + headings?: Array; + /** * Primary resolved preview image from Open Graph, Twitter, or image metadata. */ @@ -1047,6 +1053,18 @@ export namespace BatchGetResultsResponse { */ type?: string; } + + export interface Heading { + /** + * Heading level, 1–6 (from h1–h6). + */ + level: number; + + /** + * Heading text with whitespace collapsed, truncated to 1000 characters. + */ + text: string; + } } } diff --git a/src/resources/web.ts b/src/resources/web.ts index 4145f32..50bceb6 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -176,17 +176,17 @@ export class Web extends APIResource { * * ### Billing & errors * - * | HTTP status | Billed? | Meaning | - * | ----------- | ----------------------------------------- | ---------------------------------------------------------------------------------------- | - * | 200 | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing | - * | 400 | No | Invalid input, skipped PDF, or the page could not be scraped | - * | 401 / 403 | No | Invalid/disabled key, insufficient permissions, or credits exhausted; inspect error_code | - * | 404 | No | Target page returned or fingerprinted as not found | - * | 408 | No | Request timed out | - * | 413 | No | Target content exceeds the maximum supported size (20 MB) | - * | 415 | No | Unsupported content type | - * | 429 | No | Per-minute rate limit exceeded; honor Retry-After | - * | 500 | No | Internal error | + * | HTTP status | Billed? | Meaning | + * | ----------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + * | 200 | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing | + * | 400 | No | Invalid input, skipped PDF, or the page could not be scraped. error_code WEBSITE_BLOCKED specifically means the site answered with an anti-bot challenge, CAPTCHA wall, or login shell instead of the page (even when the site returned HTTP 200) — retrying later or from another country sometimes succeeds | + * | 401 / 403 | No | Invalid/disabled key, insufficient permissions, or credits exhausted; inspect error_code | + * | 404 | No | Target page returned or fingerprinted as not found | + * | 408 | No | Request timed out | + * | 413 | No | Target content exceeds the maximum supported size (20 MB) | + * | 415 | No | Unsupported content type | + * | 429 | No | Per-minute rate limit exceeded; honor Retry-After | + * | 500 | No | Internal error | * * @example * ```ts @@ -1296,6 +1296,12 @@ export namespace WebWebCrawlMdResponse { */ favicon?: string; + /** + * Page headings (h1–h6) in document order, extracted from the unfiltered document. + * Capped at the first 500 headings. Omitted when the page has none. + */ + headings?: Array; + /** * Primary resolved preview image from Open Graph, Twitter, or image metadata. */ @@ -1369,6 +1375,18 @@ export namespace WebWebCrawlMdResponse { */ type?: string; } + + export interface Heading { + /** + * Heading level, 1–6 (from h1–h6). + */ + level: number; + + /** + * Heading text with whitespace collapsed, truncated to 1000 characters. + */ + text: string; + } } } @@ -1498,6 +1516,12 @@ export namespace WebWebScrapeHTMLResponse { */ favicon?: string; + /** + * Page headings (h1–h6) in document order, extracted from the unfiltered document. + * Capped at the first 500 headings. Omitted when the page has none. + */ + headings?: Array; + /** * Primary resolved preview image from Open Graph, Twitter, or image metadata. */ @@ -1576,6 +1600,18 @@ export namespace WebWebScrapeHTMLResponse { */ type?: string; } + + export interface Heading { + /** + * Heading level, 1–6 (from h1–h6). + */ + level: number; + + /** + * Heading text with whitespace collapsed, truncated to 1000 characters. + */ + text: string; + } } export interface ActionsApplied { @@ -1810,6 +1846,12 @@ export namespace WebWebScrapeMdResponse { */ favicon?: string; + /** + * Page headings (h1–h6) in document order, extracted from the unfiltered document. + * Capped at the first 500 headings. Omitted when the page has none. + */ + headings?: Array; + /** * Primary resolved preview image from Open Graph, Twitter, or image metadata. */ @@ -1888,6 +1930,18 @@ export namespace WebWebScrapeMdResponse { */ type?: string; } + + export interface Heading { + /** + * Heading level, 1–6 (from h1–h6). + */ + level: number; + + /** + * Heading text with whitespace collapsed, truncated to 1000 characters. + */ + text: string; + } } export interface ActionsApplied { From fd6690d37c59c46a8e34bc497dfe6013cb20f434 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Mon, 10 Aug 2026 09:03:48 +0000 Subject: [PATCH 2/3] feat(api): api update --- .stats.yml | 4 +-- packages/mcp-server/src/local-docs-search.ts | 23 +++++++------- src/resources/batch.ts | 15 ++++++++- src/resources/utility.ts | 33 ++++++++++---------- src/resources/web.ts | 14 +++++++++ tests/api-resources/batch.test.ts | 1 + tests/api-resources/web.test.ts | 1 + 7 files changed, 61 insertions(+), 30 deletions(-) diff --git a/.stats.yml b/.stats.yml index 90b5514..f9b95cb 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,4 +1,4 @@ configured_endpoints: 40 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/context-dev/context.dev-1c93116e47cab52ea63490f5bca186ed3acda8bbd7f0ce5a320effb9f5b72b1f.yml -openapi_spec_hash: f56204d55bd4bffb6e4d50d6a5d9471a +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/context-dev/context.dev-7f75f39699c1298d16691b5a58b1312a229b78288fba6e2de4040ba1422e530f.yml +openapi_spec_hash: b3ad781596e4c52fde918cfaae54a5d4 config_hash: 920678668dd2da6f8966fbf1b8fde4e2 diff --git a/packages/mcp-server/src/local-docs-search.ts b/packages/mcp-server/src/local-docs-search.ts index aacf645..241a346 100644 --- a/packages/mcp-server/src/local-docs-search.ts +++ b/packages/mcp-server/src/local-docs-search.ts @@ -195,6 +195,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ 'excludeSelectors?: string[];', 'headers?: object;', "includeFrames?: boolean | 'true' | 'false';", + "includeHTML?: boolean | 'true' | 'false';", "includeImages?: boolean | 'true' | 'false';", "includeLinks?: boolean | 'true' | 'false';", 'includeSelectors?: string[];', @@ -209,9 +210,9 @@ const EMBEDDED_METHODS: MethodEntry[] = [ "zdr?: 'enabled' | 'disabled';", ], response: - "{ contentLength: number; markdown: string; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; success: true; url: string; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; actionsHtmlStale?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", + "{ contentLength: number; markdown: string; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; success: true; url: string; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; actionsHtmlStale?: boolean; html?: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }", markdown: - "## web_scrape_md\n\n`client.web.webScrapeMd(url: string, actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; }[], country?: string, excludeSelectors?: string[], headers?: object, includeFrames?: boolean | 'true' | 'false', includeImages?: boolean | 'true' | 'false', includeLinks?: boolean | 'true' | 'false', includeSelectors?: string[], maxAgeMs?: number, pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }, settleAnimations?: boolean | 'true' | 'false', shortenBase64Images?: boolean | 'true' | 'false', tags?: string[], timeoutMS?: number, useMainContentOnly?: boolean | 'true' | 'false', waitForMs?: number, zdr?: 'enabled' | 'disabled'): { contentLength: number; markdown: string; metadata: object; success: true; url: string; actionsApplied?: object[]; actionsHtmlStale?: boolean; key_metadata?: object; }`\n\n**get** `/web/scrape/markdown`\n\nScrapes the given URL into LLM usable Markdown. Inspect key_metadata on JSON responses from a recognized API key; use error_code to distinguish stable failure categories.\n\n### YouTube\n\nYouTube URLs return the video or channel itself rather than the surrounding player and navigation chrome. A URL addressing a single video (`/watch`, `youtu.be`, `/shorts`, `/embed`, `/live`) returns its title, channel, duration, view count, keywords, full description, and the transcript when the video has captions that can be retrieved; videos without captions return everything except the transcript. A channel URL (`/channel/UC…`, `/@handle`, `/c/…`, `/user/…`) returns its name, handle, subscriber count, video count, and full description. When `includeImages=true`, video responses also include the thumbnail and channel responses include the avatar. Costs the same as any other scrape.\n\n### Billing & errors\n\n| HTTP status | Billed? | Meaning |\n| --- | --- | --- |\n| 200 | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing |\n| 400 | No | Invalid input, skipped PDF, or the page could not be scraped. error_code WEBSITE_BLOCKED specifically means the site answered with an anti-bot challenge, CAPTCHA wall, or login shell instead of the page (even when the site returned HTTP 200) — retrying later or from another country sometimes succeeds |\n| 401 / 403 | No | Invalid/disabled key, insufficient permissions, or credits exhausted; inspect error_code |\n| 404 | No | Target page returned or fingerprinted as not found |\n| 408 | No | Request timed out |\n| 413 | No | Target content exceeds the maximum supported size (20 MB) |\n| 415 | No | Unsupported content type |\n| 429 | No | Per-minute rate limit exceeded; honor Retry-After |\n| 500 | No | Internal error |\n\n### Parameters\n\n- `url: string`\n Full URL to scrape into LLM usable Markdown (must include http:// or https:// protocol)\n\n- `actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; }[]`\n Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions.\n\n- `country?: string`\n Fetch the target page through a residential proxy in this country (ISO 3166-1 alpha-2).\n\n- `excludeSelectors?: string[]`\n CSS selectors to remove before conversion to Markdown. Applied after includeSelectors. Exclusion takes precedence: an element matching both is removed. Examples: \"nav\", \"footer\", \".ad-banner\", \"[aria-hidden=true]\".\n\n- `headers?: object`\n Optional outbound HTTP headers forwarded only to the target URL, sent as deep-object query params such as headers[X-Custom]=value. When provided, caching is bypassed: the result is neither read from nor written to cache.\n\n- `includeFrames?: boolean | 'true' | 'false'`\n When true, the contents of iframes are rendered to Markdown.\n\n- `includeImages?: boolean | 'true' | 'false'`\n Include image references in Markdown output\n\n- `includeLinks?: boolean | 'true' | 'false'`\n Preserve hyperlinks in Markdown output\n\n- `includeSelectors?: string[]`\n CSS selectors. When provided, only matching HTML subtrees (and their descendants) are kept before conversion to Markdown. When omitted, the entire document is kept. Examples: \"article.main\", \"#content\", \"[role=main]\".\n\n- `maxAgeMs?: number`\n Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh.\n\n- `pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }`\n PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range.\n - `end?: number`\n Last 1-based PDF page to parse. When omitted, parsing ends at the last page. Must be greater than or equal to start when both are provided.\n - `ocr?: boolean | 'true' | 'false'`\n When true, OCR the selected PDF pages that have no usable text layer (scans), replacing each recovered page's text with the OCR result while pages with a real text layer keep it. Billed at 1 credit per page OCR actually recovered, on top of the base request cost. When false, no OCR runs.\n - `shouldParse?: boolean | 'true' | 'false'`\n When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and a 400 PDF_SKIPPED is returned.\n - `start?: number`\n First 1-based PDF page to parse. When omitted, parsing starts at the first page.\n\n- `settleAnimations?: boolean | 'true' | 'false'`\n When true, waits briefly for CSS and transition animations to settle before converting to Markdown. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages.\n\n- `shortenBase64Images?: boolean | 'true' | 'false'`\n Shorten base64-encoded image data in the Markdown output\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n- `useMainContentOnly?: boolean | 'true' | 'false'`\n Extract only the main content of the page, excluding headers, footers, sidebars, and navigation\n\n- `waitForMs?: number`\n Optional browser wait time in milliseconds after initial page load before converting the page to Markdown. Min: 0. Max: 30000 (30 seconds).\n\n- `zdr?: 'enabled' | 'disabled'`\n Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.\n\n### Returns\n\n- `{ contentLength: number; markdown: string; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; success: true; url: string; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; actionsHtmlStale?: boolean; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `contentLength: number`\n - `markdown: string`\n - `metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }`\n - `success: true`\n - `url: string`\n - `actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]`\n - `actionsHtmlStale?: boolean`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.webScrapeMd({ url: 'https://example.com' });\n\nconsole.log(response);\n```", + "## web_scrape_md\n\n`client.web.webScrapeMd(url: string, actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; }[], country?: string, excludeSelectors?: string[], headers?: object, includeFrames?: boolean | 'true' | 'false', includeHTML?: boolean | 'true' | 'false', includeImages?: boolean | 'true' | 'false', includeLinks?: boolean | 'true' | 'false', includeSelectors?: string[], maxAgeMs?: number, pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }, settleAnimations?: boolean | 'true' | 'false', shortenBase64Images?: boolean | 'true' | 'false', tags?: string[], timeoutMS?: number, useMainContentOnly?: boolean | 'true' | 'false', waitForMs?: number, zdr?: 'enabled' | 'disabled'): { contentLength: number; markdown: string; metadata: object; success: true; url: string; actionsApplied?: object[]; actionsHtmlStale?: boolean; html?: string; key_metadata?: object; }`\n\n**get** `/web/scrape/markdown`\n\nScrapes the given URL into LLM usable Markdown. Inspect key_metadata on JSON responses from a recognized API key; use error_code to distinguish stable failure categories.\n\n### YouTube\n\nYouTube URLs return the video or channel itself rather than the surrounding player and navigation chrome. A URL addressing a single video (`/watch`, `youtu.be`, `/shorts`, `/embed`, `/live`) returns its title, channel, duration, view count, keywords, full description, and the transcript when the video has captions that can be retrieved; videos without captions return everything except the transcript. A channel URL (`/channel/UC…`, `/@handle`, `/c/…`, `/user/…`) returns its name, handle, subscriber count, video count, and full description. When `includeImages=true`, video responses also include the thumbnail and channel responses include the avatar. Costs the same as any other scrape.\n\n### Billing & errors\n\n| HTTP status | Billed? | Meaning |\n| --- | --- | --- |\n| 200 | Yes — 1 credit, or 2 credits with actions | Successful scrape, including a zero-length result when includeSelectors matched nothing |\n| 400 | No | Invalid input, skipped PDF, or the page could not be scraped. error_code WEBSITE_BLOCKED specifically means the site answered with an anti-bot challenge, CAPTCHA wall, or login shell instead of the page (even when the site returned HTTP 200) — retrying later or from another country sometimes succeeds |\n| 401 / 403 | No | Invalid/disabled key, insufficient permissions, or credits exhausted; inspect error_code |\n| 404 | No | Target page returned or fingerprinted as not found |\n| 408 | No | Request timed out |\n| 413 | No | Target content exceeds the maximum supported size (20 MB) |\n| 415 | No | Unsupported content type |\n| 429 | No | Per-minute rate limit exceeded; honor Retry-After |\n| 500 | No | Internal error |\n\n### Parameters\n\n- `url: string`\n Full URL to scrape into LLM usable Markdown (must include http:// or https:// protocol)\n\n- `actions?: { do: 'wait'; timeMs: number; } | { action: string; do: 'perform'; }[]`\n Optional browser actions executed in array order after the page loads and before content is captured. Requires a paid plan. Send a JSON array in the query parameter. Maximum: 5 actions.\n\n- `country?: string`\n Fetch the target page through a residential proxy in this country (ISO 3166-1 alpha-2).\n\n- `excludeSelectors?: string[]`\n CSS selectors to remove before conversion to Markdown. Applied after includeSelectors. Exclusion takes precedence: an element matching both is removed. Examples: \"nav\", \"footer\", \".ad-banner\", \"[aria-hidden=true]\".\n\n- `headers?: object`\n Optional outbound HTTP headers forwarded only to the target URL, sent as deep-object query params such as headers[X-Custom]=value. When provided, caching is bypassed: the result is neither read from nor written to cache.\n\n- `includeFrames?: boolean | 'true' | 'false'`\n When true, the contents of iframes are rendered to Markdown.\n\n- `includeHTML?: boolean | 'true' | 'false'`\n When true, the response also includes an `html` field with the page HTML the Markdown was converted from — the same body the Scrape HTML endpoint returns for the equivalent request.\n\n- `includeImages?: boolean | 'true' | 'false'`\n Include image references in Markdown output\n\n- `includeLinks?: boolean | 'true' | 'false'`\n Preserve hyperlinks in Markdown output\n\n- `includeSelectors?: string[]`\n CSS selectors. When provided, only matching HTML subtrees (and their descendants) are kept before conversion to Markdown. When omitted, the entire document is kept. Examples: \"article.main\", \"#content\", \"[role=main]\".\n\n- `maxAgeMs?: number`\n Return a cached result if a prior scrape for the same parameters exists and is younger than this many milliseconds. Defaults to 1 day (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0 to always scrape fresh.\n\n- `pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }`\n PDF parsing controls. Use start/end to limit text extraction and embedded-image detection/OCR to an inclusive 1-based page range.\n - `end?: number`\n Last 1-based PDF page to parse. When omitted, parsing ends at the last page. Must be greater than or equal to start when both are provided.\n - `ocr?: boolean | 'true' | 'false'`\n When true, OCR the selected PDF pages that have no usable text layer (scans), replacing each recovered page's text with the OCR result while pages with a real text layer keep it. Billed at 1 credit per page OCR actually recovered, on top of the base request cost. When false, no OCR runs.\n - `shouldParse?: boolean | 'true' | 'false'`\n When true, PDF URLs are fetched and parsed. When false, PDF URLs are skipped and a 400 PDF_SKIPPED is returned.\n - `start?: number`\n First 1-based PDF page to parse. When omitted, parsing starts at the first page.\n\n- `settleAnimations?: boolean | 'true' | 'false'`\n When true, waits briefly for CSS and transition animations to settle before converting to Markdown. Defaults to false. This adds a bit of latency in exchange for more stable output on animated pages.\n\n- `shortenBase64Images?: boolean | 'true' | 'false'`\n Shorten base64-encoded image data in the Markdown output\n\n- `tags?: string[]`\n Optional comma-separated caller-defined tags for tracking this request. Tags are recorded on the request's usage log and can be used to filter usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n- `useMainContentOnly?: boolean | 'true' | 'false'`\n Extract only the main content of the page, excluding headers, footers, sidebars, and navigation\n\n- `waitForMs?: number`\n Optional browser wait time in milliseconds after initial page load before converting the page to Markdown. Min: 0. Max: 30000 (30 seconds).\n\n- `zdr?: 'enabled' | 'disabled'`\n Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.\n\n### Returns\n\n- `{ contentLength: number; markdown: string; metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }; success: true; url: string; actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]; actionsHtmlStale?: boolean; html?: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; }`\n\n - `contentLength: number`\n - `markdown: string`\n - `metadata: { finalUrl: string; sourceUrl: string; additionalMeta?: object; alternates?: { href: string; hreflang?: string; title?: string; type?: string; }[]; author?: string; canonicalUrl?: string; description?: string; favicon?: string; headings?: { level: number; text: string; }[]; image?: string; jsonLd?: object[]; keywords?: string[]; language?: string; modifiedTime?: string; openGraph?: object; publishedTime?: string; robots?: string; siteName?: string; title?: string; twitter?: object; }`\n - `success: true`\n - `url: string`\n - `actionsApplied?: { instruction: string; status: 'applied' | 'failed' | 'skipped'; completionEvidence?: string; durationMs?: number; error?: string; method?: string; targetDescription?: string; }[]`\n - `actionsHtmlStale?: boolean`\n - `html?: string`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.web.webScrapeMd({ url: 'https://example.com' });\n\nconsole.log(response);\n```", perLanguage: { typescript: { method: 'client.web.webScrapeMd', @@ -240,7 +241,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ php: { method: 'web->webScrapeMd', example: - "web->webScrapeMd(\n url: 'https://example.com',\n actions: [['do' => 'wait', 'timeMs' => 0]],\n country: 'de',\n excludeSelectors: ['x'],\n headers: ['foo' => 'J!'],\n includeFrames: 'true',\n includeImages: 'true',\n includeLinks: 'true',\n includeSelectors: ['x'],\n maxAgeMs: 0,\n pdf: ['end' => 1, 'ocr' => 'true', 'shouldParse' => 'true', 'start' => 1],\n settleAnimations: 'true',\n shortenBase64Images: 'true',\n tags: ['production', 'team-alpha'],\n timeoutMs: 1,\n useMainContentOnly: 'true',\n waitForMs: 0,\n zdr: 'enabled',\n);\n\nvar_dump($response);", + "web->webScrapeMd(\n url: 'https://example.com',\n actions: [['do' => 'wait', 'timeMs' => 0]],\n country: 'de',\n excludeSelectors: ['x'],\n headers: ['foo' => 'J!'],\n includeFrames: 'true',\n includeHTML: 'true',\n includeImages: 'true',\n includeLinks: 'true',\n includeSelectors: ['x'],\n maxAgeMs: 0,\n pdf: ['end' => 1, 'ocr' => 'true', 'shouldParse' => 'true', 'start' => 1],\n settleAnimations: 'true',\n shortenBase64Images: 'true',\n tags: ['production', 'team-alpha'],\n timeoutMs: 1,\n useMainContentOnly: 'true',\n waitForMs: 0,\n zdr: 'enabled',\n);\n\nvar_dump($response);", }, http: { example: @@ -1170,21 +1171,21 @@ const EMBEDDED_METHODS: MethodEntry[] = [ name: 'prefetch', endpoint: '/utility/prefetch', httpMethod: 'post', - summary: 'Prefetch brand data', + summary: 'Prefetch data', description: - "Signal that you may fetch brand data soon to improve latency. The type field selects what to prefetch (currently only 'brand') and identifier carries exactly one lookup key: a domain, or an email whose domain is extracted and validated (free email providers and disposable email addresses are not allowed).", + "Signal that you may fetch data soon to improve latency. The type field selects what to prefetch ('brand' queues a brand data fetch, 'styleguide' queues a styleguide extraction) and identifier carries exactly one lookup key: a domain, or an email whose domain is extracted and validated (free email providers and disposable email addresses are not allowed).", stainlessPath: '(resource) utility > (method) prefetch', qualified: 'client.utility.prefetch', params: [ 'identifier: { domain: string; } | { email: string; };', - "type: 'brand';", + "type: 'brand' | 'styleguide';", 'tags?: string[];', 'timeoutMS?: number;', ], response: - "{ domain?: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; message?: string; status?: string; type?: 'brand'; }", + "{ domain?: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; message?: string; status?: string; type?: 'brand' | 'styleguide'; }", markdown: - "## prefetch\n\n`client.utility.prefetch(identifier: { domain: string; } | { email: string; }, type: 'brand', tags?: string[], timeoutMS?: number): { domain?: string; key_metadata?: object; message?: string; status?: string; type?: 'brand'; }`\n\n**post** `/utility/prefetch`\n\nSignal that you may fetch brand data soon to improve latency. The type field selects what to prefetch (currently only 'brand') and identifier carries exactly one lookup key: a domain, or an email whose domain is extracted and validated (free email providers and disposable email addresses are not allowed).\n\n### Parameters\n\n- `identifier: { domain: string; } | { email: string; }`\n Identifier of the brand to prefetch. Provide exactly one of domain or email.\n\n- `type: 'brand'`\n What to prefetch. Currently only 'brand' is supported.\n\n- `tags?: string[]`\n Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n### Returns\n\n- `{ domain?: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; message?: string; status?: string; type?: 'brand'; }`\n\n - `domain?: string`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n - `message?: string`\n - `status?: string`\n - `type?: 'brand'`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.utility.prefetch({\n identifier: { domain: 'xxx' },\n type: 'brand',\n});\n\nconsole.log(response);\n```", + "## prefetch\n\n`client.utility.prefetch(identifier: { domain: string; } | { email: string; }, type: 'brand' | 'styleguide', tags?: string[], timeoutMS?: number): { domain?: string; key_metadata?: object; message?: string; status?: string; type?: 'brand' | 'styleguide'; }`\n\n**post** `/utility/prefetch`\n\nSignal that you may fetch data soon to improve latency. The type field selects what to prefetch ('brand' queues a brand data fetch, 'styleguide' queues a styleguide extraction) and identifier carries exactly one lookup key: a domain, or an email whose domain is extracted and validated (free email providers and disposable email addresses are not allowed).\n\n### Parameters\n\n- `identifier: { domain: string; } | { email: string; }`\n Identifier of the target to prefetch. Provide exactly one of domain or email.\n\n- `type: 'brand' | 'styleguide'`\n What to prefetch: 'brand' warms the brand data cache, 'styleguide' warms the styleguide cache.\n\n- `tags?: string[]`\n Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.\n\n- `timeoutMS?: number`\n Optional timeout in milliseconds for the request. If the request takes longer than this value, it will be aborted with a 408 status code. Maximum allowed value is 300000ms (5 minutes).\n\n### Returns\n\n- `{ domain?: string; key_metadata?: { credits_consumed: number; credits_remaining: number; }; message?: string; status?: string; type?: 'brand' | 'styleguide'; }`\n\n - `domain?: string`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n - `message?: string`\n - `status?: string`\n - `type?: 'brand' | 'styleguide'`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.utility.prefetch({\n identifier: { domain: 'xxx' },\n type: 'brand',\n});\n\nconsole.log(response);\n```", perLanguage: { typescript: { method: 'client.utility.prefetch', @@ -1925,7 +1926,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ stainlessPath: '(resource) batch > (method) submit', qualified: 'client.batch.submit', params: [ - "input: { data: { format: 'markdown'; urls: { url: string; itemId?: string; meta?: object; }[]; options?: { country?: string; excludeSelectors?: string[]; includeImages?: boolean; includeLinks?: boolean; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }; settleAnimations?: boolean; shortenBase64Images?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; } | { format: 'html'; urls: { url: string; itemId?: string; meta?: object; }[]; options?: { country?: string; excludeSelectors?: string[]; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }; settleAnimations?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; }; mode: 'scrape'; } | { data: { format: 'markdown'; source: { type: 'start_url'; url: string; controls?: { followSubdomains?: boolean; maxDepth?: number; maxUrls?: number; regex?: string; }; } | { domain: string; type: 'sitemap'; controls?: { maxUrls?: number; regex?: string; }; }; options?: { country?: string; excludeSelectors?: string[]; includeImages?: boolean; includeLinks?: boolean; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }; settleAnimations?: boolean; shortenBase64Images?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; } | { format: 'html'; source: { type: 'start_url'; url: string; controls?: { followSubdomains?: boolean; maxDepth?: number; maxUrls?: number; regex?: string; }; } | { domain: string; type: 'sitemap'; controls?: { maxUrls?: number; regex?: string; }; }; options?: { country?: string; excludeSelectors?: string[]; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }; settleAnimations?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; }; mode: 'crawl'; };", + "input: { data: { format: 'markdown'; urls: { url: string; itemId?: string; meta?: object; }[]; options?: { country?: string; excludeSelectors?: string[]; includeHTML?: boolean; includeImages?: boolean; includeLinks?: boolean; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }; settleAnimations?: boolean; shortenBase64Images?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; } | { format: 'html'; urls: { url: string; itemId?: string; meta?: object; }[]; options?: { country?: string; excludeSelectors?: string[]; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }; settleAnimations?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; }; mode: 'scrape'; } | { data: { format: 'markdown'; source: { type: 'start_url'; url: string; controls?: { followSubdomains?: boolean; maxDepth?: number; maxUrls?: number; regex?: string; }; } | { domain: string; type: 'sitemap'; controls?: { maxUrls?: number; regex?: string; }; }; options?: { country?: string; excludeSelectors?: string[]; includeHTML?: boolean; includeImages?: boolean; includeLinks?: boolean; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }; settleAnimations?: boolean; shortenBase64Images?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; } | { format: 'html'; source: { type: 'start_url'; url: string; controls?: { followSubdomains?: boolean; maxDepth?: number; maxUrls?: number; regex?: string; }; } | { domain: string; type: 'sitemap'; controls?: { maxUrls?: number; regex?: string; }; }; options?: { country?: string; excludeSelectors?: string[]; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }; settleAnimations?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; }; mode: 'crawl'; };", 'tags?: string[];', 'webhookUrl?: string;', 'Idempotency-Key?: string;', @@ -1933,7 +1934,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ response: "{ id: string; crawl: { follow_subdomains: boolean; max_depth: number; max_pages: number; source: object | object; url_pattern: string; }; created_at: string; credits: { reserved: number; }; format: 'markdown' | 'html'; input: { duplicates: number; invalid: number; reserved: number; reserved_is_ceiling: boolean; submitted: number; }; invalid_urls: { reason: string; url: string; }[]; mode: 'scrape' | 'crawl'; status: 'queued'; tags: string[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; webhook_secret?: string; }", markdown: - "## submit\n\n`client.batch.submit(input: { data: { format: 'markdown'; urls: object[]; options?: object; } | { format: 'html'; urls: object[]; options?: object; }; mode: 'scrape'; } | { data: { format: 'markdown'; source: object | object; options?: object; } | { format: 'html'; source: object | object; options?: object; }; mode: 'crawl'; }, tags?: string[], webhookUrl?: string, Idempotency-Key?: string): { id: string; crawl: crawl_controls; created_at: string; credits: object; format: 'markdown' | 'html'; input: intake; invalid_urls: object[]; mode: 'scrape' | 'crawl'; status: 'queued'; tags: string[]; key_metadata?: object; webhook_secret?: string; }`\n\n**post** `/batch/submit`\n\nScrape 25K URLs or crawl large websites asynchronously. \n\n### Parameters\n\n- `input: { data: { format: 'markdown'; urls: { url: string; itemId?: string; meta?: object; }[]; options?: { country?: string; excludeSelectors?: string[]; includeImages?: boolean; includeLinks?: boolean; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }; settleAnimations?: boolean; shortenBase64Images?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; } | { format: 'html'; urls: { url: string; itemId?: string; meta?: object; }[]; options?: { country?: string; excludeSelectors?: string[]; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }; settleAnimations?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; }; mode: 'scrape'; } | { data: { format: 'markdown'; source: { type: 'start_url'; url: string; controls?: { followSubdomains?: boolean; maxDepth?: number; maxUrls?: number; regex?: string; }; } | { domain: string; type: 'sitemap'; controls?: { maxUrls?: number; regex?: string; }; }; options?: { country?: string; excludeSelectors?: string[]; includeImages?: boolean; includeLinks?: boolean; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }; settleAnimations?: boolean; shortenBase64Images?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; } | { format: 'html'; source: { type: 'start_url'; url: string; controls?: { followSubdomains?: boolean; maxDepth?: number; maxUrls?: number; regex?: string; }; } | { domain: string; type: 'sitemap'; controls?: { maxUrls?: number; regex?: string; }; }; options?: { country?: string; excludeSelectors?: string[]; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }; settleAnimations?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; }; mode: 'crawl'; }`\n Choose a URL list or a site crawl.\n\n- `tags?: string[]`\n Tags stored on the batch. Filter the batch list by them later.\n\n- `webhookUrl?: string`\n URL notified when the batch finishes.\n\n- `Idempotency-Key?: string`\n Any string unique to this submission. Retries with the same key return the original batch.\n\n### Returns\n\n- `{ id: string; crawl: { follow_subdomains: boolean; max_depth: number; max_pages: number; source: object | object; url_pattern: string; }; created_at: string; credits: { reserved: number; }; format: 'markdown' | 'html'; input: { duplicates: number; invalid: number; reserved: number; reserved_is_ceiling: boolean; submitted: number; }; invalid_urls: { reason: string; url: string; }[]; mode: 'scrape' | 'crawl'; status: 'queued'; tags: string[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; webhook_secret?: string; }`\n\n - `id: string`\n - `crawl: { follow_subdomains: boolean; max_depth: number; max_pages: number; source: { type: 'start_url'; url: string; } | { domain: string; type: 'sitemap'; }; url_pattern: string; }`\n - `created_at: string`\n - `credits: { reserved: number; }`\n - `format: 'markdown' | 'html'`\n - `input: { duplicates: number; invalid: number; reserved: number; reserved_is_ceiling: boolean; submitted: number; }`\n - `invalid_urls: { reason: string; url: string; }[]`\n - `mode: 'scrape' | 'crawl'`\n - `status: 'queued'`\n - `tags: string[]`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n - `webhook_secret?: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.batch.submit({ input: {\n data: { format: 'markdown', urls: [{ url: 'https://example.com/products/anvil' }, { url: 'https://example.com/products/hammer' }] },\n mode: 'scrape',\n} });\n\nconsole.log(response);\n```", + "## submit\n\n`client.batch.submit(input: { data: { format: 'markdown'; urls: object[]; options?: object; } | { format: 'html'; urls: object[]; options?: object; }; mode: 'scrape'; } | { data: { format: 'markdown'; source: object | object; options?: object; } | { format: 'html'; source: object | object; options?: object; }; mode: 'crawl'; }, tags?: string[], webhookUrl?: string, Idempotency-Key?: string): { id: string; crawl: crawl_controls; created_at: string; credits: object; format: 'markdown' | 'html'; input: intake; invalid_urls: object[]; mode: 'scrape' | 'crawl'; status: 'queued'; tags: string[]; key_metadata?: object; webhook_secret?: string; }`\n\n**post** `/batch/submit`\n\nScrape 25K URLs or crawl large websites asynchronously. \n\n### Parameters\n\n- `input: { data: { format: 'markdown'; urls: { url: string; itemId?: string; meta?: object; }[]; options?: { country?: string; excludeSelectors?: string[]; includeHTML?: boolean; includeImages?: boolean; includeLinks?: boolean; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }; settleAnimations?: boolean; shortenBase64Images?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; } | { format: 'html'; urls: { url: string; itemId?: string; meta?: object; }[]; options?: { country?: string; excludeSelectors?: string[]; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }; settleAnimations?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; }; mode: 'scrape'; } | { data: { format: 'markdown'; source: { type: 'start_url'; url: string; controls?: { followSubdomains?: boolean; maxDepth?: number; maxUrls?: number; regex?: string; }; } | { domain: string; type: 'sitemap'; controls?: { maxUrls?: number; regex?: string; }; }; options?: { country?: string; excludeSelectors?: string[]; includeHTML?: boolean; includeImages?: boolean; includeLinks?: boolean; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }; settleAnimations?: boolean; shortenBase64Images?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; } | { format: 'html'; source: { type: 'start_url'; url: string; controls?: { followSubdomains?: boolean; maxDepth?: number; maxUrls?: number; regex?: string; }; } | { domain: string; type: 'sitemap'; controls?: { maxUrls?: number; regex?: string; }; }; options?: { country?: string; excludeSelectors?: string[]; includeSelectors?: string[]; maxAgeMs?: number; pdf?: { end?: number; ocr?: boolean | 'true' | 'false'; shouldParse?: boolean | 'true' | 'false'; start?: number; }; settleAnimations?: boolean; useMainContentOnly?: boolean; waitForMs?: number; }; }; mode: 'crawl'; }`\n Choose a URL list or a site crawl.\n\n- `tags?: string[]`\n Tags stored on the batch. Filter the batch list by them later.\n\n- `webhookUrl?: string`\n URL notified when the batch finishes.\n\n- `Idempotency-Key?: string`\n Any string unique to this submission. Retries with the same key return the original batch.\n\n### Returns\n\n- `{ id: string; crawl: { follow_subdomains: boolean; max_depth: number; max_pages: number; source: object | object; url_pattern: string; }; created_at: string; credits: { reserved: number; }; format: 'markdown' | 'html'; input: { duplicates: number; invalid: number; reserved: number; reserved_is_ceiling: boolean; submitted: number; }; invalid_urls: { reason: string; url: string; }[]; mode: 'scrape' | 'crawl'; status: 'queued'; tags: string[]; key_metadata?: { credits_consumed: number; credits_remaining: number; }; webhook_secret?: string; }`\n\n - `id: string`\n - `crawl: { follow_subdomains: boolean; max_depth: number; max_pages: number; source: { type: 'start_url'; url: string; } | { domain: string; type: 'sitemap'; }; url_pattern: string; }`\n - `created_at: string`\n - `credits: { reserved: number; }`\n - `format: 'markdown' | 'html'`\n - `input: { duplicates: number; invalid: number; reserved: number; reserved_is_ceiling: boolean; submitted: number; }`\n - `invalid_urls: { reason: string; url: string; }[]`\n - `mode: 'scrape' | 'crawl'`\n - `status: 'queued'`\n - `tags: string[]`\n - `key_metadata?: { credits_consumed: number; credits_remaining: number; }`\n - `webhook_secret?: string`\n\n### Example\n\n```typescript\nimport ContextDev from 'context.dev';\n\nconst client = new ContextDev();\n\nconst response = await client.batch.submit({ input: {\n data: { format: 'markdown', urls: [{ url: 'https://example.com/products/anvil' }, { url: 'https://example.com/products/hammer' }] },\n mode: 'scrape',\n} });\n\nconsole.log(response);\n```", perLanguage: { typescript: { method: 'client.batch.submit', @@ -1963,7 +1964,7 @@ const EMBEDDED_METHODS: MethodEntry[] = [ php: { method: 'batch->submit', example: - "batch->submit(\n input: [\n 'data' => [\n 'format' => 'markdown',\n 'urls' => [\n [\n 'url' => 'https://example.com/products/anvil',\n 'itemID' => 'sku-1',\n 'meta' => ['category' => 'bar'],\n ],\n [\n 'url' => 'https://example.com/products/hammer',\n 'itemID' => 'sku-2',\n 'meta' => ['foo' => 'bar'],\n ],\n ],\n 'options' => [\n 'country' => 'de',\n 'excludeSelectors' => ['x'],\n 'includeImages' => true,\n 'includeLinks' => true,\n 'includeSelectors' => ['x'],\n 'maxAgeMs' => 0,\n 'pdf' => [\n 'end' => 1, 'ocr' => 'true', 'shouldParse' => 'true', 'start' => 1\n ],\n 'settleAnimations' => true,\n 'shortenBase64Images' => true,\n 'useMainContentOnly' => true,\n 'waitForMs' => 0,\n ],\n ],\n 'mode' => 'scrape',\n ],\n tags: ['docs', 'competitor'],\n webhookURL: 'webhookUrl',\n idempotencyKey: 'Idempotency-Key',\n);\n\nvar_dump($response);", + "batch->submit(\n input: [\n 'data' => [\n 'format' => 'markdown',\n 'urls' => [\n [\n 'url' => 'https://example.com/products/anvil',\n 'itemID' => 'sku-1',\n 'meta' => ['category' => 'bar'],\n ],\n [\n 'url' => 'https://example.com/products/hammer',\n 'itemID' => 'sku-2',\n 'meta' => ['foo' => 'bar'],\n ],\n ],\n 'options' => [\n 'country' => 'de',\n 'excludeSelectors' => ['x'],\n 'includeHTML' => true,\n 'includeImages' => true,\n 'includeLinks' => true,\n 'includeSelectors' => ['x'],\n 'maxAgeMs' => 0,\n 'pdf' => [\n 'end' => 1, 'ocr' => 'true', 'shouldParse' => 'true', 'start' => 1\n ],\n 'settleAnimations' => true,\n 'shortenBase64Images' => true,\n 'useMainContentOnly' => true,\n 'waitForMs' => 0,\n ],\n ],\n 'mode' => 'scrape',\n ],\n tags: ['docs', 'competitor'],\n webhookURL: 'webhookUrl',\n idempotencyKey: 'Idempotency-Key',\n);\n\nvar_dump($response);", }, http: { example: diff --git a/src/resources/batch.ts b/src/resources/batch.ts index 062b78a..8d94e5b 100644 --- a/src/resources/batch.ts +++ b/src/resources/batch.ts @@ -897,7 +897,8 @@ export namespace BatchGetResultsResponse { url: string; /** - * Raw page HTML. Present on html batches. + * Page HTML. Present on html batches, and on markdown batches submitted with + * `options.includeHTML`. */ html?: string; @@ -1573,6 +1574,12 @@ export namespace BatchSubmitParams { */ excludeSelectors?: Array | null; + /** + * Also include each page's HTML in its result record, as an `html` field alongside + * the Markdown. + */ + includeHTML?: boolean; + /** * Include image references in the Markdown. */ @@ -2336,6 +2343,12 @@ export namespace BatchSubmitParams { */ excludeSelectors?: Array | null; + /** + * Also include each page's HTML in its result record, as an `html` field alongside + * the Markdown. + */ + includeHTML?: boolean; + /** * Include image references in the Markdown. */ diff --git a/src/resources/utility.ts b/src/resources/utility.ts index e2efd7a..b972fe9 100644 --- a/src/resources/utility.ts +++ b/src/resources/utility.ts @@ -6,10 +6,11 @@ import { RequestOptions } from '../internal/request-options'; export class Utility extends APIResource { /** - * Signal that you may fetch brand data soon to improve latency. The type field - * selects what to prefetch (currently only 'brand') and identifier carries exactly - * one lookup key: a domain, or an email whose domain is extracted and validated - * (free email providers and disposable email addresses are not allowed). + * Signal that you may fetch data soon to improve latency. The type field selects + * what to prefetch ('brand' queues a brand data fetch, 'styleguide' queues a + * styleguide extraction) and identifier carries exactly one lookup key: a domain, + * or an email whose domain is extracted and validated (free email providers and + * disposable email addresses are not allowed). * * @example * ```ts @@ -47,10 +48,9 @@ export interface UtilityPrefetchResponse { status?: string; /** - * The type of prefetch that was queued, echoed from the request (currently always - * 'brand') + * The type of prefetch that was queued, echoed from the request */ - type?: 'brand'; + type?: 'brand' | 'styleguide'; } export namespace UtilityPrefetchResponse { @@ -73,16 +73,17 @@ export namespace UtilityPrefetchResponse { export interface UtilityPrefetchParams { /** - * Identifier of the brand to prefetch. Provide exactly one of domain or email. + * Identifier of the target to prefetch. Provide exactly one of domain or email. */ identifier: | UtilityPrefetchParams.UtilityPrefetchDomainIdentifier | UtilityPrefetchParams.UtilityPrefetchEmailIdentifier; /** - * What to prefetch. Currently only 'brand' is supported. + * What to prefetch: 'brand' warms the brand data cache, 'styleguide' warms the + * styleguide cache. */ - type: 'brand'; + type: 'brand' | 'styleguide'; /** * Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. @@ -99,23 +100,23 @@ export interface UtilityPrefetchParams { export namespace UtilityPrefetchParams { /** - * Prefetch brand data by domain. + * Prefetch by domain. */ export interface UtilityPrefetchDomainIdentifier { /** - * Domain name to prefetch brand data for + * Domain name to prefetch data for */ domain: string; } /** - * Prefetch brand data by email. The domain will be extracted and validated. + * Prefetch by email. The domain will be extracted and validated. */ export interface UtilityPrefetchEmailIdentifier { /** - * Email address to prefetch brand data for. The domain will be extracted from the - * email. Free email providers (gmail.com, yahoo.com, etc.) and disposable email - * addresses are not allowed. + * Email address to prefetch data for. The domain will be extracted from the email. + * Free email providers (gmail.com, yahoo.com, etc.) and disposable email addresses + * are not allowed. */ email: string; } diff --git a/src/resources/web.ts b/src/resources/web.ts index 50bceb6..f895755 100644 --- a/src/resources/web.ts +++ b/src/resources/web.ts @@ -1793,6 +1793,13 @@ export interface WebWebScrapeMdResponse { */ actionsHtmlStale?: boolean; + /** + * Only present when includeHTML=true: the page HTML the Markdown was converted + * from — the same body the Scrape HTML endpoint returns for the equivalent + * request. + */ + html?: string; + /** * Metadata about the API key used for the request. Included in every response * whenever a valid API key is provided, even when the response status is not 200. @@ -4061,6 +4068,13 @@ export interface WebWebScrapeMdParams { */ includeFrames?: boolean | 'true' | 'false'; + /** + * When true, the response also includes an `html` field with the page HTML the + * Markdown was converted from — the same body the Scrape HTML endpoint returns for + * the equivalent request. + */ + includeHTML?: boolean | 'true' | 'false'; + /** * Include image references in Markdown output */ diff --git a/tests/api-resources/batch.test.ts b/tests/api-resources/batch.test.ts index f03fcda..2c68862 100644 --- a/tests/api-resources/batch.test.ts +++ b/tests/api-resources/batch.test.ts @@ -142,6 +142,7 @@ describe('resource batch', () => { options: { country: 'de', excludeSelectors: ['x'], + includeHTML: true, includeImages: true, includeLinks: true, includeSelectors: ['x'], diff --git a/tests/api-resources/web.test.ts b/tests/api-resources/web.test.ts index 4a13912..9e7e929 100644 --- a/tests/api-resources/web.test.ts +++ b/tests/api-resources/web.test.ts @@ -355,6 +355,7 @@ describe('resource web', () => { excludeSelectors: ['x'], headers: { foo: 'J!' }, includeFrames: 'true', + includeHTML: 'true', includeImages: 'true', includeLinks: 'true', includeSelectors: ['x'], From 06c70d60d896ed3859d2fad12cd5108349e887d4 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Mon, 10 Aug 2026 09:04:17 +0000 Subject: [PATCH 3/3] release: 2.11.0 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 9 +++++++++ package.json | 2 +- packages/mcp-server/manifest.json | 2 +- packages/mcp-server/package.json | 2 +- packages/mcp-server/src/server.ts | 2 +- src/version.ts | 2 +- 7 files changed, 15 insertions(+), 6 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index f393718..a9b8e02 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "2.10.0" + ".": "2.11.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 3fd653c..e9ece08 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,14 @@ # Changelog +## 2.11.0 (2026-08-10) + +Full Changelog: [v2.10.0...v2.11.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.10.0...v2.11.0) + +### Features + +* **api:** api update ([fd6690d](https://github.com/context-dot-dev/context-typescript-sdk/commit/fd6690d37c59c46a8e34bc497dfe6013cb20f434)) +* **api:** api update ([ac230f1](https://github.com/context-dot-dev/context-typescript-sdk/commit/ac230f179b78122b5c1c604dbf78ed7ee915d979)) + ## 2.10.0 (2026-08-07) Full Changelog: [v2.9.0...v2.10.0](https://github.com/context-dot-dev/context-typescript-sdk/compare/v2.9.0...v2.10.0) diff --git a/package.json b/package.json index c02fc2e..3028cba 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "context.dev", - "version": "2.10.0", + "version": "2.11.0", "description": "The official TypeScript library for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/packages/mcp-server/manifest.json b/packages/mcp-server/manifest.json index f35389b..b57a40e 100644 --- a/packages/mcp-server/manifest.json +++ b/packages/mcp-server/manifest.json @@ -1,7 +1,7 @@ { "dxt_version": "0.2", "name": "context.dev-mcp", - "version": "2.10.0", + "version": "2.11.0", "description": "The official MCP Server for the Context Dev API", "author": { "name": "Context Dev", diff --git a/packages/mcp-server/package.json b/packages/mcp-server/package.json index 189a44b..cd21bdb 100644 --- a/packages/mcp-server/package.json +++ b/packages/mcp-server/package.json @@ -1,6 +1,6 @@ { "name": "context.dev-mcp", - "version": "2.10.0", + "version": "2.11.0", "description": "The official MCP Server for the Context Dev API", "author": "Context Dev ", "types": "dist/index.d.ts", diff --git a/packages/mcp-server/src/server.ts b/packages/mcp-server/src/server.ts index ed00e66..d3682d4 100644 --- a/packages/mcp-server/src/server.ts +++ b/packages/mcp-server/src/server.ts @@ -28,7 +28,7 @@ export const newMcpServer = async ({ new McpServer( { name: 'context_dev_api', - version: '2.10.0', + version: '2.11.0', }, { instructions: await getInstructions({ stainlessApiKey, customInstructionsPath }), diff --git a/src/version.ts b/src/version.ts index 7b16f63..e91ff8d 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '2.10.0'; // x-release-please-version +export const VERSION = '2.11.0'; // x-release-please-version