{"openapi":"3.1.0","info":{"title":"Expand.ai API","version":"0.0.1","description":"Fetch web pages as LLM-ready Markdown, JSON Mode responses, Highlights snippets, and Batched Fetch runs.","summary":"Public Fetch API for LLM-ready web content."},"paths":{"/v1/fetch":{"post":{"tags":["Fetch"],"operationId":"fetch.fetch","parameters":[{"name":"include","in":"query","schema":{"type":"string","description":"Include Options for the response. Use a comma-separated list with `appendix` for Appendix and `statejson` for State JSON. Defaults to State JSON when omitted; use `include=` for Markdown only. For search requests without a URL include parameter, the request body include fields define the search corpus.","examples":["appendix","appendix,statejson",""]},"required":false,"description":"Include Options for the response. Use a comma-separated list with `appendix` for Appendix and `statejson` for State JSON. Defaults to State JSON when omitted; use `include=` for Markdown only. For search requests without a URL include parameter, the request body include fields define the search corpus."}],"security":[{"apiKey":[]},{"cookie":[]},{"bearer":[]}],"responses":{"200":{"description":"LLM-ready Markdown document","content":{"text/markdown":{"schema":{"type":"string","description":"LLM-ready Markdown document"}}}},"400":{"description":"The request did not match the expected schema","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/HttpApiDecodeError"},{"$ref":"#/components/schemas/BadRequest"}]}}}},"401":{"description":"AuthFailed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthFailed"}}}},"403":{"description":"AccessBlocked","content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["organizationId","_tag"],"properties":{"organizationId":{"type":"string","description":"a non empty string","title":"nonEmptyString","minLength":1},"blockedUntil":{"anyOf":[{"$ref":"#/components/schemas/DateTimeUtc"},{"type":"null"}]},"_tag":{"type":"string","enum":["AccessBlocked"]}},"additionalProperties":false},{"$ref":"#/components/schemas/FetchBlocked"}]}}}},"413":{"description":"PayloadTooLarge","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PayloadTooLarge"},{"$ref":"#/components/schemas/FetchPageTooLarge"}]}}}},"429":{"description":"TooManyRequests","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TooManyRequests"},{"$ref":"#/components/schemas/FetchConcurrencyLimitExceeded"}]}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying. Prefer it over your own backoff for the first attempt — retrying sooner spends your timeout budget on a refusal the server already predicted.","required":true,"schema":{"type":"integer","format":"int32","minimum":0},"example":20}}},"500":{"description":"InternalError","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalError"}}}},"502":{"description":"FetchCaptureFailed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/FetchCaptureFailed"},{"$ref":"#/components/schemas/FetchNavigationFailed"}]}}}},"503":{"description":"ServiceUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailable"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying. Prefer it over your own backoff for the first attempt — retrying sooner spends your timeout budget on a refusal the server already predicted.","required":true,"schema":{"type":"integer","format":"int32","minimum":0},"example":20}}},"504":{"description":"FetchCaptureTimeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FetchCaptureTimeout"}}}},"529":{"description":"FetchCapacityTimeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FetchCapacityTimeout"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying a request that could not start because the org was at capacity.","required":true,"schema":{"type":"integer","format":"int32","minimum":0},"example":5}}}},"description":"Fetch a URL and return an LLM-ready Markdown document. Use Include Options to request Appendix or State JSON when you need more evidence.","summary":"Fetch","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"The URL to fetch content from (http or https only)","examples":["https://www.stripe.com/docs/api"]},"include":{"type":"object","required":[],"description":"Specifies which content formats to include in the response","additionalProperties":false,"properties":{"html":{"anyOf":[{"type":"boolean","description":"Set to true to include HTML","examples":[true]},{"type":"object","description":"Options for customizing HTML content extraction"},{"type":"array","description":"Options for customizing HTML content extraction"}]},"markdown":{"anyOf":[{"type":"boolean","description":"Set to true to include markdown","examples":[true]},{"type":"object","description":"Options for customizing markdown content extraction"},{"type":"array","description":"Options for customizing markdown content extraction"}]},"screenshot":{"anyOf":[{"type":"boolean","description":"Set to true to include a screenshot","examples":[true]},{"type":"object","required":[],"additionalProperties":false,"description":"Options for customizing screenshot capture behavior","properties":{"fullPage":{"type":"boolean","description":"Whether to capture the full page including content below the fold","examples":[true]}}}]},"links":{"anyOf":[{"type":"boolean","description":"Set to true to include links","examples":[true]},{"type":"object","required":[],"additionalProperties":false,"description":"Options for customizing link extraction","properties":{"sameDomainOnly":{"type":"boolean","description":"Only include links from the same domain as the fetched URL","examples":[true],"default":true},"includePatterns":{"type":"array","description":"Regex patterns - only include links matching at least one pattern","examples":[["docs","api"]],"items":{"type":"string"}},"excludePatterns":{"type":"array","description":"Regex patterns - exclude links matching any pattern","examples":[["login","logout","\\?.*"]],"items":{"type":"string"}}}}]},"meta":{"type":"boolean","description":"Set to true to include page metadata","examples":[true],"default":true},"response":{"type":"object","required":[],"additionalProperties":false,"description":"Configure response info options (headers inclusion)","properties":{"includeHeaders":{"type":"boolean","description":"Whether to include HTTP response headers","default":false}}},"json":{"type":"boolean","description":"Include pruned JSON in the response (opt-in)","examples":[true],"default":false},"appendix":{"type":"boolean","description":"Set to true to include extracted links and sidebar content","examples":[true]}}},"search":{"type":"object","required":["query"],"description":"Options for Highlights. When present, Fetch returns search results only.","additionalProperties":false,"properties":{"query":{"type":"string","description":"Query to find relevant snippets from the included Highlights corpus","examples":["pricing plans","API authentication methods"]},"maxResults":{"type":"integer","description":"Maximum number of search snippets to return (1-50)","minimum":1,"maximum":50,"examples":[5],"default":5},"minScore":{"type":"number","description":"Minimum relevance score threshold (0-1). Defaults to 0.6; set 0 to disable filtering.","minimum":0,"maximum":1,"examples":[0.6],"default":0.6}}},"browserConfig":{"type":"object","required":[],"description":"Configuration options for browser behavior during the fetch","additionalProperties":false,"properties":{"scrollFullPage":{"type":"boolean","description":"Whether to scroll the entire page to capture lazy-loaded content","examples":[true],"default":false}}}},"additionalProperties":false,"description":"Request parameters for fetching and extracting content from a web page"},"examples":{"minimal":{"summary":"Minimal Fetch request","value":{"url":"https://example.com"}}}}},"required":true}}},"/v1/fetch/json":{"post":{"tags":["Fetch"],"operationId":"fetch.fetchJson","parameters":[{"name":"include","in":"query","schema":{"type":"string","description":"Include Options for the response. Use a comma-separated list with `appendix` for Appendix and `statejson` for State JSON. Defaults to State JSON when omitted; use `include=` for Markdown only. For search requests without a URL include parameter, the request body include fields define the search corpus.","examples":["appendix","appendix,statejson",""]},"required":false,"description":"Include Options for the response. Use a comma-separated list with `appendix` for Appendix and `statejson` for State JSON. Defaults to State JSON when omitted; use `include=` for Markdown only. For search requests without a URL include parameter, the request body include fields define the search corpus."}],"security":[{"apiKey":[]},{"cookie":[]},{"bearer":[]}],"responses":{"200":{"description":"Fetch JSON Mode response for `/v1/fetch/json`. Mirrors the Markdown response as discrete fields for JSON-native consumers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FetchObjectModeResult"}}}},"400":{"description":"The request did not match the expected schema","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/HttpApiDecodeError"},{"$ref":"#/components/schemas/BadRequest"}]}}}},"401":{"description":"AuthFailed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthFailed"}}}},"403":{"description":"AccessBlocked","content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["organizationId","_tag"],"properties":{"organizationId":{"type":"string","description":"a non empty string","title":"nonEmptyString","minLength":1},"blockedUntil":{"anyOf":[{"$ref":"#/components/schemas/DateTimeUtc"},{"type":"null"}]},"_tag":{"type":"string","enum":["AccessBlocked"]}},"additionalProperties":false},{"$ref":"#/components/schemas/FetchBlocked"}]}}}},"413":{"description":"PayloadTooLarge","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PayloadTooLarge"},{"$ref":"#/components/schemas/FetchPageTooLarge"}]}}}},"429":{"description":"TooManyRequests","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TooManyRequests"},{"$ref":"#/components/schemas/FetchConcurrencyLimitExceeded"}]}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying. Prefer it over your own backoff for the first attempt — retrying sooner spends your timeout budget on a refusal the server already predicted.","required":true,"schema":{"type":"integer","format":"int32","minimum":0},"example":20}}},"500":{"description":"InternalError","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalError"}}}},"502":{"description":"FetchCaptureFailed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/FetchCaptureFailed"},{"$ref":"#/components/schemas/FetchNavigationFailed"}]}}}},"503":{"description":"ServiceUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailable"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying. Prefer it over your own backoff for the first attempt — retrying sooner spends your timeout budget on a refusal the server already predicted.","required":true,"schema":{"type":"integer","format":"int32","minimum":0},"example":20}}},"504":{"description":"FetchCaptureTimeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FetchCaptureTimeout"}}}},"529":{"description":"FetchCapacityTimeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FetchCapacityTimeout"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying a request that could not start because the org was at capacity.","required":true,"schema":{"type":"integer","format":"int32","minimum":0},"example":5}}}},"description":"Fetch a URL and return a structured JSON response containing page metadata, Markdown, State JSON, and search results when requested.","summary":"Fetch JSON Mode","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"The URL to fetch content from (http or https only)","examples":["https://www.stripe.com/docs/api"]},"include":{"type":"object","required":[],"description":"Specifies which content formats to include in the response","additionalProperties":false,"properties":{"html":{"anyOf":[{"type":"boolean","description":"Set to true to include HTML","examples":[true]},{"type":"object","description":"Options for customizing HTML content extraction"},{"type":"array","description":"Options for customizing HTML content extraction"}]},"markdown":{"anyOf":[{"type":"boolean","description":"Set to true to include markdown","examples":[true]},{"type":"object","description":"Options for customizing markdown content extraction"},{"type":"array","description":"Options for customizing markdown content extraction"}]},"screenshot":{"anyOf":[{"type":"boolean","description":"Set to true to include a screenshot","examples":[true]},{"type":"object","required":[],"additionalProperties":false,"description":"Options for customizing screenshot capture behavior","properties":{"fullPage":{"type":"boolean","description":"Whether to capture the full page including content below the fold","examples":[true]}}}]},"links":{"anyOf":[{"type":"boolean","description":"Set to true to include links","examples":[true]},{"type":"object","required":[],"additionalProperties":false,"description":"Options for customizing link extraction","properties":{"sameDomainOnly":{"type":"boolean","description":"Only include links from the same domain as the fetched URL","examples":[true],"default":true},"includePatterns":{"type":"array","description":"Regex patterns - only include links matching at least one pattern","examples":[["docs","api"]],"items":{"type":"string"}},"excludePatterns":{"type":"array","description":"Regex patterns - exclude links matching any pattern","examples":[["login","logout","\\?.*"]],"items":{"type":"string"}}}}]},"meta":{"type":"boolean","description":"Set to true to include page metadata","examples":[true],"default":true},"response":{"type":"object","required":[],"additionalProperties":false,"description":"Configure response info options (headers inclusion)","properties":{"includeHeaders":{"type":"boolean","description":"Whether to include HTTP response headers","default":false}}},"json":{"type":"boolean","description":"Include pruned JSON in the response (opt-in)","examples":[true],"default":false},"appendix":{"type":"boolean","description":"Set to true to include extracted links and sidebar content","examples":[true]}}},"search":{"type":"object","required":["query"],"description":"Options for Highlights. When present, Fetch returns search results only.","additionalProperties":false,"properties":{"query":{"type":"string","description":"Query to find relevant snippets from the included Highlights corpus","examples":["pricing plans","API authentication methods"]},"maxResults":{"type":"integer","description":"Maximum number of search snippets to return (1-50)","minimum":1,"maximum":50,"examples":[5],"default":5},"minScore":{"type":"number","description":"Minimum relevance score threshold (0-1). Defaults to 0.6; set 0 to disable filtering.","minimum":0,"maximum":1,"examples":[0.6],"default":0.6}}},"browserConfig":{"type":"object","required":[],"description":"Configuration options for browser behavior during the fetch","additionalProperties":false,"properties":{"scrollFullPage":{"type":"boolean","description":"Whether to scroll the entire page to capture lazy-loaded content","examples":[true],"default":false}}}},"additionalProperties":false,"description":"Request parameters for fetching and extracting content from a web page"},"examples":{"minimal":{"summary":"Minimal Fetch JSON Mode request","value":{"url":"https://example.com"}}}}},"required":true}}},"/v1/fetch/search":{"post":{"tags":["Fetch"],"operationId":"fetch.fetchSearch","parameters":[],"security":[{"apiKey":[]},{"cookie":[]},{"bearer":[]}],"responses":{"200":{"description":"FetchSnapshotSearchResult","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FetchSnapshotSearchResult"}}}},"400":{"description":"The request did not match the expected schema","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/HttpApiDecodeError"},{"$ref":"#/components/schemas/BadRequest"}]}}}},"401":{"description":"AuthFailed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthFailed"}}}},"403":{"description":"AccessBlocked","content":{"application/json":{"schema":{"type":"object","required":["organizationId","_tag"],"properties":{"organizationId":{"type":"string","description":"a non empty string","title":"nonEmptyString","minLength":1},"blockedUntil":{"anyOf":[{"$ref":"#/components/schemas/DateTimeUtc"},{"type":"null"}]},"_tag":{"type":"string","enum":["AccessBlocked"]}},"additionalProperties":false}}}},"404":{"description":"FetchSnapshotSearchNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FetchSnapshotSearchNotFound"}}}},"413":{"description":"PayloadTooLarge","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayloadTooLarge"}}}},"429":{"description":"TooManyRequests","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TooManyRequests"},{"$ref":"#/components/schemas/FetchConcurrencyLimitExceeded"}]}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying. Prefer it over your own backoff for the first attempt — retrying sooner spends your timeout budget on a refusal the server already predicted.","required":true,"schema":{"type":"integer","format":"int32","minimum":0},"example":20}}},"500":{"description":"InternalError","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalError"}}}},"503":{"description":"ServiceUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailable"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying. Prefer it over your own backoff for the first attempt — retrying sooner spends your timeout budget on a refusal the server already predicted.","required":true,"schema":{"type":"integer","format":"int32","minimum":0},"example":20}}}},"description":"Use Highlights to search a previous Fetch by snapshotId without starting a new browser capture.","summary":"Highlights","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["snapshotId","search"],"properties":{"snapshotId":{"type":"string","description":"Snapshot ID returned by a previous Fetch response.","title":"nonEmptyString","minLength":1},"search":{"type":"object","required":["query"],"description":"Options for Highlights. When present, Fetch returns search results only.","additionalProperties":false,"properties":{"query":{"type":"string","description":"Query to find relevant snippets from the included Highlights corpus","examples":["pricing plans","API authentication methods"]},"maxResults":{"type":"integer","description":"Maximum number of search snippets to return (1-50)","minimum":1,"maximum":50,"examples":[5],"default":5},"minScore":{"type":"number","description":"Minimum relevance score threshold (0-1). Defaults to 0.6; set 0 to disable filtering.","minimum":0,"maximum":1,"examples":[0.6],"default":0.6}}},"include":{"type":"object","required":[],"description":"Search corpus include config. Defaults to Markdown and State JSON.","additionalProperties":false,"properties":{"html":{"anyOf":[{"type":"boolean","description":"Set to true to include HTML","examples":[true]},{"type":"object","description":"Options for customizing HTML content extraction"},{"type":"array","description":"Options for customizing HTML content extraction"}]},"markdown":{"anyOf":[{"type":"boolean","description":"Set to true to include markdown","examples":[true]},{"type":"object","description":"Options for customizing markdown content extraction"},{"type":"array","description":"Options for customizing markdown content extraction"}]},"screenshot":{"anyOf":[{"type":"boolean","description":"Set to true to include a screenshot","examples":[true]},{"type":"object","required":[],"additionalProperties":false,"description":"Options for customizing screenshot capture behavior","properties":{"fullPage":{"type":"boolean","description":"Whether to capture the full page including content below the fold","examples":[true]}}}]},"links":{"anyOf":[{"type":"boolean","description":"Set to true to include links","examples":[true]},{"type":"object","required":[],"additionalProperties":false,"description":"Options for customizing link extraction","properties":{"sameDomainOnly":{"type":"boolean","description":"Only include links from the same domain as the fetched URL","examples":[true],"default":true},"includePatterns":{"type":"array","description":"Regex patterns - only include links matching at least one pattern","examples":[["docs","api"]],"items":{"type":"string"}},"excludePatterns":{"type":"array","description":"Regex patterns - exclude links matching any pattern","examples":[["login","logout","\\?.*"]],"items":{"type":"string"}}}}]},"meta":{"type":"boolean","description":"Set to true to include page metadata","examples":[true],"default":true},"response":{"type":"object","required":[],"additionalProperties":false,"description":"Configure response info options (headers inclusion)","properties":{"includeHeaders":{"type":"boolean","description":"Whether to include HTTP response headers","default":false}}},"json":{"type":"boolean","description":"Include pruned JSON in the response (opt-in)","examples":[true],"default":false},"appendix":{"type":"boolean","description":"Set to true to include extracted links and sidebar content","examples":[true]}}}},"additionalProperties":false,"description":"Request parameters for searching a previously captured Fetch snapshot."},"examples":{"minimal":{"summary":"Minimal Highlights request","value":{"snapshotId":"snapshot_example","search":{"query":"authentication","maxResults":5}}}}}},"required":true}}},"/v1/fetch/batched":{"post":{"tags":["Fetch"],"operationId":"fetch.batched","parameters":[{"name":"x-idempotency-key","in":"header","schema":{"type":"string","description":"Optional caller-supplied key that prevents duplicate Batched Fetch runs across separate calls. When omitted, the API generates a unique key. Replaying an identical request with the same key returns the same run ID; reusing the key with a different payload returns a 409 response.","title":"maxLength(255)","minLength":1,"maxLength":255},"required":false,"description":"Optional caller-supplied key that prevents duplicate Batched Fetch runs across separate calls. When omitted, the API generates a unique key. Replaying an identical request with the same key returns the same run ID; reusing the key with a different payload returns a 409 response."}],"security":[{"apiKey":[]},{"cookie":[]},{"bearer":[]}],"responses":{"200":{"description":"BatchedRun","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchedRun"}}}},"400":{"description":"The request did not match the expected schema","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/HttpApiDecodeError"},{"$ref":"#/components/schemas/BadRequest"}]}}}},"401":{"description":"AuthFailed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthFailed"}}}},"403":{"description":"AccessBlocked","content":{"application/json":{"schema":{"type":"object","required":["organizationId","_tag"],"properties":{"organizationId":{"type":"string","description":"a non empty string","title":"nonEmptyString","minLength":1},"blockedUntil":{"anyOf":[{"$ref":"#/components/schemas/DateTimeUtc"},{"type":"null"}]},"_tag":{"type":"string","enum":["AccessBlocked"]}},"additionalProperties":false}}}},"409":{"description":"BatchedIdempotencyConflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchedIdempotencyConflict"}}}},"413":{"description":"PayloadTooLarge","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayloadTooLarge"}}}},"429":{"description":"TooManyRequests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequests"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying. Prefer it over your own backoff for the first attempt — retrying sooner spends your timeout budget on a refusal the server already predicted.","required":true,"schema":{"type":"integer","format":"int32","minimum":0},"example":20}}},"500":{"description":"InternalError","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalError"}}}},"503":{"description":"ServiceUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailable"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying. Prefer it over your own backoff for the first attempt — retrying sooner spends your timeout budget on a refusal the server already predicted.","required":true,"schema":{"type":"integer","format":"int32","minimum":0},"example":20}}}},"description":"Start a Batched Fetch over multiple URLs using shared Fetch input and Include Options. Search is not supported for Batched Fetch requests.","summary":"Start Batched Fetch","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["urls"],"properties":{"urls":{"type":"array","minItems":1,"items":{"type":"string"},"description":"List of URLs to fetch using shared options.","examples":[["https://example.com/","https://example.com/about"]]},"include":{"type":"object","required":[],"description":"Specifies which content formats to include in the response","additionalProperties":false,"properties":{"html":{"anyOf":[{"type":"boolean","description":"Set to true to include HTML","examples":[true]},{"type":"object","description":"Options for customizing HTML content extraction"},{"type":"array","description":"Options for customizing HTML content extraction"}]},"markdown":{"anyOf":[{"type":"boolean","description":"Set to true to include markdown","examples":[true]},{"type":"object","description":"Options for customizing markdown content extraction"},{"type":"array","description":"Options for customizing markdown content extraction"}]},"screenshot":{"anyOf":[{"type":"boolean","description":"Set to true to include a screenshot","examples":[true]},{"type":"object","required":[],"additionalProperties":false,"description":"Options for customizing screenshot capture behavior","properties":{"fullPage":{"type":"boolean","description":"Whether to capture the full page including content below the fold","examples":[true]}}}]},"links":{"anyOf":[{"type":"boolean","description":"Set to true to include links","examples":[true]},{"type":"object","required":[],"additionalProperties":false,"description":"Options for customizing link extraction","properties":{"sameDomainOnly":{"type":"boolean","description":"Only include links from the same domain as the fetched URL","examples":[true],"default":true},"includePatterns":{"type":"array","description":"Regex patterns - only include links matching at least one pattern","examples":[["docs","api"]],"items":{"type":"string"}},"excludePatterns":{"type":"array","description":"Regex patterns - exclude links matching any pattern","examples":[["login","logout","\\?.*"]],"items":{"type":"string"}}}}]},"meta":{"type":"boolean","description":"Set to true to include page metadata","examples":[true],"default":true},"response":{"type":"object","required":[],"additionalProperties":false,"description":"Configure response info options (headers inclusion)","properties":{"includeHeaders":{"type":"boolean","description":"Whether to include HTTP response headers","default":false}}},"json":{"type":"boolean","description":"Include pruned JSON in the response (opt-in)","examples":[true],"default":false},"appendix":{"type":"boolean","description":"Set to true to include extracted links and sidebar content","examples":[true]}}},"browserConfig":{"type":"object","required":[],"description":"Configuration options for browser behavior during the fetch","additionalProperties":false,"properties":{"scrollFullPage":{"type":"boolean","description":"Whether to scroll the entire page to capture lazy-loaded content","examples":[true],"default":false}}}},"additionalProperties":false,"description":"FetchInput payload with an array of URLs."},"examples":{"minimal":{"summary":"Minimal Batched Fetch request","value":{"urls":["https://example.com","https://example.com/about"]}}}}},"required":true}}},"/v1/fetch/batched/{id}":{"get":{"tags":["Fetch"],"operationId":"fetch.getBatched","parameters":[{"name":"id","in":"path","schema":{"$ref":"#/components/schemas/NonEmptyString"},"required":true},{"name":"limit","in":"query","schema":{"type":"string","description":"Maximum number of results per page (default 10, max 100)"},"required":false,"description":"Maximum number of results per page (default 10, max 100)"},{"name":"offset","in":"query","schema":{"type":"string","description":"Offset from start (default 0)"},"required":false,"description":"Offset from start (default 0)"},{"name":"include","in":"query","schema":{"type":"string","contentMediaType":"application/json","contentSchema":{"type":"object","required":[],"description":"Specifies which content formats to include in the response","additionalProperties":false,"properties":{"html":{"anyOf":[{"type":"boolean","description":"Set to true to include HTML","examples":[true]},{"type":"object","description":"Options for customizing HTML content extraction"},{"type":"array","description":"Options for customizing HTML content extraction"}]},"markdown":{"anyOf":[{"type":"boolean","description":"Set to true to include markdown","examples":[true]},{"type":"object","description":"Options for customizing markdown content extraction"},{"type":"array","description":"Options for customizing markdown content extraction"}]},"screenshot":{"anyOf":[{"type":"boolean","description":"Set to true to include a screenshot","examples":[true]},{"type":"object","required":[],"additionalProperties":false,"description":"Options for customizing screenshot capture behavior","properties":{"fullPage":{"type":"boolean","description":"Whether to capture the full page including content below the fold","examples":[true]}}}]},"links":{"anyOf":[{"type":"boolean","description":"Set to true to include links","examples":[true]},{"type":"object","required":[],"additionalProperties":false,"description":"Options for customizing link extraction","properties":{"sameDomainOnly":{"type":"boolean","description":"Only include links from the same domain as the fetched URL","examples":[true],"default":true},"includePatterns":{"type":"array","description":"Regex patterns - only include links matching at least one pattern","examples":[["docs","api"]],"items":{"type":"string"}},"excludePatterns":{"type":"array","description":"Regex patterns - exclude links matching any pattern","examples":[["login","logout","\\?.*"]],"items":{"type":"string"}}}}]},"meta":{"type":"boolean","description":"Set to true to include page metadata","examples":[true],"default":true},"response":{"type":"object","required":[],"additionalProperties":false,"description":"Configure response info options (headers inclusion)","properties":{"includeHeaders":{"type":"boolean","description":"Whether to include HTTP response headers","default":false}}},"json":{"type":"boolean","description":"Include pruned JSON in the response (opt-in)","examples":[true],"default":false},"appendix":{"type":"boolean","description":"Set to true to include extracted links and sidebar content","examples":[true]}}},"description":"JSON-encoded Include Options selecting captured content. When omitted, the original POST include is used. A provided include must be a subset of content captured by the POST."},"required":false,"description":"JSON-encoded Include Options selecting captured content. When omitted, the original POST include is used. A provided include must be a subset of content captured by the POST."}],"security":[{"apiKey":[]},{"cookie":[]},{"bearer":[]}],"responses":{"200":{"description":"BatchedStatus","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchedStatus"}}}},"400":{"description":"The request did not match the expected schema","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/HttpApiDecodeError"},{"$ref":"#/components/schemas/BatchedIncludeUnsupported"}]}}}},"401":{"description":"AuthFailed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthFailed"}}}},"404":{"description":"BatchedNotFound"},"413":{"description":"PayloadTooLarge","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayloadTooLarge"}}}},"429":{"description":"TooManyRequests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequests"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying. Prefer it over your own backoff for the first attempt — retrying sooner spends your timeout budget on a refusal the server already predicted.","required":true,"schema":{"type":"integer","format":"int32","minimum":0},"example":20}}},"500":{"description":"InternalError","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalError"}}}},"503":{"description":"ServiceUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailable"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying. Prefer it over your own backoff for the first attempt — retrying sooner spends your timeout budget on a refusal the server already predicted.","required":true,"schema":{"type":"integer","format":"int32","minimum":0},"example":20}}}},"description":"Get persisted Batched Fetch status and paginated results with each URL's lifecycle state. CANCELLING means accepted cancellation is still draining.","summary":"Get Batched Status"}},"/v1/fetch/batched/{id}/cancel":{"post":{"tags":["Fetch"],"operationId":"fetch.cancelBatched","parameters":[{"name":"id","in":"path","schema":{"$ref":"#/components/schemas/NonEmptyString"},"required":true}],"security":[{"apiKey":[]},{"cookie":[]},{"bearer":[]}],"responses":{"200":{"description":"BatchedCancellation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchedCancellation"}}}},"400":{"description":"The request did not match the expected schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpApiDecodeError"}}}},"401":{"description":"AuthFailed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthFailed"}}}},"404":{"description":"BatchedNotFound"},"409":{"description":"BatchedCancellationConflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchedCancellationConflict"}}}},"413":{"description":"PayloadTooLarge","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayloadTooLarge"}}}},"429":{"description":"TooManyRequests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequests"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying. Prefer it over your own backoff for the first attempt — retrying sooner spends your timeout budget on a refusal the server already predicted.","required":true,"schema":{"type":"integer","format":"int32","minimum":0},"example":20}}},"500":{"description":"InternalError","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalError"}}}},"503":{"description":"ServiceUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailable"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying. Prefer it over your own backoff for the first attempt — retrying sooner spends your timeout budget on a refusal the server already predicted.","required":true,"schema":{"type":"integer","format":"int32","minimum":0},"example":20}}}},"description":"Request cancellation. QUEUED work is cancelled immediately; CANCELLING means running work is draining. Repeated cancellation is idempotent.","summary":"Cancel Batched Fetch"}}},"components":{"schemas":{"HttpApiDecodeError":{"type":"object","required":["issues","message","_tag"],"properties":{"issues":{"type":"array","items":{"$ref":"#/components/schemas/Issue"}},"message":{"type":"string"},"_tag":{"type":"string","enum":["HttpApiDecodeError"]}},"additionalProperties":false,"description":"The request did not match the expected schema"},"Issue":{"type":"object","required":["_tag","path","message"],"properties":{"_tag":{"type":"string","enum":["Pointer","Unexpected","Missing","Composite","Refinement","Transformation","Type","Forbidden"],"description":"The tag identifying the type of parse issue"},"path":{"type":"array","items":{"$ref":"#/components/schemas/PropertyKey"},"description":"The path to the property where the issue occurred"},"message":{"type":"string","description":"A descriptive message explaining the issue"}},"additionalProperties":false,"description":"Represents an error encountered while parsing a value to match the schema"},"PropertyKey":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"object","required":["_tag","key"],"properties":{"_tag":{"type":"string","enum":["symbol"]},"key":{"type":"string"}},"additionalProperties":false,"description":"an object to be decoded into a globally shared symbol"}]},"BadRequest":{"type":"object","required":["message","_tag"],"properties":{"message":{"type":"string"},"_tag":{"type":"string","enum":["BadRequest"]}},"additionalProperties":false},"InternalError":{"type":"object","required":["retryable","_tag"],"properties":{"retryable":{"type":"boolean","enum":[true],"description":"Always true: an unexpected server-side failure may not recur, so a retry is worthwhile."},"_tag":{"type":"string","enum":["InternalError"]}},"additionalProperties":false},"TooManyRequests":{"type":"object","required":["retryable","_tag"],"properties":{"retryable":{"type":"boolean","enum":[true],"description":"Always true: the request was throttled, so the same request can succeed after a delay."},"retryAfterSeconds":{"type":"number","description":"Seconds until the rate-limit window that refused this request resets."},"_tag":{"type":"string","enum":["TooManyRequests"]}},"additionalProperties":false},"FetchConcurrencyLimitExceeded":{"type":"object","required":["retryable","retryAfterSeconds","maxConcurrency","_tag"],"properties":{"retryable":{"type":"boolean","enum":[true],"description":"Always true: the capture never ran, so the same request succeeds once a slot frees."},"retryAfterSeconds":{"type":"number","description":"How long to wait before retrying, matching the Retry-After header on this response"},"maxConcurrency":{"type":"number","description":"The organization's browser-concurrency limit — the number of captures it may run at once","examples":[5]},"message":{"type":"string","description":"Names the cause and the remedies: lower concurrency, use the batched endpoints, or raise the tier"},"requestId":{"type":"string","description":"Trace ID for this request, also sent as the x-expand-trace-id header"},"_tag":{"type":"string","enum":["FetchConcurrencyLimitExceeded"]}},"additionalProperties":false},"ServiceUnavailable":{"type":"object","required":["retryable","_tag"],"properties":{"message":{"type":"string"},"requestId":{"type":"string"},"retryable":{"type":"boolean","enum":[true],"description":"Always true: this status covers failures that were not shown to be permanent, so a retry is worthwhile. It is not a guarantee that the cause was temporary — an error we can prove is permanent is returned as a 502 with retryable false instead."},"_tag":{"type":"string","enum":["ServiceUnavailable"]}},"additionalProperties":false},"PayloadTooLarge":{"type":"object","required":["_tag"],"properties":{"_tag":{"type":"string","enum":["PayloadTooLarge"]}},"additionalProperties":false},"FetchPageTooLarge":{"type":"object","required":["url","_tag"],"properties":{"url":{"type":"string","description":"URL whose capture was rejected on size"},"limitKind":{"type":"string","enum":["transfer_bytes","domsnapshot_bytes","ast_bytes"],"description":"Which page-weight ceiling was exceeded","examples":["domsnapshot_bytes"]},"limitBytes":{"type":"number","description":"The configured ceiling in bytes"},"measuredBytes":{"type":"number","description":"What the page actually measured, in bytes"},"_tag":{"type":"string","enum":["FetchPageTooLarge"]}},"additionalProperties":false},"AuthFailed":{"type":"object","required":["reason","_tag"],"properties":{"reason":{"type":"string","enum":["InvalidApiKey","InvalidToken","InvalidSession","InvalidTenant"]},"description":{"anyOf":[{"type":"string"},{"type":"object","required":["message"],"properties":{"message":{"type":"string"}},"additionalProperties":false}]},"_tag":{"type":"string","enum":["AuthFailed"]}},"additionalProperties":false},"DateTimeUtc":{"type":"string","description":"a string to be decoded into a DateTime.Utc"},"FetchBlocked":{"type":"object","required":["url","_tag"],"properties":{"url":{"type":"string","description":"URL whose capture was blocked"},"blockedType":{"type":"string","description":"hfc blocked classification (e.g. captcha, botProtection, ipBlock, authWall)","examples":["botProtection"]},"_tag":{"type":"string","enum":["FetchBlocked"]}},"additionalProperties":false},"FetchCaptureFailed":{"type":"object","required":["url","failureType","retryable","_tag"],"properties":{"url":{"type":"string","description":"URL whose capture could not be completed"},"failureType":{"type":"string","enum":["pageNeverSettled","capabilityFailed"],"description":"Bounded capture failure classification: the page never produced navigation activity (pageNeverSettled), or no capture satisfied a required capability (capabilityFailed)","examples":["pageNeverSettled"]},"retryable":{"type":"boolean","enum":[false],"description":"Always false: the capture was retried against fresh infrastructure and reached the same outcome."},"_tag":{"type":"string","enum":["FetchCaptureFailed"]}},"additionalProperties":false},"FetchNavigationFailed":{"type":"object","required":["url","failureType","retryable","_tag"],"properties":{"url":{"type":"string","description":"URL whose navigation did not produce a fetchable document"},"failureType":{"type":"string","enum":["browserInternalDocument"],"description":"Bounded navigation failure classification"},"retryable":{"type":"boolean","enum":[false],"description":"Always false: the verdict is deterministic for this URL, so a retry reaches the same outcome."},"_tag":{"type":"string","enum":["FetchNavigationFailed"]}},"additionalProperties":false},"FetchCapacityTimeout":{"type":"object","required":["url","retryable","_tag"],"properties":{"url":{"type":"string","description":"URL whose capture never started before the server deadline"},"timeoutMs":{"type":"number","description":"Configured server request ceiling that expired, in milliseconds","examples":[150000]},"retryable":{"type":"boolean","enum":[true],"description":"Always true: the capture never started, so the same request succeeds once capacity frees."},"_tag":{"type":"string","enum":["FetchCapacityTimeout"]}},"additionalProperties":false},"FetchCaptureTimeout":{"type":"object","required":["url","retryable","_tag"],"properties":{"url":{"type":"string","description":"URL whose fetch produced no publishable capture result before the server deadline"},"timeoutMs":{"type":"number","description":"Configured server request ceiling that expired, in milliseconds","examples":[150000]},"retryable":{"type":"boolean","enum":[false],"description":"Always false: the run had already started and the deadline expired without a publishable result, so an automatic retry would amplify whatever is already slow."},"_tag":{"type":"string","enum":["FetchCaptureTimeout"]}},"additionalProperties":false},"FetchObjectModeResult":{"type":"object","required":["meta","markdown","json"],"properties":{"meta":{"$ref":"#/components/schemas/FetchObjectModeMeta"},"markdown":{"type":"string","description":"Main content body from the text/markdown response, without front-matter or evidence sections."},"json":{"type":"array","items":{"$ref":"#/components/schemas/FetchObjectModeEvidence"},"description":"Selected JSON evidence in canonical emission order."},"data":{"type":"object","required":[],"properties":{"assets":{"type":"array","items":{"$ref":"#/components/schemas/FetchAssetReference"}},"degraded":{"$ref":"#/components/schemas/FetchDegradedInfo"},"search":{"$ref":"#/components/schemas/FetchSearchResult"},"screenshot":{"type":"object","required":["url","fullPage"],"properties":{"url":{"type":"string","description":"Presigned URL for the screenshot image","examples":["https://s3.amazonaws.com/bucket/snapshots/abcd/screenshot.jpeg?X-Amz-Signature=..."]},"fullPage":{"type":"boolean","description":"Whether the screenshot captures the full scrollable page or just the viewport","examples":[true]}},"additionalProperties":false,"description":"Screenshot of the fetched page"}},"additionalProperties":false,"description":"Additional fetch data for fields not represented in Markdown or selected JSON evidence."}},"additionalProperties":false,"description":"Fetch JSON Mode response for `/v1/fetch/json`. Mirrors the Markdown response as discrete fields for JSON-native consumers."},"FetchObjectModeMeta":{"type":"object","required":["version","url","capturedAt","snapshotId","lang","pageType","playground"],"properties":{"version":{"type":"number","enum":[1],"description":"Schema version. Breaking shape changes bump this; additive fields do not."},"url":{"type":"string"},"capturedAt":{"type":"string"},"snapshotId":{"type":"string"},"lang":{"type":"string"},"pageType":{"type":"string"},"playground":{"type":"string"},"title":{"type":"string"},"finalUrl":{"type":"string"},"canonical":{"type":"string"},"description":{"type":"string"},"author":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"image":{"type":"string"},"paginationNext":{"type":"string"},"appendix":{"$ref":"#/components/schemas/FetchObjectModeAppendixHint"},"stateJson":{"$ref":"#/components/schemas/FetchObjectModeStateJsonHint"},"markdown":{"$ref":"#/components/schemas/FetchObjectModeMarkdownHint"},"blocked":{"type":"string","description":"HFC blocked sub-class when != none. Present only on short-circuited / partial responses."},"loadingStatus":{"type":"string","description":"HFC loading status when != none. Present only when the capture hit its deadline without settling."}},"additionalProperties":false,"description":"Structured page metadata in Fetch JSON Mode responses."},"FetchObjectModeAppendixHint":{"type":"object","required":["url","links"],"properties":{"url":{"type":"string","description":"URL to fetch the full appendix. Lazy-loaded so default responses stay small."},"links":{"$ref":"#/components/schemas/FetchObjectModeAppendixLinks"}},"additionalProperties":false},"FetchObjectModeAppendixLinks":{"type":"object","required":["sameDomain","external"],"properties":{"sameDomain":{"type":"number","description":"Number of appendix links on the captured domain."},"external":{"type":"number","description":"Number of appendix links pointing to other domains."}},"additionalProperties":false,"description":"Appendix link counts grouped by destination."},"FetchObjectModeStateJsonHint":{"type":"object","required":["moreTokens"],"properties":{"moreTokens":{"type":"number","description":"Approximate token count available from the referenced state JSON evidence."}},"additionalProperties":false},"FetchObjectModeMarkdownHint":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"URL to fetch the full markdown for this snapshot."},"moreTokens":{"type":"number","description":"Approximate token count available from the referenced markdown. Not populated today: the hint names the route, and callers needing the size can ask it."}},"additionalProperties":false},"FetchObjectModeEvidence":{"type":"object","required":["id","kind","role","score"],"properties":{"id":{"type":"number","description":"Evidence ID. Fetch via /s/<snapshotId>?id=<id>."},"kind":{"type":"string","enum":["inline","network"]},"role":{"type":"string","enum":["ld+json","next-data","nuxt","apollo-state","initial-state","application-json","script-tag","data-attribute","network-json","network-response","other"]},"score":{"type":"number","description":"Evidence relevance score, 0–1."},"url":{"type":"string","description":"Sanitized originating request URL. Network only. See urlRedacted and urlOmitted for disclosure qualifiers."},"method":{"type":"string","description":"HTTP method. Network only."},"body":{"$id":"/schemas/unknown","title":"unknown","description":"Raw payload. Present when the evidence fit the token budget; absent for referenced evidence."},"moreTokens":{"type":"number","description":"Approximate token count omitted from referenced evidence."},"keys":{"type":"array","items":{"type":"string"},"description":"Sample of top-level keys from referenced JSON evidence."},"urlRedacted":{"type":"boolean","enum":[true],"description":"True when the sanitized URL differs from the captured URL because userinfo was removed or sensitive query values were replaced with REDACTED. Present only when redaction happened."},"urlOmitted":{"type":"string","enum":["invalid","unsafe","too-long"],"description":"Reason the originating URL was withheld entirely: \"invalid\", \"unsafe\", or \"too-long\". Present only when url is absent."}},"additionalProperties":false},"FetchAssetReference":{"type":"object","required":["id","kind","placeholder","archiveKey","mimeType","sha256","bytes"],"properties":{"id":{"type":"string","description":"Stable asset identifier. For data-url assets this is the decoded-byte SHA-256 hex digest.","examples":["9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"]},"kind":{"type":"string","enum":["data-url"],"description":"Asset source kind."},"placeholder":{"type":"string","description":"Markdown/AST placeholder replacing the raw data URL.","examples":["expand-asset:data-url:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"]},"archiveKey":{"type":"string","description":"Synthetic WACZ archive key for retrieving the decoded asset bytes.","examples":["data-url:sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"]},"mimeType":{"type":"string","description":"Decoded asset MIME type.","examples":["image/svg+xml","image/png"]},"sha256":{"type":"string","description":"Decoded-byte SHA-256 digest prefixed with sha256:.","examples":["sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"]},"bytes":{"type":"number","description":"Decoded byte length.","examples":[312]}},"additionalProperties":false,"description":"Reference to an extracted asset whose bytes are stored in the snapshot archive."},"FetchDegradedInfo":{"type":"object","required":["reason","skipped","limitKind"],"properties":{"reason":{"type":"string","enum":["pageTooLarge","modelInputTooLarge"]},"skipped":{"type":"array","items":{"type":"string","enum":["hfc"]},"description":"Processing stages skipped; hfc is the HTML field-classification stage."},"limitKind":{"type":"string","enum":["domsnapshot_bytes","ast_bytes","hfc_tokens"]},"measuredBytes":{"type":"integer","description":"Measured page size in bytes at the checkpoint that triggered degradation.","title":"nonNegative","minimum":0},"thresholdBytes":{"type":"integer","description":"Configured degradation threshold in bytes.","title":"nonNegative","minimum":0},"measuredTokens":{"type":"integer","description":"Tokenized HFC model input size in tokens.","title":"nonNegative","minimum":0},"thresholdTokens":{"type":"integer","description":"Configured HFC input-token ceiling.","title":"nonNegative","minimum":0}},"additionalProperties":false,"description":"Reduced-fidelity processing applied because the page crossed a configured processing threshold."},"FetchSearchResult":{"type":"object","required":["query","snippets"],"properties":{"query":{"type":"string"},"snippets":{"type":"array","items":{"type":"object","required":["source","text","score"],"properties":{"type":{"type":"string","enum":["text"],"description":"Type identifier for TextPart compatibility","default":"text"},"source":{"type":"string","enum":["markdown","appendix","statejson"]},"text":{"type":"string","description":"Readable snippet content"},"json":{"$id":"/schemas/unknown","title":"unknown"},"score":{"type":"number","description":"Normalized fused relevance score (0-1)","title":"between(0, 1)","minimum":0,"maximum":1},"location":{"$ref":"#/components/schemas/FetchSearchSnippetLocation"}},"additionalProperties":false}},"meta":{"$ref":"#/components/schemas/FetchSearchMeta"}},"additionalProperties":false},"FetchSearchSnippetLocation":{"type":"object","required":[],"properties":{"evidenceId":{"allOf":[{"$ref":"#/components/schemas/Int","description":"Canonical public evidence target within a snapshot","title":"between(1, 2147483647)","minimum":1,"maximum":2147483647}],"description":"Canonical public evidence target for this snippet"},"markdownBlockId":{"type":"string","description":"Deprecated Source Block identity; use evidenceId"},"nodeIds":{"type":"array","items":{"type":"number"},"description":"Deprecated replay element linkage; use evidenceId for public citations"},"stateJsonSourceId":{"type":"number","description":"Deprecated State JSON source-object index; use evidenceId for public citations"},"jsonPath":{"type":"string","description":"JSON path for State JSON snippets"}},"additionalProperties":false},"Int":{"type":"integer","description":"an integer","title":"int"},"FetchSearchMeta":{"type":"object","required":["durationMs","sources"],"properties":{"durationMs":{"type":"number","description":"Total elapsed search time in milliseconds.","title":"nonNegative","minimum":0},"sources":{"type":"array","items":{"$ref":"#/components/schemas/FetchSearchSourceMeta"}}},"additionalProperties":false},"FetchSearchSourceMeta":{"type":"object","required":["source","chunkCount","batchCount","ranker","fallback","durationMs"],"properties":{"source":{"type":"string","enum":["markdown","appendix","statejson"]},"chunkCount":{"type":"integer","description":"Number of search chunks considered for this source.","title":"nonNegative","minimum":0},"batchCount":{"type":"integer","description":"Number of ranking batches evaluated for this source.","title":"nonNegative","minimum":0},"ranker":{"type":"string","enum":["zeroentropy","mixedbread","local_lexical"]},"fallback":{"type":"boolean"},"fallbackReason":{"type":"string","enum":["timeout","error"]},"durationMs":{"type":"number","description":"Elapsed search time for this source in milliseconds.","title":"nonNegative","minimum":0}},"additionalProperties":false},"FetchSnapshotSearchResult":{"type":"object","required":["snapshotId","response","search","durationMs","playground"],"properties":{"snapshotId":{"type":"string","description":"Snapshot ID searched.","title":"nonEmptyString","minLength":1},"response":{"$ref":"#/components/schemas/ResponseInfo"},"search":{"$ref":"#/components/schemas/FetchSearchResult"},"durationMs":{"type":"number","description":"Duration of the search operation in milliseconds.","title":"nonNegative","minimum":0},"playground":{"type":"string","description":"Public playground URL for the searched snapshot. Use its origin to build citation links for the snippets below."}},"additionalProperties":false},"ResponseInfo":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"The final URL after any redirects","examples":["https://stripe.com/docs/api"]},"requestedUrl":{"allOf":[{"$ref":"#/components/schemas/URL"}],"description":"The originally requested URL, present only when a redirect occurred. When absent, the request was served directly without redirect.","examples":["https://www.stripe.com/docs/api"]},"originStatusCode":{"type":"number","description":"HTTP status code returned by the origin website. Absent when the fetch is still pending or the origin response could not be determined.","examples":[200]},"redirectStatusCode":{"type":"number","description":"HTTP status code of the redirect response (e.g. 301, 302). Present only when a redirect occurred.","examples":[301]},"headers":{"type":"object","required":[],"properties":{},"additionalProperties":{"type":"string"},"description":"Response headers from the fetch operation (keys are lower-cased HTTP header names)","examples":[{"content-type":"text/html; charset=utf-8"}]}},"additionalProperties":false,"description":"HTTP response information for the searched snapshot."},"URL":{"type":"string","description":"a string to be decoded into a URL"},"FetchSnapshotSearchNotFound":{"type":"object","required":["snapshotId","_tag"],"properties":{"snapshotId":{"$ref":"#/components/schemas/NonEmptyString"},"_tag":{"type":"string","enum":["FetchSnapshotSearchNotFound"]}},"additionalProperties":false},"NonEmptyString":{"type":"string","description":"a non empty string","title":"nonEmptyString","minLength":1},"BatchedRun":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"Batched run ID"}},"additionalProperties":false},"BatchedIdempotencyConflict":{"type":"object","required":["existingRunId","reason","_tag"],"properties":{"existingRunId":{"type":"string","description":"Batched run created by the original request."},"reason":{"type":"string","enum":["payload_mismatch"],"description":"The idempotency key was previously used with a different request body."},"_tag":{"type":"string","enum":["BatchedIdempotencyConflict"]}},"additionalProperties":false},"BatchedStatus":{"type":"object","required":["id","status","batchedStatus","totalUrls","results","pagination"],"properties":{"id":{"type":"string","description":"Batched run ID"},"status":{"type":"string","enum":["QUEUED","RUNNING","CANCELLING","COMPLETED","FAILED","CANCELLED"],"description":"Page-level status: whether this page is stable and requested result content extracted successfully. CANCELLING means accepted cancellation is still draining; FAILED can indicate an unreadable persisted result."},"batchedStatus":{"type":"string","enum":["QUEUED","RUNNING","CANCELLING","COMPLETED","FAILED","CANCELLED"],"description":"Overall Batched Fetch status. This is the exact persisted status, including CANCELLING while active items drain."},"totalUrls":{"type":"number","description":"Total number of URLs in the Batched Fetch"},"results":{"type":"array","items":{"$ref":"#/components/schemas/BatchedFetchItem"},"description":"Paginated fetch results"},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"additionalProperties":false},"BatchedFetchItem":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["QUEUED","RUNNING","SUCCEEDED","FAILED","CANCELLED"],"description":"Persisted lifecycle state for this URL in the Batched Fetch"},"data":{"type":"object","required":["response"],"properties":{"response":{"$ref":"#/components/schemas/ResponseInfo"},"meta":{"allOf":[{"$ref":"#/components/schemas/PageMeta"}],"description":"Page metadata extracted from HTML head (title, description, Open Graph, Twitter Card, icons)"},"json":{"type":"array","items":{"anyOf":[{"type":"object","required":[],"properties":{},"additionalProperties":{"$id":"/schemas/unknown","title":"unknown"}},{"type":"array","items":{"$id":"/schemas/unknown","title":"unknown"}}]},"description":"Pruned structured JSON values extracted from the page (from HTML and network responses). This is recomputed on every fetch and is not persisted."},"snapshotId":{"allOf":[{"$ref":"#/components/schemas/NonEmptyString"}],"description":"Stable snapshot id for replay and full-document references"},"html":{"type":"string","description":"The HTML content of the fetched page","title":"nonEmptyString","examples":["<html><body><h1>Welcome to our API</h1></body></html>"],"minLength":1},"markdown":{"type":"string","description":"The markdown-formatted content extracted from the page","title":"nonEmptyString","examples":["# API Documentation\n\nWelcome to our API. This guide will help you get started..."],"minLength":1},"screenshot":{"type":"object","required":["url","fullPage"],"properties":{"url":{"type":"string","description":"Presigned URL for the screenshot image","examples":["https://s3.amazonaws.com/bucket/snapshots/abcd/screenshot.jpeg?X-Amz-Signature=..."]},"fullPage":{"type":"boolean","description":"Whether the screenshot captures the full scrollable page or just the viewport","examples":[true]}},"additionalProperties":false,"description":"Screenshot of the fetched page"},"search":{"allOf":[{"$ref":"#/components/schemas/FetchSearchResult"}],"description":"Search result returned when the request includes search.query"},"links":{"type":"array","items":{"$ref":"#/components/schemas/FetchLink"},"description":"Links extracted from the page"},"appendix":{"type":"string","description":"Extracted links and sidebar content","title":"nonEmptyString","minLength":1},"renderEngines":{"allOf":[{"$ref":"#/components/schemas/RenderEnginesInfo"}],"description":"Rendering engines actually used for response fields such as markdown or tree output"},"assets":{"type":"array","items":{"$ref":"#/components/schemas/FetchAssetReference"},"description":"Non-persisted manifest of assets extracted during fetch capture."},"degraded":{"allOf":[{"$ref":"#/components/schemas/FetchDegradedInfo"}],"description":"Details of processing stages skipped because the page crossed a configured size threshold."}},"additionalProperties":false,"description":"Fetch data for this URL. Absent when the URL was refused — read `error` instead."},"error":{"anyOf":[{"$ref":"#/components/schemas/FetchBlocked"},{"$ref":"#/components/schemas/FetchPageTooLarge"},{"$ref":"#/components/schemas/FetchNavigationFailed"},{"$ref":"#/components/schemas/FetchCaptureFailed"},{"$ref":"#/components/schemas/FetchCaptureTimeout"},{"$ref":"#/components/schemas/FetchCapacityTimeout"}],"description":"Present when this URL ended without a snapshot. Carries the error the synchronous /v1/fetch endpoint would have returned (403 FetchBlocked, 413 FetchPageTooLarge, 502 FetchNavigationFailed, 502 FetchCaptureFailed, 504 FetchCaptureTimeout, or 529 FetchCapacityTimeout)."}},"additionalProperties":false},"PageMeta":{"type":"object","required":[],"properties":{"title":{"type":"string","description":"Page title from <title> tag","examples":["Stripe API Reference"]},"description":{"type":"string","description":"Meta description from <meta name=\"description\">","examples":["Complete reference for the Stripe API."]},"canonicalUrl":{"type":"string","description":"Canonical URL from <link rel=\"canonical\">","title":"nonEmptyString","examples":["https://stripe.com/docs/api"],"minLength":1},"language":{"type":"string","description":"Page language from <html lang=\"...\">","title":"nonEmptyString","examples":["en","en-US","de"],"minLength":1},"charset":{"type":"string","description":"Character encoding from <meta charset=\"...\">","title":"nonEmptyString","examples":["utf-8","UTF-8"],"minLength":1},"favicon":{"type":"string","description":"Primary favicon URL: regular icons before Apple touch icons, then scalable, then the largest declared square size, then document order","title":"nonEmptyString","examples":["/favicon.ico"],"minLength":1},"icons":{"type":"array","items":{"$ref":"#/components/schemas/IconMeta"},"description":"All icon links (favicons, apple-touch-icons, etc.)"},"openGraph":{"allOf":[{"$ref":"#/components/schemas/OpenGraphMeta"}],"description":"Open Graph metadata from og:* meta tags"},"twitter":{"allOf":[{"$ref":"#/components/schemas/TwitterCardMeta"}],"description":"Twitter Card metadata from twitter:* meta tags"}},"additionalProperties":false,"description":"Comprehensive metadata extracted from the page HTML head section"},"IconMeta":{"type":"object","required":["href","rel"],"properties":{"href":{"type":"string","description":"Icon URL or path","title":"nonEmptyString","examples":["/favicon.ico","https://example.com/icon-192.png"],"minLength":1},"rel":{"type":"string","description":"Link relationship type","title":"nonEmptyString","examples":["icon","apple-touch-icon","shortcut icon"],"minLength":1},"type":{"type":"string","description":"MIME type of the icon","title":"nonEmptyString","examples":["image/png","image/x-icon","image/svg+xml"],"minLength":1},"sizes":{"type":"string","description":"Icon dimensions","title":"nonEmptyString","examples":["32x32","180x180","192x192"],"minLength":1}},"additionalProperties":false,"description":"Favicon or app icon metadata from <link> tags"},"OpenGraphMeta":{"type":"object","required":[],"properties":{"title":{"type":"string","description":"Open Graph title (og:title)","examples":["Stripe | Payment Processing Platform"]},"description":{"type":"string","description":"Open Graph description (og:description)","examples":["Online payment processing for internet businesses."]},"type":{"type":"string","description":"Open Graph type (og:type) - website, article, product, etc.","title":"nonEmptyString","examples":["website","article"],"minLength":1},"url":{"type":"string","description":"Canonical URL for the content (og:url)","title":"nonEmptyString","examples":["https://stripe.com"],"minLength":1},"siteName":{"type":"string","description":"Site name (og:site_name)","examples":["Stripe"]},"locale":{"type":"string","description":"Locale in language_TERRITORY format (og:locale)","examples":["en_US","de_DE"]},"images":{"type":"array","items":{"$ref":"#/components/schemas/OgImage"},"description":"Open Graph images (og:image and related properties)"}},"additionalProperties":false,"description":"Open Graph protocol metadata for rich link previews"},"OgImage":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"Image URL","title":"nonEmptyString","examples":["https://example.com/og-image.png"],"minLength":1},"width":{"type":"number","description":"Image width in pixels","examples":[1200]},"height":{"type":"number","description":"Image height in pixels","examples":[630]},"alt":{"type":"string","description":"Image alt text for accessibility","examples":["Product screenshot showing dashboard"]}},"additionalProperties":false,"description":"Open Graph image with optional dimensions and alt text"},"TwitterCardMeta":{"type":"object","required":[],"properties":{"card":{"type":"string","description":"Twitter card type (twitter:card)","title":"nonEmptyString","examples":["summary","summary_large_image","app","player"],"minLength":1},"site":{"type":"string","description":"Twitter @username of the website (twitter:site)","examples":["@stripe"]},"creator":{"type":"string","description":"Twitter @username of content creator (twitter:creator)","examples":["@johndoe"]},"title":{"type":"string","description":"Title for Twitter card (twitter:title)","examples":["Stripe API Reference"]},"description":{"type":"string","description":"Description for Twitter card (twitter:description)","examples":["Complete reference documentation for the Stripe API."]},"image":{"type":"string","description":"Image URL for Twitter card (twitter:image)","title":"nonEmptyString","examples":["https://stripe.com/twitter-card.png"],"minLength":1}},"additionalProperties":false,"description":"Twitter Card metadata for social sharing previews"},"FetchLink":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"The URL of the link","examples":["https://example.com/page"]},"text":{"type":"string","description":"The anchor text of the link","examples":["Click here"]}},"additionalProperties":false,"description":"A link extracted from the page"},"RenderEnginesInfo":{"type":"object","required":[],"properties":{"capture":{"type":"string","enum":["rust"],"description":"Actual snapshot capture engine used for this response","examples":["rust"]},"markdown":{"type":"string","enum":["rust"],"description":"Actual markdown renderer used for this response","examples":["rust"]},"tree":{"type":"string","enum":["rust"],"description":"Actual tree renderer used for this response","examples":["rust"]}},"additionalProperties":false,"description":"Rendering engines actually used to produce this response"},"PaginationMeta":{"type":"object","required":["total","limit","offset","hasMore"],"properties":{"total":{"type":"number","description":"Total number of results"},"limit":{"type":"number","description":"Page size"},"offset":{"type":"number","description":"Offset from start"},"hasMore":{"type":"boolean","description":"Whether more results are available"}},"additionalProperties":false,"description":"Pagination metadata"},"BatchedIncludeUnsupported":{"type":"object","required":["unsupportedFields","_tag"],"properties":{"unsupportedFields":{"type":"array","items":{"type":"string"},"description":"The include fields that are not supported by batched fetches."},"_tag":{"type":"string","enum":["BatchedIncludeUnsupported"]}},"additionalProperties":false},"BatchedCancellation":{"type":"object","required":["id","status"],"properties":{"id":{"type":"string","description":"Batched run ID"},"status":{"type":"string","enum":["CANCELLING","CANCELLED"],"description":"Cancellation state. CANCELLING means already-running items are draining."}},"additionalProperties":false},"BatchedCancellationConflict":{"type":"object","required":["id","status","_tag"],"properties":{"id":{"type":"string","description":"Batched run ID"},"status":{"type":"string","enum":["COMPLETED","FAILED"],"description":"Terminal status that prevents cancellation"},"_tag":{"type":"string","enum":["BatchedCancellationConflict"]}},"additionalProperties":false}},"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-expand-api-key","in":"header"},"cookie":{"type":"apiKey","name":"xpnd.session_token","in":"cookie"},"bearer":{"type":"http","scheme":"bearer"}}},"security":[],"tags":[{"name":"Fetch","description":"Fetch web pages as LLM-ready Markdown, JSON Mode responses, Highlights snippets, and Batched Fetch runs."}]}