{ "openapi": "3.1.0", "info": { "title": "Jina AI API", "description": "Jina AI APIs on three hosts: Reader (`r.jina.ai`), Search (`s.jina.ai`) and the Search Foundation models (`api.jina.ai`).\n\n| I want to | Endpoint |\n|---|---|\n| Read a web page or PDF as LLM-friendly Markdown | [GET r.jina.ai/{url}](#tag/reader/GET/{url}) · [POST r.jina.ai](#tag/reader/POST/) |\n| Search the web and get the result pages as text | [GET s.jina.ai/{q}](#tag/search/GET/{q}) · [POST s.jina.ai/search](#tag/search/POST/search) |\n| Embed text, images, audio, video or PDFs | [POST /v1/embeddings](#tag/search-foundation-models/POST/v1/embeddings) |\n| Rerank candidates against a query | [POST /v1/rerank](#tag/search-foundation-models/POST/v1/rerank) |\n| Transcribe a document image (OCR) | [POST /v1/chat/completions](#tag/generative-models/POST/v1/chat/completions) |\n| Embed a large dataset asynchronously | [POST /v1/batch/embeddings](#tag/batch-embeddings/POST/v1/batch/embeddings) |\n| See which models exist and what they cost | [GET /v1/models](#tag/model-list/GET/v1/models) |\n\n**Authentication.** Send `Authorization: Bearer `. Get a key at https://jina.ai/?sui=apikey. Reader also answers without a key, at a lower rate limit; Search needs one.\n\n**EU.** `eu.r.jina.ai` and `eu.s.jina.ai` keep all processing inside the EU.\n\n**For LLMs.** `curl docs.jina.ai` returns the meta-prompt, a plain-text guide to these APIs written for coding agents. This reference as Markdown: `curl docs.jina.ai/api.md`.\n\n**Rate limits.** r.jina.ai 500 RPM (5k premium), s.jina.ai 100 RPM (1k premium).\n\n_Merged from https://api.jina.ai/openapi.json, https://r.jina.ai/openapi.json, https://s.jina.ai/openapi.json. Plain text: https://docs.jina.ai/api.md. Spec: https://docs.jina.ai/openapi.json._\n\nBest-in-class embeddings, rerankers and document models for multilingual and multimodal search.\n\n## Capabilities\n\n- **Text embeddings** — dense vectors for semantic search, similarity, clustering and classification, in 100+ languages.\n- **Multimodal embeddings** — images, video, audio and PDFs embedded into the same space as text, so a query in one modality retrieves another.\n- **Reranking** — score a query against a candidate set and reorder it; more accurate than embedding similarity, and the usual second stage after it.\n- **Document OCR** — read a page image and return its content as text or markdown, with tables and layout preserved, over the OpenAI chat completions schema.\n- **Batch embeddings** — the same embedding models over JSONL, asynchronously, for workloads too large to send inline.\n\n## Authentication\n\nEvery endpoint except `GET /v1/models` requires a key:\n\n```\nAuthorization: Bearer jina_YOUR_API_KEY\n```\n\nGet one at [jina.ai/api-dashboard/key-manager](https://jina.ai/api-dashboard/key-manager).\n\n## Rate limits\n\nRequests per minute and tokens per minute. Anything over a limit answers `429`.\n\n| Endpoint | Free | Paid | Premium |\n|---|---|---|---|\n| `/v1/embeddings` | 500 RPM · 1M TPM | 500 RPM · 10M TPM | 5,000 RPM · 100M TPM |\n| `/v1/rerank` | 500 RPM · 1M TPM | 500 RPM · 10M TPM | 5,000 RPM · 100M TPM |\n| `/v1/chat/completions` | 100 RPM · 500K TPM | 100 RPM · 5M TPM | 1,000 RPM · 50M TPM |\n\n## Errors\n\nFailures carry a `detail`, a `code` from the table below and the `request_id` to quote in a support request. `/v1/chat/completions` is the exception: it answers in OpenAI's error envelope, with the same code inside it.\n\n| Code | Status | Meaning |\n|---|---|---|\n| `INPUT_INVALID_LABELS` | 400 | Invalid training labels |\n| `INPUT_LABEL_LIMIT_EXCEEDED` | 400 | Label limit exceeded: labels provided, maximum allowed for your plan |\n| `INPUT_MODEL_NOT_FOUND` | 400 | Model '' not found |\n| `INPUT_TOKEN_LIMIT_EXCEEDED` | 400 | Input text exceeds the model's maximum of tokens |\n| `AUTH_INVALID_API_KEY` | 401 | Invalid API key |\n| `AUTH_INVALID_FORMAT` | 401 | Invalid authorization format |\n| `AUTH_MISSING_API_KEY` | 401 | Authentication required |\n| `AUTHZ_INSUFFICIENT_BALANCE` | 403 | Insufficient account balance |\n| `AUTHZ_RESOURCE_LIMIT_EXCEEDED` | 403 | Resource limit exceeded for your plan |\n| `RESOURCE_NOT_FOUND` | 404 | '' not found or access denied |\n| `CONFLICT_RESOURCE_BUSY` | 409 | '' is currently being modified |\n| `RATE_CONCURRENCY_LIMIT_EXCEEDED` | 429 | Concurrency limit exceeded: / concurrent requests |\n| `RATE_IP_LIMIT_EXCEEDED` | 429 | IP rate limit exceeded |\n| `RATE_REQUEST_LIMIT_EXCEEDED` | 429 | Request rate limit exceeded: / requests per minute |\n| `RATE_TOKEN_LIMIT_EXCEEDED` | 429 | Token rate limit exceeded: / tokens per minute |\n| `INTERNAL_ERROR` | 500 | An unexpected error occurred |\n| `SERVICE_UNAVAILABLE` | 503 | Service temporarily unavailable |\n| `SERVICE_TIMEOUT` | 504 | Service request timed out |", "version": "2026.10.13.1624" }, "servers": [ { "url": "https://api.jina.ai" } ], "paths": { "/": { "get": { "tags": [ "Reader" ], "parameters": [ { "name": "url", "in": "query", "schema": { "type": "string" }, "description": "The URL to read. Not needed when the URL is already in the path (`https://r.jina.ai/`)." }, { "name": "preloadUrl", "in": "query", "schema": { "type": "string" }, "description": "URL to preload before scraping.\n\nIgnored when no URL is provided." }, { "name": "noServiceWorker", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Disable service workers when running the browser.\n\nUseful for bypassing service-worker-based caching or interception." }, { "name": "html", "in": "query", "schema": { "type": "string" }, "description": "Raw HTML to convert, instead of fetching a URL. Used when no `url` is given." }, { "name": "base", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x0d" } ], "default": "initial" }, "description": "Select base modes of relative URLs.\n\nSupported: initial, final" }, { "name": "pdf", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_FancyFile@0x0e" } ] }, { "type": "string" } ], "summary": "Base64 encoded PDF.", "description": "Base64 encoded PDF." } }, { "name": "file", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_FancyFile@0x0e" } ] }, { "type": "string" } ], "summary": "Base64 encoded file.", "description": "Base64 encoded file." }, "description": "Base64-encoded file (PDF, DOC, XLS, PPT, ...) to convert instead of a URL." }, { "name": "page", "in": "query", "schema": { "type": "number", "summary": "Steer which page to return for document files (1-indexed).", "description": "Steer which page to return for document files (1-indexed).\n\n- Some validators will be applied on value(s): (v) => Number.isInteger(v) && v >= 1" } }, { "name": "respondWith", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x0f" } ] }, { "type": "string" } ], "default": "content" }, "description": "Specifies the (non-default) form of the crawled data you prefer.\n\nSupported formats: \n- markdown\n- html\n- text\n- pageshot\n- screenshot\n- content\n- frontmatter\n- any combination of the above\n- vlm\n- jina-ocr-v1\n- jina-ocr\n- readerlm-v2\n\nDefault: content" }, { "name": "withGeneratedAlt", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, "description": "Enable automatic alt-text generating for images without an meaningful alt-text.\n\nNote: Does not work when `X-Respond-With` is specified" }, { "name": "retainImages", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x11" } ], "default": "all" }, "description": "Image retention modes.\n\nSupported modes: \n- all: all images\n- none: no images\n- alt: only alt text\n- all_p: all images and with generated alt text\n- alt_p: only alt text and with generated alt" }, { "name": "retainMedia", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x12" } ], "default": "link" }, "description": "Media retention modes for video, audio, and embedded video iframes.\n\nSupported modes: \n- none: no media\n- text: plain label, e.g. `Video 1`\n- link: markdown link, e.g. `[Video 1](url)` (default)\n- image: markdown image syntax, e.g. `![Video 1](url)`\n- html: original HTML with irrelevant attributes (class, id, style, data-*, aria-*) stripped" }, { "name": "preset", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x13" } ] }, "description": "Apply a preset configuration for common scenarios.\n\nSupported presets:\n- reader: optimized for display to human users\n- index: optimized for semantic indexing\n- research: optimized for academic/research AI agents\n- agent: optimized for day-to-day AI agents\n- spider: optimized for recursive site crawling\n\nPreset values are applied only to options not explicitly set by the caller." }, { "name": "retainLinks", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x14" } ], "default": "all" }, "description": "Link retention modes.\n\nSupported modes: \n- all: all links\n- none: no links\n- text: only link text\n- gpt-oss: gpt-oss link citation format `【{id}†.*】`" }, { "name": "withLinksSummary", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, { "type": "string" } ] }, "description": "Enable dedicated summary section for hyper links on the page." }, { "name": "withImagesSummary", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Enable dedicated summary section for images on the page." }, { "name": "noCache", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Ignores internal cache if this header is specified with a value.\n\nEquivalent to X-Cache-Tolerance: 0" }, { "name": "removeOverlay", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Specify whether to remove overlay elements from the page." }, { "name": "detachInvisibles", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Temporarily detach elements with computed `display:none` before snapshotting, then restore them.\n\nRequires the browser engine and disables caching." }, { "name": "noGfm", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, { "type": "string" } ] }, "description": "Opt out of GitHub Flavored Markdown. `true` disables GFM; `table` drops only GFM tables and keeps the table HTML." }, { "name": "cacheTolerance", "in": "query", "schema": { "type": "number" }, "description": "Sets internal cache tolerance in seconds if this header is specified with a integer." }, { "name": "targetSelector", "in": "query", "schema": { "type": "string" }, "description": "Specifies a CSS selector for return target instead of the full html.\n\nImplies `X-Wait-For-Selector: (same selector)`" }, { "name": "waitForSelector", "in": "query", "schema": { "type": "string" }, "description": "Specifies a CSS selector to wait for the appearance of such an element before returning.\n\nExample: `X-Wait-For-Selector: .content-block`" }, { "name": "removeSelector", "in": "query", "schema": { "type": "string" }, "description": "Specifies a CSS selector to remove elements from the full html.\n\nExample `X-Remove-Selector: nav`" }, { "name": "keepImgDataUrl", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Keep data-url as it instead of transforming them to object-url. (Only applicable when targeting markdown format)\n\nExample `X-Keep-Img-Data-Url: true`" }, { "name": "withIframe", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, { "type": "string" } ] }, "description": "Enable filling iframe contents into main. (violates standards)" }, { "name": "withShadowDom", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Enable filling shadow dom contents into main. (violates standards)" }, { "name": "skipCertVerification", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Enable skipping SSL certificate verification. (violates security best practices)" }, { "name": "setCookies", "in": "query", "schema": { "oneOf": [ { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, { "type": "string" } ] }, "description": "Cookies to send when fetching the URL, for pages that need a login. Requests with cookies are not cached." }, { "name": "exportStorageState", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Export the browser storage state (cookies and per-origin localStorage) accumulated during the crawl.\n\nWhen enabled, the JSON response includes a `storageState` field whose shape mirrors the `storageState` request option, so it can be fed back into a subsequent request.\n\nRequires the browser engine and disables caching." }, { "name": "proxyUrl", "in": "query", "schema": { "type": "string" }, "description": "Specifies your custom proxy if you prefer to use one.\n\nSupported protocols: \n- http\n- https\n- socks4\n- socks5\n\nFor authentication, https://user:pass@host:port" }, { "name": "proxyResources", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Whether to load resources like image/style/scripts via the proxy server." }, { "name": "proxy", "in": "query", "schema": { "type": "string" }, "description": "Use a proxy server provided by us.\n\nOptionally specify two-letter country code." }, { "name": "userAgent", "in": "query", "schema": { "type": "string" }, "description": "Override User-Agent.\n\nSeveral special values: \n- browser: use the internal browser UA\n- auto: pass-through your UA if it starts with `Mozilla/5.0`, otherwise use the internal browser UA\n- inherit / pass-through: use the User-Agent from the request context if applicable\n- bot: Use a pre-defined bot User-Agent from this service\n- diversify: Use a diversified browser User-Agent\n\nOr specify your own user agent string.\n\nNote: anonymous users specifying a browser UA will have no effect and will fall back to the internal browser UA.\n\nDefault: browser" }, { "name": "engine", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x1a" } ] }, { "type": "string" } ] }, "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering" }, { "name": "injectPageScript", "in": "query", "schema": { "type": "string" }, "description": "JavaScript to run in the page before extraction, inline or as a URL, e.g. to change the DOM." }, { "name": "injectFrameScript", "in": "query", "schema": { "type": "string" }, "description": "Like `injectPageScript`, for frames." }, { "name": "timeout", "in": "query", "schema": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v > 0 && v <= 180" } }, { "name": "locale", "in": "query", "schema": { "type": "string" }, "description": "Specify browser locale for the page." }, { "name": "referer", "in": "query", "schema": { "type": "string" }, "description": "Specify referer for the page." }, { "name": "tokenBudget", "in": "query", "schema": { "type": "number" }, "description": "Specify a budget in tokens.\n\nIf the resulting token cost exceeds the budget, the request is rejected.\n\nNote this parameter is ignored for the search endpoint." }, { "name": "assertStatusCode", "in": "query", "schema": { "type": "number" }, "description": "Assert the HTTP status code of the crawled page. If the actual status code does not match the asserted one, the request is rejected with 422 Unprocessable Entity." }, { "name": "instruction", "in": "query", "schema": { "type": "string" } }, { "name": "jsonSchema", "in": "query", "schema": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true } }, { "name": "robotsTxt", "in": "query", "schema": { "type": "string" }, "description": "Load and conform to the respective robot.txt on the target origin.\n\nOptionally specify a bot UA to check against." }, { "name": "zeroDataRetention", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] } }, { "name": "respondTiming", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x24" } ] }, "description": "Explicitly specify the respond timing. One of the following:\n\n- html: directly return unrendered HTML\n- visible-content: return immediately when any content becomes available\n- mutation-idle: wait for DOM mutations to settle and remain unchanged for at least 0.2s\n- resource-idle: wait for no additional resources that would affect page logic and content has SUCCEEDED loading in 0.5s\n- media-idle: wait for no additional resources, including media resources, has SUCCEEDED loading in 0.5s\n- network-idle: wait for full load of webpage, also known as networkidle0." }, { "name": "markdownChunking", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x25" } ] }, { "type": "string" } ] }, "description": "Opt-in markdown chunking.\n\nSupported values: \n- true\n- h1\n- h2\n- h3\n- h4\n- h5\n- structured\n- s1\n- s2\n- s3\n- s4\n- s5\n\nNote if you are expecting text return, the chunking is done by injecting character \\u001D" }, { "name": "maxTokens", "in": "query", "schema": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v >= 500" } }, { "name": "Accept", "description": "Specifies your preference for the response format.\n\nSupported formats: \n- text/event-stream\n- application/json or text/json\n- text/plain", "in": "header", "schema": { "type": "string" } }, { "name": "X-Cache-Tolerance", "description": "Sets internal cache tolerance in seconds if this header is specified with a integer.", "in": "header", "schema": { "type": "string" } }, { "name": "X-No-Cache", "description": "Ignores internal cache if this header is specified with a value.\n\nEquivalent to X-Cache-Tolerance: 0", "in": "header", "schema": { "type": "string" } }, { "name": "X-Respond-With", "description": "Specifies the (non-default) form of the crawled data you prefer.\n\nSupported formats: \n- markdown\n- html\n- text\n- pageshot\n- screenshot\n- content\n- frontmatter\n- any combination of the above\n- vlm\n- jina-ocr-v1\n- jina-ocr\n- readerlm-v2\n\nDefault: content", "in": "header", "schema": { "type": "string" } }, { "name": "X-Wait-For-Selector", "description": "Specifies a CSS selector to wait for the appearance of such an element before returning.\n\nExample: `X-Wait-For-Selector: .content-block`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Target-Selector", "description": "Specifies a CSS selector for return target instead of the full html.\n\nImplies `X-Wait-For-Selector: (same selector)`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Remove-Selector", "description": "Specifies a CSS selector to remove elements from the full html.\n\nExample `X-Remove-Selector: nav`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Keep-Img-Data-Url", "description": "Keep data-url as it instead of transforming them to object-url. (Only applicable when targeting markdown format)\n\nExample `X-Keep-Img-Data-Url: true`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Proxy-Url", "description": "Specifies your custom proxy if you prefer to use one.\n\nSupported protocols: \n- http\n- https\n- socks4\n- socks5\n\nFor authentication, https://user:pass@host:port", "in": "header", "schema": { "type": "string" } }, { "name": "X-Proxy-Resources", "description": "Whether to load resources like image/style/scripts via the proxy server.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Proxy", "description": "Use a proxy server provided by us.\n\nOptionally specify two-letter country code.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Robots-Txt", "description": "Load and conform to the respective robot.txt on the target origin.\n\nOptionally specify a bot UA to check against.", "in": "header", "schema": { "type": "string" } }, { "name": "DNT", "description": "When set to 1, prevent the result of this request to be cached in the system.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Set-Cookie", "description": "Sets cookie(s) to the headless browser for your request. \n\nSyntax is the same with standard Set-Cookie", "in": "header", "schema": { "type": "string" } }, { "name": "X-Export-Storage-State", "description": "Export the browser storage state (cookies and per-origin localStorage) accumulated during the crawl.\n\nWhen enabled, the JSON response includes a `storageState` field whose shape mirrors the `storageState` request option, so it can be fed back into a subsequent request.\n\nRequires the browser engine and disables caching.", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Generated-Alt", "description": "Enable automatic alt-text generating for images without an meaningful alt-text.\n\nNote: Does not work when `X-Respond-With` is specified", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Images-Summary", "description": "Enable dedicated summary section for images on the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-links-Summary", "description": "Enable dedicated summary section for hyper links on the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Retain-Links", "description": "Link retention modes.\n\nSupported modes: \n- all: all links\n- none: no links\n- text: only link text\n- gpt-oss: gpt-oss link citation format `【{id}†.*】`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Retain-Images", "description": "Image retention modes.\n\nSupported modes: \n- all: all images\n- none: no images\n- alt: only alt text\n- all_p: all images and with generated alt text\n- alt_p: only alt text and with generated alt", "in": "header", "schema": { "type": "string" } }, { "name": "X-Retain-Media", "description": "Media retention modes for video, audio, and embedded video iframes.\n\nSupported modes: \n- none: no media\n- text: plain label, e.g. `Video 1`\n- link: markdown link, e.g. `[Video 1](url)` (default)\n- image: markdown image syntax, e.g. `![Video 1](url)`\n- html: original HTML with irrelevant attributes (class, id, style, data-*, aria-*) stripped", "in": "header", "schema": { "type": "string" } }, { "name": "X-Preset", "description": "Apply a preset configuration for common scenarios.\n\nSupported presets:\n- reader: optimized for display to human users\n- index: optimized for semantic indexing\n- research: optimized for academic/research AI agents\n- agent: optimized for day-to-day AI agents\n- spider: optimized for recursive site crawling\n\nPreset values are applied only to options not explicitly set by the caller.", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Iframe", "description": "Enable filling iframe contents into main. (violates standards)", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Shadow-Dom", "description": "Enable filling shadow dom contents into main. (violates standards)", "in": "header", "schema": { "type": "string" } }, { "name": "X-Skip-Cert-Verification", "description": "Enable skipping SSL certificate verification. (violates security best practices)", "in": "header", "schema": { "type": "string" } }, { "name": "X-User-Agent", "description": "Override User-Agent.\n\nSeveral special values: \n- browser: use the internal browser UA\n- auto: pass-through your UA if it starts with `Mozilla/5.0`, otherwise use the internal browser UA\n- inherit / pass-through: use the User-Agent from the request context if applicable\n- bot: Use a pre-defined bot User-Agent from this service\n- diversify: Use a diversified browser User-Agent\n\nOr specify your own user agent string.\n\nNote: anonymous users specifying a browser UA will have no effect and will fall back to the internal browser UA.\n\nDefault: browser", "in": "header", "schema": { "type": "string" } }, { "name": "X-Timeout", "description": "Specify timeout in seconds. Max 180.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Locale", "description": "Specify browser locale for the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Referer", "description": "Specify referer for the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Token-Budget", "description": "Specify a budget in tokens.\n\nIf the resulting token cost exceeds the budget, the request is rejected.\n\nNote this parameter is ignored for the search endpoint.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Max-Tokens", "description": "Trim the response content at a maximum number of tokens.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Assert-Status-Code", "description": "Assert the HTTP status code of the crawled page. If the actual status code does not match the asserted one, the request is rejected with 422 Unprocessable Entity.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Respond-Timing", "description": "Explicitly specify the respond timing. One of the following:\n\n- html: directly return unrendered HTML\n- visible-content: return immediately when any content becomes available\n- mutation-idle: wait for DOM mutations to settle and remain unchanged for at least 0.2s\n- resource-idle: wait for no additional resources that would affect page logic and content has SUCCEEDED loading in 0.5s\n- media-idle: wait for no additional resources, including media resources, has SUCCEEDED loading in 0.5s\n- network-idle: wait for full load of webpage, also known as networkidle0.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Engine", "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering", "in": "header", "schema": { "type": "string" } }, { "name": "X-Base", "description": "Select base modes of relative URLs.\n\nSupported: initial, final", "in": "header", "schema": { "type": "string" } }, { "name": "X-Remove-Overlay", "description": "Specify whether to remove overlay elements from the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Detach-Invisibles", "description": "Temporarily detach elements with computed `display:none` before snapshotting, then restore them.\n\nRequires the browser engine and disables caching.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Markdown-Chunking", "description": "Opt-in markdown chunking.\n\nSupported values: \n- true\n- h1\n- h2\n- h3\n- h4\n- h5\n- structured\n- s1\n- s2\n- s3\n- s4\n- s5\n\nNote if you are expecting text return, the chunking is done by injecting character \\u001D", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Heading-Style", "description": "Heading style of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: setext, atx", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Hr", "description": "Hr text of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Bullet-List-Marker", "description": "Bullet list marker of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: -, +, *", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Em-Delimiter", "description": "Em delimiter of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: _, *", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Strong-Delimiter", "description": "Strong delimiter of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: **, __", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Link-Style", "description": "Link style of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: inlined, referenced, discarded", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Link-Reference-Style", "description": "Link reference style of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: full, collapsed, shortcut, discarded", "in": "header", "schema": { "type": "string" } }, { "name": "X-Page", "description": "Steer which page to return for uploaded files (PDF, DOC, XLS, PPT, etc.).\n\n1-indexed; ignored when no file/PDF is uploaded.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Preload-Url", "description": "URL to preload before scraping.\n\nIgnored when no URL is provided.", "in": "header", "schema": { "type": "string" } }, { "name": "X-No-Service-Worker", "description": "Disable service workers when running the browser.\n\nUseful for bypassing service-worker-based caching or interception.", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "title": "ReaderEnvelopeWrappedString", "type": "object", "properties": { "code": { "type": "number", "summary": "Envelope code.\n\nMirror of HTTP status code", "description": "[REQUIRED]\n\nEnvelope code.\n\nMirror of HTTP status code", "default": 200 }, "status": { "type": "number", "summary": "Envelope status.\n\nIn extension to HTTP status code", "description": "[REQUIRED]\n\nEnvelope status.\n\nIn extension to HTTP status code", "default": 20000 }, "data": { "type": "string", "summary": "The result payload you expect", "description": "The result payload you expect" }, "meta": { "description": "The metadata that the payload sometimes came with", "nullable": true, "summary": "The metadata that the payload sometimes came with" } }, "required": [ "code", "status" ], "primitive": true }, { "title": "ReaderEnvelopeWrappedObject", "type": "object", "properties": { "code": { "type": "number", "summary": "Envelope code.\n\nMirror of HTTP status code", "description": "[REQUIRED]\n\nEnvelope code.\n\nMirror of HTTP status code", "default": 200 }, "status": { "type": "number", "summary": "Envelope status.\n\nIn extension to HTTP status code", "description": "[REQUIRED]\n\nEnvelope status.\n\nIn extension to HTTP status code", "default": 20000 }, "data": { "description": "The result payload you expect", "nullable": true, "summary": "The result payload you expect" }, "meta": { "description": "The metadata that the payload sometimes came with", "nullable": true, "summary": "The metadata that the payload sometimes came with" } }, "required": [ "code", "status" ], "primitive": true } ] } } }, "headers": {} }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_ParamValidationError@0x27" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_DataStreamBrokenError@0x28" } ] } ] } } }, "headers": {} }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_AuthenticationFailedError@0x29" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_AuthenticationRequiredError@0x2a" } ] } ] } } }, "headers": {} }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_TierFeatureConstraintError@0x2b" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_InsufficientBalanceError@0x2c" } ] } ] } } }, "headers": {} }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_OperationNotAllowedError@0x2d" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_AbuseAlleviationError@0x2e" } ] } ] } } }, "headers": {} }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_ResourcePolicyDenyError@0x2f" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_BudgetExceededError@0x30" } ] } ] } } }, "headers": {} }, "413": { "description": "Payload Too Large", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_TargetFileTooLargeError@0x31" } ] } } }, "headers": {} }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_SubmittedDataMalformedError@0x32" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_DownstreamServiceFailureError@0x33" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_AssertionFailureError@0x34" } ] } ] } } }, "headers": {} }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_RateLimitTriggeredError@0x35" } ] } } }, "headers": {} }, "451": { "description": "Unavailable For Legal Reasons", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_HarmfulContentError@0x36" } ] } } }, "headers": {} }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_DownstreamServiceError@0x37" } ] } } }, "headers": {} }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_ServiceNodeResourceDrainError@0x38" } ] } } }, "headers": {} } }, "summary": "getIndex", "operationId": "reader_get_root", "security": [ { "HTTPBearer": [] }, {} ], "x-scalar-ignore": true }, "post": { "tags": [ "Reader" ], "parameters": [ { "name": "url", "in": "query", "schema": { "type": "string" }, "description": "The URL to read. Not needed when the URL is already in the path (`https://r.jina.ai/`)." }, { "name": "preloadUrl", "in": "query", "schema": { "type": "string" }, "description": "URL to preload before scraping.\n\nIgnored when no URL is provided." }, { "name": "noServiceWorker", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Disable service workers when running the browser.\n\nUseful for bypassing service-worker-based caching or interception." }, { "name": "html", "in": "query", "schema": { "type": "string" }, "description": "Raw HTML to convert, instead of fetching a URL. Used when no `url` is given." }, { "name": "base", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x0d" } ], "default": "initial" }, "description": "Select base modes of relative URLs.\n\nSupported: initial, final" }, { "name": "pdf", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_FancyFile@0x0e" } ] }, { "type": "string" } ], "summary": "Base64 encoded PDF.", "description": "Base64 encoded PDF." } }, { "name": "file", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_FancyFile@0x0e" } ] }, { "type": "string" } ], "summary": "Base64 encoded file.", "description": "Base64 encoded file." }, "description": "Base64-encoded file (PDF, DOC, XLS, PPT, ...) to convert instead of a URL." }, { "name": "page", "in": "query", "schema": { "type": "number", "summary": "Steer which page to return for document files (1-indexed).", "description": "Steer which page to return for document files (1-indexed).\n\n- Some validators will be applied on value(s): (v) => Number.isInteger(v) && v >= 1" } }, { "name": "respondWith", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x0f" } ] }, { "type": "string" } ], "default": "content" }, "description": "Specifies the (non-default) form of the crawled data you prefer.\n\nSupported formats: \n- markdown\n- html\n- text\n- pageshot\n- screenshot\n- content\n- frontmatter\n- any combination of the above\n- vlm\n- jina-ocr-v1\n- jina-ocr\n- readerlm-v2\n\nDefault: content" }, { "name": "withGeneratedAlt", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, "description": "Enable automatic alt-text generating for images without an meaningful alt-text.\n\nNote: Does not work when `X-Respond-With` is specified" }, { "name": "retainImages", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x11" } ], "default": "all" }, "description": "Image retention modes.\n\nSupported modes: \n- all: all images\n- none: no images\n- alt: only alt text\n- all_p: all images and with generated alt text\n- alt_p: only alt text and with generated alt" }, { "name": "retainMedia", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x12" } ], "default": "link" }, "description": "Media retention modes for video, audio, and embedded video iframes.\n\nSupported modes: \n- none: no media\n- text: plain label, e.g. `Video 1`\n- link: markdown link, e.g. `[Video 1](url)` (default)\n- image: markdown image syntax, e.g. `![Video 1](url)`\n- html: original HTML with irrelevant attributes (class, id, style, data-*, aria-*) stripped" }, { "name": "preset", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x13" } ] }, "description": "Apply a preset configuration for common scenarios.\n\nSupported presets:\n- reader: optimized for display to human users\n- index: optimized for semantic indexing\n- research: optimized for academic/research AI agents\n- agent: optimized for day-to-day AI agents\n- spider: optimized for recursive site crawling\n\nPreset values are applied only to options not explicitly set by the caller." }, { "name": "retainLinks", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x14" } ], "default": "all" }, "description": "Link retention modes.\n\nSupported modes: \n- all: all links\n- none: no links\n- text: only link text\n- gpt-oss: gpt-oss link citation format `【{id}†.*】`" }, { "name": "withLinksSummary", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, { "type": "string" } ] }, "description": "Enable dedicated summary section for hyper links on the page." }, { "name": "withImagesSummary", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Enable dedicated summary section for images on the page." }, { "name": "noCache", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Ignores internal cache if this header is specified with a value.\n\nEquivalent to X-Cache-Tolerance: 0" }, { "name": "removeOverlay", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Specify whether to remove overlay elements from the page." }, { "name": "detachInvisibles", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Temporarily detach elements with computed `display:none` before snapshotting, then restore them.\n\nRequires the browser engine and disables caching." }, { "name": "noGfm", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, { "type": "string" } ] }, "description": "Opt out of GitHub Flavored Markdown. `true` disables GFM; `table` drops only GFM tables and keeps the table HTML." }, { "name": "cacheTolerance", "in": "query", "schema": { "type": "number" }, "description": "Sets internal cache tolerance in seconds if this header is specified with a integer." }, { "name": "targetSelector", "in": "query", "schema": { "type": "string" }, "description": "Specifies a CSS selector for return target instead of the full html.\n\nImplies `X-Wait-For-Selector: (same selector)`" }, { "name": "waitForSelector", "in": "query", "schema": { "type": "string" }, "description": "Specifies a CSS selector to wait for the appearance of such an element before returning.\n\nExample: `X-Wait-For-Selector: .content-block`" }, { "name": "removeSelector", "in": "query", "schema": { "type": "string" }, "description": "Specifies a CSS selector to remove elements from the full html.\n\nExample `X-Remove-Selector: nav`" }, { "name": "keepImgDataUrl", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Keep data-url as it instead of transforming them to object-url. (Only applicable when targeting markdown format)\n\nExample `X-Keep-Img-Data-Url: true`" }, { "name": "withIframe", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, { "type": "string" } ] }, "description": "Enable filling iframe contents into main. (violates standards)" }, { "name": "withShadowDom", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Enable filling shadow dom contents into main. (violates standards)" }, { "name": "skipCertVerification", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Enable skipping SSL certificate verification. (violates security best practices)" }, { "name": "setCookies", "in": "query", "schema": { "oneOf": [ { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, { "type": "string" } ] }, "description": "Cookies to send when fetching the URL, for pages that need a login. Requests with cookies are not cached." }, { "name": "exportStorageState", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Export the browser storage state (cookies and per-origin localStorage) accumulated during the crawl.\n\nWhen enabled, the JSON response includes a `storageState` field whose shape mirrors the `storageState` request option, so it can be fed back into a subsequent request.\n\nRequires the browser engine and disables caching." }, { "name": "proxyUrl", "in": "query", "schema": { "type": "string" }, "description": "Specifies your custom proxy if you prefer to use one.\n\nSupported protocols: \n- http\n- https\n- socks4\n- socks5\n\nFor authentication, https://user:pass@host:port" }, { "name": "proxyResources", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Whether to load resources like image/style/scripts via the proxy server." }, { "name": "proxy", "in": "query", "schema": { "type": "string" }, "description": "Use a proxy server provided by us.\n\nOptionally specify two-letter country code." }, { "name": "userAgent", "in": "query", "schema": { "type": "string" }, "description": "Override User-Agent.\n\nSeveral special values: \n- browser: use the internal browser UA\n- auto: pass-through your UA if it starts with `Mozilla/5.0`, otherwise use the internal browser UA\n- inherit / pass-through: use the User-Agent from the request context if applicable\n- bot: Use a pre-defined bot User-Agent from this service\n- diversify: Use a diversified browser User-Agent\n\nOr specify your own user agent string.\n\nNote: anonymous users specifying a browser UA will have no effect and will fall back to the internal browser UA.\n\nDefault: browser" }, { "name": "engine", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x1a" } ] }, { "type": "string" } ] }, "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering" }, { "name": "injectPageScript", "in": "query", "schema": { "type": "string" }, "description": "JavaScript to run in the page before extraction, inline or as a URL, e.g. to change the DOM." }, { "name": "injectFrameScript", "in": "query", "schema": { "type": "string" }, "description": "Like `injectPageScript`, for frames." }, { "name": "timeout", "in": "query", "schema": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v > 0 && v <= 180" } }, { "name": "locale", "in": "query", "schema": { "type": "string" }, "description": "Specify browser locale for the page." }, { "name": "referer", "in": "query", "schema": { "type": "string" }, "description": "Specify referer for the page." }, { "name": "tokenBudget", "in": "query", "schema": { "type": "number" }, "description": "Specify a budget in tokens.\n\nIf the resulting token cost exceeds the budget, the request is rejected.\n\nNote this parameter is ignored for the search endpoint." }, { "name": "assertStatusCode", "in": "query", "schema": { "type": "number" }, "description": "Assert the HTTP status code of the crawled page. If the actual status code does not match the asserted one, the request is rejected with 422 Unprocessable Entity." }, { "name": "instruction", "in": "query", "schema": { "type": "string" } }, { "name": "jsonSchema", "in": "query", "schema": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true } }, { "name": "robotsTxt", "in": "query", "schema": { "type": "string" }, "description": "Load and conform to the respective robot.txt on the target origin.\n\nOptionally specify a bot UA to check against." }, { "name": "zeroDataRetention", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] } }, { "name": "respondTiming", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x24" } ] }, "description": "Explicitly specify the respond timing. One of the following:\n\n- html: directly return unrendered HTML\n- visible-content: return immediately when any content becomes available\n- mutation-idle: wait for DOM mutations to settle and remain unchanged for at least 0.2s\n- resource-idle: wait for no additional resources that would affect page logic and content has SUCCEEDED loading in 0.5s\n- media-idle: wait for no additional resources, including media resources, has SUCCEEDED loading in 0.5s\n- network-idle: wait for full load of webpage, also known as networkidle0." }, { "name": "markdownChunking", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x25" } ] }, { "type": "string" } ] }, "description": "Opt-in markdown chunking.\n\nSupported values: \n- true\n- h1\n- h2\n- h3\n- h4\n- h5\n- structured\n- s1\n- s2\n- s3\n- s4\n- s5\n\nNote if you are expecting text return, the chunking is done by injecting character \\u001D" }, { "name": "maxTokens", "in": "query", "schema": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v >= 500" } }, { "name": "Accept", "description": "Specifies your preference for the response format.\n\nSupported formats: \n- text/event-stream\n- application/json or text/json\n- text/plain", "in": "header", "schema": { "type": "string" } }, { "name": "X-Cache-Tolerance", "description": "Sets internal cache tolerance in seconds if this header is specified with a integer.", "in": "header", "schema": { "type": "string" } }, { "name": "X-No-Cache", "description": "Ignores internal cache if this header is specified with a value.\n\nEquivalent to X-Cache-Tolerance: 0", "in": "header", "schema": { "type": "string" } }, { "name": "X-Respond-With", "description": "Specifies the (non-default) form of the crawled data you prefer.\n\nSupported formats: \n- markdown\n- html\n- text\n- pageshot\n- screenshot\n- content\n- frontmatter\n- any combination of the above\n- vlm\n- jina-ocr-v1\n- jina-ocr\n- readerlm-v2\n\nDefault: content", "in": "header", "schema": { "type": "string" } }, { "name": "X-Wait-For-Selector", "description": "Specifies a CSS selector to wait for the appearance of such an element before returning.\n\nExample: `X-Wait-For-Selector: .content-block`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Target-Selector", "description": "Specifies a CSS selector for return target instead of the full html.\n\nImplies `X-Wait-For-Selector: (same selector)`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Remove-Selector", "description": "Specifies a CSS selector to remove elements from the full html.\n\nExample `X-Remove-Selector: nav`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Keep-Img-Data-Url", "description": "Keep data-url as it instead of transforming them to object-url. (Only applicable when targeting markdown format)\n\nExample `X-Keep-Img-Data-Url: true`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Proxy-Url", "description": "Specifies your custom proxy if you prefer to use one.\n\nSupported protocols: \n- http\n- https\n- socks4\n- socks5\n\nFor authentication, https://user:pass@host:port", "in": "header", "schema": { "type": "string" } }, { "name": "X-Proxy-Resources", "description": "Whether to load resources like image/style/scripts via the proxy server.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Proxy", "description": "Use a proxy server provided by us.\n\nOptionally specify two-letter country code.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Robots-Txt", "description": "Load and conform to the respective robot.txt on the target origin.\n\nOptionally specify a bot UA to check against.", "in": "header", "schema": { "type": "string" } }, { "name": "DNT", "description": "When set to 1, prevent the result of this request to be cached in the system.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Set-Cookie", "description": "Sets cookie(s) to the headless browser for your request. \n\nSyntax is the same with standard Set-Cookie", "in": "header", "schema": { "type": "string" } }, { "name": "X-Export-Storage-State", "description": "Export the browser storage state (cookies and per-origin localStorage) accumulated during the crawl.\n\nWhen enabled, the JSON response includes a `storageState` field whose shape mirrors the `storageState` request option, so it can be fed back into a subsequent request.\n\nRequires the browser engine and disables caching.", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Generated-Alt", "description": "Enable automatic alt-text generating for images without an meaningful alt-text.\n\nNote: Does not work when `X-Respond-With` is specified", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Images-Summary", "description": "Enable dedicated summary section for images on the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-links-Summary", "description": "Enable dedicated summary section for hyper links on the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Retain-Links", "description": "Link retention modes.\n\nSupported modes: \n- all: all links\n- none: no links\n- text: only link text\n- gpt-oss: gpt-oss link citation format `【{id}†.*】`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Retain-Images", "description": "Image retention modes.\n\nSupported modes: \n- all: all images\n- none: no images\n- alt: only alt text\n- all_p: all images and with generated alt text\n- alt_p: only alt text and with generated alt", "in": "header", "schema": { "type": "string" } }, { "name": "X-Retain-Media", "description": "Media retention modes for video, audio, and embedded video iframes.\n\nSupported modes: \n- none: no media\n- text: plain label, e.g. `Video 1`\n- link: markdown link, e.g. `[Video 1](url)` (default)\n- image: markdown image syntax, e.g. `![Video 1](url)`\n- html: original HTML with irrelevant attributes (class, id, style, data-*, aria-*) stripped", "in": "header", "schema": { "type": "string" } }, { "name": "X-Preset", "description": "Apply a preset configuration for common scenarios.\n\nSupported presets:\n- reader: optimized for display to human users\n- index: optimized for semantic indexing\n- research: optimized for academic/research AI agents\n- agent: optimized for day-to-day AI agents\n- spider: optimized for recursive site crawling\n\nPreset values are applied only to options not explicitly set by the caller.", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Iframe", "description": "Enable filling iframe contents into main. (violates standards)", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Shadow-Dom", "description": "Enable filling shadow dom contents into main. (violates standards)", "in": "header", "schema": { "type": "string" } }, { "name": "X-Skip-Cert-Verification", "description": "Enable skipping SSL certificate verification. (violates security best practices)", "in": "header", "schema": { "type": "string" } }, { "name": "X-User-Agent", "description": "Override User-Agent.\n\nSeveral special values: \n- browser: use the internal browser UA\n- auto: pass-through your UA if it starts with `Mozilla/5.0`, otherwise use the internal browser UA\n- inherit / pass-through: use the User-Agent from the request context if applicable\n- bot: Use a pre-defined bot User-Agent from this service\n- diversify: Use a diversified browser User-Agent\n\nOr specify your own user agent string.\n\nNote: anonymous users specifying a browser UA will have no effect and will fall back to the internal browser UA.\n\nDefault: browser", "in": "header", "schema": { "type": "string" } }, { "name": "X-Timeout", "description": "Specify timeout in seconds. Max 180.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Locale", "description": "Specify browser locale for the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Referer", "description": "Specify referer for the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Token-Budget", "description": "Specify a budget in tokens.\n\nIf the resulting token cost exceeds the budget, the request is rejected.\n\nNote this parameter is ignored for the search endpoint.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Max-Tokens", "description": "Trim the response content at a maximum number of tokens.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Assert-Status-Code", "description": "Assert the HTTP status code of the crawled page. If the actual status code does not match the asserted one, the request is rejected with 422 Unprocessable Entity.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Respond-Timing", "description": "Explicitly specify the respond timing. One of the following:\n\n- html: directly return unrendered HTML\n- visible-content: return immediately when any content becomes available\n- mutation-idle: wait for DOM mutations to settle and remain unchanged for at least 0.2s\n- resource-idle: wait for no additional resources that would affect page logic and content has SUCCEEDED loading in 0.5s\n- media-idle: wait for no additional resources, including media resources, has SUCCEEDED loading in 0.5s\n- network-idle: wait for full load of webpage, also known as networkidle0.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Engine", "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering", "in": "header", "schema": { "type": "string" } }, { "name": "X-Base", "description": "Select base modes of relative URLs.\n\nSupported: initial, final", "in": "header", "schema": { "type": "string" } }, { "name": "X-Remove-Overlay", "description": "Specify whether to remove overlay elements from the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Detach-Invisibles", "description": "Temporarily detach elements with computed `display:none` before snapshotting, then restore them.\n\nRequires the browser engine and disables caching.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Markdown-Chunking", "description": "Opt-in markdown chunking.\n\nSupported values: \n- true\n- h1\n- h2\n- h3\n- h4\n- h5\n- structured\n- s1\n- s2\n- s3\n- s4\n- s5\n\nNote if you are expecting text return, the chunking is done by injecting character \\u001D", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Heading-Style", "description": "Heading style of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: setext, atx", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Hr", "description": "Hr text of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Bullet-List-Marker", "description": "Bullet list marker of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: -, +, *", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Em-Delimiter", "description": "Em delimiter of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: _, *", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Strong-Delimiter", "description": "Strong delimiter of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: **, __", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Link-Style", "description": "Link style of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: inlined, referenced, discarded", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Link-Reference-Style", "description": "Link reference style of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: full, collapsed, shortcut, discarded", "in": "header", "schema": { "type": "string" } }, { "name": "X-Page", "description": "Steer which page to return for uploaded files (PDF, DOC, XLS, PPT, etc.).\n\n1-indexed; ignored when no file/PDF is uploaded.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Preload-Url", "description": "URL to preload before scraping.\n\nIgnored when no URL is provided.", "in": "header", "schema": { "type": "string" } }, { "name": "X-No-Service-Worker", "description": "Disable service workers when running the browser.\n\nUseful for bypassing service-worker-based caching or interception.", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_JinaEmbeddingsAuthDTO@0x0b" }, { "$ref": "#/components/schemas/Reader_CrawlerOptionsHeaderOnly@0x39" }, { "$ref": "#/components/schemas/Reader_CrawlerOptions@0x26" } ] } }, "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_JinaEmbeddingsAuthDTO@0x0b" }, { "$ref": "#/components/schemas/Reader_CrawlerOptionsHeaderOnly@0x39" }, { "$ref": "#/components/schemas/Reader_CrawlerOptions@0x26" } ] } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL to read. Not needed when the URL is already in the path (`https://r.jina.ai/`)." }, "preloadUrl": { "type": "string", "description": "URL to preload before scraping.\n\nIgnored when no URL is provided." }, "noServiceWorker": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Disable service workers when running the browser.\n\nUseful for bypassing service-worker-based caching or interception." }, "html": { "type": "string", "description": "Raw HTML to convert, instead of fetching a URL. Used when no `url` is given." }, "base": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x0d" } ], "default": "initial", "description": "Select base modes of relative URLs.\n\nSupported: initial, final" }, "pdf": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_FancyFile@0x0e" } ] }, { "type": "string" } ], "summary": "Base64 encoded PDF.", "description": "Base64 encoded PDF." }, "file": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_FancyFile@0x0e" } ] }, { "type": "string" } ], "summary": "Base64 encoded file.", "description": "Base64-encoded file (PDF, DOC, XLS, PPT, ...) to convert instead of a URL." }, "page": { "type": "number", "summary": "Steer which page to return for document files (1-indexed).", "description": "Steer which page to return for document files (1-indexed).\n\n- Some validators will be applied on value(s): (v) => Number.isInteger(v) && v >= 1" }, "respondWith": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x0f" } ] }, { "type": "string" } ], "default": "content", "description": "Specifies the (non-default) form of the crawled data you prefer.\n\nSupported formats: \n- markdown\n- html\n- text\n- pageshot\n- screenshot\n- content\n- frontmatter\n- any combination of the above\n- vlm\n- jina-ocr-v1\n- jina-ocr\n- readerlm-v2\n\nDefault: content" }, "withGeneratedAlt": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ], "description": "Enable automatic alt-text generating for images without an meaningful alt-text.\n\nNote: Does not work when `X-Respond-With` is specified" }, "retainImages": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x11" } ], "default": "all", "description": "Image retention modes.\n\nSupported modes: \n- all: all images\n- none: no images\n- alt: only alt text\n- all_p: all images and with generated alt text\n- alt_p: only alt text and with generated alt" }, "retainMedia": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x12" } ], "default": "link", "description": "Media retention modes for video, audio, and embedded video iframes.\n\nSupported modes: \n- none: no media\n- text: plain label, e.g. `Video 1`\n- link: markdown link, e.g. `[Video 1](url)` (default)\n- image: markdown image syntax, e.g. `![Video 1](url)`\n- html: original HTML with irrelevant attributes (class, id, style, data-*, aria-*) stripped" }, "preset": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x13" } ], "description": "Apply a preset configuration for common scenarios.\n\nSupported presets:\n- reader: optimized for display to human users\n- index: optimized for semantic indexing\n- research: optimized for academic/research AI agents\n- agent: optimized for day-to-day AI agents\n- spider: optimized for recursive site crawling\n\nPreset values are applied only to options not explicitly set by the caller." }, "retainLinks": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x14" } ], "default": "all", "description": "Link retention modes.\n\nSupported modes: \n- all: all links\n- none: no links\n- text: only link text\n- gpt-oss: gpt-oss link citation format `【{id}†.*】`" }, "withLinksSummary": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, { "type": "string" } ], "description": "Enable dedicated summary section for hyper links on the page." }, "withImagesSummary": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Enable dedicated summary section for images on the page." }, "noCache": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Ignores internal cache if this header is specified with a value.\n\nEquivalent to X-Cache-Tolerance: 0" }, "removeOverlay": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Specify whether to remove overlay elements from the page." }, "detachInvisibles": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Temporarily detach elements with computed `display:none` before snapshotting, then restore them.\n\nRequires the browser engine and disables caching." }, "noGfm": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, { "type": "string" } ], "description": "Opt out of GitHub Flavored Markdown. `true` disables GFM; `table` drops only GFM tables and keeps the table HTML." }, "cacheTolerance": { "type": "number", "description": "Sets internal cache tolerance in seconds if this header is specified with a integer." }, "targetSelector": { "type": "string", "description": "Specifies a CSS selector for return target instead of the full html.\n\nImplies `X-Wait-For-Selector: (same selector)`" }, "waitForSelector": { "type": "string", "description": "Specifies a CSS selector to wait for the appearance of such an element before returning.\n\nExample: `X-Wait-For-Selector: .content-block`" }, "removeSelector": { "type": "string", "description": "Specifies a CSS selector to remove elements from the full html.\n\nExample `X-Remove-Selector: nav`" }, "keepImgDataUrl": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Keep data-url as it instead of transforming them to object-url. (Only applicable when targeting markdown format)\n\nExample `X-Keep-Img-Data-Url: true`" }, "withIframe": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, { "type": "string" } ], "description": "Enable filling iframe contents into main. (violates standards)" }, "withShadowDom": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Enable filling shadow dom contents into main. (violates standards)" }, "skipCertVerification": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Enable skipping SSL certificate verification. (violates security best practices)" }, "setCookies": { "oneOf": [ { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, { "type": "string" } ], "description": "Cookies to send when fetching the URL, for pages that need a login. Requests with cookies are not cached." }, "exportStorageState": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Export the browser storage state (cookies and per-origin localStorage) accumulated during the crawl.\n\nWhen enabled, the JSON response includes a `storageState` field whose shape mirrors the `storageState` request option, so it can be fed back into a subsequent request.\n\nRequires the browser engine and disables caching." }, "proxyUrl": { "type": "string", "description": "Specifies your custom proxy if you prefer to use one.\n\nSupported protocols: \n- http\n- https\n- socks4\n- socks5\n\nFor authentication, https://user:pass@host:port" }, "proxyResources": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Whether to load resources like image/style/scripts via the proxy server." }, "proxy": { "type": "string", "description": "Use a proxy server provided by us.\n\nOptionally specify two-letter country code." }, "userAgent": { "type": "string", "description": "Override User-Agent.\n\nSeveral special values: \n- browser: use the internal browser UA\n- auto: pass-through your UA if it starts with `Mozilla/5.0`, otherwise use the internal browser UA\n- inherit / pass-through: use the User-Agent from the request context if applicable\n- bot: Use a pre-defined bot User-Agent from this service\n- diversify: Use a diversified browser User-Agent\n\nOr specify your own user agent string.\n\nNote: anonymous users specifying a browser UA will have no effect and will fall back to the internal browser UA.\n\nDefault: browser" }, "engine": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x1a" } ] }, { "type": "string" } ], "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering" }, "injectPageScript": { "type": "string", "description": "JavaScript to run in the page before extraction, inline or as a URL, e.g. to change the DOM." }, "injectFrameScript": { "type": "string", "description": "Like `injectPageScript`, for frames." }, "timeout": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v > 0 && v <= 180" }, "locale": { "type": "string", "description": "Specify browser locale for the page." }, "referer": { "type": "string", "description": "Specify referer for the page." }, "tokenBudget": { "type": "number", "description": "Specify a budget in tokens.\n\nIf the resulting token cost exceeds the budget, the request is rejected.\n\nNote this parameter is ignored for the search endpoint." }, "assertStatusCode": { "type": "number", "description": "Assert the HTTP status code of the crawled page. If the actual status code does not match the asserted one, the request is rejected with 422 Unprocessable Entity." }, "instruction": { "type": "string" }, "jsonSchema": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "robotsTxt": { "type": "string", "description": "Load and conform to the respective robot.txt on the target origin.\n\nOptionally specify a bot UA to check against." }, "zeroDataRetention": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "respondTiming": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x24" } ], "description": "Explicitly specify the respond timing. One of the following:\n\n- html: directly return unrendered HTML\n- visible-content: return immediately when any content becomes available\n- mutation-idle: wait for DOM mutations to settle and remain unchanged for at least 0.2s\n- resource-idle: wait for no additional resources that would affect page logic and content has SUCCEEDED loading in 0.5s\n- media-idle: wait for no additional resources, including media resources, has SUCCEEDED loading in 0.5s\n- network-idle: wait for full load of webpage, also known as networkidle0." }, "markdownChunking": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x25" } ] }, { "type": "string" } ], "description": "Opt-in markdown chunking.\n\nSupported values: \n- true\n- h1\n- h2\n- h3\n- h4\n- h5\n- structured\n- s1\n- s2\n- s3\n- s4\n- s5\n\nNote if you are expecting text return, the chunking is done by injecting character \\u001D" }, "maxTokens": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v >= 500" } } } } } }, "responses": { "200": { "description": "OK", "content": { "text/plain; charset=utf-8": { "schema": { "type": "string" } }, "application/json": { "schema": { "title": "ReaderEnvelopeWrappedFormattedPageDto", "type": "object", "properties": { "code": { "type": "number", "summary": "Envelope code.\n\nMirror of HTTP status code", "description": "[REQUIRED]\n\nEnvelope code.\n\nMirror of HTTP status code", "default": 200 }, "status": { "type": "number", "summary": "Envelope status.\n\nIn extension to HTTP status code", "description": "[REQUIRED]\n\nEnvelope status.\n\nIn extension to HTTP status code", "default": 20000 }, "data": { "allOf": [ { "$ref": "#/components/schemas/Reader_FormattedPageDto@0x41" } ], "summary": "The result payload you expect", "description": "The result payload you expect" }, "meta": { "description": "The metadata that the payload sometimes came with", "nullable": true, "summary": "The metadata that the payload sometimes came with" } }, "required": [ "code", "status" ], "primitive": true } }, "text/event-stream": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_OutputServerEventStream@0x42" } ] } } }, "headers": {} }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_ParamValidationError@0x27" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_DataStreamBrokenError@0x28" } ] } ] } } }, "headers": {} }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_AuthenticationFailedError@0x29" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_AuthenticationRequiredError@0x2a" } ] } ] } } }, "headers": {} }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_TierFeatureConstraintError@0x2b" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_InsufficientBalanceError@0x2c" } ] } ] } } }, "headers": {} }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_OperationNotAllowedError@0x2d" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_AbuseAlleviationError@0x2e" } ] } ] } } }, "headers": {} }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_ResourcePolicyDenyError@0x2f" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_BudgetExceededError@0x30" } ] } ] } } }, "headers": {} }, "413": { "description": "Payload Too Large", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_TargetFileTooLargeError@0x31" } ] } } }, "headers": {} }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_SubmittedDataMalformedError@0x32" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_DownstreamServiceFailureError@0x33" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_AssertionFailureError@0x34" } ] } ] } } }, "headers": {} }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_RateLimitTriggeredError@0x35" } ] } } }, "headers": {} }, "451": { "description": "Unavailable For Legal Reasons", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_HarmfulContentError@0x36" } ] } } }, "headers": {} }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_DownstreamServiceError@0x37" } ] } } }, "headers": {} }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_ServiceNodeResourceDrainError@0x38" } ] } } }, "headers": {} } }, "summary": "Read a URL (JSON body)", "operationId": "reader_post_root", "security": [ { "HTTPBearer": [] }, {} ], "description": "Send `{\"url\": \"...\"}` as JSON, with the same `X-*` headers as the GET form.\n\n`Accept: application/json` returns JSON: the content is in `data.content`, and with `X-With-Links-Summary` / `X-With-Images-Summary` the links and images are in `data.links` and `data.images`. `Accept: text/event-stream` streams the result." }, "servers": [ { "url": "https://r.jina.ai" } ] }, "/{url}": { "get": { "tags": [ "Reader" ], "parameters": [ { "name": "url", "in": "path", "schema": { "type": "string" }, "required": true, "description": "The URL to read. Not needed when the URL is already in the path (`https://r.jina.ai/`)." }, { "name": "preloadUrl", "in": "query", "schema": { "type": "string" }, "description": "URL to preload before scraping.\n\nIgnored when no URL is provided." }, { "name": "noServiceWorker", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Disable service workers when running the browser.\n\nUseful for bypassing service-worker-based caching or interception." }, { "name": "html", "in": "query", "schema": { "type": "string" }, "description": "Raw HTML to convert, instead of fetching a URL. Used when no `url` is given." }, { "name": "base", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x0d" } ], "default": "initial" }, "description": "Select base modes of relative URLs.\n\nSupported: initial, final" }, { "name": "pdf", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_FancyFile@0x0e" } ] }, { "type": "string" } ], "summary": "Base64 encoded PDF.", "description": "Base64 encoded PDF." } }, { "name": "file", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_FancyFile@0x0e" } ] }, { "type": "string" } ], "summary": "Base64 encoded file.", "description": "Base64 encoded file." }, "description": "Base64-encoded file (PDF, DOC, XLS, PPT, ...) to convert instead of a URL." }, { "name": "page", "in": "query", "schema": { "type": "number", "summary": "Steer which page to return for document files (1-indexed).", "description": "Steer which page to return for document files (1-indexed).\n\n- Some validators will be applied on value(s): (v) => Number.isInteger(v) && v >= 1" } }, { "name": "respondWith", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x0f" } ] }, { "type": "string" } ], "default": "content" }, "description": "Specifies the (non-default) form of the crawled data you prefer.\n\nSupported formats: \n- markdown\n- html\n- text\n- pageshot\n- screenshot\n- content\n- frontmatter\n- any combination of the above\n- vlm\n- jina-ocr-v1\n- jina-ocr\n- readerlm-v2\n\nDefault: content" }, { "name": "withGeneratedAlt", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, "description": "Enable automatic alt-text generating for images without an meaningful alt-text.\n\nNote: Does not work when `X-Respond-With` is specified" }, { "name": "retainImages", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x11" } ], "default": "all" }, "description": "Image retention modes.\n\nSupported modes: \n- all: all images\n- none: no images\n- alt: only alt text\n- all_p: all images and with generated alt text\n- alt_p: only alt text and with generated alt" }, { "name": "retainMedia", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x12" } ], "default": "link" }, "description": "Media retention modes for video, audio, and embedded video iframes.\n\nSupported modes: \n- none: no media\n- text: plain label, e.g. `Video 1`\n- link: markdown link, e.g. `[Video 1](url)` (default)\n- image: markdown image syntax, e.g. `![Video 1](url)`\n- html: original HTML with irrelevant attributes (class, id, style, data-*, aria-*) stripped" }, { "name": "preset", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x13" } ] }, "description": "Apply a preset configuration for common scenarios.\n\nSupported presets:\n- reader: optimized for display to human users\n- index: optimized for semantic indexing\n- research: optimized for academic/research AI agents\n- agent: optimized for day-to-day AI agents\n- spider: optimized for recursive site crawling\n\nPreset values are applied only to options not explicitly set by the caller." }, { "name": "retainLinks", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x14" } ], "default": "all" }, "description": "Link retention modes.\n\nSupported modes: \n- all: all links\n- none: no links\n- text: only link text\n- gpt-oss: gpt-oss link citation format `【{id}†.*】`" }, { "name": "withLinksSummary", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, { "type": "string" } ] }, "description": "Enable dedicated summary section for hyper links on the page." }, { "name": "withImagesSummary", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Enable dedicated summary section for images on the page." }, { "name": "noCache", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Ignores internal cache if this header is specified with a value.\n\nEquivalent to X-Cache-Tolerance: 0" }, { "name": "removeOverlay", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Specify whether to remove overlay elements from the page." }, { "name": "detachInvisibles", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Temporarily detach elements with computed `display:none` before snapshotting, then restore them.\n\nRequires the browser engine and disables caching." }, { "name": "noGfm", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, { "type": "string" } ] }, "description": "Opt out of GitHub Flavored Markdown. `true` disables GFM; `table` drops only GFM tables and keeps the table HTML." }, { "name": "cacheTolerance", "in": "query", "schema": { "type": "number" }, "description": "Sets internal cache tolerance in seconds if this header is specified with a integer." }, { "name": "targetSelector", "in": "query", "schema": { "type": "string" }, "description": "Specifies a CSS selector for return target instead of the full html.\n\nImplies `X-Wait-For-Selector: (same selector)`" }, { "name": "waitForSelector", "in": "query", "schema": { "type": "string" }, "description": "Specifies a CSS selector to wait for the appearance of such an element before returning.\n\nExample: `X-Wait-For-Selector: .content-block`" }, { "name": "removeSelector", "in": "query", "schema": { "type": "string" }, "description": "Specifies a CSS selector to remove elements from the full html.\n\nExample `X-Remove-Selector: nav`" }, { "name": "keepImgDataUrl", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Keep data-url as it instead of transforming them to object-url. (Only applicable when targeting markdown format)\n\nExample `X-Keep-Img-Data-Url: true`" }, { "name": "withIframe", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, { "type": "string" } ] }, "description": "Enable filling iframe contents into main. (violates standards)" }, { "name": "withShadowDom", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Enable filling shadow dom contents into main. (violates standards)" }, { "name": "skipCertVerification", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Enable skipping SSL certificate verification. (violates security best practices)" }, { "name": "setCookies", "in": "query", "schema": { "oneOf": [ { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, { "type": "string" } ] }, "description": "Cookies to send when fetching the URL, for pages that need a login. Requests with cookies are not cached." }, { "name": "exportStorageState", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Export the browser storage state (cookies and per-origin localStorage) accumulated during the crawl.\n\nWhen enabled, the JSON response includes a `storageState` field whose shape mirrors the `storageState` request option, so it can be fed back into a subsequent request.\n\nRequires the browser engine and disables caching." }, { "name": "proxyUrl", "in": "query", "schema": { "type": "string" }, "description": "Specifies your custom proxy if you prefer to use one.\n\nSupported protocols: \n- http\n- https\n- socks4\n- socks5\n\nFor authentication, https://user:pass@host:port" }, { "name": "proxyResources", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Whether to load resources like image/style/scripts via the proxy server." }, { "name": "proxy", "in": "query", "schema": { "type": "string" }, "description": "Use a proxy server provided by us.\n\nOptionally specify two-letter country code." }, { "name": "userAgent", "in": "query", "schema": { "type": "string" }, "description": "Override User-Agent.\n\nSeveral special values: \n- browser: use the internal browser UA\n- auto: pass-through your UA if it starts with `Mozilla/5.0`, otherwise use the internal browser UA\n- inherit / pass-through: use the User-Agent from the request context if applicable\n- bot: Use a pre-defined bot User-Agent from this service\n- diversify: Use a diversified browser User-Agent\n\nOr specify your own user agent string.\n\nNote: anonymous users specifying a browser UA will have no effect and will fall back to the internal browser UA.\n\nDefault: browser" }, { "name": "engine", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x1a" } ] }, { "type": "string" } ] }, "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering" }, { "name": "injectPageScript", "in": "query", "schema": { "type": "string" }, "description": "JavaScript to run in the page before extraction, inline or as a URL, e.g. to change the DOM." }, { "name": "injectFrameScript", "in": "query", "schema": { "type": "string" }, "description": "Like `injectPageScript`, for frames." }, { "name": "timeout", "in": "query", "schema": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v > 0 && v <= 180" } }, { "name": "locale", "in": "query", "schema": { "type": "string" }, "description": "Specify browser locale for the page." }, { "name": "referer", "in": "query", "schema": { "type": "string" }, "description": "Specify referer for the page." }, { "name": "tokenBudget", "in": "query", "schema": { "type": "number" }, "description": "Specify a budget in tokens.\n\nIf the resulting token cost exceeds the budget, the request is rejected.\n\nNote this parameter is ignored for the search endpoint." }, { "name": "assertStatusCode", "in": "query", "schema": { "type": "number" }, "description": "Assert the HTTP status code of the crawled page. If the actual status code does not match the asserted one, the request is rejected with 422 Unprocessable Entity." }, { "name": "instruction", "in": "query", "schema": { "type": "string" } }, { "name": "jsonSchema", "in": "query", "schema": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true } }, { "name": "robotsTxt", "in": "query", "schema": { "type": "string" }, "description": "Load and conform to the respective robot.txt on the target origin.\n\nOptionally specify a bot UA to check against." }, { "name": "zeroDataRetention", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] } }, { "name": "respondTiming", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x24" } ] }, "description": "Explicitly specify the respond timing. One of the following:\n\n- html: directly return unrendered HTML\n- visible-content: return immediately when any content becomes available\n- mutation-idle: wait for DOM mutations to settle and remain unchanged for at least 0.2s\n- resource-idle: wait for no additional resources that would affect page logic and content has SUCCEEDED loading in 0.5s\n- media-idle: wait for no additional resources, including media resources, has SUCCEEDED loading in 0.5s\n- network-idle: wait for full load of webpage, also known as networkidle0." }, { "name": "markdownChunking", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x25" } ] }, { "type": "string" } ] }, "description": "Opt-in markdown chunking.\n\nSupported values: \n- true\n- h1\n- h2\n- h3\n- h4\n- h5\n- structured\n- s1\n- s2\n- s3\n- s4\n- s5\n\nNote if you are expecting text return, the chunking is done by injecting character \\u001D" }, { "name": "maxTokens", "in": "query", "schema": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v >= 500" } }, { "name": "Accept", "description": "Specifies your preference for the response format.\n\nSupported formats: \n- text/event-stream\n- application/json or text/json\n- text/plain", "in": "header", "schema": { "type": "string" } }, { "name": "X-Cache-Tolerance", "description": "Sets internal cache tolerance in seconds if this header is specified with a integer.", "in": "header", "schema": { "type": "string" } }, { "name": "X-No-Cache", "description": "Ignores internal cache if this header is specified with a value.\n\nEquivalent to X-Cache-Tolerance: 0", "in": "header", "schema": { "type": "string" } }, { "name": "X-Respond-With", "description": "Specifies the (non-default) form of the crawled data you prefer.\n\nSupported formats: \n- markdown\n- html\n- text\n- pageshot\n- screenshot\n- content\n- frontmatter\n- any combination of the above\n- vlm\n- jina-ocr-v1\n- jina-ocr\n- readerlm-v2\n\nDefault: content", "in": "header", "schema": { "type": "string" } }, { "name": "X-Wait-For-Selector", "description": "Specifies a CSS selector to wait for the appearance of such an element before returning.\n\nExample: `X-Wait-For-Selector: .content-block`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Target-Selector", "description": "Specifies a CSS selector for return target instead of the full html.\n\nImplies `X-Wait-For-Selector: (same selector)`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Remove-Selector", "description": "Specifies a CSS selector to remove elements from the full html.\n\nExample `X-Remove-Selector: nav`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Keep-Img-Data-Url", "description": "Keep data-url as it instead of transforming them to object-url. (Only applicable when targeting markdown format)\n\nExample `X-Keep-Img-Data-Url: true`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Proxy-Url", "description": "Specifies your custom proxy if you prefer to use one.\n\nSupported protocols: \n- http\n- https\n- socks4\n- socks5\n\nFor authentication, https://user:pass@host:port", "in": "header", "schema": { "type": "string" } }, { "name": "X-Proxy-Resources", "description": "Whether to load resources like image/style/scripts via the proxy server.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Proxy", "description": "Use a proxy server provided by us.\n\nOptionally specify two-letter country code.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Robots-Txt", "description": "Load and conform to the respective robot.txt on the target origin.\n\nOptionally specify a bot UA to check against.", "in": "header", "schema": { "type": "string" } }, { "name": "DNT", "description": "When set to 1, prevent the result of this request to be cached in the system.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Set-Cookie", "description": "Sets cookie(s) to the headless browser for your request. \n\nSyntax is the same with standard Set-Cookie", "in": "header", "schema": { "type": "string" } }, { "name": "X-Export-Storage-State", "description": "Export the browser storage state (cookies and per-origin localStorage) accumulated during the crawl.\n\nWhen enabled, the JSON response includes a `storageState` field whose shape mirrors the `storageState` request option, so it can be fed back into a subsequent request.\n\nRequires the browser engine and disables caching.", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Generated-Alt", "description": "Enable automatic alt-text generating for images without an meaningful alt-text.\n\nNote: Does not work when `X-Respond-With` is specified", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Images-Summary", "description": "Enable dedicated summary section for images on the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-links-Summary", "description": "Enable dedicated summary section for hyper links on the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Retain-Links", "description": "Link retention modes.\n\nSupported modes: \n- all: all links\n- none: no links\n- text: only link text\n- gpt-oss: gpt-oss link citation format `【{id}†.*】`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Retain-Images", "description": "Image retention modes.\n\nSupported modes: \n- all: all images\n- none: no images\n- alt: only alt text\n- all_p: all images and with generated alt text\n- alt_p: only alt text and with generated alt", "in": "header", "schema": { "type": "string" } }, { "name": "X-Retain-Media", "description": "Media retention modes for video, audio, and embedded video iframes.\n\nSupported modes: \n- none: no media\n- text: plain label, e.g. `Video 1`\n- link: markdown link, e.g. `[Video 1](url)` (default)\n- image: markdown image syntax, e.g. `![Video 1](url)`\n- html: original HTML with irrelevant attributes (class, id, style, data-*, aria-*) stripped", "in": "header", "schema": { "type": "string" } }, { "name": "X-Preset", "description": "Apply a preset configuration for common scenarios.\n\nSupported presets:\n- reader: optimized for display to human users\n- index: optimized for semantic indexing\n- research: optimized for academic/research AI agents\n- agent: optimized for day-to-day AI agents\n- spider: optimized for recursive site crawling\n\nPreset values are applied only to options not explicitly set by the caller.", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Iframe", "description": "Enable filling iframe contents into main. (violates standards)", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Shadow-Dom", "description": "Enable filling shadow dom contents into main. (violates standards)", "in": "header", "schema": { "type": "string" } }, { "name": "X-Skip-Cert-Verification", "description": "Enable skipping SSL certificate verification. (violates security best practices)", "in": "header", "schema": { "type": "string" } }, { "name": "X-User-Agent", "description": "Override User-Agent.\n\nSeveral special values: \n- browser: use the internal browser UA\n- auto: pass-through your UA if it starts with `Mozilla/5.0`, otherwise use the internal browser UA\n- inherit / pass-through: use the User-Agent from the request context if applicable\n- bot: Use a pre-defined bot User-Agent from this service\n- diversify: Use a diversified browser User-Agent\n\nOr specify your own user agent string.\n\nNote: anonymous users specifying a browser UA will have no effect and will fall back to the internal browser UA.\n\nDefault: browser", "in": "header", "schema": { "type": "string" } }, { "name": "X-Timeout", "description": "Specify timeout in seconds. Max 180.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Locale", "description": "Specify browser locale for the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Referer", "description": "Specify referer for the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Token-Budget", "description": "Specify a budget in tokens.\n\nIf the resulting token cost exceeds the budget, the request is rejected.\n\nNote this parameter is ignored for the search endpoint.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Max-Tokens", "description": "Trim the response content at a maximum number of tokens.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Assert-Status-Code", "description": "Assert the HTTP status code of the crawled page. If the actual status code does not match the asserted one, the request is rejected with 422 Unprocessable Entity.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Respond-Timing", "description": "Explicitly specify the respond timing. One of the following:\n\n- html: directly return unrendered HTML\n- visible-content: return immediately when any content becomes available\n- mutation-idle: wait for DOM mutations to settle and remain unchanged for at least 0.2s\n- resource-idle: wait for no additional resources that would affect page logic and content has SUCCEEDED loading in 0.5s\n- media-idle: wait for no additional resources, including media resources, has SUCCEEDED loading in 0.5s\n- network-idle: wait for full load of webpage, also known as networkidle0.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Engine", "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering", "in": "header", "schema": { "type": "string" } }, { "name": "X-Base", "description": "Select base modes of relative URLs.\n\nSupported: initial, final", "in": "header", "schema": { "type": "string" } }, { "name": "X-Remove-Overlay", "description": "Specify whether to remove overlay elements from the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Detach-Invisibles", "description": "Temporarily detach elements with computed `display:none` before snapshotting, then restore them.\n\nRequires the browser engine and disables caching.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Markdown-Chunking", "description": "Opt-in markdown chunking.\n\nSupported values: \n- true\n- h1\n- h2\n- h3\n- h4\n- h5\n- structured\n- s1\n- s2\n- s3\n- s4\n- s5\n\nNote if you are expecting text return, the chunking is done by injecting character \\u001D", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Heading-Style", "description": "Heading style of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: setext, atx", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Hr", "description": "Hr text of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Bullet-List-Marker", "description": "Bullet list marker of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: -, +, *", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Em-Delimiter", "description": "Em delimiter of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: _, *", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Strong-Delimiter", "description": "Strong delimiter of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: **, __", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Link-Style", "description": "Link style of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: inlined, referenced, discarded", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Link-Reference-Style", "description": "Link reference style of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: full, collapsed, shortcut, discarded", "in": "header", "schema": { "type": "string" } }, { "name": "X-Page", "description": "Steer which page to return for uploaded files (PDF, DOC, XLS, PPT, etc.).\n\n1-indexed; ignored when no file/PDF is uploaded.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Preload-Url", "description": "URL to preload before scraping.\n\nIgnored when no URL is provided.", "in": "header", "schema": { "type": "string" } }, { "name": "X-No-Service-Worker", "description": "Disable service workers when running the browser.\n\nUseful for bypassing service-worker-based caching or interception.", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain; charset=utf-8": { "schema": { "type": "string" } }, "application/json": { "schema": { "title": "ReaderEnvelopeWrappedFormattedPageDto", "type": "object", "properties": { "code": { "type": "number", "summary": "Envelope code.\n\nMirror of HTTP status code", "description": "[REQUIRED]\n\nEnvelope code.\n\nMirror of HTTP status code", "default": 200 }, "status": { "type": "number", "summary": "Envelope status.\n\nIn extension to HTTP status code", "description": "[REQUIRED]\n\nEnvelope status.\n\nIn extension to HTTP status code", "default": 20000 }, "data": { "allOf": [ { "$ref": "#/components/schemas/Reader_FormattedPageDto@0x41" } ], "summary": "The result payload you expect", "description": "The result payload you expect" }, "meta": { "description": "The metadata that the payload sometimes came with", "nullable": true, "summary": "The metadata that the payload sometimes came with" } }, "required": [ "code", "status" ], "primitive": true } }, "text/event-stream": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_OutputServerEventStream@0x42" } ] } } }, "headers": {} }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_ParamValidationError@0x27" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_DataStreamBrokenError@0x28" } ] } ] } } }, "headers": {} }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_AuthenticationFailedError@0x29" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_AuthenticationRequiredError@0x2a" } ] } ] } } }, "headers": {} }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_TierFeatureConstraintError@0x2b" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_InsufficientBalanceError@0x2c" } ] } ] } } }, "headers": {} }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_OperationNotAllowedError@0x2d" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_AbuseAlleviationError@0x2e" } ] } ] } } }, "headers": {} }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_ResourcePolicyDenyError@0x2f" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_BudgetExceededError@0x30" } ] } ] } } }, "headers": {} }, "413": { "description": "Payload Too Large", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_TargetFileTooLargeError@0x31" } ] } } }, "headers": {} }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_SubmittedDataMalformedError@0x32" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_DownstreamServiceFailureError@0x33" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_AssertionFailureError@0x34" } ] } ] } } }, "headers": {} }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_RateLimitTriggeredError@0x35" } ] } } }, "headers": {} }, "451": { "description": "Unavailable For Legal Reasons", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_HarmfulContentError@0x36" } ] } } }, "headers": {} }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_DownstreamServiceError@0x37" } ] } } }, "headers": {} }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_ServiceNodeResourceDrainError@0x38" } ] } } }, "headers": {} } }, "summary": "Read a URL", "operationId": "reader_get_url", "security": [ { "HTTPBearer": [] }, {} ], "description": "Put the target URL right after `https://r.jina.ai/`, e.g. `https://r.jina.ai/https://example.com`.\n\nReturns the page as LLM-friendly Markdown. Every option is an `X-*` header, or the query parameter of the same name." }, "post": { "tags": [ "Reader" ], "parameters": [ { "name": "url", "in": "path", "schema": { "type": "string" }, "required": true, "description": "The URL to read. Not needed when the URL is already in the path (`https://r.jina.ai/`)." }, { "name": "preloadUrl", "in": "query", "schema": { "type": "string" }, "description": "URL to preload before scraping.\n\nIgnored when no URL is provided." }, { "name": "noServiceWorker", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Disable service workers when running the browser.\n\nUseful for bypassing service-worker-based caching or interception." }, { "name": "html", "in": "query", "schema": { "type": "string" }, "description": "Raw HTML to convert, instead of fetching a URL. Used when no `url` is given." }, { "name": "base", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x0d" } ], "default": "initial" }, "description": "Select base modes of relative URLs.\n\nSupported: initial, final" }, { "name": "pdf", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_FancyFile@0x0e" } ] }, { "type": "string" } ], "summary": "Base64 encoded PDF.", "description": "Base64 encoded PDF." } }, { "name": "file", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_FancyFile@0x0e" } ] }, { "type": "string" } ], "summary": "Base64 encoded file.", "description": "Base64 encoded file." }, "description": "Base64-encoded file (PDF, DOC, XLS, PPT, ...) to convert instead of a URL." }, { "name": "page", "in": "query", "schema": { "type": "number", "summary": "Steer which page to return for document files (1-indexed).", "description": "Steer which page to return for document files (1-indexed).\n\n- Some validators will be applied on value(s): (v) => Number.isInteger(v) && v >= 1" } }, { "name": "respondWith", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x0f" } ] }, { "type": "string" } ], "default": "content" }, "description": "Specifies the (non-default) form of the crawled data you prefer.\n\nSupported formats: \n- markdown\n- html\n- text\n- pageshot\n- screenshot\n- content\n- frontmatter\n- any combination of the above\n- vlm\n- jina-ocr-v1\n- jina-ocr\n- readerlm-v2\n\nDefault: content" }, { "name": "withGeneratedAlt", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, "description": "Enable automatic alt-text generating for images without an meaningful alt-text.\n\nNote: Does not work when `X-Respond-With` is specified" }, { "name": "retainImages", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x11" } ], "default": "all" }, "description": "Image retention modes.\n\nSupported modes: \n- all: all images\n- none: no images\n- alt: only alt text\n- all_p: all images and with generated alt text\n- alt_p: only alt text and with generated alt" }, { "name": "retainMedia", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x12" } ], "default": "link" }, "description": "Media retention modes for video, audio, and embedded video iframes.\n\nSupported modes: \n- none: no media\n- text: plain label, e.g. `Video 1`\n- link: markdown link, e.g. `[Video 1](url)` (default)\n- image: markdown image syntax, e.g. `![Video 1](url)`\n- html: original HTML with irrelevant attributes (class, id, style, data-*, aria-*) stripped" }, { "name": "preset", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x13" } ] }, "description": "Apply a preset configuration for common scenarios.\n\nSupported presets:\n- reader: optimized for display to human users\n- index: optimized for semantic indexing\n- research: optimized for academic/research AI agents\n- agent: optimized for day-to-day AI agents\n- spider: optimized for recursive site crawling\n\nPreset values are applied only to options not explicitly set by the caller." }, { "name": "retainLinks", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x14" } ], "default": "all" }, "description": "Link retention modes.\n\nSupported modes: \n- all: all links\n- none: no links\n- text: only link text\n- gpt-oss: gpt-oss link citation format `【{id}†.*】`" }, { "name": "withLinksSummary", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, { "type": "string" } ] }, "description": "Enable dedicated summary section for hyper links on the page." }, { "name": "withImagesSummary", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Enable dedicated summary section for images on the page." }, { "name": "noCache", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Ignores internal cache if this header is specified with a value.\n\nEquivalent to X-Cache-Tolerance: 0" }, { "name": "removeOverlay", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Specify whether to remove overlay elements from the page." }, { "name": "detachInvisibles", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Temporarily detach elements with computed `display:none` before snapshotting, then restore them.\n\nRequires the browser engine and disables caching." }, { "name": "noGfm", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, { "type": "string" } ] }, "description": "Opt out of GitHub Flavored Markdown. `true` disables GFM; `table` drops only GFM tables and keeps the table HTML." }, { "name": "cacheTolerance", "in": "query", "schema": { "type": "number" }, "description": "Sets internal cache tolerance in seconds if this header is specified with a integer." }, { "name": "targetSelector", "in": "query", "schema": { "type": "string" }, "description": "Specifies a CSS selector for return target instead of the full html.\n\nImplies `X-Wait-For-Selector: (same selector)`" }, { "name": "waitForSelector", "in": "query", "schema": { "type": "string" }, "description": "Specifies a CSS selector to wait for the appearance of such an element before returning.\n\nExample: `X-Wait-For-Selector: .content-block`" }, { "name": "removeSelector", "in": "query", "schema": { "type": "string" }, "description": "Specifies a CSS selector to remove elements from the full html.\n\nExample `X-Remove-Selector: nav`" }, { "name": "keepImgDataUrl", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Keep data-url as it instead of transforming them to object-url. (Only applicable when targeting markdown format)\n\nExample `X-Keep-Img-Data-Url: true`" }, { "name": "withIframe", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, { "type": "string" } ] }, "description": "Enable filling iframe contents into main. (violates standards)" }, { "name": "withShadowDom", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Enable filling shadow dom contents into main. (violates standards)" }, { "name": "skipCertVerification", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Enable skipping SSL certificate verification. (violates security best practices)" }, { "name": "setCookies", "in": "query", "schema": { "oneOf": [ { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, { "type": "string" } ] }, "description": "Cookies to send when fetching the URL, for pages that need a login. Requests with cookies are not cached." }, { "name": "exportStorageState", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Export the browser storage state (cookies and per-origin localStorage) accumulated during the crawl.\n\nWhen enabled, the JSON response includes a `storageState` field whose shape mirrors the `storageState` request option, so it can be fed back into a subsequent request.\n\nRequires the browser engine and disables caching." }, { "name": "proxyUrl", "in": "query", "schema": { "type": "string" }, "description": "Specifies your custom proxy if you prefer to use one.\n\nSupported protocols: \n- http\n- https\n- socks4\n- socks5\n\nFor authentication, https://user:pass@host:port" }, { "name": "proxyResources", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "description": "Whether to load resources like image/style/scripts via the proxy server." }, { "name": "proxy", "in": "query", "schema": { "type": "string" }, "description": "Use a proxy server provided by us.\n\nOptionally specify two-letter country code." }, { "name": "userAgent", "in": "query", "schema": { "type": "string" }, "description": "Override User-Agent.\n\nSeveral special values: \n- browser: use the internal browser UA\n- auto: pass-through your UA if it starts with `Mozilla/5.0`, otherwise use the internal browser UA\n- inherit / pass-through: use the User-Agent from the request context if applicable\n- bot: Use a pre-defined bot User-Agent from this service\n- diversify: Use a diversified browser User-Agent\n\nOr specify your own user agent string.\n\nNote: anonymous users specifying a browser UA will have no effect and will fall back to the internal browser UA.\n\nDefault: browser" }, { "name": "engine", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x1a" } ] }, { "type": "string" } ] }, "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering" }, { "name": "injectPageScript", "in": "query", "schema": { "type": "string" }, "description": "JavaScript to run in the page before extraction, inline or as a URL, e.g. to change the DOM." }, { "name": "injectFrameScript", "in": "query", "schema": { "type": "string" }, "description": "Like `injectPageScript`, for frames." }, { "name": "timeout", "in": "query", "schema": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v > 0 && v <= 180" } }, { "name": "locale", "in": "query", "schema": { "type": "string" }, "description": "Specify browser locale for the page." }, { "name": "referer", "in": "query", "schema": { "type": "string" }, "description": "Specify referer for the page." }, { "name": "tokenBudget", "in": "query", "schema": { "type": "number" }, "description": "Specify a budget in tokens.\n\nIf the resulting token cost exceeds the budget, the request is rejected.\n\nNote this parameter is ignored for the search endpoint." }, { "name": "assertStatusCode", "in": "query", "schema": { "type": "number" }, "description": "Assert the HTTP status code of the crawled page. If the actual status code does not match the asserted one, the request is rejected with 422 Unprocessable Entity." }, { "name": "instruction", "in": "query", "schema": { "type": "string" } }, { "name": "jsonSchema", "in": "query", "schema": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true } }, { "name": "robotsTxt", "in": "query", "schema": { "type": "string" }, "description": "Load and conform to the respective robot.txt on the target origin.\n\nOptionally specify a bot UA to check against." }, { "name": "zeroDataRetention", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] } }, { "name": "respondTiming", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x24" } ] }, "description": "Explicitly specify the respond timing. One of the following:\n\n- html: directly return unrendered HTML\n- visible-content: return immediately when any content becomes available\n- mutation-idle: wait for DOM mutations to settle and remain unchanged for at least 0.2s\n- resource-idle: wait for no additional resources that would affect page logic and content has SUCCEEDED loading in 0.5s\n- media-idle: wait for no additional resources, including media resources, has SUCCEEDED loading in 0.5s\n- network-idle: wait for full load of webpage, also known as networkidle0." }, { "name": "markdownChunking", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x25" } ] }, { "type": "string" } ] }, "description": "Opt-in markdown chunking.\n\nSupported values: \n- true\n- h1\n- h2\n- h3\n- h4\n- h5\n- structured\n- s1\n- s2\n- s3\n- s4\n- s5\n\nNote if you are expecting text return, the chunking is done by injecting character \\u001D" }, { "name": "maxTokens", "in": "query", "schema": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v >= 500" } }, { "name": "Accept", "description": "Specifies your preference for the response format.\n\nSupported formats: \n- text/event-stream\n- application/json or text/json\n- text/plain", "in": "header", "schema": { "type": "string" } }, { "name": "X-Cache-Tolerance", "description": "Sets internal cache tolerance in seconds if this header is specified with a integer.", "in": "header", "schema": { "type": "string" } }, { "name": "X-No-Cache", "description": "Ignores internal cache if this header is specified with a value.\n\nEquivalent to X-Cache-Tolerance: 0", "in": "header", "schema": { "type": "string" } }, { "name": "X-Respond-With", "description": "Specifies the (non-default) form of the crawled data you prefer.\n\nSupported formats: \n- markdown\n- html\n- text\n- pageshot\n- screenshot\n- content\n- frontmatter\n- any combination of the above\n- vlm\n- jina-ocr-v1\n- jina-ocr\n- readerlm-v2\n\nDefault: content", "in": "header", "schema": { "type": "string" } }, { "name": "X-Wait-For-Selector", "description": "Specifies a CSS selector to wait for the appearance of such an element before returning.\n\nExample: `X-Wait-For-Selector: .content-block`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Target-Selector", "description": "Specifies a CSS selector for return target instead of the full html.\n\nImplies `X-Wait-For-Selector: (same selector)`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Remove-Selector", "description": "Specifies a CSS selector to remove elements from the full html.\n\nExample `X-Remove-Selector: nav`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Keep-Img-Data-Url", "description": "Keep data-url as it instead of transforming them to object-url. (Only applicable when targeting markdown format)\n\nExample `X-Keep-Img-Data-Url: true`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Proxy-Url", "description": "Specifies your custom proxy if you prefer to use one.\n\nSupported protocols: \n- http\n- https\n- socks4\n- socks5\n\nFor authentication, https://user:pass@host:port", "in": "header", "schema": { "type": "string" } }, { "name": "X-Proxy-Resources", "description": "Whether to load resources like image/style/scripts via the proxy server.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Proxy", "description": "Use a proxy server provided by us.\n\nOptionally specify two-letter country code.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Robots-Txt", "description": "Load and conform to the respective robot.txt on the target origin.\n\nOptionally specify a bot UA to check against.", "in": "header", "schema": { "type": "string" } }, { "name": "DNT", "description": "When set to 1, prevent the result of this request to be cached in the system.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Set-Cookie", "description": "Sets cookie(s) to the headless browser for your request. \n\nSyntax is the same with standard Set-Cookie", "in": "header", "schema": { "type": "string" } }, { "name": "X-Export-Storage-State", "description": "Export the browser storage state (cookies and per-origin localStorage) accumulated during the crawl.\n\nWhen enabled, the JSON response includes a `storageState` field whose shape mirrors the `storageState` request option, so it can be fed back into a subsequent request.\n\nRequires the browser engine and disables caching.", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Generated-Alt", "description": "Enable automatic alt-text generating for images without an meaningful alt-text.\n\nNote: Does not work when `X-Respond-With` is specified", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Images-Summary", "description": "Enable dedicated summary section for images on the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-links-Summary", "description": "Enable dedicated summary section for hyper links on the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Retain-Links", "description": "Link retention modes.\n\nSupported modes: \n- all: all links\n- none: no links\n- text: only link text\n- gpt-oss: gpt-oss link citation format `【{id}†.*】`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Retain-Images", "description": "Image retention modes.\n\nSupported modes: \n- all: all images\n- none: no images\n- alt: only alt text\n- all_p: all images and with generated alt text\n- alt_p: only alt text and with generated alt", "in": "header", "schema": { "type": "string" } }, { "name": "X-Retain-Media", "description": "Media retention modes for video, audio, and embedded video iframes.\n\nSupported modes: \n- none: no media\n- text: plain label, e.g. `Video 1`\n- link: markdown link, e.g. `[Video 1](url)` (default)\n- image: markdown image syntax, e.g. `![Video 1](url)`\n- html: original HTML with irrelevant attributes (class, id, style, data-*, aria-*) stripped", "in": "header", "schema": { "type": "string" } }, { "name": "X-Preset", "description": "Apply a preset configuration for common scenarios.\n\nSupported presets:\n- reader: optimized for display to human users\n- index: optimized for semantic indexing\n- research: optimized for academic/research AI agents\n- agent: optimized for day-to-day AI agents\n- spider: optimized for recursive site crawling\n\nPreset values are applied only to options not explicitly set by the caller.", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Iframe", "description": "Enable filling iframe contents into main. (violates standards)", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Shadow-Dom", "description": "Enable filling shadow dom contents into main. (violates standards)", "in": "header", "schema": { "type": "string" } }, { "name": "X-Skip-Cert-Verification", "description": "Enable skipping SSL certificate verification. (violates security best practices)", "in": "header", "schema": { "type": "string" } }, { "name": "X-User-Agent", "description": "Override User-Agent.\n\nSeveral special values: \n- browser: use the internal browser UA\n- auto: pass-through your UA if it starts with `Mozilla/5.0`, otherwise use the internal browser UA\n- inherit / pass-through: use the User-Agent from the request context if applicable\n- bot: Use a pre-defined bot User-Agent from this service\n- diversify: Use a diversified browser User-Agent\n\nOr specify your own user agent string.\n\nNote: anonymous users specifying a browser UA will have no effect and will fall back to the internal browser UA.\n\nDefault: browser", "in": "header", "schema": { "type": "string" } }, { "name": "X-Timeout", "description": "Specify timeout in seconds. Max 180.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Locale", "description": "Specify browser locale for the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Referer", "description": "Specify referer for the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Token-Budget", "description": "Specify a budget in tokens.\n\nIf the resulting token cost exceeds the budget, the request is rejected.\n\nNote this parameter is ignored for the search endpoint.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Max-Tokens", "description": "Trim the response content at a maximum number of tokens.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Assert-Status-Code", "description": "Assert the HTTP status code of the crawled page. If the actual status code does not match the asserted one, the request is rejected with 422 Unprocessable Entity.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Respond-Timing", "description": "Explicitly specify the respond timing. One of the following:\n\n- html: directly return unrendered HTML\n- visible-content: return immediately when any content becomes available\n- mutation-idle: wait for DOM mutations to settle and remain unchanged for at least 0.2s\n- resource-idle: wait for no additional resources that would affect page logic and content has SUCCEEDED loading in 0.5s\n- media-idle: wait for no additional resources, including media resources, has SUCCEEDED loading in 0.5s\n- network-idle: wait for full load of webpage, also known as networkidle0.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Engine", "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering", "in": "header", "schema": { "type": "string" } }, { "name": "X-Base", "description": "Select base modes of relative URLs.\n\nSupported: initial, final", "in": "header", "schema": { "type": "string" } }, { "name": "X-Remove-Overlay", "description": "Specify whether to remove overlay elements from the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Detach-Invisibles", "description": "Temporarily detach elements with computed `display:none` before snapshotting, then restore them.\n\nRequires the browser engine and disables caching.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Markdown-Chunking", "description": "Opt-in markdown chunking.\n\nSupported values: \n- true\n- h1\n- h2\n- h3\n- h4\n- h5\n- structured\n- s1\n- s2\n- s3\n- s4\n- s5\n\nNote if you are expecting text return, the chunking is done by injecting character \\u001D", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Heading-Style", "description": "Heading style of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: setext, atx", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Hr", "description": "Hr text of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Bullet-List-Marker", "description": "Bullet list marker of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: -, +, *", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Em-Delimiter", "description": "Em delimiter of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: _, *", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Strong-Delimiter", "description": "Strong delimiter of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: **, __", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Link-Style", "description": "Link style of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: inlined, referenced, discarded", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Link-Reference-Style", "description": "Link reference style of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: full, collapsed, shortcut, discarded", "in": "header", "schema": { "type": "string" } }, { "name": "X-Page", "description": "Steer which page to return for uploaded files (PDF, DOC, XLS, PPT, etc.).\n\n1-indexed; ignored when no file/PDF is uploaded.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Preload-Url", "description": "URL to preload before scraping.\n\nIgnored when no URL is provided.", "in": "header", "schema": { "type": "string" } }, { "name": "X-No-Service-Worker", "description": "Disable service workers when running the browser.\n\nUseful for bypassing service-worker-based caching or interception.", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_JinaEmbeddingsAuthDTO@0x0b" }, { "$ref": "#/components/schemas/Reader_CrawlerOptionsHeaderOnly@0x39" }, { "$ref": "#/components/schemas/Reader_CrawlerOptions@0x26" } ] } }, "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_JinaEmbeddingsAuthDTO@0x0b" }, { "$ref": "#/components/schemas/Reader_CrawlerOptionsHeaderOnly@0x39" }, { "$ref": "#/components/schemas/Reader_CrawlerOptions@0x26" } ] } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL to read. Not needed when the URL is already in the path (`https://r.jina.ai/`)." }, "preloadUrl": { "type": "string", "description": "URL to preload before scraping.\n\nIgnored when no URL is provided." }, "noServiceWorker": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Disable service workers when running the browser.\n\nUseful for bypassing service-worker-based caching or interception." }, "html": { "type": "string", "description": "Raw HTML to convert, instead of fetching a URL. Used when no `url` is given." }, "base": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x0d" } ], "default": "initial", "description": "Select base modes of relative URLs.\n\nSupported: initial, final" }, "pdf": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_FancyFile@0x0e" } ] }, { "type": "string" } ], "summary": "Base64 encoded PDF.", "description": "Base64 encoded PDF." }, "file": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_FancyFile@0x0e" } ] }, { "type": "string" } ], "summary": "Base64 encoded file.", "description": "Base64-encoded file (PDF, DOC, XLS, PPT, ...) to convert instead of a URL." }, "page": { "type": "number", "summary": "Steer which page to return for document files (1-indexed).", "description": "Steer which page to return for document files (1-indexed).\n\n- Some validators will be applied on value(s): (v) => Number.isInteger(v) && v >= 1" }, "respondWith": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x0f" } ] }, { "type": "string" } ], "default": "content", "description": "Specifies the (non-default) form of the crawled data you prefer.\n\nSupported formats: \n- markdown\n- html\n- text\n- pageshot\n- screenshot\n- content\n- frontmatter\n- any combination of the above\n- vlm\n- jina-ocr-v1\n- jina-ocr\n- readerlm-v2\n\nDefault: content" }, "withGeneratedAlt": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ], "description": "Enable automatic alt-text generating for images without an meaningful alt-text.\n\nNote: Does not work when `X-Respond-With` is specified" }, "retainImages": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x11" } ], "default": "all", "description": "Image retention modes.\n\nSupported modes: \n- all: all images\n- none: no images\n- alt: only alt text\n- all_p: all images and with generated alt text\n- alt_p: only alt text and with generated alt" }, "retainMedia": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x12" } ], "default": "link", "description": "Media retention modes for video, audio, and embedded video iframes.\n\nSupported modes: \n- none: no media\n- text: plain label, e.g. `Video 1`\n- link: markdown link, e.g. `[Video 1](url)` (default)\n- image: markdown image syntax, e.g. `![Video 1](url)`\n- html: original HTML with irrelevant attributes (class, id, style, data-*, aria-*) stripped" }, "preset": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x13" } ], "description": "Apply a preset configuration for common scenarios.\n\nSupported presets:\n- reader: optimized for display to human users\n- index: optimized for semantic indexing\n- research: optimized for academic/research AI agents\n- agent: optimized for day-to-day AI agents\n- spider: optimized for recursive site crawling\n\nPreset values are applied only to options not explicitly set by the caller." }, "retainLinks": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x14" } ], "default": "all", "description": "Link retention modes.\n\nSupported modes: \n- all: all links\n- none: no links\n- text: only link text\n- gpt-oss: gpt-oss link citation format `【{id}†.*】`" }, "withLinksSummary": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, { "type": "string" } ], "description": "Enable dedicated summary section for hyper links on the page." }, "withImagesSummary": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Enable dedicated summary section for images on the page." }, "noCache": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Ignores internal cache if this header is specified with a value.\n\nEquivalent to X-Cache-Tolerance: 0" }, "removeOverlay": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Specify whether to remove overlay elements from the page." }, "detachInvisibles": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Temporarily detach elements with computed `display:none` before snapshotting, then restore them.\n\nRequires the browser engine and disables caching." }, "noGfm": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, { "type": "string" } ], "description": "Opt out of GitHub Flavored Markdown. `true` disables GFM; `table` drops only GFM tables and keeps the table HTML." }, "cacheTolerance": { "type": "number", "description": "Sets internal cache tolerance in seconds if this header is specified with a integer." }, "targetSelector": { "type": "string", "description": "Specifies a CSS selector for return target instead of the full html.\n\nImplies `X-Wait-For-Selector: (same selector)`" }, "waitForSelector": { "type": "string", "description": "Specifies a CSS selector to wait for the appearance of such an element before returning.\n\nExample: `X-Wait-For-Selector: .content-block`" }, "removeSelector": { "type": "string", "description": "Specifies a CSS selector to remove elements from the full html.\n\nExample `X-Remove-Selector: nav`" }, "keepImgDataUrl": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Keep data-url as it instead of transforming them to object-url. (Only applicable when targeting markdown format)\n\nExample `X-Keep-Img-Data-Url: true`" }, "withIframe": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, { "type": "string" } ], "description": "Enable filling iframe contents into main. (violates standards)" }, "withShadowDom": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Enable filling shadow dom contents into main. (violates standards)" }, "skipCertVerification": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Enable skipping SSL certificate verification. (violates security best practices)" }, "setCookies": { "oneOf": [ { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, { "type": "string" } ], "description": "Cookies to send when fetching the URL, for pages that need a login. Requests with cookies are not cached." }, "exportStorageState": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Export the browser storage state (cookies and per-origin localStorage) accumulated during the crawl.\n\nWhen enabled, the JSON response includes a `storageState` field whose shape mirrors the `storageState` request option, so it can be fed back into a subsequent request.\n\nRequires the browser engine and disables caching." }, "proxyUrl": { "type": "string", "description": "Specifies your custom proxy if you prefer to use one.\n\nSupported protocols: \n- http\n- https\n- socks4\n- socks5\n\nFor authentication, https://user:pass@host:port" }, "proxyResources": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Whether to load resources like image/style/scripts via the proxy server." }, "proxy": { "type": "string", "description": "Use a proxy server provided by us.\n\nOptionally specify two-letter country code." }, "userAgent": { "type": "string", "description": "Override User-Agent.\n\nSeveral special values: \n- browser: use the internal browser UA\n- auto: pass-through your UA if it starts with `Mozilla/5.0`, otherwise use the internal browser UA\n- inherit / pass-through: use the User-Agent from the request context if applicable\n- bot: Use a pre-defined bot User-Agent from this service\n- diversify: Use a diversified browser User-Agent\n\nOr specify your own user agent string.\n\nNote: anonymous users specifying a browser UA will have no effect and will fall back to the internal browser UA.\n\nDefault: browser" }, "engine": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x1a" } ] }, { "type": "string" } ], "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering" }, "injectPageScript": { "type": "string", "description": "JavaScript to run in the page before extraction, inline or as a URL, e.g. to change the DOM." }, "injectFrameScript": { "type": "string", "description": "Like `injectPageScript`, for frames." }, "timeout": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v > 0 && v <= 180" }, "locale": { "type": "string", "description": "Specify browser locale for the page." }, "referer": { "type": "string", "description": "Specify referer for the page." }, "tokenBudget": { "type": "number", "description": "Specify a budget in tokens.\n\nIf the resulting token cost exceeds the budget, the request is rejected.\n\nNote this parameter is ignored for the search endpoint." }, "assertStatusCode": { "type": "number", "description": "Assert the HTTP status code of the crawled page. If the actual status code does not match the asserted one, the request is rejected with 422 Unprocessable Entity." }, "instruction": { "type": "string" }, "jsonSchema": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "robotsTxt": { "type": "string", "description": "Load and conform to the respective robot.txt on the target origin.\n\nOptionally specify a bot UA to check against." }, "zeroDataRetention": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "respondTiming": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x24" } ], "description": "Explicitly specify the respond timing. One of the following:\n\n- html: directly return unrendered HTML\n- visible-content: return immediately when any content becomes available\n- mutation-idle: wait for DOM mutations to settle and remain unchanged for at least 0.2s\n- resource-idle: wait for no additional resources that would affect page logic and content has SUCCEEDED loading in 0.5s\n- media-idle: wait for no additional resources, including media resources, has SUCCEEDED loading in 0.5s\n- network-idle: wait for full load of webpage, also known as networkidle0." }, "markdownChunking": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x25" } ] }, { "type": "string" } ], "description": "Opt-in markdown chunking.\n\nSupported values: \n- true\n- h1\n- h2\n- h3\n- h4\n- h5\n- structured\n- s1\n- s2\n- s3\n- s4\n- s5\n\nNote if you are expecting text return, the chunking is done by injecting character \\u001D" }, "maxTokens": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v >= 500" } } } } } }, "responses": { "200": { "description": "OK", "content": { "text/plain; charset=utf-8": { "schema": { "type": "string" } }, "application/json": { "schema": { "title": "ReaderEnvelopeWrappedFormattedPageDto", "type": "object", "properties": { "code": { "type": "number", "summary": "Envelope code.\n\nMirror of HTTP status code", "description": "[REQUIRED]\n\nEnvelope code.\n\nMirror of HTTP status code", "default": 200 }, "status": { "type": "number", "summary": "Envelope status.\n\nIn extension to HTTP status code", "description": "[REQUIRED]\n\nEnvelope status.\n\nIn extension to HTTP status code", "default": 20000 }, "data": { "allOf": [ { "$ref": "#/components/schemas/Reader_FormattedPageDto@0x41" } ], "summary": "The result payload you expect", "description": "The result payload you expect" }, "meta": { "description": "The metadata that the payload sometimes came with", "nullable": true, "summary": "The metadata that the payload sometimes came with" } }, "required": [ "code", "status" ], "primitive": true } }, "text/event-stream": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_OutputServerEventStream@0x42" } ] } } }, "headers": {} }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_ParamValidationError@0x27" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_DataStreamBrokenError@0x28" } ] } ] } } }, "headers": {} }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_AuthenticationFailedError@0x29" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_AuthenticationRequiredError@0x2a" } ] } ] } } }, "headers": {} }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_TierFeatureConstraintError@0x2b" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_InsufficientBalanceError@0x2c" } ] } ] } } }, "headers": {} }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_OperationNotAllowedError@0x2d" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_AbuseAlleviationError@0x2e" } ] } ] } } }, "headers": {} }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_ResourcePolicyDenyError@0x2f" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_BudgetExceededError@0x30" } ] } ] } } }, "headers": {} }, "413": { "description": "Payload Too Large", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_TargetFileTooLargeError@0x31" } ] } } }, "headers": {} }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_SubmittedDataMalformedError@0x32" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_DownstreamServiceFailureError@0x33" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_AssertionFailureError@0x34" } ] } ] } } }, "headers": {} }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_RateLimitTriggeredError@0x35" } ] } } }, "headers": {} }, "451": { "description": "Unavailable For Legal Reasons", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_HarmfulContentError@0x36" } ] } } }, "headers": {} }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_DownstreamServiceError@0x37" } ] } } }, "headers": {} }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_ServiceNodeResourceDrainError@0x38" } ] } } }, "headers": {} } }, "summary": "crawl", "operationId": "reader_post_url", "security": [ { "HTTPBearer": [] }, {} ], "x-scalar-ignore": true }, "servers": [ { "url": "https://r.jina.ai" } ] }, "/ephemeral/{encodedFid}": { "get": { "tags": [ "Reader" ], "parameters": [ { "name": "encodedFid", "in": "path", "schema": { "type": "string", "description": "[REQUIRED]" }, "required": true }, { "name": "t", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "[REQUIRED]" } }, { "name": "s", "in": "query", "schema": { "type": "string", "description": "[REQUIRED]" } }, { "name": "crop", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "title": "ReaderEnvelopeWrappedPromise", "type": "object", "properties": { "code": { "type": "number", "summary": "Envelope code.\n\nMirror of HTTP status code", "description": "[REQUIRED]\n\nEnvelope code.\n\nMirror of HTTP status code", "default": 200 }, "status": { "type": "number", "summary": "Envelope status.\n\nIn extension to HTTP status code", "description": "[REQUIRED]\n\nEnvelope status.\n\nIn extension to HTTP status code", "default": 20000 }, "data": { "description": "The result payload you expect", "nullable": true, "summary": "The result payload you expect" }, "meta": { "description": "The metadata that the payload sometimes came with", "nullable": true, "summary": "The metadata that the payload sometimes came with" } }, "required": [ "code", "status" ], "primitive": true } } }, "headers": {} }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_AuthenticationRequiredError@0x2a" } ] } } }, "headers": {} }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_OperationNotAllowedError@0x2d" } ] } } }, "headers": {} }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_ResourceNotFoundError@0x43" } ] } } }, "headers": {} } }, "summary": "getEphemeral", "operationId": "reader_get_ephemeral_encodedFid", "x-scalar-ignore": true }, "post": { "tags": [ "Reader" ], "parameters": [ { "name": "encodedFid", "in": "path", "schema": { "type": "string", "description": "[REQUIRED]" }, "required": true }, { "name": "t", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "[REQUIRED]" } }, { "name": "s", "in": "query", "schema": { "type": "string", "description": "[REQUIRED]" } }, { "name": "crop", "in": "query", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "encodedFid": { "type": "string", "description": "[REQUIRED]" }, "t": { "type": "string", "format": "date-time", "description": "[REQUIRED]" }, "s": { "type": "string", "description": "[REQUIRED]" }, "crop": { "type": "string" } }, "required": [ "encodedFid", "t", "s" ] } ] } }, "multipart/form-data": { "schema": { "allOf": [ { "type": "object", "properties": { "encodedFid": { "type": "string", "description": "[REQUIRED]" }, "t": { "type": "string", "format": "date-time", "description": "[REQUIRED]" }, "s": { "type": "string", "description": "[REQUIRED]" }, "crop": { "type": "string" } }, "required": [ "encodedFid", "t", "s" ] } ] } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "encodedFid": { "type": "string", "description": "[REQUIRED]" }, "t": { "type": "string", "format": "date-time", "description": "[REQUIRED]" }, "s": { "type": "string", "description": "[REQUIRED]" }, "crop": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "title": "ReaderEnvelopeWrappedPromise", "type": "object", "properties": { "code": { "type": "number", "summary": "Envelope code.\n\nMirror of HTTP status code", "description": "[REQUIRED]\n\nEnvelope code.\n\nMirror of HTTP status code", "default": 200 }, "status": { "type": "number", "summary": "Envelope status.\n\nIn extension to HTTP status code", "description": "[REQUIRED]\n\nEnvelope status.\n\nIn extension to HTTP status code", "default": 20000 }, "data": { "description": "The result payload you expect", "nullable": true, "summary": "The result payload you expect" }, "meta": { "description": "The metadata that the payload sometimes came with", "nullable": true, "summary": "The metadata that the payload sometimes came with" } }, "required": [ "code", "status" ], "primitive": true } } }, "headers": {} }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_AuthenticationRequiredError@0x2a" } ] } } }, "headers": {} }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_OperationNotAllowedError@0x2d" } ] } } }, "headers": {} }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Reader_ResourceNotFoundError@0x43" } ] } } }, "headers": {} } }, "summary": "getEphemeral", "operationId": "reader_post_ephemeral_encodedFid", "x-scalar-ignore": true }, "servers": [ { "url": "https://r.jina.ai" } ] }, "/{q}": { "get": { "tags": [ "Search" ], "parameters": [ { "name": "url", "in": "query", "schema": { "type": "string" }, "description": "The URL to read. Not needed when the URL is already in the path (`https://r.jina.ai/`)." }, { "name": "preloadUrl", "in": "query", "schema": { "type": "string" }, "description": "URL to preload before scraping.\n\nIgnored when no URL is provided." }, { "name": "noServiceWorker", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Disable service workers when running the browser.\n\nUseful for bypassing service-worker-based caching or interception." }, { "name": "html", "in": "query", "schema": { "type": "string" }, "description": "Raw HTML to convert, instead of fetching a URL. Used when no `url` is given." }, { "name": "base", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x0e" } ], "default": "initial" }, "description": "Select base modes of relative URLs.\n\nSupported: initial, final" }, { "name": "pdf", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_FancyFile@0x0f" } ] }, { "type": "string" } ], "summary": "Base64 encoded PDF.", "description": "Base64 encoded PDF." } }, { "name": "file", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_FancyFile@0x0f" } ] }, { "type": "string" } ], "summary": "Base64 encoded file.", "description": "Base64 encoded file." }, "description": "Base64-encoded file (PDF, DOC, XLS, PPT, ...) to convert instead of a URL." }, { "name": "page", "in": "query", "schema": { "type": "number" }, "description": "Steer which page to return for uploaded files (PDF, DOC, XLS, PPT, etc.).\n\n1-indexed; ignored when no file/PDF is uploaded." }, { "name": "respondWith", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x10" } ] }, { "type": "string" } ], "default": "content" }, "description": "Specifies the (non-default) form of the crawled data you prefer.\n\nSupported formats: \n- markdown\n- html\n- text\n- pageshot\n- screenshot\n- content\n- frontmatter\n- any combination of the above\n- vlm\n- jina-ocr-v1\n- jina-ocr\n- readerlm-v2\n\nDefault: content" }, { "name": "withGeneratedAlt", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ] }, "description": "Enable automatic alt-text generating for images without an meaningful alt-text.\n\nNote: Does not work when `X-Respond-With` is specified" }, { "name": "retainImages", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x12" } ], "default": "all" }, "description": "Image retention modes.\n\nSupported modes: \n- all: all images\n- none: no images\n- alt: only alt text\n- all_p: all images and with generated alt text\n- alt_p: only alt text and with generated alt" }, { "name": "retainMedia", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x13" } ], "default": "link" }, "description": "Media retention modes for video, audio, and embedded video iframes.\n\nSupported modes: \n- none: no media\n- text: plain label, e.g. `Video 1`\n- link: markdown link, e.g. `[Video 1](url)` (default)\n- image: markdown image syntax, e.g. `![Video 1](url)`\n- html: original HTML with irrelevant attributes (class, id, style, data-*, aria-*) stripped" }, { "name": "preset", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x14" } ] }, "description": "Apply a preset configuration for common scenarios.\n\nSupported presets:\n- reader: optimized for display to human users\n- index: optimized for semantic indexing\n- research: optimized for academic/research AI agents\n- agent: optimized for day-to-day AI agents\n- spider: optimized for recursive site crawling\n\nPreset values are applied only to options not explicitly set by the caller." }, { "name": "retainLinks", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x15" } ], "default": "all" }, "description": "Link retention modes.\n\nSupported modes: \n- all: all links\n- none: no links\n- text: only link text\n- gpt-oss: gpt-oss link citation format `【{id}†.*】`" }, { "name": "withLinksSummary", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ] }, { "type": "string" } ] }, "description": "Enable dedicated summary section for hyper links on the page." }, { "name": "withImagesSummary", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Enable dedicated summary section for images on the page." }, { "name": "noCache", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Ignores internal cache if this header is specified with a value.\n\nEquivalent to X-Cache-Tolerance: 0" }, { "name": "removeOverlay", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Specify whether to remove overlay elements from the page." }, { "name": "detachInvisibles", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Temporarily detach elements with computed `display:none` before snapshotting, then restore them.\n\nRequires the browser engine and disables caching." }, { "name": "noGfm", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ] }, { "type": "string" } ] }, "description": "Opt out of GitHub Flavored Markdown. `true` disables GFM; `table` drops only GFM tables and keeps the table HTML." }, { "name": "cacheTolerance", "in": "query", "schema": { "type": "number" }, "description": "Sets internal cache tolerance in seconds if this header is specified with a integer." }, { "name": "targetSelector", "in": "query", "schema": { "type": "string" }, "description": "Specifies a CSS selector for return target instead of the full html.\n\nImplies `X-Wait-For-Selector: (same selector)`" }, { "name": "waitForSelector", "in": "query", "schema": { "type": "string" }, "description": "Specifies a CSS selector to wait for the appearance of such an element before returning.\n\nExample: `X-Wait-For-Selector: .content-block`" }, { "name": "removeSelector", "in": "query", "schema": { "type": "string" }, "description": "Specifies a CSS selector to remove elements from the full html.\n\nExample `X-Remove-Selector: nav`" }, { "name": "keepImgDataUrl", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Keep data-url as it instead of transforming them to object-url. (Only applicable when targeting markdown format)\n\nExample `X-Keep-Img-Data-Url: true`" }, { "name": "withIframe", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ] }, { "type": "string" } ] }, "description": "Enable filling iframe contents into main. (violates standards)" }, { "name": "withShadowDom", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Enable filling shadow dom contents into main. (violates standards)" }, { "name": "skipCertVerification", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Enable skipping SSL certificate verification. (violates security best practices)" }, { "name": "setCookies", "in": "query", "schema": { "oneOf": [ { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, { "type": "string" } ] }, "description": "Cookies to send when fetching each result page, for pages that need a login. Requests with cookies are not cached." }, { "name": "exportStorageState", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Export the browser storage state (cookies and per-origin localStorage) accumulated during the crawl.\n\nWhen enabled, the JSON response includes a `storageState` field whose shape mirrors the `storageState` request option, so it can be fed back into a subsequent request.\n\nRequires the browser engine and disables caching." }, { "name": "proxyUrl", "in": "query", "schema": { "type": "string" }, "description": "Specifies your custom proxy if you prefer to use one.\n\nSupported protocols: \n- http\n- https\n- socks4\n- socks5\n\nFor authentication, https://user:pass@host:port" }, { "name": "proxyResources", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Whether to load resources like image/style/scripts via the proxy server." }, { "name": "proxy", "in": "query", "schema": { "type": "string" }, "description": "Use a proxy server provided by us.\n\nOptionally specify two-letter country code." }, { "name": "userAgent", "in": "query", "schema": { "type": "string" }, "description": "Override User-Agent.\n\nSeveral special values: \n- browser: use the internal browser UA\n- auto: pass-through your UA if it starts with `Mozilla/5.0`, otherwise use the internal browser UA\n- inherit / pass-through: use the User-Agent from the request context if applicable\n- bot: Use a pre-defined bot User-Agent from this service\n- diversify: Use a diversified browser User-Agent\n\nOr specify your own user agent string.\n\nNote: anonymous users specifying a browser UA will have no effect and will fall back to the internal browser UA.\n\nDefault: browser" }, { "name": "engine", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x2a" } ] }, "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering" }, { "name": "injectPageScript", "in": "query", "schema": { "type": "string" }, "description": "JavaScript to run in each result page before extraction, inline or as a URL." }, { "name": "injectFrameScript", "in": "query", "schema": { "type": "string" }, "description": "Like `injectPageScript`, for frames." }, { "name": "timeout", "in": "query", "schema": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v > 0 && v <= 180" } }, { "name": "locale", "in": "query", "schema": { "type": "string" }, "description": "Specify browser locale for the page." }, { "name": "referer", "in": "query", "schema": { "type": "string" }, "description": "Specify referer for the page." }, { "name": "tokenBudget", "in": "query", "schema": { "type": "number" }, "description": "Specify a budget in tokens.\n\nIf the resulting token cost exceeds the budget, the request is rejected.\n\nNote this parameter is ignored for the search endpoint." }, { "name": "assertStatusCode", "in": "query", "schema": { "type": "number" }, "description": "Assert the HTTP status code of the crawled page. If the actual status code does not match the asserted one, the request is rejected with 422 Unprocessable Entity." }, { "name": "instruction", "in": "query", "schema": { "type": "string" } }, { "name": "jsonSchema", "in": "query", "schema": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true } }, { "name": "robotsTxt", "in": "query", "schema": { "type": "string" }, "description": "Load and conform to the respective robot.txt on the target origin.\n\nOptionally specify a bot UA to check against." }, { "name": "zeroDataRetention", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] } }, { "name": "respondTiming", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x25" } ] }, "description": "Explicitly specify the respond timing. One of the following:\n\n- html: directly return unrendered HTML\n- visible-content: return immediately when any content becomes available\n- mutation-idle: wait for DOM mutations to settle and remain unchanged for at least 0.2s\n- resource-idle: wait for no additional resources that would affect page logic and content has SUCCEEDED loading in 0.5s\n- media-idle: wait for no additional resources, including media resources, has SUCCEEDED loading in 0.5s\n- network-idle: wait for full load of webpage, also known as networkidle0." }, { "name": "markdownChunking", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x26" } ] }, { "type": "string" } ] }, "description": "Opt-in markdown chunking.\n\nSupported values: \n- true\n- h1\n- h2\n- h3\n- h4\n- h5\n- structured\n- s1\n- s2\n- s3\n- s4\n- s5\n\nNote if you are expecting text return, the chunking is done by injecting character \\u001D" }, { "name": "maxTokens", "in": "query", "schema": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v >= 500" } }, { "name": "ext", "in": "query", "schema": { "summary": "Returns web pages with a specific file extension. Example: to find the Honda GX120 Owner’s manual in PDF, type “Honda GX120 ownners manual ext:pdf”.", "description": "Returns web pages with a specific file extension. Example: to find the Honda GX120 Owner’s manual in PDF, type “Honda GX120 ownners manual ext:pdf”.", "type": "string" }, "description": "Search operator `ext:` (file extension)." }, { "name": "filetype", "in": "query", "schema": { "summary": "Returns web pages created in the specified file type. Example: to find a web page created in PDF format about the evaluation of age-related cognitive changes, type “evaluation of age cognitive changes filetype:pdf”.", "description": "Returns web pages created in the specified file type. Example: to find a web page created in PDF format about the evaluation of age-related cognitive changes, type “evaluation of age cognitive changes filetype:pdf”.", "type": "string" }, "description": "Search operator `filetype:`, e.g. `pdf`." }, { "name": "intitle", "in": "query", "schema": { "summary": "Returns webpages containing the specified term in the title of the page. Example: to find pages about SEO conferences making sure the results contain 2023 in the title, type “seo conference intitle:2023”.", "description": "Returns webpages containing the specified term in the title of the page. Example: to find pages about SEO conferences making sure the results contain 2023 in the title, type “seo conference intitle:2023”.", "type": "string" }, "description": "Search operator `intitle:`: words that must appear in the page title." }, { "name": "loc", "in": "query", "schema": { "summary": "Returns web pages written in the specified language. The language code must be in the ISO 639-1 two-letter code format. Example: to find information on visas only in Spanish, type “visas lang:es”.", "description": "Returns web pages written in the specified language. The language code must be in the ISO 639-1 two-letter code format. Example: to find information on visas only in Spanish, type “visas lang:es”.", "type": "string" }, "description": "Search operator `loc:` (location)." }, { "name": "site", "in": "query", "schema": { "summary": "Returns web pages coming only from a specific web site. Example: to find information about Goggles only on Brave pages, type “goggles site:brave.com”.", "description": "Returns web pages coming only from a specific web site. Example: to find information about Goggles only on Brave pages, type “goggles site:brave.com”.", "type": "string" }, "description": "Keep results to this domain, e.g. `https://jina.ai`. Same as the `X-Site` header." }, { "name": "type", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x29" } ], "default": "web" }, "description": "Result type: `web` (default), `images` or `news`." }, { "name": "num", "in": "query", "schema": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v >= 0 && v <= 20" }, "description": "Maximum number of results, 0 to 20, default 10. Larger values can add latency and drop special result types." }, { "name": "count", "in": "query", "schema": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v >= 0 && v <= 20" }, "description": "Same as `num`." }, { "name": "provider", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x2b" } ] }, "description": "Search engine to use: `google`, `bing` or `reader`." }, { "name": "gl", "in": "query", "schema": { "type": "string", "description": "- Some validators will be applied on value(s): (v) => WORLD_COUNTRY_CODES.includes(v?.toLowerCase())" }, "description": "Country to search from, as a two-letter country code." }, { "name": "hl", "in": "query", "schema": { "type": "string", "description": "- Some validators will be applied on value(s): (v) => serper_search_2.WORLD_LANGUAGES.some(l => l.code === v)" }, "description": "Language of the search, as a two-letter language code." }, { "name": "location", "in": "query", "schema": { "type": "string" }, "description": "Where the search should originate from. City level works best." }, { "name": "fallback", "in": "query", "schema": { "type": "boolean" }, "description": "If `true` and the search returns nothing, fall back to local search results. Default `false`." }, { "name": "q", "in": "path", "schema": { "type": "string" }, "required": true, "description": "The search query. Not needed when the query is already in the path (`https://s.jina.ai/`)." }, { "name": "nfpr", "in": "query", "schema": { "type": "boolean" }, "description": "Passed to the search engine; on Google, `true` turns off query auto-correction." }, { "name": "Accept", "description": "Specifies your preference for the response format.\n\nSupported formats: \n- text/event-stream\n- application/json or text/json\n- text/plain", "in": "header", "schema": { "type": "string" } }, { "name": "X-Cache-Tolerance", "description": "Sets internal cache tolerance in seconds if this header is specified with a integer.", "in": "header", "schema": { "type": "string" } }, { "name": "X-No-Cache", "description": "Ignores internal cache if this header is specified with a value.\n\nEquivalent to X-Cache-Tolerance: 0", "in": "header", "schema": { "type": "string" } }, { "name": "X-Respond-With", "description": "Specifies the (non-default) form of the crawled data you prefer.\n\nSupported formats: \n- markdown\n- html\n- text\n- pageshot\n- screenshot\n- content\n- frontmatter\n- any combination of the above\n- vlm\n- jina-ocr-v1\n- jina-ocr\n- readerlm-v2\n\nDefault: content", "in": "header", "schema": { "type": "string" } }, { "name": "X-Wait-For-Selector", "description": "Specifies a CSS selector to wait for the appearance of such an element before returning.\n\nExample: `X-Wait-For-Selector: .content-block`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Target-Selector", "description": "Specifies a CSS selector for return target instead of the full html.\n\nImplies `X-Wait-For-Selector: (same selector)`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Remove-Selector", "description": "Specifies a CSS selector to remove elements from the full html.\n\nExample `X-Remove-Selector: nav`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Keep-Img-Data-Url", "description": "Keep data-url as it instead of transforming them to object-url. (Only applicable when targeting markdown format)\n\nExample `X-Keep-Img-Data-Url: true`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Proxy-Url", "description": "Specifies your custom proxy if you prefer to use one.\n\nSupported protocols: \n- http\n- https\n- socks4\n- socks5\n\nFor authentication, https://user:pass@host:port", "in": "header", "schema": { "type": "string" } }, { "name": "X-Proxy-Resources", "description": "Whether to load resources like image/style/scripts via the proxy server.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Proxy", "description": "Use a proxy server provided by us.\n\nOptionally specify two-letter country code.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Robots-Txt", "description": "Load and conform to the respective robot.txt on the target origin.\n\nOptionally specify a bot UA to check against.", "in": "header", "schema": { "type": "string" } }, { "name": "DNT", "description": "When set to 1, prevent the result of this request to be cached in the system.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Set-Cookie", "description": "Sets cookie(s) to the headless browser for your request. \n\nSyntax is the same with standard Set-Cookie", "in": "header", "schema": { "type": "string" } }, { "name": "X-Export-Storage-State", "description": "Export the browser storage state (cookies and per-origin localStorage) accumulated during the crawl.\n\nWhen enabled, the JSON response includes a `storageState` field whose shape mirrors the `storageState` request option, so it can be fed back into a subsequent request.\n\nRequires the browser engine and disables caching.", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Generated-Alt", "description": "Enable automatic alt-text generating for images without an meaningful alt-text.\n\nNote: Does not work when `X-Respond-With` is specified", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Images-Summary", "description": "Enable dedicated summary section for images on the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-links-Summary", "description": "Enable dedicated summary section for hyper links on the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Retain-Links", "description": "Link retention modes.\n\nSupported modes: \n- all: all links\n- none: no links\n- text: only link text\n- gpt-oss: gpt-oss link citation format `【{id}†.*】`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Retain-Images", "description": "Image retention modes.\n\nSupported modes: \n- all: all images\n- none: no images\n- alt: only alt text\n- all_p: all images and with generated alt text\n- alt_p: only alt text and with generated alt", "in": "header", "schema": { "type": "string" } }, { "name": "X-Retain-Media", "description": "Media retention modes for video, audio, and embedded video iframes.\n\nSupported modes: \n- none: no media\n- text: plain label, e.g. `Video 1`\n- link: markdown link, e.g. `[Video 1](url)` (default)\n- image: markdown image syntax, e.g. `![Video 1](url)`\n- html: original HTML with irrelevant attributes (class, id, style, data-*, aria-*) stripped", "in": "header", "schema": { "type": "string" } }, { "name": "X-Preset", "description": "Apply a preset configuration for common scenarios.\n\nSupported presets:\n- reader: optimized for display to human users\n- index: optimized for semantic indexing\n- research: optimized for academic/research AI agents\n- agent: optimized for day-to-day AI agents\n- spider: optimized for recursive site crawling\n\nPreset values are applied only to options not explicitly set by the caller.", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Iframe", "description": "Enable filling iframe contents into main. (violates standards)", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Shadow-Dom", "description": "Enable filling shadow dom contents into main. (violates standards)", "in": "header", "schema": { "type": "string" } }, { "name": "X-Skip-Cert-Verification", "description": "Enable skipping SSL certificate verification. (violates security best practices)", "in": "header", "schema": { "type": "string" } }, { "name": "X-User-Agent", "description": "Override User-Agent.\n\nSeveral special values: \n- browser: use the internal browser UA\n- auto: pass-through your UA if it starts with `Mozilla/5.0`, otherwise use the internal browser UA\n- inherit / pass-through: use the User-Agent from the request context if applicable\n- bot: Use a pre-defined bot User-Agent from this service\n- diversify: Use a diversified browser User-Agent\n\nOr specify your own user agent string.\n\nNote: anonymous users specifying a browser UA will have no effect and will fall back to the internal browser UA.\n\nDefault: browser", "in": "header", "schema": { "type": "string" } }, { "name": "X-Timeout", "description": "Specify timeout in seconds. Max 180.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Locale", "description": "Specify browser locale for the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Referer", "description": "Specify referer for the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Token-Budget", "description": "Specify a budget in tokens.\n\nIf the resulting token cost exceeds the budget, the request is rejected.\n\nNote this parameter is ignored for the search endpoint.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Max-Tokens", "description": "Trim the response content at a maximum number of tokens.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Assert-Status-Code", "description": "Assert the HTTP status code of the crawled page. If the actual status code does not match the asserted one, the request is rejected with 422 Unprocessable Entity.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Respond-Timing", "description": "Explicitly specify the respond timing. One of the following:\n\n- html: directly return unrendered HTML\n- visible-content: return immediately when any content becomes available\n- mutation-idle: wait for DOM mutations to settle and remain unchanged for at least 0.2s\n- resource-idle: wait for no additional resources that would affect page logic and content has SUCCEEDED loading in 0.5s\n- media-idle: wait for no additional resources, including media resources, has SUCCEEDED loading in 0.5s\n- network-idle: wait for full load of webpage, also known as networkidle0.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Engine", "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering", "in": "header", "schema": { "type": "string" } }, { "name": "X-Base", "description": "Select base modes of relative URLs.\n\nSupported: initial, final", "in": "header", "schema": { "type": "string" } }, { "name": "X-Remove-Overlay", "description": "Specify whether to remove overlay elements from the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Detach-Invisibles", "description": "Temporarily detach elements with computed `display:none` before snapshotting, then restore them.\n\nRequires the browser engine and disables caching.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Markdown-Chunking", "description": "Opt-in markdown chunking.\n\nSupported values: \n- true\n- h1\n- h2\n- h3\n- h4\n- h5\n- structured\n- s1\n- s2\n- s3\n- s4\n- s5\n\nNote if you are expecting text return, the chunking is done by injecting character \\u001D", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Heading-Style", "description": "Heading style of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: setext, atx", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Hr", "description": "Hr text of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Bullet-List-Marker", "description": "Bullet list marker of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: -, +, *", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Em-Delimiter", "description": "Em delimiter of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: _, *", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Strong-Delimiter", "description": "Strong delimiter of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: **, __", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Link-Style", "description": "Link style of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: inlined, referenced, discarded", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Link-Reference-Style", "description": "Link reference style of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: full, collapsed, shortcut, discarded", "in": "header", "schema": { "type": "string" } }, { "name": "X-Page", "description": "Steer which page to return for uploaded files (PDF, DOC, XLS, PPT, etc.).\n\n1-indexed; ignored when no file/PDF is uploaded.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Preload-Url", "description": "URL to preload before scraping.\n\nIgnored when no URL is provided.", "in": "header", "schema": { "type": "string" } }, { "name": "X-No-Service-Worker", "description": "Disable service workers when running the browser.\n\nUseful for bypassing service-worker-based caching or interception.", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain; charset=utf-8": { "schema": { "type": "string" } }, "application/json": { "schema": { "title": "ReaderEnvelopeWrappedArray", "type": "object", "properties": { "code": { "type": "number", "summary": "Envelope code.\n\nMirror of HTTP status code", "description": "[REQUIRED]\n\nEnvelope code.\n\nMirror of HTTP status code", "default": 200 }, "status": { "type": "number", "summary": "Envelope status.\n\nIn extension to HTTP status code", "description": "[REQUIRED]\n\nEnvelope status.\n\nIn extension to HTTP status code", "default": 20000 }, "data": { "allOf": [ { "$ref": "#/components/schemas/Search_Array@0x33" } ], "summary": "The result payload you expect", "description": "The result payload you expect" }, "meta": { "description": "The metadata that the payload sometimes came with", "nullable": true, "summary": "The metadata that the payload sometimes came with" } }, "required": [ "code", "status" ], "primitive": true } }, "text/event-stream": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_OutputServerEventStream@0x34" } ] } } }, "headers": {} }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_ParamValidationError@0x35" } ] } } }, "headers": {} }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_AuthenticationFailedError@0x36" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Search_AuthenticationRequiredError@0x37" } ] } ] } } }, "headers": {} }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_InsufficientBalanceError@0x38" } ] } } }, "headers": {} }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_AbuseAlleviationError@0x39" } ] } } }, "headers": {} }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_AssertionFailureError@0x3a" } ] } } }, "headers": {} }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_RateLimitTriggeredError@0x3b" } ] } } }, "headers": {} }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_DownstreamServiceError@0x3c" } ] } } }, "headers": {} }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_ServiceBadAttemptError@0x3d" } ] } } }, "headers": {} } }, "summary": "Search the web", "operationId": "search_get_q", "security": [ { "HTTPBearer": [] }, {} ], "description": "Put the query right after `https://s.jina.ai/`, e.g. `https://s.jina.ai/jina%20ai`.\n\nReturns the top results with each page's content as LLM-friendly text. `X-Respond-With: no-content` returns the results without page content; `X-Site` keeps results to one domain." }, "post": { "tags": [ "Search" ], "parameters": [ { "name": "url", "in": "query", "schema": { "type": "string" }, "description": "The URL to read. Not needed when the URL is already in the path (`https://r.jina.ai/`)." }, { "name": "preloadUrl", "in": "query", "schema": { "type": "string" }, "description": "URL to preload before scraping.\n\nIgnored when no URL is provided." }, { "name": "noServiceWorker", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Disable service workers when running the browser.\n\nUseful for bypassing service-worker-based caching or interception." }, { "name": "html", "in": "query", "schema": { "type": "string" }, "description": "Raw HTML to convert, instead of fetching a URL. Used when no `url` is given." }, { "name": "base", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x0e" } ], "default": "initial" }, "description": "Select base modes of relative URLs.\n\nSupported: initial, final" }, { "name": "pdf", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_FancyFile@0x0f" } ] }, { "type": "string" } ], "summary": "Base64 encoded PDF.", "description": "Base64 encoded PDF." } }, { "name": "file", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_FancyFile@0x0f" } ] }, { "type": "string" } ], "summary": "Base64 encoded file.", "description": "Base64 encoded file." }, "description": "Base64-encoded file (PDF, DOC, XLS, PPT, ...) to convert instead of a URL." }, { "name": "page", "in": "query", "schema": { "type": "number" }, "description": "Steer which page to return for uploaded files (PDF, DOC, XLS, PPT, etc.).\n\n1-indexed; ignored when no file/PDF is uploaded." }, { "name": "respondWith", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x10" } ] }, { "type": "string" } ], "default": "content" }, "description": "Specifies the (non-default) form of the crawled data you prefer.\n\nSupported formats: \n- markdown\n- html\n- text\n- pageshot\n- screenshot\n- content\n- frontmatter\n- any combination of the above\n- vlm\n- jina-ocr-v1\n- jina-ocr\n- readerlm-v2\n\nDefault: content" }, { "name": "withGeneratedAlt", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ] }, "description": "Enable automatic alt-text generating for images without an meaningful alt-text.\n\nNote: Does not work when `X-Respond-With` is specified" }, { "name": "retainImages", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x12" } ], "default": "all" }, "description": "Image retention modes.\n\nSupported modes: \n- all: all images\n- none: no images\n- alt: only alt text\n- all_p: all images and with generated alt text\n- alt_p: only alt text and with generated alt" }, { "name": "retainMedia", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x13" } ], "default": "link" }, "description": "Media retention modes for video, audio, and embedded video iframes.\n\nSupported modes: \n- none: no media\n- text: plain label, e.g. `Video 1`\n- link: markdown link, e.g. `[Video 1](url)` (default)\n- image: markdown image syntax, e.g. `![Video 1](url)`\n- html: original HTML with irrelevant attributes (class, id, style, data-*, aria-*) stripped" }, { "name": "preset", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x14" } ] }, "description": "Apply a preset configuration for common scenarios.\n\nSupported presets:\n- reader: optimized for display to human users\n- index: optimized for semantic indexing\n- research: optimized for academic/research AI agents\n- agent: optimized for day-to-day AI agents\n- spider: optimized for recursive site crawling\n\nPreset values are applied only to options not explicitly set by the caller." }, { "name": "retainLinks", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x15" } ], "default": "all" }, "description": "Link retention modes.\n\nSupported modes: \n- all: all links\n- none: no links\n- text: only link text\n- gpt-oss: gpt-oss link citation format `【{id}†.*】`" }, { "name": "withLinksSummary", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ] }, { "type": "string" } ] }, "description": "Enable dedicated summary section for hyper links on the page." }, { "name": "withImagesSummary", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Enable dedicated summary section for images on the page." }, { "name": "noCache", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Ignores internal cache if this header is specified with a value.\n\nEquivalent to X-Cache-Tolerance: 0" }, { "name": "removeOverlay", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Specify whether to remove overlay elements from the page." }, { "name": "detachInvisibles", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Temporarily detach elements with computed `display:none` before snapshotting, then restore them.\n\nRequires the browser engine and disables caching." }, { "name": "noGfm", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ] }, { "type": "string" } ] }, "description": "Opt out of GitHub Flavored Markdown. `true` disables GFM; `table` drops only GFM tables and keeps the table HTML." }, { "name": "cacheTolerance", "in": "query", "schema": { "type": "number" }, "description": "Sets internal cache tolerance in seconds if this header is specified with a integer." }, { "name": "targetSelector", "in": "query", "schema": { "type": "string" }, "description": "Specifies a CSS selector for return target instead of the full html.\n\nImplies `X-Wait-For-Selector: (same selector)`" }, { "name": "waitForSelector", "in": "query", "schema": { "type": "string" }, "description": "Specifies a CSS selector to wait for the appearance of such an element before returning.\n\nExample: `X-Wait-For-Selector: .content-block`" }, { "name": "removeSelector", "in": "query", "schema": { "type": "string" }, "description": "Specifies a CSS selector to remove elements from the full html.\n\nExample `X-Remove-Selector: nav`" }, { "name": "keepImgDataUrl", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Keep data-url as it instead of transforming them to object-url. (Only applicable when targeting markdown format)\n\nExample `X-Keep-Img-Data-Url: true`" }, { "name": "withIframe", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ] }, { "type": "string" } ] }, "description": "Enable filling iframe contents into main. (violates standards)" }, { "name": "withShadowDom", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Enable filling shadow dom contents into main. (violates standards)" }, { "name": "skipCertVerification", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Enable skipping SSL certificate verification. (violates security best practices)" }, { "name": "setCookies", "in": "query", "schema": { "oneOf": [ { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, { "type": "string" } ] }, "description": "Cookies to send when fetching each result page, for pages that need a login. Requests with cookies are not cached." }, { "name": "exportStorageState", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Export the browser storage state (cookies and per-origin localStorage) accumulated during the crawl.\n\nWhen enabled, the JSON response includes a `storageState` field whose shape mirrors the `storageState` request option, so it can be fed back into a subsequent request.\n\nRequires the browser engine and disables caching." }, { "name": "proxyUrl", "in": "query", "schema": { "type": "string" }, "description": "Specifies your custom proxy if you prefer to use one.\n\nSupported protocols: \n- http\n- https\n- socks4\n- socks5\n\nFor authentication, https://user:pass@host:port" }, { "name": "proxyResources", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Whether to load resources like image/style/scripts via the proxy server." }, { "name": "proxy", "in": "query", "schema": { "type": "string" }, "description": "Use a proxy server provided by us.\n\nOptionally specify two-letter country code." }, { "name": "userAgent", "in": "query", "schema": { "type": "string" }, "description": "Override User-Agent.\n\nSeveral special values: \n- browser: use the internal browser UA\n- auto: pass-through your UA if it starts with `Mozilla/5.0`, otherwise use the internal browser UA\n- inherit / pass-through: use the User-Agent from the request context if applicable\n- bot: Use a pre-defined bot User-Agent from this service\n- diversify: Use a diversified browser User-Agent\n\nOr specify your own user agent string.\n\nNote: anonymous users specifying a browser UA will have no effect and will fall back to the internal browser UA.\n\nDefault: browser" }, { "name": "engine", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x2a" } ] }, "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering" }, { "name": "injectPageScript", "in": "query", "schema": { "type": "string" }, "description": "JavaScript to run in each result page before extraction, inline or as a URL." }, { "name": "injectFrameScript", "in": "query", "schema": { "type": "string" }, "description": "Like `injectPageScript`, for frames." }, { "name": "timeout", "in": "query", "schema": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v > 0 && v <= 180" } }, { "name": "locale", "in": "query", "schema": { "type": "string" }, "description": "Specify browser locale for the page." }, { "name": "referer", "in": "query", "schema": { "type": "string" }, "description": "Specify referer for the page." }, { "name": "tokenBudget", "in": "query", "schema": { "type": "number" }, "description": "Specify a budget in tokens.\n\nIf the resulting token cost exceeds the budget, the request is rejected.\n\nNote this parameter is ignored for the search endpoint." }, { "name": "assertStatusCode", "in": "query", "schema": { "type": "number" }, "description": "Assert the HTTP status code of the crawled page. If the actual status code does not match the asserted one, the request is rejected with 422 Unprocessable Entity." }, { "name": "instruction", "in": "query", "schema": { "type": "string" } }, { "name": "jsonSchema", "in": "query", "schema": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true } }, { "name": "robotsTxt", "in": "query", "schema": { "type": "string" }, "description": "Load and conform to the respective robot.txt on the target origin.\n\nOptionally specify a bot UA to check against." }, { "name": "zeroDataRetention", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] } }, { "name": "respondTiming", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x25" } ] }, "description": "Explicitly specify the respond timing. One of the following:\n\n- html: directly return unrendered HTML\n- visible-content: return immediately when any content becomes available\n- mutation-idle: wait for DOM mutations to settle and remain unchanged for at least 0.2s\n- resource-idle: wait for no additional resources that would affect page logic and content has SUCCEEDED loading in 0.5s\n- media-idle: wait for no additional resources, including media resources, has SUCCEEDED loading in 0.5s\n- network-idle: wait for full load of webpage, also known as networkidle0." }, { "name": "markdownChunking", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x26" } ] }, { "type": "string" } ] }, "description": "Opt-in markdown chunking.\n\nSupported values: \n- true\n- h1\n- h2\n- h3\n- h4\n- h5\n- structured\n- s1\n- s2\n- s3\n- s4\n- s5\n\nNote if you are expecting text return, the chunking is done by injecting character \\u001D" }, { "name": "maxTokens", "in": "query", "schema": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v >= 500" } }, { "name": "ext", "in": "query", "schema": { "summary": "Returns web pages with a specific file extension. Example: to find the Honda GX120 Owner’s manual in PDF, type “Honda GX120 ownners manual ext:pdf”.", "description": "Returns web pages with a specific file extension. Example: to find the Honda GX120 Owner’s manual in PDF, type “Honda GX120 ownners manual ext:pdf”.", "type": "string" }, "description": "Search operator `ext:` (file extension)." }, { "name": "filetype", "in": "query", "schema": { "summary": "Returns web pages created in the specified file type. Example: to find a web page created in PDF format about the evaluation of age-related cognitive changes, type “evaluation of age cognitive changes filetype:pdf”.", "description": "Returns web pages created in the specified file type. Example: to find a web page created in PDF format about the evaluation of age-related cognitive changes, type “evaluation of age cognitive changes filetype:pdf”.", "type": "string" }, "description": "Search operator `filetype:`, e.g. `pdf`." }, { "name": "intitle", "in": "query", "schema": { "summary": "Returns webpages containing the specified term in the title of the page. Example: to find pages about SEO conferences making sure the results contain 2023 in the title, type “seo conference intitle:2023”.", "description": "Returns webpages containing the specified term in the title of the page. Example: to find pages about SEO conferences making sure the results contain 2023 in the title, type “seo conference intitle:2023”.", "type": "string" }, "description": "Search operator `intitle:`: words that must appear in the page title." }, { "name": "loc", "in": "query", "schema": { "summary": "Returns web pages written in the specified language. The language code must be in the ISO 639-1 two-letter code format. Example: to find information on visas only in Spanish, type “visas lang:es”.", "description": "Returns web pages written in the specified language. The language code must be in the ISO 639-1 two-letter code format. Example: to find information on visas only in Spanish, type “visas lang:es”.", "type": "string" }, "description": "Search operator `loc:` (location)." }, { "name": "site", "in": "query", "schema": { "summary": "Returns web pages coming only from a specific web site. Example: to find information about Goggles only on Brave pages, type “goggles site:brave.com”.", "description": "Returns web pages coming only from a specific web site. Example: to find information about Goggles only on Brave pages, type “goggles site:brave.com”.", "type": "string" }, "description": "Keep results to this domain, e.g. `https://jina.ai`. Same as the `X-Site` header." }, { "name": "type", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x29" } ], "default": "web" }, "description": "Result type: `web` (default), `images` or `news`." }, { "name": "num", "in": "query", "schema": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v >= 0 && v <= 20" }, "description": "Maximum number of results, 0 to 20, default 10. Larger values can add latency and drop special result types." }, { "name": "count", "in": "query", "schema": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v >= 0 && v <= 20" }, "description": "Same as `num`." }, { "name": "provider", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x2b" } ] }, "description": "Search engine to use: `google`, `bing` or `reader`." }, { "name": "gl", "in": "query", "schema": { "type": "string", "description": "- Some validators will be applied on value(s): (v) => WORLD_COUNTRY_CODES.includes(v?.toLowerCase())" }, "description": "Country to search from, as a two-letter country code." }, { "name": "hl", "in": "query", "schema": { "type": "string", "description": "- Some validators will be applied on value(s): (v) => serper_search_2.WORLD_LANGUAGES.some(l => l.code === v)" }, "description": "Language of the search, as a two-letter language code." }, { "name": "location", "in": "query", "schema": { "type": "string" }, "description": "Where the search should originate from. City level works best." }, { "name": "fallback", "in": "query", "schema": { "type": "boolean" }, "description": "If `true` and the search returns nothing, fall back to local search results. Default `false`." }, { "name": "q", "in": "path", "schema": { "type": "string" }, "required": true, "description": "The search query. Not needed when the query is already in the path (`https://s.jina.ai/`)." }, { "name": "nfpr", "in": "query", "schema": { "type": "boolean" }, "description": "Passed to the search engine; on Google, `true` turns off query auto-correction." }, { "name": "Accept", "description": "Specifies your preference for the response format.\n\nSupported formats: \n- text/event-stream\n- application/json or text/json\n- text/plain", "in": "header", "schema": { "type": "string" } }, { "name": "X-Cache-Tolerance", "description": "Sets internal cache tolerance in seconds if this header is specified with a integer.", "in": "header", "schema": { "type": "string" } }, { "name": "X-No-Cache", "description": "Ignores internal cache if this header is specified with a value.\n\nEquivalent to X-Cache-Tolerance: 0", "in": "header", "schema": { "type": "string" } }, { "name": "X-Respond-With", "description": "Specifies the (non-default) form of the crawled data you prefer.\n\nSupported formats: \n- markdown\n- html\n- text\n- pageshot\n- screenshot\n- content\n- frontmatter\n- any combination of the above\n- vlm\n- jina-ocr-v1\n- jina-ocr\n- readerlm-v2\n\nDefault: content", "in": "header", "schema": { "type": "string" } }, { "name": "X-Wait-For-Selector", "description": "Specifies a CSS selector to wait for the appearance of such an element before returning.\n\nExample: `X-Wait-For-Selector: .content-block`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Target-Selector", "description": "Specifies a CSS selector for return target instead of the full html.\n\nImplies `X-Wait-For-Selector: (same selector)`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Remove-Selector", "description": "Specifies a CSS selector to remove elements from the full html.\n\nExample `X-Remove-Selector: nav`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Keep-Img-Data-Url", "description": "Keep data-url as it instead of transforming them to object-url. (Only applicable when targeting markdown format)\n\nExample `X-Keep-Img-Data-Url: true`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Proxy-Url", "description": "Specifies your custom proxy if you prefer to use one.\n\nSupported protocols: \n- http\n- https\n- socks4\n- socks5\n\nFor authentication, https://user:pass@host:port", "in": "header", "schema": { "type": "string" } }, { "name": "X-Proxy-Resources", "description": "Whether to load resources like image/style/scripts via the proxy server.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Proxy", "description": "Use a proxy server provided by us.\n\nOptionally specify two-letter country code.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Robots-Txt", "description": "Load and conform to the respective robot.txt on the target origin.\n\nOptionally specify a bot UA to check against.", "in": "header", "schema": { "type": "string" } }, { "name": "DNT", "description": "When set to 1, prevent the result of this request to be cached in the system.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Set-Cookie", "description": "Sets cookie(s) to the headless browser for your request. \n\nSyntax is the same with standard Set-Cookie", "in": "header", "schema": { "type": "string" } }, { "name": "X-Export-Storage-State", "description": "Export the browser storage state (cookies and per-origin localStorage) accumulated during the crawl.\n\nWhen enabled, the JSON response includes a `storageState` field whose shape mirrors the `storageState` request option, so it can be fed back into a subsequent request.\n\nRequires the browser engine and disables caching.", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Generated-Alt", "description": "Enable automatic alt-text generating for images without an meaningful alt-text.\n\nNote: Does not work when `X-Respond-With` is specified", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Images-Summary", "description": "Enable dedicated summary section for images on the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-links-Summary", "description": "Enable dedicated summary section for hyper links on the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Retain-Links", "description": "Link retention modes.\n\nSupported modes: \n- all: all links\n- none: no links\n- text: only link text\n- gpt-oss: gpt-oss link citation format `【{id}†.*】`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Retain-Images", "description": "Image retention modes.\n\nSupported modes: \n- all: all images\n- none: no images\n- alt: only alt text\n- all_p: all images and with generated alt text\n- alt_p: only alt text and with generated alt", "in": "header", "schema": { "type": "string" } }, { "name": "X-Retain-Media", "description": "Media retention modes for video, audio, and embedded video iframes.\n\nSupported modes: \n- none: no media\n- text: plain label, e.g. `Video 1`\n- link: markdown link, e.g. `[Video 1](url)` (default)\n- image: markdown image syntax, e.g. `![Video 1](url)`\n- html: original HTML with irrelevant attributes (class, id, style, data-*, aria-*) stripped", "in": "header", "schema": { "type": "string" } }, { "name": "X-Preset", "description": "Apply a preset configuration for common scenarios.\n\nSupported presets:\n- reader: optimized for display to human users\n- index: optimized for semantic indexing\n- research: optimized for academic/research AI agents\n- agent: optimized for day-to-day AI agents\n- spider: optimized for recursive site crawling\n\nPreset values are applied only to options not explicitly set by the caller.", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Iframe", "description": "Enable filling iframe contents into main. (violates standards)", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Shadow-Dom", "description": "Enable filling shadow dom contents into main. (violates standards)", "in": "header", "schema": { "type": "string" } }, { "name": "X-Skip-Cert-Verification", "description": "Enable skipping SSL certificate verification. (violates security best practices)", "in": "header", "schema": { "type": "string" } }, { "name": "X-User-Agent", "description": "Override User-Agent.\n\nSeveral special values: \n- browser: use the internal browser UA\n- auto: pass-through your UA if it starts with `Mozilla/5.0`, otherwise use the internal browser UA\n- inherit / pass-through: use the User-Agent from the request context if applicable\n- bot: Use a pre-defined bot User-Agent from this service\n- diversify: Use a diversified browser User-Agent\n\nOr specify your own user agent string.\n\nNote: anonymous users specifying a browser UA will have no effect and will fall back to the internal browser UA.\n\nDefault: browser", "in": "header", "schema": { "type": "string" } }, { "name": "X-Timeout", "description": "Specify timeout in seconds. Max 180.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Locale", "description": "Specify browser locale for the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Referer", "description": "Specify referer for the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Token-Budget", "description": "Specify a budget in tokens.\n\nIf the resulting token cost exceeds the budget, the request is rejected.\n\nNote this parameter is ignored for the search endpoint.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Max-Tokens", "description": "Trim the response content at a maximum number of tokens.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Assert-Status-Code", "description": "Assert the HTTP status code of the crawled page. If the actual status code does not match the asserted one, the request is rejected with 422 Unprocessable Entity.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Respond-Timing", "description": "Explicitly specify the respond timing. One of the following:\n\n- html: directly return unrendered HTML\n- visible-content: return immediately when any content becomes available\n- mutation-idle: wait for DOM mutations to settle and remain unchanged for at least 0.2s\n- resource-idle: wait for no additional resources that would affect page logic and content has SUCCEEDED loading in 0.5s\n- media-idle: wait for no additional resources, including media resources, has SUCCEEDED loading in 0.5s\n- network-idle: wait for full load of webpage, also known as networkidle0.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Engine", "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering", "in": "header", "schema": { "type": "string" } }, { "name": "X-Base", "description": "Select base modes of relative URLs.\n\nSupported: initial, final", "in": "header", "schema": { "type": "string" } }, { "name": "X-Remove-Overlay", "description": "Specify whether to remove overlay elements from the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Detach-Invisibles", "description": "Temporarily detach elements with computed `display:none` before snapshotting, then restore them.\n\nRequires the browser engine and disables caching.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Markdown-Chunking", "description": "Opt-in markdown chunking.\n\nSupported values: \n- true\n- h1\n- h2\n- h3\n- h4\n- h5\n- structured\n- s1\n- s2\n- s3\n- s4\n- s5\n\nNote if you are expecting text return, the chunking is done by injecting character \\u001D", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Heading-Style", "description": "Heading style of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: setext, atx", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Hr", "description": "Hr text of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Bullet-List-Marker", "description": "Bullet list marker of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: -, +, *", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Em-Delimiter", "description": "Em delimiter of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: _, *", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Strong-Delimiter", "description": "Strong delimiter of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: **, __", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Link-Style", "description": "Link style of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: inlined, referenced, discarded", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Link-Reference-Style", "description": "Link reference style of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: full, collapsed, shortcut, discarded", "in": "header", "schema": { "type": "string" } }, { "name": "X-Page", "description": "Steer which page to return for uploaded files (PDF, DOC, XLS, PPT, etc.).\n\n1-indexed; ignored when no file/PDF is uploaded.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Preload-Url", "description": "URL to preload before scraping.\n\nIgnored when no URL is provided.", "in": "header", "schema": { "type": "string" } }, { "name": "X-No-Service-Worker", "description": "Disable service workers when running the browser.\n\nUseful for bypassing service-worker-based caching or interception.", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_JinaEmbeddingsAuthDTO@0x0c" }, { "$ref": "#/components/schemas/Search_CrawlerOptions@0x27" }, { "$ref": "#/components/schemas/Search_GoogleSearchExplicitOperatorsDto@0x28" }, { "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x29" } ], "default": "web", "description": "Result type: `web` (default), `images` or `news`." }, "num": { "type": "number", "description": "Maximum number of results, 0 to 20, default 10. Larger values can add latency and drop special result types." }, "count": { "type": "number", "description": "Same as `num`." }, "engine": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x2a" } ], "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering" }, "provider": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x2b" } ], "description": "Search engine to use: `google`, `bing` or `reader`." }, "gl": { "type": "string", "description": "Country to search from, as a two-letter country code." }, "hl": { "type": "string", "description": "Language of the search, as a two-letter language code." }, "location": { "type": "string", "description": "Where the search should originate from. City level works best." }, "page": { "type": "number", "description": "Steer which page to return for uploaded files (PDF, DOC, XLS, PPT, etc.).\n\n1-indexed; ignored when no file/PDF is uploaded." }, "fallback": { "type": "boolean", "description": "If `true` and the search returns nothing, fall back to local search results. Default `false`." }, "q": { "type": "string", "description": "The search query. Not needed when the query is already in the path (`https://s.jina.ai/`)." }, "nfpr": { "type": "boolean", "description": "Passed to the search engine; on Google, `true` turns off query auto-correction." } } } ] } }, "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_JinaEmbeddingsAuthDTO@0x0c" }, { "$ref": "#/components/schemas/Search_CrawlerOptions@0x27" }, { "$ref": "#/components/schemas/Search_GoogleSearchExplicitOperatorsDto@0x28" }, { "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x29" } ], "default": "web", "description": "Result type: `web` (default), `images` or `news`." }, "num": { "type": "number", "description": "Maximum number of results, 0 to 20, default 10. Larger values can add latency and drop special result types." }, "count": { "type": "number", "description": "Same as `num`." }, "engine": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x2a" } ], "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering" }, "provider": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x2b" } ], "description": "Search engine to use: `google`, `bing` or `reader`." }, "gl": { "type": "string", "description": "Country to search from, as a two-letter country code." }, "hl": { "type": "string", "description": "Language of the search, as a two-letter language code." }, "location": { "type": "string", "description": "Where the search should originate from. City level works best." }, "page": { "type": "number", "description": "Steer which page to return for uploaded files (PDF, DOC, XLS, PPT, etc.).\n\n1-indexed; ignored when no file/PDF is uploaded." }, "fallback": { "type": "boolean", "description": "If `true` and the search returns nothing, fall back to local search results. Default `false`." }, "q": { "type": "string", "description": "The search query. Not needed when the query is already in the path (`https://s.jina.ai/`)." }, "nfpr": { "type": "boolean", "description": "Passed to the search engine; on Google, `true` turns off query auto-correction." } } } ] } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL to read. Not needed when the URL is already in the path (`https://r.jina.ai/`)." }, "preloadUrl": { "type": "string", "description": "URL to preload before scraping.\n\nIgnored when no URL is provided." }, "noServiceWorker": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Disable service workers when running the browser.\n\nUseful for bypassing service-worker-based caching or interception." }, "html": { "type": "string", "description": "Raw HTML to convert, instead of fetching a URL. Used when no `url` is given." }, "base": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x0e" } ], "default": "initial", "description": "Select base modes of relative URLs.\n\nSupported: initial, final" }, "pdf": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_FancyFile@0x0f" } ] }, { "type": "string" } ], "summary": "Base64 encoded PDF.", "description": "Base64 encoded PDF." }, "file": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_FancyFile@0x0f" } ] }, { "type": "string" } ], "summary": "Base64 encoded file.", "description": "Base64-encoded file (PDF, DOC, XLS, PPT, ...) to convert instead of a URL." }, "page": { "type": "number", "description": "Steer which page to return for uploaded files (PDF, DOC, XLS, PPT, etc.).\n\n1-indexed; ignored when no file/PDF is uploaded." }, "respondWith": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x10" } ] }, { "type": "string" } ], "default": "content", "description": "Specifies the (non-default) form of the crawled data you prefer.\n\nSupported formats: \n- markdown\n- html\n- text\n- pageshot\n- screenshot\n- content\n- frontmatter\n- any combination of the above\n- vlm\n- jina-ocr-v1\n- jina-ocr\n- readerlm-v2\n\nDefault: content" }, "withGeneratedAlt": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ], "description": "Enable automatic alt-text generating for images without an meaningful alt-text.\n\nNote: Does not work when `X-Respond-With` is specified" }, "retainImages": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x12" } ], "default": "all", "description": "Image retention modes.\n\nSupported modes: \n- all: all images\n- none: no images\n- alt: only alt text\n- all_p: all images and with generated alt text\n- alt_p: only alt text and with generated alt" }, "retainMedia": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x13" } ], "default": "link", "description": "Media retention modes for video, audio, and embedded video iframes.\n\nSupported modes: \n- none: no media\n- text: plain label, e.g. `Video 1`\n- link: markdown link, e.g. `[Video 1](url)` (default)\n- image: markdown image syntax, e.g. `![Video 1](url)`\n- html: original HTML with irrelevant attributes (class, id, style, data-*, aria-*) stripped" }, "preset": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x14" } ], "description": "Apply a preset configuration for common scenarios.\n\nSupported presets:\n- reader: optimized for display to human users\n- index: optimized for semantic indexing\n- research: optimized for academic/research AI agents\n- agent: optimized for day-to-day AI agents\n- spider: optimized for recursive site crawling\n\nPreset values are applied only to options not explicitly set by the caller." }, "retainLinks": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x15" } ], "default": "all", "description": "Link retention modes.\n\nSupported modes: \n- all: all links\n- none: no links\n- text: only link text\n- gpt-oss: gpt-oss link citation format `【{id}†.*】`" }, "withLinksSummary": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ] }, { "type": "string" } ], "description": "Enable dedicated summary section for hyper links on the page." }, "withImagesSummary": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Enable dedicated summary section for images on the page." }, "noCache": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Ignores internal cache if this header is specified with a value.\n\nEquivalent to X-Cache-Tolerance: 0" }, "removeOverlay": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Specify whether to remove overlay elements from the page." }, "detachInvisibles": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Temporarily detach elements with computed `display:none` before snapshotting, then restore them.\n\nRequires the browser engine and disables caching." }, "noGfm": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ] }, { "type": "string" } ], "description": "Opt out of GitHub Flavored Markdown. `true` disables GFM; `table` drops only GFM tables and keeps the table HTML." }, "cacheTolerance": { "type": "number", "description": "Sets internal cache tolerance in seconds if this header is specified with a integer." }, "targetSelector": { "type": "string", "description": "Specifies a CSS selector for return target instead of the full html.\n\nImplies `X-Wait-For-Selector: (same selector)`" }, "waitForSelector": { "type": "string", "description": "Specifies a CSS selector to wait for the appearance of such an element before returning.\n\nExample: `X-Wait-For-Selector: .content-block`" }, "removeSelector": { "type": "string", "description": "Specifies a CSS selector to remove elements from the full html.\n\nExample `X-Remove-Selector: nav`" }, "keepImgDataUrl": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Keep data-url as it instead of transforming them to object-url. (Only applicable when targeting markdown format)\n\nExample `X-Keep-Img-Data-Url: true`" }, "withIframe": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ] }, { "type": "string" } ], "description": "Enable filling iframe contents into main. (violates standards)" }, "withShadowDom": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Enable filling shadow dom contents into main. (violates standards)" }, "skipCertVerification": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Enable skipping SSL certificate verification. (violates security best practices)" }, "setCookies": { "oneOf": [ { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, { "type": "string" } ], "description": "Cookies to send when fetching each result page, for pages that need a login. Requests with cookies are not cached." }, "exportStorageState": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Export the browser storage state (cookies and per-origin localStorage) accumulated during the crawl.\n\nWhen enabled, the JSON response includes a `storageState` field whose shape mirrors the `storageState` request option, so it can be fed back into a subsequent request.\n\nRequires the browser engine and disables caching." }, "proxyUrl": { "type": "string", "description": "Specifies your custom proxy if you prefer to use one.\n\nSupported protocols: \n- http\n- https\n- socks4\n- socks5\n\nFor authentication, https://user:pass@host:port" }, "proxyResources": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Whether to load resources like image/style/scripts via the proxy server." }, "proxy": { "type": "string", "description": "Use a proxy server provided by us.\n\nOptionally specify two-letter country code." }, "userAgent": { "type": "string", "description": "Override User-Agent.\n\nSeveral special values: \n- browser: use the internal browser UA\n- auto: pass-through your UA if it starts with `Mozilla/5.0`, otherwise use the internal browser UA\n- inherit / pass-through: use the User-Agent from the request context if applicable\n- bot: Use a pre-defined bot User-Agent from this service\n- diversify: Use a diversified browser User-Agent\n\nOr specify your own user agent string.\n\nNote: anonymous users specifying a browser UA will have no effect and will fall back to the internal browser UA.\n\nDefault: browser" }, "engine": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x2a" } ], "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering" }, "injectPageScript": { "type": "string", "description": "JavaScript to run in each result page before extraction, inline or as a URL." }, "injectFrameScript": { "type": "string", "description": "Like `injectPageScript`, for frames." }, "timeout": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v > 0 && v <= 180" }, "locale": { "type": "string", "description": "Specify browser locale for the page." }, "referer": { "type": "string", "description": "Specify referer for the page." }, "tokenBudget": { "type": "number", "description": "Specify a budget in tokens.\n\nIf the resulting token cost exceeds the budget, the request is rejected.\n\nNote this parameter is ignored for the search endpoint." }, "assertStatusCode": { "type": "number", "description": "Assert the HTTP status code of the crawled page. If the actual status code does not match the asserted one, the request is rejected with 422 Unprocessable Entity." }, "instruction": { "type": "string" }, "jsonSchema": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "robotsTxt": { "type": "string", "description": "Load and conform to the respective robot.txt on the target origin.\n\nOptionally specify a bot UA to check against." }, "zeroDataRetention": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "respondTiming": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x25" } ], "description": "Explicitly specify the respond timing. One of the following:\n\n- html: directly return unrendered HTML\n- visible-content: return immediately when any content becomes available\n- mutation-idle: wait for DOM mutations to settle and remain unchanged for at least 0.2s\n- resource-idle: wait for no additional resources that would affect page logic and content has SUCCEEDED loading in 0.5s\n- media-idle: wait for no additional resources, including media resources, has SUCCEEDED loading in 0.5s\n- network-idle: wait for full load of webpage, also known as networkidle0." }, "markdownChunking": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x26" } ] }, { "type": "string" } ], "description": "Opt-in markdown chunking.\n\nSupported values: \n- true\n- h1\n- h2\n- h3\n- h4\n- h5\n- structured\n- s1\n- s2\n- s3\n- s4\n- s5\n\nNote if you are expecting text return, the chunking is done by injecting character \\u001D" }, "maxTokens": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v >= 500" }, "ext": { "summary": "Returns web pages with a specific file extension. Example: to find the Honda GX120 Owner’s manual in PDF, type “Honda GX120 ownners manual ext:pdf”.", "description": "Search operator `ext:` (file extension).", "type": "string" }, "filetype": { "summary": "Returns web pages created in the specified file type. Example: to find a web page created in PDF format about the evaluation of age-related cognitive changes, type “evaluation of age cognitive changes filetype:pdf”.", "description": "Search operator `filetype:`, e.g. `pdf`.", "type": "string" }, "intitle": { "summary": "Returns webpages containing the specified term in the title of the page. Example: to find pages about SEO conferences making sure the results contain 2023 in the title, type “seo conference intitle:2023”.", "description": "Search operator `intitle:`: words that must appear in the page title.", "type": "string" }, "loc": { "summary": "Returns web pages written in the specified language. The language code must be in the ISO 639-1 two-letter code format. Example: to find information on visas only in Spanish, type “visas lang:es”.", "description": "Search operator `loc:` (location).", "type": "string" }, "site": { "summary": "Returns web pages coming only from a specific web site. Example: to find information about Goggles only on Brave pages, type “goggles site:brave.com”.", "description": "Keep results to this domain, e.g. `https://jina.ai`. Same as the `X-Site` header.", "type": "string" }, "type": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x29" } ], "default": "web", "description": "Result type: `web` (default), `images` or `news`." }, "num": { "type": "number", "description": "Maximum number of results, 0 to 20, default 10. Larger values can add latency and drop special result types." }, "count": { "type": "number", "description": "Same as `num`." }, "provider": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x2b" } ], "description": "Search engine to use: `google`, `bing` or `reader`." }, "gl": { "type": "string", "description": "Country to search from, as a two-letter country code." }, "hl": { "type": "string", "description": "Language of the search, as a two-letter language code." }, "location": { "type": "string", "description": "Where the search should originate from. City level works best." }, "fallback": { "type": "boolean", "description": "If `true` and the search returns nothing, fall back to local search results. Default `false`." }, "q": { "type": "string", "description": "The search query. Not needed when the query is already in the path (`https://s.jina.ai/`)." }, "nfpr": { "type": "boolean", "description": "Passed to the search engine; on Google, `true` turns off query auto-correction." } } } } } }, "responses": { "200": { "description": "OK", "content": { "text/plain; charset=utf-8": { "schema": { "type": "string" } }, "application/json": { "schema": { "title": "ReaderEnvelopeWrappedArray", "type": "object", "properties": { "code": { "type": "number", "summary": "Envelope code.\n\nMirror of HTTP status code", "description": "[REQUIRED]\n\nEnvelope code.\n\nMirror of HTTP status code", "default": 200 }, "status": { "type": "number", "summary": "Envelope status.\n\nIn extension to HTTP status code", "description": "[REQUIRED]\n\nEnvelope status.\n\nIn extension to HTTP status code", "default": 20000 }, "data": { "allOf": [ { "$ref": "#/components/schemas/Search_Array@0x33" } ], "summary": "The result payload you expect", "description": "The result payload you expect" }, "meta": { "description": "The metadata that the payload sometimes came with", "nullable": true, "summary": "The metadata that the payload sometimes came with" } }, "required": [ "code", "status" ], "primitive": true } }, "text/event-stream": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_OutputServerEventStream@0x34" } ] } } }, "headers": {} }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_ParamValidationError@0x35" } ] } } }, "headers": {} }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_AuthenticationFailedError@0x36" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Search_AuthenticationRequiredError@0x37" } ] } ] } } }, "headers": {} }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_InsufficientBalanceError@0x38" } ] } } }, "headers": {} }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_AbuseAlleviationError@0x39" } ] } } }, "headers": {} }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_AssertionFailureError@0x3a" } ] } } }, "headers": {} }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_RateLimitTriggeredError@0x3b" } ] } } }, "headers": {} }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_DownstreamServiceError@0x3c" } ] } } }, "headers": {} }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_ServiceBadAttemptError@0x3d" } ] } } }, "headers": {} } }, "summary": "search", "operationId": "search_post_q", "security": [ { "HTTPBearer": [] }, {} ], "x-scalar-ignore": true }, "servers": [ { "url": "https://s.jina.ai" } ] }, "/search": { "get": { "tags": [ "Search" ], "parameters": [ { "name": "url", "in": "query", "schema": { "type": "string" }, "description": "The URL to read. Not needed when the URL is already in the path (`https://r.jina.ai/`)." }, { "name": "preloadUrl", "in": "query", "schema": { "type": "string" }, "description": "URL to preload before scraping.\n\nIgnored when no URL is provided." }, { "name": "noServiceWorker", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Disable service workers when running the browser.\n\nUseful for bypassing service-worker-based caching or interception." }, { "name": "html", "in": "query", "schema": { "type": "string" }, "description": "Raw HTML to convert, instead of fetching a URL. Used when no `url` is given." }, { "name": "base", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x0e" } ], "default": "initial" }, "description": "Select base modes of relative URLs.\n\nSupported: initial, final" }, { "name": "pdf", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_FancyFile@0x0f" } ] }, { "type": "string" } ], "summary": "Base64 encoded PDF.", "description": "Base64 encoded PDF." } }, { "name": "file", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_FancyFile@0x0f" } ] }, { "type": "string" } ], "summary": "Base64 encoded file.", "description": "Base64 encoded file." }, "description": "Base64-encoded file (PDF, DOC, XLS, PPT, ...) to convert instead of a URL." }, { "name": "page", "in": "query", "schema": { "type": "number" }, "description": "Steer which page to return for uploaded files (PDF, DOC, XLS, PPT, etc.).\n\n1-indexed; ignored when no file/PDF is uploaded." }, { "name": "respondWith", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x10" } ] }, { "type": "string" } ], "default": "content" }, "description": "Specifies the (non-default) form of the crawled data you prefer.\n\nSupported formats: \n- markdown\n- html\n- text\n- pageshot\n- screenshot\n- content\n- frontmatter\n- any combination of the above\n- vlm\n- jina-ocr-v1\n- jina-ocr\n- readerlm-v2\n\nDefault: content" }, { "name": "withGeneratedAlt", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ] }, "description": "Enable automatic alt-text generating for images without an meaningful alt-text.\n\nNote: Does not work when `X-Respond-With` is specified" }, { "name": "retainImages", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x12" } ], "default": "all" }, "description": "Image retention modes.\n\nSupported modes: \n- all: all images\n- none: no images\n- alt: only alt text\n- all_p: all images and with generated alt text\n- alt_p: only alt text and with generated alt" }, { "name": "retainMedia", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x13" } ], "default": "link" }, "description": "Media retention modes for video, audio, and embedded video iframes.\n\nSupported modes: \n- none: no media\n- text: plain label, e.g. `Video 1`\n- link: markdown link, e.g. `[Video 1](url)` (default)\n- image: markdown image syntax, e.g. `![Video 1](url)`\n- html: original HTML with irrelevant attributes (class, id, style, data-*, aria-*) stripped" }, { "name": "preset", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x14" } ] }, "description": "Apply a preset configuration for common scenarios.\n\nSupported presets:\n- reader: optimized for display to human users\n- index: optimized for semantic indexing\n- research: optimized for academic/research AI agents\n- agent: optimized for day-to-day AI agents\n- spider: optimized for recursive site crawling\n\nPreset values are applied only to options not explicitly set by the caller." }, { "name": "retainLinks", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x15" } ], "default": "all" }, "description": "Link retention modes.\n\nSupported modes: \n- all: all links\n- none: no links\n- text: only link text\n- gpt-oss: gpt-oss link citation format `【{id}†.*】`" }, { "name": "withLinksSummary", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ] }, { "type": "string" } ] }, "description": "Enable dedicated summary section for hyper links on the page." }, { "name": "withImagesSummary", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Enable dedicated summary section for images on the page." }, { "name": "noCache", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Ignores internal cache if this header is specified with a value.\n\nEquivalent to X-Cache-Tolerance: 0" }, { "name": "removeOverlay", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Specify whether to remove overlay elements from the page." }, { "name": "detachInvisibles", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Temporarily detach elements with computed `display:none` before snapshotting, then restore them.\n\nRequires the browser engine and disables caching." }, { "name": "noGfm", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ] }, { "type": "string" } ] }, "description": "Opt out of GitHub Flavored Markdown. `true` disables GFM; `table` drops only GFM tables and keeps the table HTML." }, { "name": "cacheTolerance", "in": "query", "schema": { "type": "number" }, "description": "Sets internal cache tolerance in seconds if this header is specified with a integer." }, { "name": "targetSelector", "in": "query", "schema": { "type": "string" }, "description": "Specifies a CSS selector for return target instead of the full html.\n\nImplies `X-Wait-For-Selector: (same selector)`" }, { "name": "waitForSelector", "in": "query", "schema": { "type": "string" }, "description": "Specifies a CSS selector to wait for the appearance of such an element before returning.\n\nExample: `X-Wait-For-Selector: .content-block`" }, { "name": "removeSelector", "in": "query", "schema": { "type": "string" }, "description": "Specifies a CSS selector to remove elements from the full html.\n\nExample `X-Remove-Selector: nav`" }, { "name": "keepImgDataUrl", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Keep data-url as it instead of transforming them to object-url. (Only applicable when targeting markdown format)\n\nExample `X-Keep-Img-Data-Url: true`" }, { "name": "withIframe", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ] }, { "type": "string" } ] }, "description": "Enable filling iframe contents into main. (violates standards)" }, { "name": "withShadowDom", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Enable filling shadow dom contents into main. (violates standards)" }, { "name": "skipCertVerification", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Enable skipping SSL certificate verification. (violates security best practices)" }, { "name": "setCookies", "in": "query", "schema": { "oneOf": [ { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, { "type": "string" } ] }, "description": "Cookies to send when fetching each result page, for pages that need a login. Requests with cookies are not cached." }, { "name": "exportStorageState", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Export the browser storage state (cookies and per-origin localStorage) accumulated during the crawl.\n\nWhen enabled, the JSON response includes a `storageState` field whose shape mirrors the `storageState` request option, so it can be fed back into a subsequent request.\n\nRequires the browser engine and disables caching." }, { "name": "proxyUrl", "in": "query", "schema": { "type": "string" }, "description": "Specifies your custom proxy if you prefer to use one.\n\nSupported protocols: \n- http\n- https\n- socks4\n- socks5\n\nFor authentication, https://user:pass@host:port" }, { "name": "proxyResources", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Whether to load resources like image/style/scripts via the proxy server." }, { "name": "proxy", "in": "query", "schema": { "type": "string" }, "description": "Use a proxy server provided by us.\n\nOptionally specify two-letter country code." }, { "name": "userAgent", "in": "query", "schema": { "type": "string" }, "description": "Override User-Agent.\n\nSeveral special values: \n- browser: use the internal browser UA\n- auto: pass-through your UA if it starts with `Mozilla/5.0`, otherwise use the internal browser UA\n- inherit / pass-through: use the User-Agent from the request context if applicable\n- bot: Use a pre-defined bot User-Agent from this service\n- diversify: Use a diversified browser User-Agent\n\nOr specify your own user agent string.\n\nNote: anonymous users specifying a browser UA will have no effect and will fall back to the internal browser UA.\n\nDefault: browser" }, { "name": "engine", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x2a" } ] }, "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering" }, { "name": "injectPageScript", "in": "query", "schema": { "type": "string" }, "description": "JavaScript to run in each result page before extraction, inline or as a URL." }, { "name": "injectFrameScript", "in": "query", "schema": { "type": "string" }, "description": "Like `injectPageScript`, for frames." }, { "name": "timeout", "in": "query", "schema": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v > 0 && v <= 180" } }, { "name": "locale", "in": "query", "schema": { "type": "string" }, "description": "Specify browser locale for the page." }, { "name": "referer", "in": "query", "schema": { "type": "string" }, "description": "Specify referer for the page." }, { "name": "tokenBudget", "in": "query", "schema": { "type": "number" }, "description": "Specify a budget in tokens.\n\nIf the resulting token cost exceeds the budget, the request is rejected.\n\nNote this parameter is ignored for the search endpoint." }, { "name": "assertStatusCode", "in": "query", "schema": { "type": "number" }, "description": "Assert the HTTP status code of the crawled page. If the actual status code does not match the asserted one, the request is rejected with 422 Unprocessable Entity." }, { "name": "instruction", "in": "query", "schema": { "type": "string" } }, { "name": "jsonSchema", "in": "query", "schema": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true } }, { "name": "robotsTxt", "in": "query", "schema": { "type": "string" }, "description": "Load and conform to the respective robot.txt on the target origin.\n\nOptionally specify a bot UA to check against." }, { "name": "zeroDataRetention", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] } }, { "name": "respondTiming", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x25" } ] }, "description": "Explicitly specify the respond timing. One of the following:\n\n- html: directly return unrendered HTML\n- visible-content: return immediately when any content becomes available\n- mutation-idle: wait for DOM mutations to settle and remain unchanged for at least 0.2s\n- resource-idle: wait for no additional resources that would affect page logic and content has SUCCEEDED loading in 0.5s\n- media-idle: wait for no additional resources, including media resources, has SUCCEEDED loading in 0.5s\n- network-idle: wait for full load of webpage, also known as networkidle0." }, { "name": "markdownChunking", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x26" } ] }, { "type": "string" } ] }, "description": "Opt-in markdown chunking.\n\nSupported values: \n- true\n- h1\n- h2\n- h3\n- h4\n- h5\n- structured\n- s1\n- s2\n- s3\n- s4\n- s5\n\nNote if you are expecting text return, the chunking is done by injecting character \\u001D" }, { "name": "maxTokens", "in": "query", "schema": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v >= 500" } }, { "name": "ext", "in": "query", "schema": { "summary": "Returns web pages with a specific file extension. Example: to find the Honda GX120 Owner’s manual in PDF, type “Honda GX120 ownners manual ext:pdf”.", "description": "Returns web pages with a specific file extension. Example: to find the Honda GX120 Owner’s manual in PDF, type “Honda GX120 ownners manual ext:pdf”.", "type": "string" }, "description": "Search operator `ext:` (file extension)." }, { "name": "filetype", "in": "query", "schema": { "summary": "Returns web pages created in the specified file type. Example: to find a web page created in PDF format about the evaluation of age-related cognitive changes, type “evaluation of age cognitive changes filetype:pdf”.", "description": "Returns web pages created in the specified file type. Example: to find a web page created in PDF format about the evaluation of age-related cognitive changes, type “evaluation of age cognitive changes filetype:pdf”.", "type": "string" }, "description": "Search operator `filetype:`, e.g. `pdf`." }, { "name": "intitle", "in": "query", "schema": { "summary": "Returns webpages containing the specified term in the title of the page. Example: to find pages about SEO conferences making sure the results contain 2023 in the title, type “seo conference intitle:2023”.", "description": "Returns webpages containing the specified term in the title of the page. Example: to find pages about SEO conferences making sure the results contain 2023 in the title, type “seo conference intitle:2023”.", "type": "string" }, "description": "Search operator `intitle:`: words that must appear in the page title." }, { "name": "loc", "in": "query", "schema": { "summary": "Returns web pages written in the specified language. The language code must be in the ISO 639-1 two-letter code format. Example: to find information on visas only in Spanish, type “visas lang:es”.", "description": "Returns web pages written in the specified language. The language code must be in the ISO 639-1 two-letter code format. Example: to find information on visas only in Spanish, type “visas lang:es”.", "type": "string" }, "description": "Search operator `loc:` (location)." }, { "name": "site", "in": "query", "schema": { "summary": "Returns web pages coming only from a specific web site. Example: to find information about Goggles only on Brave pages, type “goggles site:brave.com”.", "description": "Returns web pages coming only from a specific web site. Example: to find information about Goggles only on Brave pages, type “goggles site:brave.com”.", "type": "string" }, "description": "Keep results to this domain, e.g. `https://jina.ai`. Same as the `X-Site` header." }, { "name": "type", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x29" } ], "default": "web" }, "description": "Result type: `web` (default), `images` or `news`." }, { "name": "num", "in": "query", "schema": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v >= 0 && v <= 20" }, "description": "Maximum number of results, 0 to 20, default 10. Larger values can add latency and drop special result types." }, { "name": "count", "in": "query", "schema": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v >= 0 && v <= 20" }, "description": "Same as `num`." }, { "name": "provider", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x2b" } ] }, "description": "Search engine to use: `google`, `bing` or `reader`." }, { "name": "gl", "in": "query", "schema": { "type": "string", "description": "- Some validators will be applied on value(s): (v) => WORLD_COUNTRY_CODES.includes(v?.toLowerCase())" }, "description": "Country to search from, as a two-letter country code." }, { "name": "hl", "in": "query", "schema": { "type": "string", "description": "- Some validators will be applied on value(s): (v) => serper_search_2.WORLD_LANGUAGES.some(l => l.code === v)" }, "description": "Language of the search, as a two-letter language code." }, { "name": "location", "in": "query", "schema": { "type": "string" }, "description": "Where the search should originate from. City level works best." }, { "name": "fallback", "in": "query", "schema": { "type": "boolean" }, "description": "If `true` and the search returns nothing, fall back to local search results. Default `false`." }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "The search query. Not needed when the query is already in the path (`https://s.jina.ai/`)." }, { "name": "nfpr", "in": "query", "schema": { "type": "boolean" }, "description": "Passed to the search engine; on Google, `true` turns off query auto-correction." }, { "name": "Accept", "description": "Specifies your preference for the response format.\n\nSupported formats: \n- text/event-stream\n- application/json or text/json\n- text/plain", "in": "header", "schema": { "type": "string" } }, { "name": "X-Cache-Tolerance", "description": "Sets internal cache tolerance in seconds if this header is specified with a integer.", "in": "header", "schema": { "type": "string" } }, { "name": "X-No-Cache", "description": "Ignores internal cache if this header is specified with a value.\n\nEquivalent to X-Cache-Tolerance: 0", "in": "header", "schema": { "type": "string" } }, { "name": "X-Respond-With", "description": "Specifies the (non-default) form of the crawled data you prefer.\n\nSupported formats: \n- markdown\n- html\n- text\n- pageshot\n- screenshot\n- content\n- frontmatter\n- any combination of the above\n- vlm\n- jina-ocr-v1\n- jina-ocr\n- readerlm-v2\n\nDefault: content", "in": "header", "schema": { "type": "string" } }, { "name": "X-Wait-For-Selector", "description": "Specifies a CSS selector to wait for the appearance of such an element before returning.\n\nExample: `X-Wait-For-Selector: .content-block`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Target-Selector", "description": "Specifies a CSS selector for return target instead of the full html.\n\nImplies `X-Wait-For-Selector: (same selector)`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Remove-Selector", "description": "Specifies a CSS selector to remove elements from the full html.\n\nExample `X-Remove-Selector: nav`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Keep-Img-Data-Url", "description": "Keep data-url as it instead of transforming them to object-url. (Only applicable when targeting markdown format)\n\nExample `X-Keep-Img-Data-Url: true`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Proxy-Url", "description": "Specifies your custom proxy if you prefer to use one.\n\nSupported protocols: \n- http\n- https\n- socks4\n- socks5\n\nFor authentication, https://user:pass@host:port", "in": "header", "schema": { "type": "string" } }, { "name": "X-Proxy-Resources", "description": "Whether to load resources like image/style/scripts via the proxy server.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Proxy", "description": "Use a proxy server provided by us.\n\nOptionally specify two-letter country code.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Robots-Txt", "description": "Load and conform to the respective robot.txt on the target origin.\n\nOptionally specify a bot UA to check against.", "in": "header", "schema": { "type": "string" } }, { "name": "DNT", "description": "When set to 1, prevent the result of this request to be cached in the system.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Set-Cookie", "description": "Sets cookie(s) to the headless browser for your request. \n\nSyntax is the same with standard Set-Cookie", "in": "header", "schema": { "type": "string" } }, { "name": "X-Export-Storage-State", "description": "Export the browser storage state (cookies and per-origin localStorage) accumulated during the crawl.\n\nWhen enabled, the JSON response includes a `storageState` field whose shape mirrors the `storageState` request option, so it can be fed back into a subsequent request.\n\nRequires the browser engine and disables caching.", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Generated-Alt", "description": "Enable automatic alt-text generating for images without an meaningful alt-text.\n\nNote: Does not work when `X-Respond-With` is specified", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Images-Summary", "description": "Enable dedicated summary section for images on the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-links-Summary", "description": "Enable dedicated summary section for hyper links on the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Retain-Links", "description": "Link retention modes.\n\nSupported modes: \n- all: all links\n- none: no links\n- text: only link text\n- gpt-oss: gpt-oss link citation format `【{id}†.*】`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Retain-Images", "description": "Image retention modes.\n\nSupported modes: \n- all: all images\n- none: no images\n- alt: only alt text\n- all_p: all images and with generated alt text\n- alt_p: only alt text and with generated alt", "in": "header", "schema": { "type": "string" } }, { "name": "X-Retain-Media", "description": "Media retention modes for video, audio, and embedded video iframes.\n\nSupported modes: \n- none: no media\n- text: plain label, e.g. `Video 1`\n- link: markdown link, e.g. `[Video 1](url)` (default)\n- image: markdown image syntax, e.g. `![Video 1](url)`\n- html: original HTML with irrelevant attributes (class, id, style, data-*, aria-*) stripped", "in": "header", "schema": { "type": "string" } }, { "name": "X-Preset", "description": "Apply a preset configuration for common scenarios.\n\nSupported presets:\n- reader: optimized for display to human users\n- index: optimized for semantic indexing\n- research: optimized for academic/research AI agents\n- agent: optimized for day-to-day AI agents\n- spider: optimized for recursive site crawling\n\nPreset values are applied only to options not explicitly set by the caller.", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Iframe", "description": "Enable filling iframe contents into main. (violates standards)", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Shadow-Dom", "description": "Enable filling shadow dom contents into main. (violates standards)", "in": "header", "schema": { "type": "string" } }, { "name": "X-Skip-Cert-Verification", "description": "Enable skipping SSL certificate verification. (violates security best practices)", "in": "header", "schema": { "type": "string" } }, { "name": "X-User-Agent", "description": "Override User-Agent.\n\nSeveral special values: \n- browser: use the internal browser UA\n- auto: pass-through your UA if it starts with `Mozilla/5.0`, otherwise use the internal browser UA\n- inherit / pass-through: use the User-Agent from the request context if applicable\n- bot: Use a pre-defined bot User-Agent from this service\n- diversify: Use a diversified browser User-Agent\n\nOr specify your own user agent string.\n\nNote: anonymous users specifying a browser UA will have no effect and will fall back to the internal browser UA.\n\nDefault: browser", "in": "header", "schema": { "type": "string" } }, { "name": "X-Timeout", "description": "Specify timeout in seconds. Max 180.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Locale", "description": "Specify browser locale for the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Referer", "description": "Specify referer for the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Token-Budget", "description": "Specify a budget in tokens.\n\nIf the resulting token cost exceeds the budget, the request is rejected.\n\nNote this parameter is ignored for the search endpoint.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Max-Tokens", "description": "Trim the response content at a maximum number of tokens.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Assert-Status-Code", "description": "Assert the HTTP status code of the crawled page. If the actual status code does not match the asserted one, the request is rejected with 422 Unprocessable Entity.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Respond-Timing", "description": "Explicitly specify the respond timing. One of the following:\n\n- html: directly return unrendered HTML\n- visible-content: return immediately when any content becomes available\n- mutation-idle: wait for DOM mutations to settle and remain unchanged for at least 0.2s\n- resource-idle: wait for no additional resources that would affect page logic and content has SUCCEEDED loading in 0.5s\n- media-idle: wait for no additional resources, including media resources, has SUCCEEDED loading in 0.5s\n- network-idle: wait for full load of webpage, also known as networkidle0.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Engine", "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering", "in": "header", "schema": { "type": "string" } }, { "name": "X-Base", "description": "Select base modes of relative URLs.\n\nSupported: initial, final", "in": "header", "schema": { "type": "string" } }, { "name": "X-Remove-Overlay", "description": "Specify whether to remove overlay elements from the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Detach-Invisibles", "description": "Temporarily detach elements with computed `display:none` before snapshotting, then restore them.\n\nRequires the browser engine and disables caching.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Markdown-Chunking", "description": "Opt-in markdown chunking.\n\nSupported values: \n- true\n- h1\n- h2\n- h3\n- h4\n- h5\n- structured\n- s1\n- s2\n- s3\n- s4\n- s5\n\nNote if you are expecting text return, the chunking is done by injecting character \\u001D", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Heading-Style", "description": "Heading style of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: setext, atx", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Hr", "description": "Hr text of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Bullet-List-Marker", "description": "Bullet list marker of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: -, +, *", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Em-Delimiter", "description": "Em delimiter of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: _, *", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Strong-Delimiter", "description": "Strong delimiter of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: **, __", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Link-Style", "description": "Link style of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: inlined, referenced, discarded", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Link-Reference-Style", "description": "Link reference style of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: full, collapsed, shortcut, discarded", "in": "header", "schema": { "type": "string" } }, { "name": "X-Page", "description": "Steer which page to return for uploaded files (PDF, DOC, XLS, PPT, etc.).\n\n1-indexed; ignored when no file/PDF is uploaded.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Preload-Url", "description": "URL to preload before scraping.\n\nIgnored when no URL is provided.", "in": "header", "schema": { "type": "string" } }, { "name": "X-No-Service-Worker", "description": "Disable service workers when running the browser.\n\nUseful for bypassing service-worker-based caching or interception.", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain; charset=utf-8": { "schema": { "type": "string" } }, "application/json": { "schema": { "title": "ReaderEnvelopeWrappedArray", "type": "object", "properties": { "code": { "type": "number", "summary": "Envelope code.\n\nMirror of HTTP status code", "description": "[REQUIRED]\n\nEnvelope code.\n\nMirror of HTTP status code", "default": 200 }, "status": { "type": "number", "summary": "Envelope status.\n\nIn extension to HTTP status code", "description": "[REQUIRED]\n\nEnvelope status.\n\nIn extension to HTTP status code", "default": 20000 }, "data": { "allOf": [ { "$ref": "#/components/schemas/Search_Array@0x3e" } ], "summary": "The result payload you expect", "description": "The result payload you expect" }, "meta": { "description": "The metadata that the payload sometimes came with", "nullable": true, "summary": "The metadata that the payload sometimes came with" } }, "required": [ "code", "status" ], "primitive": true } }, "text/event-stream": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_OutputServerEventStream@0x34" } ] } } }, "headers": {} }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_ParamValidationError@0x35" } ] } } }, "headers": {} }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_AuthenticationFailedError@0x36" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Search_AuthenticationRequiredError@0x37" } ] } ] } } }, "headers": {} }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_InsufficientBalanceError@0x38" } ] } } }, "headers": {} }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_AbuseAlleviationError@0x39" } ] } } }, "headers": {} }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_AssertionFailureError@0x3a" } ] } } }, "headers": {} }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_RateLimitTriggeredError@0x3b" } ] } } }, "headers": {} }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_DownstreamServiceError@0x3c" } ] } } }, "headers": {} }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_ServiceBadAttemptError@0x3d" } ] } } }, "headers": {} } }, "summary": "searchIndex", "operationId": "search_get_search", "security": [ { "HTTPBearer": [] }, {} ], "x-scalar-ignore": true }, "post": { "tags": [ "Search" ], "parameters": [ { "name": "url", "in": "query", "schema": { "type": "string" }, "description": "The URL to read. Not needed when the URL is already in the path (`https://r.jina.ai/`)." }, { "name": "preloadUrl", "in": "query", "schema": { "type": "string" }, "description": "URL to preload before scraping.\n\nIgnored when no URL is provided." }, { "name": "noServiceWorker", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Disable service workers when running the browser.\n\nUseful for bypassing service-worker-based caching or interception." }, { "name": "html", "in": "query", "schema": { "type": "string" }, "description": "Raw HTML to convert, instead of fetching a URL. Used when no `url` is given." }, { "name": "base", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x0e" } ], "default": "initial" }, "description": "Select base modes of relative URLs.\n\nSupported: initial, final" }, { "name": "pdf", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_FancyFile@0x0f" } ] }, { "type": "string" } ], "summary": "Base64 encoded PDF.", "description": "Base64 encoded PDF." } }, { "name": "file", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_FancyFile@0x0f" } ] }, { "type": "string" } ], "summary": "Base64 encoded file.", "description": "Base64 encoded file." }, "description": "Base64-encoded file (PDF, DOC, XLS, PPT, ...) to convert instead of a URL." }, { "name": "page", "in": "query", "schema": { "type": "number" }, "description": "Steer which page to return for uploaded files (PDF, DOC, XLS, PPT, etc.).\n\n1-indexed; ignored when no file/PDF is uploaded." }, { "name": "respondWith", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x10" } ] }, { "type": "string" } ], "default": "content" }, "description": "Specifies the (non-default) form of the crawled data you prefer.\n\nSupported formats: \n- markdown\n- html\n- text\n- pageshot\n- screenshot\n- content\n- frontmatter\n- any combination of the above\n- vlm\n- jina-ocr-v1\n- jina-ocr\n- readerlm-v2\n\nDefault: content" }, { "name": "withGeneratedAlt", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ] }, "description": "Enable automatic alt-text generating for images without an meaningful alt-text.\n\nNote: Does not work when `X-Respond-With` is specified" }, { "name": "retainImages", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x12" } ], "default": "all" }, "description": "Image retention modes.\n\nSupported modes: \n- all: all images\n- none: no images\n- alt: only alt text\n- all_p: all images and with generated alt text\n- alt_p: only alt text and with generated alt" }, { "name": "retainMedia", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x13" } ], "default": "link" }, "description": "Media retention modes for video, audio, and embedded video iframes.\n\nSupported modes: \n- none: no media\n- text: plain label, e.g. `Video 1`\n- link: markdown link, e.g. `[Video 1](url)` (default)\n- image: markdown image syntax, e.g. `![Video 1](url)`\n- html: original HTML with irrelevant attributes (class, id, style, data-*, aria-*) stripped" }, { "name": "preset", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x14" } ] }, "description": "Apply a preset configuration for common scenarios.\n\nSupported presets:\n- reader: optimized for display to human users\n- index: optimized for semantic indexing\n- research: optimized for academic/research AI agents\n- agent: optimized for day-to-day AI agents\n- spider: optimized for recursive site crawling\n\nPreset values are applied only to options not explicitly set by the caller." }, { "name": "retainLinks", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x15" } ], "default": "all" }, "description": "Link retention modes.\n\nSupported modes: \n- all: all links\n- none: no links\n- text: only link text\n- gpt-oss: gpt-oss link citation format `【{id}†.*】`" }, { "name": "withLinksSummary", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ] }, { "type": "string" } ] }, "description": "Enable dedicated summary section for hyper links on the page." }, { "name": "withImagesSummary", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Enable dedicated summary section for images on the page." }, { "name": "noCache", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Ignores internal cache if this header is specified with a value.\n\nEquivalent to X-Cache-Tolerance: 0" }, { "name": "removeOverlay", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Specify whether to remove overlay elements from the page." }, { "name": "detachInvisibles", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Temporarily detach elements with computed `display:none` before snapshotting, then restore them.\n\nRequires the browser engine and disables caching." }, { "name": "noGfm", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ] }, { "type": "string" } ] }, "description": "Opt out of GitHub Flavored Markdown. `true` disables GFM; `table` drops only GFM tables and keeps the table HTML." }, { "name": "cacheTolerance", "in": "query", "schema": { "type": "number" }, "description": "Sets internal cache tolerance in seconds if this header is specified with a integer." }, { "name": "targetSelector", "in": "query", "schema": { "type": "string" }, "description": "Specifies a CSS selector for return target instead of the full html.\n\nImplies `X-Wait-For-Selector: (same selector)`" }, { "name": "waitForSelector", "in": "query", "schema": { "type": "string" }, "description": "Specifies a CSS selector to wait for the appearance of such an element before returning.\n\nExample: `X-Wait-For-Selector: .content-block`" }, { "name": "removeSelector", "in": "query", "schema": { "type": "string" }, "description": "Specifies a CSS selector to remove elements from the full html.\n\nExample `X-Remove-Selector: nav`" }, { "name": "keepImgDataUrl", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Keep data-url as it instead of transforming them to object-url. (Only applicable when targeting markdown format)\n\nExample `X-Keep-Img-Data-Url: true`" }, { "name": "withIframe", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ] }, { "type": "string" } ] }, "description": "Enable filling iframe contents into main. (violates standards)" }, { "name": "withShadowDom", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Enable filling shadow dom contents into main. (violates standards)" }, { "name": "skipCertVerification", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Enable skipping SSL certificate verification. (violates security best practices)" }, { "name": "setCookies", "in": "query", "schema": { "oneOf": [ { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, { "type": "string" } ] }, "description": "Cookies to send when fetching each result page, for pages that need a login. Requests with cookies are not cached." }, { "name": "exportStorageState", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Export the browser storage state (cookies and per-origin localStorage) accumulated during the crawl.\n\nWhen enabled, the JSON response includes a `storageState` field whose shape mirrors the `storageState` request option, so it can be fed back into a subsequent request.\n\nRequires the browser engine and disables caching." }, { "name": "proxyUrl", "in": "query", "schema": { "type": "string" }, "description": "Specifies your custom proxy if you prefer to use one.\n\nSupported protocols: \n- http\n- https\n- socks4\n- socks5\n\nFor authentication, https://user:pass@host:port" }, { "name": "proxyResources", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "description": "Whether to load resources like image/style/scripts via the proxy server." }, { "name": "proxy", "in": "query", "schema": { "type": "string" }, "description": "Use a proxy server provided by us.\n\nOptionally specify two-letter country code." }, { "name": "userAgent", "in": "query", "schema": { "type": "string" }, "description": "Override User-Agent.\n\nSeveral special values: \n- browser: use the internal browser UA\n- auto: pass-through your UA if it starts with `Mozilla/5.0`, otherwise use the internal browser UA\n- inherit / pass-through: use the User-Agent from the request context if applicable\n- bot: Use a pre-defined bot User-Agent from this service\n- diversify: Use a diversified browser User-Agent\n\nOr specify your own user agent string.\n\nNote: anonymous users specifying a browser UA will have no effect and will fall back to the internal browser UA.\n\nDefault: browser" }, { "name": "engine", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x2a" } ] }, "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering" }, { "name": "injectPageScript", "in": "query", "schema": { "type": "string" }, "description": "JavaScript to run in each result page before extraction, inline or as a URL." }, { "name": "injectFrameScript", "in": "query", "schema": { "type": "string" }, "description": "Like `injectPageScript`, for frames." }, { "name": "timeout", "in": "query", "schema": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v > 0 && v <= 180" } }, { "name": "locale", "in": "query", "schema": { "type": "string" }, "description": "Specify browser locale for the page." }, { "name": "referer", "in": "query", "schema": { "type": "string" }, "description": "Specify referer for the page." }, { "name": "tokenBudget", "in": "query", "schema": { "type": "number" }, "description": "Specify a budget in tokens.\n\nIf the resulting token cost exceeds the budget, the request is rejected.\n\nNote this parameter is ignored for the search endpoint." }, { "name": "assertStatusCode", "in": "query", "schema": { "type": "number" }, "description": "Assert the HTTP status code of the crawled page. If the actual status code does not match the asserted one, the request is rejected with 422 Unprocessable Entity." }, { "name": "instruction", "in": "query", "schema": { "type": "string" } }, { "name": "jsonSchema", "in": "query", "schema": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true } }, { "name": "robotsTxt", "in": "query", "schema": { "type": "string" }, "description": "Load and conform to the respective robot.txt on the target origin.\n\nOptionally specify a bot UA to check against." }, { "name": "zeroDataRetention", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] } }, { "name": "respondTiming", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x25" } ] }, "description": "Explicitly specify the respond timing. One of the following:\n\n- html: directly return unrendered HTML\n- visible-content: return immediately when any content becomes available\n- mutation-idle: wait for DOM mutations to settle and remain unchanged for at least 0.2s\n- resource-idle: wait for no additional resources that would affect page logic and content has SUCCEEDED loading in 0.5s\n- media-idle: wait for no additional resources, including media resources, has SUCCEEDED loading in 0.5s\n- network-idle: wait for full load of webpage, also known as networkidle0." }, { "name": "markdownChunking", "in": "query", "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x26" } ] }, { "type": "string" } ] }, "description": "Opt-in markdown chunking.\n\nSupported values: \n- true\n- h1\n- h2\n- h3\n- h4\n- h5\n- structured\n- s1\n- s2\n- s3\n- s4\n- s5\n\nNote if you are expecting text return, the chunking is done by injecting character \\u001D" }, { "name": "maxTokens", "in": "query", "schema": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v >= 500" } }, { "name": "ext", "in": "query", "schema": { "summary": "Returns web pages with a specific file extension. Example: to find the Honda GX120 Owner’s manual in PDF, type “Honda GX120 ownners manual ext:pdf”.", "description": "Returns web pages with a specific file extension. Example: to find the Honda GX120 Owner’s manual in PDF, type “Honda GX120 ownners manual ext:pdf”.", "type": "string" }, "description": "Search operator `ext:` (file extension)." }, { "name": "filetype", "in": "query", "schema": { "summary": "Returns web pages created in the specified file type. Example: to find a web page created in PDF format about the evaluation of age-related cognitive changes, type “evaluation of age cognitive changes filetype:pdf”.", "description": "Returns web pages created in the specified file type. Example: to find a web page created in PDF format about the evaluation of age-related cognitive changes, type “evaluation of age cognitive changes filetype:pdf”.", "type": "string" }, "description": "Search operator `filetype:`, e.g. `pdf`." }, { "name": "intitle", "in": "query", "schema": { "summary": "Returns webpages containing the specified term in the title of the page. Example: to find pages about SEO conferences making sure the results contain 2023 in the title, type “seo conference intitle:2023”.", "description": "Returns webpages containing the specified term in the title of the page. Example: to find pages about SEO conferences making sure the results contain 2023 in the title, type “seo conference intitle:2023”.", "type": "string" }, "description": "Search operator `intitle:`: words that must appear in the page title." }, { "name": "loc", "in": "query", "schema": { "summary": "Returns web pages written in the specified language. The language code must be in the ISO 639-1 two-letter code format. Example: to find information on visas only in Spanish, type “visas lang:es”.", "description": "Returns web pages written in the specified language. The language code must be in the ISO 639-1 two-letter code format. Example: to find information on visas only in Spanish, type “visas lang:es”.", "type": "string" }, "description": "Search operator `loc:` (location)." }, { "name": "site", "in": "query", "schema": { "summary": "Returns web pages coming only from a specific web site. Example: to find information about Goggles only on Brave pages, type “goggles site:brave.com”.", "description": "Returns web pages coming only from a specific web site. Example: to find information about Goggles only on Brave pages, type “goggles site:brave.com”.", "type": "string" }, "description": "Keep results to this domain, e.g. `https://jina.ai`. Same as the `X-Site` header." }, { "name": "type", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x29" } ], "default": "web" }, "description": "Result type: `web` (default), `images` or `news`." }, { "name": "num", "in": "query", "schema": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v >= 0 && v <= 20" }, "description": "Maximum number of results, 0 to 20, default 10. Larger values can add latency and drop special result types." }, { "name": "count", "in": "query", "schema": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v >= 0 && v <= 20" }, "description": "Same as `num`." }, { "name": "provider", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x2b" } ] }, "description": "Search engine to use: `google`, `bing` or `reader`." }, { "name": "gl", "in": "query", "schema": { "type": "string", "description": "- Some validators will be applied on value(s): (v) => WORLD_COUNTRY_CODES.includes(v?.toLowerCase())" }, "description": "Country to search from, as a two-letter country code." }, { "name": "hl", "in": "query", "schema": { "type": "string", "description": "- Some validators will be applied on value(s): (v) => serper_search_2.WORLD_LANGUAGES.some(l => l.code === v)" }, "description": "Language of the search, as a two-letter language code." }, { "name": "location", "in": "query", "schema": { "type": "string" }, "description": "Where the search should originate from. City level works best." }, { "name": "fallback", "in": "query", "schema": { "type": "boolean" }, "description": "If `true` and the search returns nothing, fall back to local search results. Default `false`." }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "The search query. Not needed when the query is already in the path (`https://s.jina.ai/`)." }, { "name": "nfpr", "in": "query", "schema": { "type": "boolean" }, "description": "Passed to the search engine; on Google, `true` turns off query auto-correction." }, { "name": "Accept", "description": "Specifies your preference for the response format.\n\nSupported formats: \n- text/event-stream\n- application/json or text/json\n- text/plain", "in": "header", "schema": { "type": "string" } }, { "name": "X-Cache-Tolerance", "description": "Sets internal cache tolerance in seconds if this header is specified with a integer.", "in": "header", "schema": { "type": "string" } }, { "name": "X-No-Cache", "description": "Ignores internal cache if this header is specified with a value.\n\nEquivalent to X-Cache-Tolerance: 0", "in": "header", "schema": { "type": "string" } }, { "name": "X-Respond-With", "description": "Specifies the (non-default) form of the crawled data you prefer.\n\nSupported formats: \n- markdown\n- html\n- text\n- pageshot\n- screenshot\n- content\n- frontmatter\n- any combination of the above\n- vlm\n- jina-ocr-v1\n- jina-ocr\n- readerlm-v2\n\nDefault: content", "in": "header", "schema": { "type": "string" } }, { "name": "X-Wait-For-Selector", "description": "Specifies a CSS selector to wait for the appearance of such an element before returning.\n\nExample: `X-Wait-For-Selector: .content-block`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Target-Selector", "description": "Specifies a CSS selector for return target instead of the full html.\n\nImplies `X-Wait-For-Selector: (same selector)`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Remove-Selector", "description": "Specifies a CSS selector to remove elements from the full html.\n\nExample `X-Remove-Selector: nav`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Keep-Img-Data-Url", "description": "Keep data-url as it instead of transforming them to object-url. (Only applicable when targeting markdown format)\n\nExample `X-Keep-Img-Data-Url: true`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Proxy-Url", "description": "Specifies your custom proxy if you prefer to use one.\n\nSupported protocols: \n- http\n- https\n- socks4\n- socks5\n\nFor authentication, https://user:pass@host:port", "in": "header", "schema": { "type": "string" } }, { "name": "X-Proxy-Resources", "description": "Whether to load resources like image/style/scripts via the proxy server.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Proxy", "description": "Use a proxy server provided by us.\n\nOptionally specify two-letter country code.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Robots-Txt", "description": "Load and conform to the respective robot.txt on the target origin.\n\nOptionally specify a bot UA to check against.", "in": "header", "schema": { "type": "string" } }, { "name": "DNT", "description": "When set to 1, prevent the result of this request to be cached in the system.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Set-Cookie", "description": "Sets cookie(s) to the headless browser for your request. \n\nSyntax is the same with standard Set-Cookie", "in": "header", "schema": { "type": "string" } }, { "name": "X-Export-Storage-State", "description": "Export the browser storage state (cookies and per-origin localStorage) accumulated during the crawl.\n\nWhen enabled, the JSON response includes a `storageState` field whose shape mirrors the `storageState` request option, so it can be fed back into a subsequent request.\n\nRequires the browser engine and disables caching.", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Generated-Alt", "description": "Enable automatic alt-text generating for images without an meaningful alt-text.\n\nNote: Does not work when `X-Respond-With` is specified", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Images-Summary", "description": "Enable dedicated summary section for images on the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-links-Summary", "description": "Enable dedicated summary section for hyper links on the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Retain-Links", "description": "Link retention modes.\n\nSupported modes: \n- all: all links\n- none: no links\n- text: only link text\n- gpt-oss: gpt-oss link citation format `【{id}†.*】`", "in": "header", "schema": { "type": "string" } }, { "name": "X-Retain-Images", "description": "Image retention modes.\n\nSupported modes: \n- all: all images\n- none: no images\n- alt: only alt text\n- all_p: all images and with generated alt text\n- alt_p: only alt text and with generated alt", "in": "header", "schema": { "type": "string" } }, { "name": "X-Retain-Media", "description": "Media retention modes for video, audio, and embedded video iframes.\n\nSupported modes: \n- none: no media\n- text: plain label, e.g. `Video 1`\n- link: markdown link, e.g. `[Video 1](url)` (default)\n- image: markdown image syntax, e.g. `![Video 1](url)`\n- html: original HTML with irrelevant attributes (class, id, style, data-*, aria-*) stripped", "in": "header", "schema": { "type": "string" } }, { "name": "X-Preset", "description": "Apply a preset configuration for common scenarios.\n\nSupported presets:\n- reader: optimized for display to human users\n- index: optimized for semantic indexing\n- research: optimized for academic/research AI agents\n- agent: optimized for day-to-day AI agents\n- spider: optimized for recursive site crawling\n\nPreset values are applied only to options not explicitly set by the caller.", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Iframe", "description": "Enable filling iframe contents into main. (violates standards)", "in": "header", "schema": { "type": "string" } }, { "name": "X-With-Shadow-Dom", "description": "Enable filling shadow dom contents into main. (violates standards)", "in": "header", "schema": { "type": "string" } }, { "name": "X-Skip-Cert-Verification", "description": "Enable skipping SSL certificate verification. (violates security best practices)", "in": "header", "schema": { "type": "string" } }, { "name": "X-User-Agent", "description": "Override User-Agent.\n\nSeveral special values: \n- browser: use the internal browser UA\n- auto: pass-through your UA if it starts with `Mozilla/5.0`, otherwise use the internal browser UA\n- inherit / pass-through: use the User-Agent from the request context if applicable\n- bot: Use a pre-defined bot User-Agent from this service\n- diversify: Use a diversified browser User-Agent\n\nOr specify your own user agent string.\n\nNote: anonymous users specifying a browser UA will have no effect and will fall back to the internal browser UA.\n\nDefault: browser", "in": "header", "schema": { "type": "string" } }, { "name": "X-Timeout", "description": "Specify timeout in seconds. Max 180.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Locale", "description": "Specify browser locale for the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Referer", "description": "Specify referer for the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Token-Budget", "description": "Specify a budget in tokens.\n\nIf the resulting token cost exceeds the budget, the request is rejected.\n\nNote this parameter is ignored for the search endpoint.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Max-Tokens", "description": "Trim the response content at a maximum number of tokens.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Assert-Status-Code", "description": "Assert the HTTP status code of the crawled page. If the actual status code does not match the asserted one, the request is rejected with 422 Unprocessable Entity.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Respond-Timing", "description": "Explicitly specify the respond timing. One of the following:\n\n- html: directly return unrendered HTML\n- visible-content: return immediately when any content becomes available\n- mutation-idle: wait for DOM mutations to settle and remain unchanged for at least 0.2s\n- resource-idle: wait for no additional resources that would affect page logic and content has SUCCEEDED loading in 0.5s\n- media-idle: wait for no additional resources, including media resources, has SUCCEEDED loading in 0.5s\n- network-idle: wait for full load of webpage, also known as networkidle0.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Engine", "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering", "in": "header", "schema": { "type": "string" } }, { "name": "X-Base", "description": "Select base modes of relative URLs.\n\nSupported: initial, final", "in": "header", "schema": { "type": "string" } }, { "name": "X-Remove-Overlay", "description": "Specify whether to remove overlay elements from the page.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Detach-Invisibles", "description": "Temporarily detach elements with computed `display:none` before snapshotting, then restore them.\n\nRequires the browser engine and disables caching.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Markdown-Chunking", "description": "Opt-in markdown chunking.\n\nSupported values: \n- true\n- h1\n- h2\n- h3\n- h4\n- h5\n- structured\n- s1\n- s2\n- s3\n- s4\n- s5\n\nNote if you are expecting text return, the chunking is done by injecting character \\u001D", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Heading-Style", "description": "Heading style of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: setext, atx", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Hr", "description": "Hr text of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Bullet-List-Marker", "description": "Bullet list marker of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: -, +, *", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Em-Delimiter", "description": "Em delimiter of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: _, *", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Strong-Delimiter", "description": "Strong delimiter of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: **, __", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Link-Style", "description": "Link style of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: inlined, referenced, discarded", "in": "header", "schema": { "type": "string" } }, { "name": "X-Md-Link-Reference-Style", "description": "Link reference style of the generated markdown.\n\nThis is an option passed through to [Turndown](https://github.com/mixmark-io/turndown?tab=readme-ov-file#options).\n\nSupported: full, collapsed, shortcut, discarded", "in": "header", "schema": { "type": "string" } }, { "name": "X-Page", "description": "Steer which page to return for uploaded files (PDF, DOC, XLS, PPT, etc.).\n\n1-indexed; ignored when no file/PDF is uploaded.", "in": "header", "schema": { "type": "string" } }, { "name": "X-Preload-Url", "description": "URL to preload before scraping.\n\nIgnored when no URL is provided.", "in": "header", "schema": { "type": "string" } }, { "name": "X-No-Service-Worker", "description": "Disable service workers when running the browser.\n\nUseful for bypassing service-worker-based caching or interception.", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_JinaEmbeddingsAuthDTO@0x0c" }, { "$ref": "#/components/schemas/Search_CrawlerOptions@0x27" }, { "$ref": "#/components/schemas/Search_GoogleSearchExplicitOperatorsDto@0x28" }, { "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x29" } ], "default": "web", "description": "Result type: `web` (default), `images` or `news`." }, "num": { "type": "number", "description": "Maximum number of results, 0 to 20, default 10. Larger values can add latency and drop special result types." }, "count": { "type": "number", "description": "Same as `num`." }, "engine": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x2a" } ], "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering" }, "provider": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x2b" } ], "description": "Search engine to use: `google`, `bing` or `reader`." }, "gl": { "type": "string", "description": "Country to search from, as a two-letter country code." }, "hl": { "type": "string", "description": "Language of the search, as a two-letter language code." }, "location": { "type": "string", "description": "Where the search should originate from. City level works best." }, "page": { "type": "number", "description": "Steer which page to return for uploaded files (PDF, DOC, XLS, PPT, etc.).\n\n1-indexed; ignored when no file/PDF is uploaded." }, "fallback": { "type": "boolean", "description": "If `true` and the search returns nothing, fall back to local search results. Default `false`." }, "q": { "type": "string", "description": "The search query. Not needed when the query is already in the path (`https://s.jina.ai/`)." }, "nfpr": { "type": "boolean", "description": "Passed to the search engine; on Google, `true` turns off query auto-correction." } } } ] } }, "multipart/form-data": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_JinaEmbeddingsAuthDTO@0x0c" }, { "$ref": "#/components/schemas/Search_CrawlerOptions@0x27" }, { "$ref": "#/components/schemas/Search_GoogleSearchExplicitOperatorsDto@0x28" }, { "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x29" } ], "default": "web", "description": "Result type: `web` (default), `images` or `news`." }, "num": { "type": "number", "description": "Maximum number of results, 0 to 20, default 10. Larger values can add latency and drop special result types." }, "count": { "type": "number", "description": "Same as `num`." }, "engine": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x2a" } ], "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering" }, "provider": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x2b" } ], "description": "Search engine to use: `google`, `bing` or `reader`." }, "gl": { "type": "string", "description": "Country to search from, as a two-letter country code." }, "hl": { "type": "string", "description": "Language of the search, as a two-letter language code." }, "location": { "type": "string", "description": "Where the search should originate from. City level works best." }, "page": { "type": "number", "description": "Steer which page to return for uploaded files (PDF, DOC, XLS, PPT, etc.).\n\n1-indexed; ignored when no file/PDF is uploaded." }, "fallback": { "type": "boolean", "description": "If `true` and the search returns nothing, fall back to local search results. Default `false`." }, "q": { "type": "string", "description": "The search query. Not needed when the query is already in the path (`https://s.jina.ai/`)." }, "nfpr": { "type": "boolean", "description": "Passed to the search engine; on Google, `true` turns off query auto-correction." } } } ] } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL to read. Not needed when the URL is already in the path (`https://r.jina.ai/`)." }, "preloadUrl": { "type": "string", "description": "URL to preload before scraping.\n\nIgnored when no URL is provided." }, "noServiceWorker": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Disable service workers when running the browser.\n\nUseful for bypassing service-worker-based caching or interception." }, "html": { "type": "string", "description": "Raw HTML to convert, instead of fetching a URL. Used when no `url` is given." }, "base": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x0e" } ], "default": "initial", "description": "Select base modes of relative URLs.\n\nSupported: initial, final" }, "pdf": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_FancyFile@0x0f" } ] }, { "type": "string" } ], "summary": "Base64 encoded PDF.", "description": "Base64 encoded PDF." }, "file": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_FancyFile@0x0f" } ] }, { "type": "string" } ], "summary": "Base64 encoded file.", "description": "Base64-encoded file (PDF, DOC, XLS, PPT, ...) to convert instead of a URL." }, "page": { "type": "number", "description": "Steer which page to return for uploaded files (PDF, DOC, XLS, PPT, etc.).\n\n1-indexed; ignored when no file/PDF is uploaded." }, "respondWith": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x10" } ] }, { "type": "string" } ], "default": "content", "description": "Specifies the (non-default) form of the crawled data you prefer.\n\nSupported formats: \n- markdown\n- html\n- text\n- pageshot\n- screenshot\n- content\n- frontmatter\n- any combination of the above\n- vlm\n- jina-ocr-v1\n- jina-ocr\n- readerlm-v2\n\nDefault: content" }, "withGeneratedAlt": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ], "description": "Enable automatic alt-text generating for images without an meaningful alt-text.\n\nNote: Does not work when `X-Respond-With` is specified" }, "retainImages": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x12" } ], "default": "all", "description": "Image retention modes.\n\nSupported modes: \n- all: all images\n- none: no images\n- alt: only alt text\n- all_p: all images and with generated alt text\n- alt_p: only alt text and with generated alt" }, "retainMedia": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x13" } ], "default": "link", "description": "Media retention modes for video, audio, and embedded video iframes.\n\nSupported modes: \n- none: no media\n- text: plain label, e.g. `Video 1`\n- link: markdown link, e.g. `[Video 1](url)` (default)\n- image: markdown image syntax, e.g. `![Video 1](url)`\n- html: original HTML with irrelevant attributes (class, id, style, data-*, aria-*) stripped" }, "preset": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x14" } ], "description": "Apply a preset configuration for common scenarios.\n\nSupported presets:\n- reader: optimized for display to human users\n- index: optimized for semantic indexing\n- research: optimized for academic/research AI agents\n- agent: optimized for day-to-day AI agents\n- spider: optimized for recursive site crawling\n\nPreset values are applied only to options not explicitly set by the caller." }, "retainLinks": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x15" } ], "default": "all", "description": "Link retention modes.\n\nSupported modes: \n- all: all links\n- none: no links\n- text: only link text\n- gpt-oss: gpt-oss link citation format `【{id}†.*】`" }, "withLinksSummary": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ] }, { "type": "string" } ], "description": "Enable dedicated summary section for hyper links on the page." }, "withImagesSummary": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Enable dedicated summary section for images on the page." }, "noCache": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Ignores internal cache if this header is specified with a value.\n\nEquivalent to X-Cache-Tolerance: 0" }, "removeOverlay": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Specify whether to remove overlay elements from the page." }, "detachInvisibles": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Temporarily detach elements with computed `display:none` before snapshotting, then restore them.\n\nRequires the browser engine and disables caching." }, "noGfm": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ] }, { "type": "string" } ], "description": "Opt out of GitHub Flavored Markdown. `true` disables GFM; `table` drops only GFM tables and keeps the table HTML." }, "cacheTolerance": { "type": "number", "description": "Sets internal cache tolerance in seconds if this header is specified with a integer." }, "targetSelector": { "type": "string", "description": "Specifies a CSS selector for return target instead of the full html.\n\nImplies `X-Wait-For-Selector: (same selector)`" }, "waitForSelector": { "type": "string", "description": "Specifies a CSS selector to wait for the appearance of such an element before returning.\n\nExample: `X-Wait-For-Selector: .content-block`" }, "removeSelector": { "type": "string", "description": "Specifies a CSS selector to remove elements from the full html.\n\nExample `X-Remove-Selector: nav`" }, "keepImgDataUrl": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Keep data-url as it instead of transforming them to object-url. (Only applicable when targeting markdown format)\n\nExample `X-Keep-Img-Data-Url: true`" }, "withIframe": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ] }, { "type": "string" } ], "description": "Enable filling iframe contents into main. (violates standards)" }, "withShadowDom": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Enable filling shadow dom contents into main. (violates standards)" }, "skipCertVerification": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Enable skipping SSL certificate verification. (violates security best practices)" }, "setCookies": { "oneOf": [ { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, { "type": "string" } ], "description": "Cookies to send when fetching each result page, for pages that need a login. Requests with cookies are not cached." }, "exportStorageState": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Export the browser storage state (cookies and per-origin localStorage) accumulated during the crawl.\n\nWhen enabled, the JSON response includes a `storageState` field whose shape mirrors the `storageState` request option, so it can be fed back into a subsequent request.\n\nRequires the browser engine and disables caching." }, "proxyUrl": { "type": "string", "description": "Specifies your custom proxy if you prefer to use one.\n\nSupported protocols: \n- http\n- https\n- socks4\n- socks5\n\nFor authentication, https://user:pass@host:port" }, "proxyResources": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Whether to load resources like image/style/scripts via the proxy server." }, "proxy": { "type": "string", "description": "Use a proxy server provided by us.\n\nOptionally specify two-letter country code." }, "userAgent": { "type": "string", "description": "Override User-Agent.\n\nSeveral special values: \n- browser: use the internal browser UA\n- auto: pass-through your UA if it starts with `Mozilla/5.0`, otherwise use the internal browser UA\n- inherit / pass-through: use the User-Agent from the request context if applicable\n- bot: Use a pre-defined bot User-Agent from this service\n- diversify: Use a diversified browser User-Agent\n\nOr specify your own user agent string.\n\nNote: anonymous users specifying a browser UA will have no effect and will fall back to the internal browser UA.\n\nDefault: browser" }, "engine": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x2a" } ], "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering" }, "injectPageScript": { "type": "string", "description": "JavaScript to run in each result page before extraction, inline or as a URL." }, "injectFrameScript": { "type": "string", "description": "Like `injectPageScript`, for frames." }, "timeout": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v > 0 && v <= 180" }, "locale": { "type": "string", "description": "Specify browser locale for the page." }, "referer": { "type": "string", "description": "Specify referer for the page." }, "tokenBudget": { "type": "number", "description": "Specify a budget in tokens.\n\nIf the resulting token cost exceeds the budget, the request is rejected.\n\nNote this parameter is ignored for the search endpoint." }, "assertStatusCode": { "type": "number", "description": "Assert the HTTP status code of the crawled page. If the actual status code does not match the asserted one, the request is rejected with 422 Unprocessable Entity." }, "instruction": { "type": "string" }, "jsonSchema": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "robotsTxt": { "type": "string", "description": "Load and conform to the respective robot.txt on the target origin.\n\nOptionally specify a bot UA to check against." }, "zeroDataRetention": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "respondTiming": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x25" } ], "description": "Explicitly specify the respond timing. One of the following:\n\n- html: directly return unrendered HTML\n- visible-content: return immediately when any content becomes available\n- mutation-idle: wait for DOM mutations to settle and remain unchanged for at least 0.2s\n- resource-idle: wait for no additional resources that would affect page logic and content has SUCCEEDED loading in 0.5s\n- media-idle: wait for no additional resources, including media resources, has SUCCEEDED loading in 0.5s\n- network-idle: wait for full load of webpage, also known as networkidle0." }, "markdownChunking": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x26" } ] }, { "type": "string" } ], "description": "Opt-in markdown chunking.\n\nSupported values: \n- true\n- h1\n- h2\n- h3\n- h4\n- h5\n- structured\n- s1\n- s2\n- s3\n- s4\n- s5\n\nNote if you are expecting text return, the chunking is done by injecting character \\u001D" }, "maxTokens": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v >= 500" }, "ext": { "summary": "Returns web pages with a specific file extension. Example: to find the Honda GX120 Owner’s manual in PDF, type “Honda GX120 ownners manual ext:pdf”.", "description": "Search operator `ext:` (file extension).", "type": "string" }, "filetype": { "summary": "Returns web pages created in the specified file type. Example: to find a web page created in PDF format about the evaluation of age-related cognitive changes, type “evaluation of age cognitive changes filetype:pdf”.", "description": "Search operator `filetype:`, e.g. `pdf`.", "type": "string" }, "intitle": { "summary": "Returns webpages containing the specified term in the title of the page. Example: to find pages about SEO conferences making sure the results contain 2023 in the title, type “seo conference intitle:2023”.", "description": "Search operator `intitle:`: words that must appear in the page title.", "type": "string" }, "loc": { "summary": "Returns web pages written in the specified language. The language code must be in the ISO 639-1 two-letter code format. Example: to find information on visas only in Spanish, type “visas lang:es”.", "description": "Search operator `loc:` (location).", "type": "string" }, "site": { "summary": "Returns web pages coming only from a specific web site. Example: to find information about Goggles only on Brave pages, type “goggles site:brave.com”.", "description": "Keep results to this domain, e.g. `https://jina.ai`. Same as the `X-Site` header.", "type": "string" }, "type": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x29" } ], "default": "web", "description": "Result type: `web` (default), `images` or `news`." }, "num": { "type": "number", "description": "Maximum number of results, 0 to 20, default 10. Larger values can add latency and drop special result types." }, "count": { "type": "number", "description": "Same as `num`." }, "provider": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x2b" } ], "description": "Search engine to use: `google`, `bing` or `reader`." }, "gl": { "type": "string", "description": "Country to search from, as a two-letter country code." }, "hl": { "type": "string", "description": "Language of the search, as a two-letter language code." }, "location": { "type": "string", "description": "Where the search should originate from. City level works best." }, "fallback": { "type": "boolean", "description": "If `true` and the search returns nothing, fall back to local search results. Default `false`." }, "q": { "type": "string", "description": "The search query. Not needed when the query is already in the path (`https://s.jina.ai/`)." }, "nfpr": { "type": "boolean", "description": "Passed to the search engine; on Google, `true` turns off query auto-correction." } } } } } }, "responses": { "200": { "description": "OK", "content": { "text/plain; charset=utf-8": { "schema": { "type": "string" } }, "application/json": { "schema": { "title": "ReaderEnvelopeWrappedArray", "type": "object", "properties": { "code": { "type": "number", "summary": "Envelope code.\n\nMirror of HTTP status code", "description": "[REQUIRED]\n\nEnvelope code.\n\nMirror of HTTP status code", "default": 200 }, "status": { "type": "number", "summary": "Envelope status.\n\nIn extension to HTTP status code", "description": "[REQUIRED]\n\nEnvelope status.\n\nIn extension to HTTP status code", "default": 20000 }, "data": { "allOf": [ { "$ref": "#/components/schemas/Search_Array@0x3e" } ], "summary": "The result payload you expect", "description": "The result payload you expect" }, "meta": { "description": "The metadata that the payload sometimes came with", "nullable": true, "summary": "The metadata that the payload sometimes came with" } }, "required": [ "code", "status" ], "primitive": true } }, "text/event-stream": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_OutputServerEventStream@0x34" } ] } } }, "headers": {} }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_ParamValidationError@0x35" } ] } } }, "headers": {} }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_AuthenticationFailedError@0x36" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Search_AuthenticationRequiredError@0x37" } ] } ] } } }, "headers": {} }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_InsufficientBalanceError@0x38" } ] } } }, "headers": {} }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_AbuseAlleviationError@0x39" } ] } } }, "headers": {} }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_AssertionFailureError@0x3a" } ] } } }, "headers": {} }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_RateLimitTriggeredError@0x3b" } ] } } }, "headers": {} }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_DownstreamServiceError@0x3c" } ] } } }, "headers": {} }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Search_ServiceBadAttemptError@0x3d" } ] } } }, "headers": {} } }, "summary": "Search the web (JSON body)", "operationId": "search_post_search", "security": [ { "HTTPBearer": [] }, {} ], "description": "Send `{\"q\": \"...\"}` as JSON, optionally with `gl`, `hl`, `location`, `num` and `page`. Same `X-*` headers as the GET form." }, "servers": [ { "url": "https://s.jina.ai" } ] }, "/v1/embeddings": { "post": { "tags": [ "Search Foundation Models" ], "summary": "Embeddings", "description": "Embed text, images, audio, video or PDFs as dense vectors.\n\n`model` selects the request shape as well as the model: each one below\nlists the inputs and options it accepts.", "operationId": "embeddings_v1_embeddings_post", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/EmbeddingsV2Request" }, { "$ref": "#/components/schemas/EmbeddingsV3Request" }, { "$ref": "#/components/schemas/EmbeddingsV4Request" }, { "$ref": "#/components/schemas/EmbeddingsV5Request" }, { "$ref": "#/components/schemas/CodeEmbeddings500MRequest" }, { "$ref": "#/components/schemas/CodeEmbeddings1500MRequest" }, { "$ref": "#/components/schemas/ClipV1Request" }, { "$ref": "#/components/schemas/ClipV2Request" }, { "$ref": "#/components/schemas/ColbertV1Request" }, { "$ref": "#/components/schemas/ColbertV2Request" } ], "title": "Embedding Request", "discriminator": { "propertyName": "model", "mapping": { "jina-embeddings-v2-base-en": "#/components/schemas/EmbeddingsV2Request", "jina-embeddings-v2-base-zh": "#/components/schemas/EmbeddingsV2Request", "jina-embeddings-v2-base-de": "#/components/schemas/EmbeddingsV2Request", "jina-embeddings-v2-base-es": "#/components/schemas/EmbeddingsV2Request", "jina-embeddings-v2-base-code": "#/components/schemas/EmbeddingsV2Request", "jina-embeddings-v3": "#/components/schemas/EmbeddingsV3Request", "jina-embeddings-v4": "#/components/schemas/EmbeddingsV4Request", "jina-embeddings-v5-text-nano": "#/components/schemas/EmbeddingsV5Request", "jina-embeddings-v5-text-small": "#/components/schemas/EmbeddingsV5Request", "jina-embeddings-v5-omni-small": "#/components/schemas/EmbeddingsV5Request", "jina-embeddings-v5-omni-nano": "#/components/schemas/EmbeddingsV5Request", "jina-code-embeddings-0.5b": "#/components/schemas/CodeEmbeddings500MRequest", "jina-code-embeddings-1.5b": "#/components/schemas/CodeEmbeddings1500MRequest", "jina-clip-v1": "#/components/schemas/ClipV1Request", "jina-clip-v2": "#/components/schemas/ClipV2Request", "jina-colbert-v1-en": "#/components/schemas/ColbertV1Request", "jina-colbert-v2": "#/components/schemas/ColbertV2Request" } } } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingResponse" } } } }, "400": { "description": "Bad Request: `INPUT_INVALID_LABELS`, `INPUT_LABEL_LIMIT_EXCEEDED`, `INPUT_MODEL_NOT_FOUND`, `INPUT_TOKEN_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized: `AUTH_INVALID_API_KEY`, `AUTH_INVALID_FORMAT`, `AUTH_MISSING_API_KEY`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden: `AUTHZ_INSUFFICIENT_BALANCE`, `AUTHZ_RESOURCE_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found: `RESOURCE_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict: `CONFLICT_RESOURCE_BUSY`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request body failed schema validation. `errors` names each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests: `RATE_CONCURRENCY_LIMIT_EXCEEDED`, `RATE_IP_LIMIT_EXCEEDED`, `RATE_REQUEST_LIMIT_EXCEEDED`, `RATE_TOKEN_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error: `INTERNAL_ERROR`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable: `SERVICE_UNAVAILABLE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout: `SERVICE_TIMEOUT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/rerank": { "post": { "tags": [ "Search Foundation Models" ], "summary": "Rerank", "description": "Score documents against a query and return them reordered.\n\nResults come back sorted by `relevance_score`, each carrying the index\nit held in the request so the caller can map them back.", "operationId": "rerank_v1_rerank_post", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TextRerankerRequest" }, { "$ref": "#/components/schemas/RerankerM0Request" }, { "$ref": "#/components/schemas/RerankerV3Request" } ], "title": "Reranking Request", "discriminator": { "propertyName": "model", "mapping": { "jina-reranker-v2-base-multilingual": "#/components/schemas/TextRerankerRequest", "jina-reranker-v1-tiny-en": "#/components/schemas/TextRerankerRequest", "jina-reranker-v1-turbo-en": "#/components/schemas/TextRerankerRequest", "jina-reranker-v1-base-en": "#/components/schemas/TextRerankerRequest", "jina-colbert-v1-en": "#/components/schemas/TextRerankerRequest", "jina-colbert-v2": "#/components/schemas/TextRerankerRequest", "jina-reranker-m0": "#/components/schemas/RerankerM0Request", "jina-reranker-v3": "#/components/schemas/RerankerV3Request", "jina-reranker-v3.5": "#/components/schemas/RerankerV3Request" } } } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RerankingResponse" } } } }, "400": { "description": "Bad Request: `INPUT_INVALID_LABELS`, `INPUT_LABEL_LIMIT_EXCEEDED`, `INPUT_MODEL_NOT_FOUND`, `INPUT_TOKEN_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized: `AUTH_INVALID_API_KEY`, `AUTH_INVALID_FORMAT`, `AUTH_MISSING_API_KEY`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden: `AUTHZ_INSUFFICIENT_BALANCE`, `AUTHZ_RESOURCE_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found: `RESOURCE_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict: `CONFLICT_RESOURCE_BUSY`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request body failed schema validation. `errors` names each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests: `RATE_CONCURRENCY_LIMIT_EXCEEDED`, `RATE_IP_LIMIT_EXCEEDED`, `RATE_REQUEST_LIMIT_EXCEEDED`, `RATE_TOKEN_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error: `INTERNAL_ERROR`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable: `SERVICE_UNAVAILABLE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout: `SERVICE_TIMEOUT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/models": { "get": { "tags": [ "Model List" ], "summary": "List Models", "description": "Every model in the catalogue, with its modalities, limits and price.", "operationId": "list_models_v1_models_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelListResponse" } } } }, "400": { "description": "Bad Request: `INPUT_INVALID_LABELS`, `INPUT_LABEL_LIMIT_EXCEEDED`, `INPUT_MODEL_NOT_FOUND`, `INPUT_TOKEN_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized: `AUTH_INVALID_API_KEY`, `AUTH_INVALID_FORMAT`, `AUTH_MISSING_API_KEY`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden: `AUTHZ_INSUFFICIENT_BALANCE`, `AUTHZ_RESOURCE_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found: `RESOURCE_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict: `CONFLICT_RESOURCE_BUSY`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request body failed schema validation. `errors` names each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests: `RATE_CONCURRENCY_LIMIT_EXCEEDED`, `RATE_IP_LIMIT_EXCEEDED`, `RATE_REQUEST_LIMIT_EXCEEDED`, `RATE_TOKEN_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error: `INTERNAL_ERROR`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable: `SERVICE_UNAVAILABLE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout: `SERVICE_TIMEOUT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/models/{model_id}": { "get": { "tags": [ "Model List" ], "summary": "Get Model", "description": "One model by id, in full (`jina-ai/jina-embeddings-v3`) or short\n(`jina-embeddings-v3`) form.", "operationId": "get_model_v1_models__model_id__get", "parameters": [ { "name": "model_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Model Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelInfo" } } } }, "400": { "description": "Bad Request: `INPUT_INVALID_LABELS`, `INPUT_LABEL_LIMIT_EXCEEDED`, `INPUT_MODEL_NOT_FOUND`, `INPUT_TOKEN_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized: `AUTH_INVALID_API_KEY`, `AUTH_INVALID_FORMAT`, `AUTH_MISSING_API_KEY`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden: `AUTHZ_INSUFFICIENT_BALANCE`, `AUTHZ_RESOURCE_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found: `RESOURCE_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict: `CONFLICT_RESOURCE_BUSY`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request body failed schema validation. `errors` names each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests: `RATE_CONCURRENCY_LIMIT_EXCEEDED`, `RATE_IP_LIMIT_EXCEEDED`, `RATE_REQUEST_LIMIT_EXCEEDED`, `RATE_TOKEN_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error: `INTERNAL_ERROR`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable: `SERVICE_UNAVAILABLE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout: `SERVICE_TIMEOUT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/chat/completions": { "post": { "tags": [ "Generative Models" ], "summary": "Chat Completions", "description": "Transcribe a document image. Send the page as an `image_url` content part and the reply is its text; `response_format` with a `json_schema` constrains that to a schema instead.", "operationId": "chat_completions_v1_chat_completions_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" } } }, "required": true }, "responses": { "200": { "description": "An OpenAI chat completion, or a stream of `chat.completion.chunk` events when `stream` is true.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request: `INPUT_INVALID_LABELS`, `INPUT_LABEL_LIMIT_EXCEEDED`, `INPUT_MODEL_NOT_FOUND`, `INPUT_TOKEN_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorResponse" } } } }, "401": { "description": "Unauthorized: `AUTH_INVALID_API_KEY`, `AUTH_INVALID_FORMAT`, `AUTH_MISSING_API_KEY`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden: `AUTHZ_INSUFFICIENT_BALANCE`, `AUTHZ_RESOURCE_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found: `RESOURCE_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorResponse" } } } }, "409": { "description": "Conflict: `CONFLICT_RESOURCE_BUSY`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorResponse" } } } }, "422": { "description": "The request body failed schema validation. `errors` names each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests: `RATE_CONCURRENCY_LIMIT_EXCEEDED`, `RATE_IP_LIMIT_EXCEEDED`, `RATE_REQUEST_LIMIT_EXCEEDED`, `RATE_TOKEN_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error: `INTERNAL_ERROR`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorResponse" } } } }, "503": { "description": "Service Unavailable: `SERVICE_UNAVAILABLE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorResponse" } } } }, "504": { "description": "Gateway Timeout: `SERVICE_TIMEOUT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIErrorResponse" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/batch/embeddings": { "post": { "tags": [ "Batch Embeddings" ], "summary": "Create a batch embedding job", "description": "Submit a batch of texts for asynchronous embedding processing.", "operationId": "create_batch_job_v1_batch_embeddings_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchEmbeddingRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchStatus" } } } }, "400": { "description": "Bad Request: `INPUT_INVALID_LABELS`, `INPUT_LABEL_LIMIT_EXCEEDED`, `INPUT_MODEL_NOT_FOUND`, `INPUT_TOKEN_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized: `AUTH_INVALID_API_KEY`, `AUTH_INVALID_FORMAT`, `AUTH_MISSING_API_KEY`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden: `AUTHZ_INSUFFICIENT_BALANCE`, `AUTHZ_RESOURCE_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found: `RESOURCE_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict: `CONFLICT_RESOURCE_BUSY`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request body failed schema validation. `errors` names each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests: `RATE_CONCURRENCY_LIMIT_EXCEEDED`, `RATE_IP_LIMIT_EXCEEDED`, `RATE_REQUEST_LIMIT_EXCEEDED`, `RATE_TOKEN_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error: `INTERNAL_ERROR`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable: `SERVICE_UNAVAILABLE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout: `SERVICE_TIMEOUT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/batch/{batch_id}": { "get": { "tags": [ "Batch Embeddings" ], "summary": "Get batch job status", "description": "Retrieve the status of a batch embedding job.", "operationId": "get_batch_status_v1_batch__batch_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Batch Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchStatus" } } } }, "400": { "description": "Bad Request: `INPUT_INVALID_LABELS`, `INPUT_LABEL_LIMIT_EXCEEDED`, `INPUT_MODEL_NOT_FOUND`, `INPUT_TOKEN_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized: `AUTH_INVALID_API_KEY`, `AUTH_INVALID_FORMAT`, `AUTH_MISSING_API_KEY`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden: `AUTHZ_INSUFFICIENT_BALANCE`, `AUTHZ_RESOURCE_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found: `RESOURCE_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict: `CONFLICT_RESOURCE_BUSY`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request body failed schema validation. `errors` names each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests: `RATE_CONCURRENCY_LIMIT_EXCEEDED`, `RATE_IP_LIMIT_EXCEEDED`, `RATE_REQUEST_LIMIT_EXCEEDED`, `RATE_TOKEN_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error: `INTERNAL_ERROR`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable: `SERVICE_UNAVAILABLE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout: `SERVICE_TIMEOUT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Batch Embeddings" ], "summary": "Cancel a batch job", "description": "Cancel a pending or processing batch job.", "operationId": "cancel_batch_job_v1_batch__batch_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Batch Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchStatus" } } } }, "400": { "description": "Bad Request: `INPUT_INVALID_LABELS`, `INPUT_LABEL_LIMIT_EXCEEDED`, `INPUT_MODEL_NOT_FOUND`, `INPUT_TOKEN_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized: `AUTH_INVALID_API_KEY`, `AUTH_INVALID_FORMAT`, `AUTH_MISSING_API_KEY`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden: `AUTHZ_INSUFFICIENT_BALANCE`, `AUTHZ_RESOURCE_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found: `RESOURCE_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict: `CONFLICT_RESOURCE_BUSY`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request body failed schema validation. `errors` names each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests: `RATE_CONCURRENCY_LIMIT_EXCEEDED`, `RATE_IP_LIMIT_EXCEEDED`, `RATE_REQUEST_LIMIT_EXCEEDED`, `RATE_TOKEN_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error: `INTERNAL_ERROR`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable: `SERVICE_UNAVAILABLE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout: `SERVICE_TIMEOUT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/batches": { "get": { "tags": [ "Batch Embeddings" ], "summary": "List batch jobs", "description": "List recent batch jobs for the authenticated user.", "operationId": "list_batch_jobs_v1_batches_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BatchStatus" }, "title": "Response List Batch Jobs V1 Batches Get" } } } }, "400": { "description": "Bad Request: `INPUT_INVALID_LABELS`, `INPUT_LABEL_LIMIT_EXCEEDED`, `INPUT_MODEL_NOT_FOUND`, `INPUT_TOKEN_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized: `AUTH_INVALID_API_KEY`, `AUTH_INVALID_FORMAT`, `AUTH_MISSING_API_KEY`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden: `AUTHZ_INSUFFICIENT_BALANCE`, `AUTHZ_RESOURCE_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found: `RESOURCE_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict: `CONFLICT_RESOURCE_BUSY`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request body failed schema validation. `errors` names each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests: `RATE_CONCURRENCY_LIMIT_EXCEEDED`, `RATE_IP_LIMIT_EXCEEDED`, `RATE_REQUEST_LIMIT_EXCEEDED`, `RATE_TOKEN_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error: `INTERNAL_ERROR`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable: `SERVICE_UNAVAILABLE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout: `SERVICE_TIMEOUT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/batch/{batch_id}/output": { "get": { "tags": [ "Batch Embeddings" ], "summary": "Download batch job output", "description": "Stream the output JSONL file for a completed batch job.", "operationId": "download_batch_output_v1_batch__batch_id__output_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Batch Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request: `INPUT_INVALID_LABELS`, `INPUT_LABEL_LIMIT_EXCEEDED`, `INPUT_MODEL_NOT_FOUND`, `INPUT_TOKEN_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized: `AUTH_INVALID_API_KEY`, `AUTH_INVALID_FORMAT`, `AUTH_MISSING_API_KEY`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden: `AUTHZ_INSUFFICIENT_BALANCE`, `AUTHZ_RESOURCE_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found: `RESOURCE_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict: `CONFLICT_RESOURCE_BUSY`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request body failed schema validation. `errors` names each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests: `RATE_CONCURRENCY_LIMIT_EXCEEDED`, `RATE_IP_LIMIT_EXCEEDED`, `RATE_REQUEST_LIMIT_EXCEEDED`, `RATE_TOKEN_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error: `INTERNAL_ERROR`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable: `SERVICE_UNAVAILABLE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout: `SERVICE_TIMEOUT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/batch/{batch_id}/errors": { "get": { "tags": [ "Batch Embeddings" ], "summary": "Download batch job error file", "description": "Stream the error JSONL file for a completed batch job.", "operationId": "download_batch_errors_v1_batch__batch_id__errors_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Batch Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Bad Request: `INPUT_INVALID_LABELS`, `INPUT_LABEL_LIMIT_EXCEEDED`, `INPUT_MODEL_NOT_FOUND`, `INPUT_TOKEN_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized: `AUTH_INVALID_API_KEY`, `AUTH_INVALID_FORMAT`, `AUTH_MISSING_API_KEY`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden: `AUTHZ_INSUFFICIENT_BALANCE`, `AUTHZ_RESOURCE_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found: `RESOURCE_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict: `CONFLICT_RESOURCE_BUSY`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request body failed schema validation. `errors` names each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too Many Requests: `RATE_CONCURRENCY_LIMIT_EXCEEDED`, `RATE_IP_LIMIT_EXCEEDED`, `RATE_REQUEST_LIMIT_EXCEEDED`, `RATE_TOKEN_LIMIT_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error: `INTERNAL_ERROR`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable: `SERVICE_UNAVAILABLE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Gateway Timeout: `SERVICE_TIMEOUT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "Reader_JinaEmbeddingsAuthDTO@0x0b": { "title": "JinaEmbeddingsAuthDTO" }, "Reader_CrawlerOptions@0x26": { "title": "CrawlerOptions", "type": "object", "properties": { "url": { "type": "string", "description": "The URL to read. Not needed when the URL is already in the path (`https://r.jina.ai/`)." }, "preloadUrl": { "type": "string", "description": "URL to preload before scraping.\n\nIgnored when no URL is provided." }, "noServiceWorker": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Disable service workers when running the browser.\n\nUseful for bypassing service-worker-based caching or interception." }, "html": { "type": "string", "description": "Raw HTML to convert, instead of fetching a URL. Used when no `url` is given." }, "base": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x0d" } ], "default": "initial", "description": "Select base modes of relative URLs.\n\nSupported: initial, final" }, "pdf": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_FancyFile@0x0e" } ] }, { "type": "string" } ], "summary": "Base64 encoded PDF.", "description": "Base64 encoded PDF." }, "file": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_FancyFile@0x0e" } ] }, { "type": "string" } ], "summary": "Base64 encoded file.", "description": "Base64-encoded file (PDF, DOC, XLS, PPT, ...) to convert instead of a URL." }, "page": { "type": "number", "summary": "Steer which page to return for document files (1-indexed).", "description": "Steer which page to return for document files (1-indexed).\n\n- Some validators will be applied on value(s): (v) => Number.isInteger(v) && v >= 1" }, "respondWith": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x0f" } ] }, { "type": "string" } ], "default": "content", "description": "Specifies the (non-default) form of the crawled data you prefer.\n\nSupported formats: \n- markdown\n- html\n- text\n- pageshot\n- screenshot\n- content\n- frontmatter\n- any combination of the above\n- vlm\n- jina-ocr-v1\n- jina-ocr\n- readerlm-v2\n\nDefault: content" }, "withGeneratedAlt": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ], "description": "Enable automatic alt-text generating for images without an meaningful alt-text.\n\nNote: Does not work when `X-Respond-With` is specified" }, "retainImages": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x11" } ], "default": "all", "description": "Image retention modes.\n\nSupported modes: \n- all: all images\n- none: no images\n- alt: only alt text\n- all_p: all images and with generated alt text\n- alt_p: only alt text and with generated alt" }, "retainMedia": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x12" } ], "default": "link", "description": "Media retention modes for video, audio, and embedded video iframes.\n\nSupported modes: \n- none: no media\n- text: plain label, e.g. `Video 1`\n- link: markdown link, e.g. `[Video 1](url)` (default)\n- image: markdown image syntax, e.g. `![Video 1](url)`\n- html: original HTML with irrelevant attributes (class, id, style, data-*, aria-*) stripped" }, "preset": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x13" } ], "description": "Apply a preset configuration for common scenarios.\n\nSupported presets:\n- reader: optimized for display to human users\n- index: optimized for semantic indexing\n- research: optimized for academic/research AI agents\n- agent: optimized for day-to-day AI agents\n- spider: optimized for recursive site crawling\n\nPreset values are applied only to options not explicitly set by the caller." }, "retainLinks": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x14" } ], "default": "all", "description": "Link retention modes.\n\nSupported modes: \n- all: all links\n- none: no links\n- text: only link text\n- gpt-oss: gpt-oss link citation format `【{id}†.*】`" }, "withLinksSummary": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, { "type": "string" } ], "description": "Enable dedicated summary section for hyper links on the page." }, "withImagesSummary": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Enable dedicated summary section for images on the page." }, "noCache": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Ignores internal cache if this header is specified with a value.\n\nEquivalent to X-Cache-Tolerance: 0" }, "removeOverlay": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Specify whether to remove overlay elements from the page." }, "detachInvisibles": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Temporarily detach elements with computed `display:none` before snapshotting, then restore them.\n\nRequires the browser engine and disables caching." }, "noGfm": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, { "type": "string" } ], "description": "Opt out of GitHub Flavored Markdown. `true` disables GFM; `table` drops only GFM tables and keeps the table HTML." }, "cacheTolerance": { "type": "number", "description": "Sets internal cache tolerance in seconds if this header is specified with a integer." }, "targetSelector": { "type": "array", "items": { "type": "string" }, "description": "Specifies a CSS selector for return target instead of the full html.\n\nImplies `X-Wait-For-Selector: (same selector)`" }, "waitForSelector": { "type": "array", "items": { "type": "string" }, "description": "Specifies a CSS selector to wait for the appearance of such an element before returning.\n\nExample: `X-Wait-For-Selector: .content-block`" }, "removeSelector": { "type": "array", "items": { "type": "string" }, "description": "Specifies a CSS selector to remove elements from the full html.\n\nExample `X-Remove-Selector: nav`" }, "keepImgDataUrl": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Keep data-url as it instead of transforming them to object-url. (Only applicable when targeting markdown format)\n\nExample `X-Keep-Img-Data-Url: true`" }, "withIframe": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, { "type": "string" } ], "description": "Enable filling iframe contents into main. (violates standards)" }, "withShadowDom": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Enable filling shadow dom contents into main. (violates standards)" }, "skipCertVerification": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Enable skipping SSL certificate verification. (violates security best practices)" }, "setCookies": { "type": "array", "items": { "oneOf": [ { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, { "type": "string" } ] }, "description": "Cookies to send when fetching the URL, for pages that need a login. Requests with cookies are not cached." }, "storageState": { "allOf": [ { "$ref": "#/components/schemas/Reader_StorageState@0x19" } ] }, "exportStorageState": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Export the browser storage state (cookies and per-origin localStorage) accumulated during the crawl.\n\nWhen enabled, the JSON response includes a `storageState` field whose shape mirrors the `storageState` request option, so it can be fed back into a subsequent request.\n\nRequires the browser engine and disables caching." }, "proxyUrl": { "type": "string", "description": "Specifies your custom proxy if you prefer to use one.\n\nSupported protocols: \n- http\n- https\n- socks4\n- socks5\n\nFor authentication, https://user:pass@host:port" }, "proxyResources": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Whether to load resources like image/style/scripts via the proxy server." }, "proxy": { "type": "string", "description": "Use a proxy server provided by us.\n\nOptionally specify two-letter country code." }, "userAgent": { "type": "string", "description": "Override User-Agent.\n\nSeveral special values: \n- browser: use the internal browser UA\n- auto: pass-through your UA if it starts with `Mozilla/5.0`, otherwise use the internal browser UA\n- inherit / pass-through: use the User-Agent from the request context if applicable\n- bot: Use a pre-defined bot User-Agent from this service\n- diversify: Use a diversified browser User-Agent\n\nOr specify your own user agent string.\n\nNote: anonymous users specifying a browser UA will have no effect and will fall back to the internal browser UA.\n\nDefault: browser" }, "engine": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x1a" } ] }, { "type": "string" } ], "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering" }, "injectPageScript": { "type": "array", "items": { "type": "string" }, "description": "JavaScript to run in the page before extraction, inline or as a URL, e.g. to change the DOM." }, "injectFrameScript": { "type": "array", "items": { "type": "string" }, "description": "Like `injectPageScript`, for frames." }, "timeout": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v > 0 && v <= 180" }, "locale": { "type": "string", "description": "Specify browser locale for the page." }, "referer": { "type": "string", "description": "Specify referer for the page." }, "tokenBudget": { "type": "number", "description": "Specify a budget in tokens.\n\nIf the resulting token cost exceeds the budget, the request is rejected.\n\nNote this parameter is ignored for the search endpoint." }, "assertStatusCode": { "type": "number", "description": "Assert the HTTP status code of the crawled page. If the actual status code does not match the asserted one, the request is rejected with 422 Unprocessable Entity." }, "viewport": { "allOf": [ { "$ref": "#/components/schemas/Reader_Viewport@0x1b" } ] }, "instruction": { "type": "string" }, "jsonSchema": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "robotsTxt": { "type": "string", "description": "Load and conform to the respective robot.txt on the target origin.\n\nOptionally specify a bot UA to check against." }, "zeroDataRetention": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "markdown": { "allOf": [ { "$ref": "#/components/schemas/Reader_TurnDownTweakableOptions@0x22" } ] }, "ocr": { "allOf": [ { "$ref": "#/components/schemas/Reader_OCRPreferences@0x23" } ] }, "respondTiming": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x24" } ], "description": "Explicitly specify the respond timing. One of the following:\n\n- html: directly return unrendered HTML\n- visible-content: return immediately when any content becomes available\n- mutation-idle: wait for DOM mutations to settle and remain unchanged for at least 0.2s\n- resource-idle: wait for no additional resources that would affect page logic and content has SUCCEEDED loading in 0.5s\n- media-idle: wait for no additional resources, including media resources, has SUCCEEDED loading in 0.5s\n- network-idle: wait for full load of webpage, also known as networkidle0." }, "markdownChunking": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x25" } ] }, { "type": "string" } ], "description": "Opt-in markdown chunking.\n\nSupported values: \n- true\n- h1\n- h2\n- h3\n- h4\n- h5\n- structured\n- s1\n- s2\n- s3\n- s4\n- s5\n\nNote if you are expecting text return, the chunking is done by injecting character \\u001D" }, "maxTokens": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v >= 500" }, "customHeader": { "type": "object", "additionalProperties": { "type": "string" }, "properties": {} } } }, "Reader_PseudoBooleanLoose@0x0c": { "title": "PseudoBooleanLoose", "anyOf": [ { "type": "boolean" }, { "type": "string", "format": "pseudo-boolean-loose" } ], "description": "A boolean value that can be represented in various formats.", "examples": [ true, false, "true", "false", "yes", "no", "1", "0", "enabled", "disabled" ] }, "Reader_enum@0x0d": { "type": "string", "enum": [ "initial", "final" ], "description": "Enum<\"initial\" | \"final\">" }, "Reader_FancyFile@0x0e": { "title": "FancyFile", "type": "string", "format": "binary" }, "Reader_enum@0x0f": { "type": "string", "enum": [ "content", "markdown", "html", "text", "pageshot", "screenshot", "vlm", "readerlm-v2", "frontmatter", "readability", "jina-ocr-v1", "jina-ocr", "pp-doclayoutv3", "pp-doclayout", "doclayout" ], "description": "Enum<\"content\" | \"markdown\" | \"html\" | \"text\" | \"pageshot\" | \"screenshot\" | \"vlm\" | \"readerlm-v2\" | \"frontmatter\" | \"readability\" | \"...>" }, "Reader_PseudoBoolean@0x10": { "title": "PseudoBoolean", "anyOf": [ { "type": "boolean" }, { "type": "string", "format": "pseudo-boolean", "description": "A boolean value that can be represented in various formats.", "examples": [ true, false, "true", "false", "yes", "no", "1", "0", "enabled", "disabled" ] } ], "description": "A boolean value that can be represented in various formats.", "examples": [ true, false, "true", "false", "yes", "no", "1", "0", "enabled", "disabled" ] }, "Reader_enum@0x11": { "type": "string", "enum": [ "none", "all", "alt", "all_p", "alt_p" ], "description": "Enum<\"none\" | \"all\" | \"alt\" | \"all_p\" | \"alt_p\">" }, "Reader_enum@0x12": { "type": "string", "enum": [ "none", "text", "link", "image", "html" ], "description": "Enum<\"none\" | \"text\" | \"link\" | \"image\" | \"html\">" }, "Reader_enum@0x13": { "type": "string", "enum": [ "reader", "index", "research", "agent", "spider", "ocr", "ocr+", "ocr++", "pdf", "pdf+", "pdf++" ], "description": "Enum<\"reader\" | \"index\" | \"research\" | \"agent\" | \"spider\" | \"ocr\" | \"ocr+\" | \"ocr++\" | \"pdf\" | \"pdf+\" | \"pdf++\">" }, "Reader_enum@0x14": { "type": "string", "enum": [ "none", "all", "text", "gpt-oss" ], "description": "Enum<\"none\" | \"all\" | \"text\" | \"gpt-oss\">" }, "Reader_StorageState@0x19": { "title": "StorageState", "type": "object", "properties": { "cookies": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Reader_Cookie@0x16" } ] }, "default": [] }, "origins": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Reader_LocalStorageOrigin@0x18" } ] }, "default": [] } } }, "Reader_Cookie@0x16": { "title": "Cookie", "type": "object", "properties": { "name": { "type": "string", "description": "[REQUIRED]" }, "value": { "type": "string", "description": "[REQUIRED]" }, "domain": { "type": "string" }, "path": { "type": "string", "default": "/" }, "expires": { "type": "string", "format": "date-time" }, "httpOnly": { "type": "boolean" }, "secure": { "type": "boolean" }, "sameSite": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x15" } ] }, { "type": "string" } ] } }, "required": [ "name", "value" ] }, "Reader_enum@0x15": { "type": "string", "enum": [ "Strict", "Lax", "None" ], "description": "Enum<\"Strict\" | \"Lax\" | \"None\">" }, "Reader_LocalStorageOrigin@0x18": { "title": "LocalStorageOrigin", "type": "object", "properties": { "origin": { "type": "string", "description": "[REQUIRED]" }, "localStorage": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Reader_LocalStorageItem@0x17" } ] }, "default": [] } }, "required": [ "origin" ] }, "Reader_LocalStorageItem@0x17": { "title": "LocalStorageItem", "type": "object", "properties": { "name": { "type": "string", "description": "[REQUIRED]" }, "value": { "type": "string", "description": "[REQUIRED]" } }, "required": [ "name", "value" ] }, "Reader_enum@0x1a": { "type": "string", "enum": [ "auto", "browser", "curl", "cf-browser-rendering" ], "description": "Enum<\"auto\" | \"browser\" | \"curl\" | \"cf-browser-rendering\">" }, "Reader_Viewport@0x1b": { "title": "Viewport", "type": "object", "properties": { "width": { "type": "number", "default": 1280 }, "height": { "type": "number", "default": 1280 }, "deviceScaleFactor": { "type": "number" }, "isMobile": { "type": "boolean" }, "isLandscape": { "type": "boolean" }, "hasTouch": { "type": "boolean" } } }, "Reader_TurnDownTweakableOptions@0x22": { "title": "TurnDownTweakableOptions", "type": "object", "properties": { "headingStyle": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x1c" } ], "summary": "Turndown options > headingStyle", "description": "Turndown options > headingStyle" }, "hr": { "type": "string", "summary": "Turndown options > hr", "description": "Turndown options > hr\n\n- Some validators will be applied on value(s): (v) => v.length > 0 && v.length <= 128" }, "bulletListMarker": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x1d" } ], "summary": "Turndown options > bulletListMarker", "description": "Turndown options > bulletListMarker" }, "emDelimiter": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x1e" } ], "summary": "Turndown options > emDelimiter", "description": "Turndown options > emDelimiter" }, "strongDelimiter": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x1f" } ], "summary": "Turndown options > strongDelimiter", "description": "Turndown options > strongDelimiter" }, "linkStyle": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x20" } ], "summary": "Turndown options > linkStyle", "description": "Turndown options > linkStyle" }, "linkReferenceStyle": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x21" } ], "summary": "Turndown options > linkReferenceStyle", "description": "Turndown options > linkReferenceStyle" } } }, "Reader_enum@0x1c": { "type": "string", "enum": [ "setext", "atx" ], "description": "Enum<\"setext\" | \"atx\">" }, "Reader_enum@0x1d": { "type": "string", "enum": [ "-", "+", "*" ], "description": "Enum<\"-\" | \"+\" | \"*\">" }, "Reader_enum@0x1e": { "type": "string", "enum": [ "_", "*" ], "description": "Enum<\"_\" | \"*\">" }, "Reader_enum@0x1f": { "type": "string", "enum": [ "__", "**" ], "description": "Enum<\"__\" | \"**\">" }, "Reader_enum@0x20": { "type": "string", "enum": [ "inlined", "referenced", "discarded" ], "description": "Enum<\"inlined\" | \"referenced\" | \"discarded\">" }, "Reader_enum@0x21": { "type": "string", "enum": [ "full", "collapsed", "shortcut", "discarded" ], "description": "Enum<\"full\" | \"collapsed\" | \"shortcut\" | \"discarded\">" }, "Reader_OCRPreferences@0x23": { "title": "OCRPreferences", "type": "object", "properties": { "preferEndToEnd": { "type": "boolean", "summary": "Prefer end-to-end OCR mode (over PDF text)", "description": "Prefer end-to-end OCR mode (over PDF text)" }, "preferImgOrder": { "type": "boolean", "summary": "Prefer better image order over particular markdown format (only applies in end-to-end mode)", "description": "Prefer better image order over particular markdown format (only applies in end-to-end mode)" }, "inlineFormula": { "type": "boolean", "summary": "Blocks with inline formulas should go through OCR (only applies in non-end-to-end mode)", "description": "Blocks with inline formulas should go through OCR (only applies in non-end-to-end mode)" }, "blockFormula": { "type": "boolean", "summary": "Formula blocks should go through OCR (only applies in non-end-to-end mode)", "description": "Formula blocks should go through OCR (only applies in non-end-to-end mode)", "default": true }, "table": { "type": "boolean", "summary": "Table blocks should go through OCR (only applies in non-end-to-end mode)", "description": "Table blocks should go through OCR (only applies in non-end-to-end mode)", "default": true } } }, "Reader_enum@0x24": { "type": "string", "enum": [ "html", "visible-content", "mutation-idle", "resource-idle", "media-idle", "network-idle" ], "description": "Enum<\"html\" | \"visible-content\" | \"mutation-idle\" | \"resource-idle\" | \"media-idle\" | \"network-idle\">" }, "Reader_enum@0x25": { "type": "string", "enum": [ "true", "h1", "h2", "h3", "h4", "h5", "structured", "s1", "s2", "s3", "s4", "s5" ], "description": "Enum<\"true\" | \"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"structured\" | \"s1\" | \"s2\" | \"s3\" | \"s4\" | \"s5\">" }, "Reader_CrawlerOptionsHeaderOnly@0x39": { "title": "CrawlerOptionsHeaderOnly", "type": "object", "properties": { "url": { "type": "string", "description": "The URL to read. Not needed when the URL is already in the path (`https://r.jina.ai/`)." }, "preloadUrl": { "type": "string", "description": "URL to preload before scraping.\n\nIgnored when no URL is provided." }, "noServiceWorker": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Disable service workers when running the browser.\n\nUseful for bypassing service-worker-based caching or interception." }, "html": { "type": "string", "description": "Raw HTML to convert, instead of fetching a URL. Used when no `url` is given." }, "base": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x0d" } ], "default": "initial", "description": "Select base modes of relative URLs.\n\nSupported: initial, final" }, "pdf": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_FancyFile@0x0e" } ] }, { "type": "string" } ], "summary": "Base64 encoded PDF.", "description": "Base64 encoded PDF." }, "file": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_FancyFile@0x0e" } ] }, { "type": "string" } ], "summary": "Base64 encoded file.", "description": "Base64-encoded file (PDF, DOC, XLS, PPT, ...) to convert instead of a URL." }, "page": { "type": "number", "summary": "Steer which page to return for document files (1-indexed).", "description": "Steer which page to return for document files (1-indexed).\n\n- Some validators will be applied on value(s): (v) => Number.isInteger(v) && v >= 1" }, "respondWith": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x0f" } ] }, { "type": "string" } ], "default": "content", "description": "Specifies the (non-default) form of the crawled data you prefer.\n\nSupported formats: \n- markdown\n- html\n- text\n- pageshot\n- screenshot\n- content\n- frontmatter\n- any combination of the above\n- vlm\n- jina-ocr-v1\n- jina-ocr\n- readerlm-v2\n\nDefault: content" }, "withGeneratedAlt": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ], "description": "Enable automatic alt-text generating for images without an meaningful alt-text.\n\nNote: Does not work when `X-Respond-With` is specified" }, "retainImages": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x11" } ], "default": "all", "description": "Image retention modes.\n\nSupported modes: \n- all: all images\n- none: no images\n- alt: only alt text\n- all_p: all images and with generated alt text\n- alt_p: only alt text and with generated alt" }, "retainMedia": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x12" } ], "default": "link", "description": "Media retention modes for video, audio, and embedded video iframes.\n\nSupported modes: \n- none: no media\n- text: plain label, e.g. `Video 1`\n- link: markdown link, e.g. `[Video 1](url)` (default)\n- image: markdown image syntax, e.g. `![Video 1](url)`\n- html: original HTML with irrelevant attributes (class, id, style, data-*, aria-*) stripped" }, "preset": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x13" } ], "description": "Apply a preset configuration for common scenarios.\n\nSupported presets:\n- reader: optimized for display to human users\n- index: optimized for semantic indexing\n- research: optimized for academic/research AI agents\n- agent: optimized for day-to-day AI agents\n- spider: optimized for recursive site crawling\n\nPreset values are applied only to options not explicitly set by the caller." }, "retainLinks": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x14" } ], "default": "all", "description": "Link retention modes.\n\nSupported modes: \n- all: all links\n- none: no links\n- text: only link text\n- gpt-oss: gpt-oss link citation format `【{id}†.*】`" }, "withLinksSummary": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, { "type": "string" } ], "description": "Enable dedicated summary section for hyper links on the page." }, "withImagesSummary": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Enable dedicated summary section for images on the page." }, "noCache": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Ignores internal cache if this header is specified with a value.\n\nEquivalent to X-Cache-Tolerance: 0" }, "removeOverlay": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Specify whether to remove overlay elements from the page." }, "detachInvisibles": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Temporarily detach elements with computed `display:none` before snapshotting, then restore them.\n\nRequires the browser engine and disables caching." }, "noGfm": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, { "type": "string" } ], "description": "Opt out of GitHub Flavored Markdown. `true` disables GFM; `table` drops only GFM tables and keeps the table HTML." }, "cacheTolerance": { "type": "number", "description": "Sets internal cache tolerance in seconds if this header is specified with a integer." }, "targetSelector": { "type": "array", "items": { "type": "string" }, "description": "Specifies a CSS selector for return target instead of the full html.\n\nImplies `X-Wait-For-Selector: (same selector)`" }, "waitForSelector": { "type": "array", "items": { "type": "string" }, "description": "Specifies a CSS selector to wait for the appearance of such an element before returning.\n\nExample: `X-Wait-For-Selector: .content-block`" }, "removeSelector": { "type": "array", "items": { "type": "string" }, "description": "Specifies a CSS selector to remove elements from the full html.\n\nExample `X-Remove-Selector: nav`" }, "keepImgDataUrl": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Keep data-url as it instead of transforming them to object-url. (Only applicable when targeting markdown format)\n\nExample `X-Keep-Img-Data-Url: true`" }, "withIframe": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBoolean@0x10" } ] }, { "type": "string" } ], "description": "Enable filling iframe contents into main. (violates standards)" }, "withShadowDom": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Enable filling shadow dom contents into main. (violates standards)" }, "skipCertVerification": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Enable skipping SSL certificate verification. (violates security best practices)" }, "setCookies": { "type": "array", "items": { "oneOf": [ { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, { "type": "string" } ] }, "description": "Cookies to send when fetching the URL, for pages that need a login. Requests with cookies are not cached." }, "storageState": { "allOf": [ { "$ref": "#/components/schemas/Reader_StorageState@0x19" } ] }, "exportStorageState": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Export the browser storage state (cookies and per-origin localStorage) accumulated during the crawl.\n\nWhen enabled, the JSON response includes a `storageState` field whose shape mirrors the `storageState` request option, so it can be fed back into a subsequent request.\n\nRequires the browser engine and disables caching." }, "proxyUrl": { "type": "string", "description": "Specifies your custom proxy if you prefer to use one.\n\nSupported protocols: \n- http\n- https\n- socks4\n- socks5\n\nFor authentication, https://user:pass@host:port" }, "proxyResources": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ], "description": "Whether to load resources like image/style/scripts via the proxy server." }, "proxy": { "type": "string", "description": "Use a proxy server provided by us.\n\nOptionally specify two-letter country code." }, "userAgent": { "type": "string", "description": "Override User-Agent.\n\nSeveral special values: \n- browser: use the internal browser UA\n- auto: pass-through your UA if it starts with `Mozilla/5.0`, otherwise use the internal browser UA\n- inherit / pass-through: use the User-Agent from the request context if applicable\n- bot: Use a pre-defined bot User-Agent from this service\n- diversify: Use a diversified browser User-Agent\n\nOr specify your own user agent string.\n\nNote: anonymous users specifying a browser UA will have no effect and will fall back to the internal browser UA.\n\nDefault: browser" }, "engine": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x1a" } ] }, { "type": "string" } ], "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering" }, "injectPageScript": { "type": "array", "items": { "type": "string" }, "description": "JavaScript to run in the page before extraction, inline or as a URL, e.g. to change the DOM." }, "injectFrameScript": { "type": "array", "items": { "type": "string" }, "description": "Like `injectPageScript`, for frames." }, "timeout": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v > 0 && v <= 180" }, "locale": { "type": "string", "description": "Specify browser locale for the page." }, "referer": { "type": "string", "description": "Specify referer for the page." }, "tokenBudget": { "type": "number", "description": "Specify a budget in tokens.\n\nIf the resulting token cost exceeds the budget, the request is rejected.\n\nNote this parameter is ignored for the search endpoint." }, "assertStatusCode": { "type": "number", "description": "Assert the HTTP status code of the crawled page. If the actual status code does not match the asserted one, the request is rejected with 422 Unprocessable Entity." }, "viewport": { "allOf": [ { "$ref": "#/components/schemas/Reader_Viewport@0x1b" } ] }, "instruction": { "type": "string" }, "jsonSchema": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "robotsTxt": { "type": "string", "description": "Load and conform to the respective robot.txt on the target origin.\n\nOptionally specify a bot UA to check against." }, "zeroDataRetention": { "allOf": [ { "$ref": "#/components/schemas/Reader_PseudoBooleanLoose@0x0c" } ] }, "markdown": { "allOf": [ { "$ref": "#/components/schemas/Reader_TurnDownTweakableOptions@0x22" } ] }, "ocr": { "allOf": [ { "$ref": "#/components/schemas/Reader_OCRPreferences@0x23" } ] }, "respondTiming": { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x24" } ], "description": "Explicitly specify the respond timing. One of the following:\n\n- html: directly return unrendered HTML\n- visible-content: return immediately when any content becomes available\n- mutation-idle: wait for DOM mutations to settle and remain unchanged for at least 0.2s\n- resource-idle: wait for no additional resources that would affect page logic and content has SUCCEEDED loading in 0.5s\n- media-idle: wait for no additional resources, including media resources, has SUCCEEDED loading in 0.5s\n- network-idle: wait for full load of webpage, also known as networkidle0." }, "markdownChunking": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_enum@0x25" } ] }, { "type": "string" } ], "description": "Opt-in markdown chunking.\n\nSupported values: \n- true\n- h1\n- h2\n- h3\n- h4\n- h5\n- structured\n- s1\n- s2\n- s3\n- s4\n- s5\n\nNote if you are expecting text return, the chunking is done by injecting character \\u001D" }, "maxTokens": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v >= 500" }, "customHeader": { "type": "object", "additionalProperties": { "type": "string" }, "properties": {} } } }, "Reader_ParamValidationError@0x27": { "title": "ParamValidationError", "type": "object", "properties": { "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 400 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 40001 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Reader_DataStreamBrokenError@0x28": { "title": "DataStreamBrokenError", "type": "object", "properties": { "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 400 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 40003 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Reader_AuthenticationFailedError@0x29": { "title": "AuthenticationFailedError", "type": "object", "properties": { "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 401 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 40102 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Reader_AuthenticationRequiredError@0x2a": { "title": "AuthenticationRequiredError", "type": "object", "properties": { "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 401 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 40103 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Reader_TierFeatureConstraintError@0x2b": { "title": "TierFeatureConstraintError", "type": "object", "properties": { "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 402 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 40202 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Reader_InsufficientBalanceError@0x2c": { "title": "InsufficientBalanceError", "type": "object", "properties": { "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 402 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 40203 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Reader_OperationNotAllowedError@0x2d": { "title": "OperationNotAllowedError", "type": "object", "properties": { "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 403 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 40301 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Reader_AbuseAlleviationError@0x2e": { "title": "AbuseAlleviationError", "type": "object", "properties": { "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 403 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 40305 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Reader_ResourcePolicyDenyError@0x2f": { "title": "ResourcePolicyDenyError", "type": "object", "properties": { "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 409 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 40902 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Reader_BudgetExceededError@0x30": { "title": "BudgetExceededError", "type": "object", "properties": { "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 409 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 40904 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Reader_TargetFileTooLargeError@0x31": { "title": "TargetFileTooLargeError", "type": "object", "properties": { "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 413 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 41302 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Reader_SubmittedDataMalformedError@0x32": { "title": "SubmittedDataMalformedError", "type": "object", "properties": { "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 422 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 42203 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Reader_DownstreamServiceFailureError@0x33": { "title": "DownstreamServiceFailureError", "type": "object", "properties": { "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 422 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 42205 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Reader_AssertionFailureError@0x34": { "title": "AssertionFailureError", "type": "object", "properties": { "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 422 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 42206 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Reader_RateLimitTriggeredError@0x35": { "title": "RateLimitTriggeredError", "type": "object", "properties": { "retryAfter": { "type": "number", "summary": "Retry after seconds", "description": "Retry after seconds" }, "retryAfterDate": { "type": "string", "format": "date-time", "summary": "Retry after date", "description": "Retry after date" }, "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 429 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 42903 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Reader_HarmfulContentError@0x36": { "title": "HarmfulContentError", "type": "object", "properties": { "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 451 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 45101 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Reader_DownstreamServiceError@0x37": { "title": "DownstreamServiceError", "type": "object", "properties": { "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 500 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 50002 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Reader_ServiceNodeResourceDrainError@0x38": { "title": "ServiceNodeResourceDrainError", "type": "object", "properties": { "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 503 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 50303 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Reader_FormattedPageDto@0x41": { "title": "FormattedPageDto", "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string", "description": "The URL to read. Not needed when the URL is already in the path (`https://r.jina.ai/`)." }, "content": { "type": "string" }, "chunks": { "allOf": [ { "$ref": "#/components/schemas/Reader_Array@0x3a" } ] }, "publishedTime": { "type": "string" }, "html": { "type": "string", "description": "Raw HTML to convert, instead of fetching a URL. Used when no `url` is given." }, "text": { "type": "string" }, "screenshotUrl": { "type": "string" }, "pageshotUrl": { "type": "string" }, "numPages": { "type": "number" }, "links": { "oneOf": [ { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, { "allOf": [ { "$ref": "#/components/schemas/Reader_Record@0x3b" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_Array@0x3c" } ] } ] }, "images": { "oneOf": [ { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, { "allOf": [ { "$ref": "#/components/schemas/Reader_Record@0x3d" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Reader_Array@0x3e" } ] } ] }, "warning": { "type": "string" }, "metadata": { "oneOf": [ { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, { "allOf": [ { "$ref": "#/components/schemas/Reader_Record@0x3f" } ] } ] }, "external": { "oneOf": [ { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, { "allOf": [ { "$ref": "#/components/schemas/Reader_Record@0x08|object>@0x09|object>@0x40" } ] } ] }, "httpStatus": { "type": "number" }, "httpStatusText": { "type": "string" }, "storageState": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true } }, "required": [ "url" ] }, "Reader_Array@0x3a": { "title": "Array", "type": "array", "items": { "type": "string" } }, "Reader_Record@0x3b": { "title": "Record", "type": "object", "properties": {}, "additionalProperties": { "type": "string" } }, "Reader_Array@0x3c": { "title": "Array", "type": "array", "items": { "type": "string" } }, "Reader_Record@0x3d": { "title": "Record", "type": "object", "properties": {}, "additionalProperties": { "type": "string" } }, "Reader_Array@0x3e": { "title": "Array", "type": "array", "items": { "type": "string" } }, "Reader_Record@0x3f": { "title": "Record", "type": "object", "properties": {}, "additionalProperties": { "type": "string" } }, "Reader_Record@0x08|object>@0x09|object>@0x40": { "title": "Record@0x08|object>@0x09|object>", "type": "object", "properties": {}, "additionalProperties": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_Record@0x08|object>@0x09" } ] }, { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true } ] } }, "Reader_Record@0x08|object>@0x09": { "title": "Record@0x08|object>", "type": "object", "properties": {}, "additionalProperties": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reader_Record@0x08" } ] }, { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true } ] } }, "Reader_Record@0x08": { "title": "Record", "type": "object", "properties": {}, "additionalProperties": { "oneOf": [ { "type": "string" }, { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true } ] } }, "Reader_OutputServerEventStream@0x42": { "type": "string", "format": "binary", "description": "Binary data (stream)" }, "Reader_ResourceNotFoundError@0x43": { "title": "ResourceNotFoundError", "type": "object", "properties": { "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 404 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 40401 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Search_JinaEmbeddingsAuthDTO@0x0c": { "title": "JinaEmbeddingsAuthDTO" }, "Search_CrawlerOptions@0x27": { "title": "CrawlerOptions", "type": "object", "properties": { "url": { "type": "string", "description": "The URL to read. Not needed when the URL is already in the path (`https://r.jina.ai/`)." }, "preloadUrl": { "type": "string", "description": "URL to preload before scraping.\n\nIgnored when no URL is provided." }, "noServiceWorker": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Disable service workers when running the browser.\n\nUseful for bypassing service-worker-based caching or interception." }, "html": { "type": "string", "description": "Raw HTML to convert, instead of fetching a URL. Used when no `url` is given." }, "base": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x0e" } ], "default": "initial", "description": "Select base modes of relative URLs.\n\nSupported: initial, final" }, "pdf": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_FancyFile@0x0f" } ] }, { "type": "string" } ], "summary": "Base64 encoded PDF.", "description": "Base64 encoded PDF." }, "file": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_FancyFile@0x0f" } ] }, { "type": "string" } ], "summary": "Base64 encoded file.", "description": "Base64-encoded file (PDF, DOC, XLS, PPT, ...) to convert instead of a URL." }, "page": { "type": "number", "summary": "Steer which page to return for document files (1-indexed).", "description": "Steer which page to return for document files (1-indexed).\n\n- Some validators will be applied on value(s): (v) => Number.isInteger(v) && v >= 1" }, "respondWith": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x10" } ] }, { "type": "string" } ], "default": "content", "description": "Specifies the (non-default) form of the crawled data you prefer.\n\nSupported formats: \n- markdown\n- html\n- text\n- pageshot\n- screenshot\n- content\n- frontmatter\n- any combination of the above\n- vlm\n- jina-ocr-v1\n- jina-ocr\n- readerlm-v2\n\nDefault: content" }, "withGeneratedAlt": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ], "description": "Enable automatic alt-text generating for images without an meaningful alt-text.\n\nNote: Does not work when `X-Respond-With` is specified" }, "retainImages": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x12" } ], "default": "all", "description": "Image retention modes.\n\nSupported modes: \n- all: all images\n- none: no images\n- alt: only alt text\n- all_p: all images and with generated alt text\n- alt_p: only alt text and with generated alt" }, "retainMedia": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x13" } ], "default": "link", "description": "Media retention modes for video, audio, and embedded video iframes.\n\nSupported modes: \n- none: no media\n- text: plain label, e.g. `Video 1`\n- link: markdown link, e.g. `[Video 1](url)` (default)\n- image: markdown image syntax, e.g. `![Video 1](url)`\n- html: original HTML with irrelevant attributes (class, id, style, data-*, aria-*) stripped" }, "preset": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x14" } ], "description": "Apply a preset configuration for common scenarios.\n\nSupported presets:\n- reader: optimized for display to human users\n- index: optimized for semantic indexing\n- research: optimized for academic/research AI agents\n- agent: optimized for day-to-day AI agents\n- spider: optimized for recursive site crawling\n\nPreset values are applied only to options not explicitly set by the caller." }, "retainLinks": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x15" } ], "default": "all", "description": "Link retention modes.\n\nSupported modes: \n- all: all links\n- none: no links\n- text: only link text\n- gpt-oss: gpt-oss link citation format `【{id}†.*】`" }, "withLinksSummary": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ] }, { "type": "string" } ], "description": "Enable dedicated summary section for hyper links on the page." }, "withImagesSummary": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Enable dedicated summary section for images on the page." }, "noCache": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Ignores internal cache if this header is specified with a value.\n\nEquivalent to X-Cache-Tolerance: 0" }, "removeOverlay": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Specify whether to remove overlay elements from the page." }, "detachInvisibles": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Temporarily detach elements with computed `display:none` before snapshotting, then restore them.\n\nRequires the browser engine and disables caching." }, "noGfm": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ] }, { "type": "string" } ], "description": "Opt out of GitHub Flavored Markdown. `true` disables GFM; `table` drops only GFM tables and keeps the table HTML." }, "cacheTolerance": { "type": "number", "description": "Sets internal cache tolerance in seconds if this header is specified with a integer." }, "targetSelector": { "type": "array", "items": { "type": "string" }, "description": "Specifies a CSS selector for return target instead of the full html.\n\nImplies `X-Wait-For-Selector: (same selector)`" }, "waitForSelector": { "type": "array", "items": { "type": "string" }, "description": "Specifies a CSS selector to wait for the appearance of such an element before returning.\n\nExample: `X-Wait-For-Selector: .content-block`" }, "removeSelector": { "type": "array", "items": { "type": "string" }, "description": "Specifies a CSS selector to remove elements from the full html.\n\nExample `X-Remove-Selector: nav`" }, "keepImgDataUrl": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Keep data-url as it instead of transforming them to object-url. (Only applicable when targeting markdown format)\n\nExample `X-Keep-Img-Data-Url: true`" }, "withIframe": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBoolean@0x11" } ] }, { "type": "string" } ], "description": "Enable filling iframe contents into main. (violates standards)" }, "withShadowDom": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Enable filling shadow dom contents into main. (violates standards)" }, "skipCertVerification": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Enable skipping SSL certificate verification. (violates security best practices)" }, "setCookies": { "type": "array", "items": { "oneOf": [ { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, { "type": "string" } ] }, "description": "Cookies to send when fetching each result page, for pages that need a login. Requests with cookies are not cached." }, "storageState": { "allOf": [ { "$ref": "#/components/schemas/Search_StorageState@0x1a" } ] }, "exportStorageState": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Export the browser storage state (cookies and per-origin localStorage) accumulated during the crawl.\n\nWhen enabled, the JSON response includes a `storageState` field whose shape mirrors the `storageState` request option, so it can be fed back into a subsequent request.\n\nRequires the browser engine and disables caching." }, "proxyUrl": { "type": "string", "description": "Specifies your custom proxy if you prefer to use one.\n\nSupported protocols: \n- http\n- https\n- socks4\n- socks5\n\nFor authentication, https://user:pass@host:port" }, "proxyResources": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ], "description": "Whether to load resources like image/style/scripts via the proxy server." }, "proxy": { "type": "string", "description": "Use a proxy server provided by us.\n\nOptionally specify two-letter country code." }, "userAgent": { "type": "string", "description": "Override User-Agent.\n\nSeveral special values: \n- browser: use the internal browser UA\n- auto: pass-through your UA if it starts with `Mozilla/5.0`, otherwise use the internal browser UA\n- inherit / pass-through: use the User-Agent from the request context if applicable\n- bot: Use a pre-defined bot User-Agent from this service\n- diversify: Use a diversified browser User-Agent\n\nOr specify your own user agent string.\n\nNote: anonymous users specifying a browser UA will have no effect and will fall back to the internal browser UA.\n\nDefault: browser" }, "engine": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x1b" } ] }, { "type": "string" } ], "description": "Specify the engine to use for crawling.\n\nSupported: browser, direct, cf-browser-rendering" }, "injectPageScript": { "type": "array", "items": { "type": "string" }, "description": "JavaScript to run in each result page before extraction, inline or as a URL." }, "injectFrameScript": { "type": "array", "items": { "type": "string" }, "description": "Like `injectPageScript`, for frames." }, "timeout": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v > 0 && v <= 180" }, "locale": { "type": "string", "description": "Specify browser locale for the page." }, "referer": { "type": "string", "description": "Specify referer for the page." }, "tokenBudget": { "type": "number", "description": "Specify a budget in tokens.\n\nIf the resulting token cost exceeds the budget, the request is rejected.\n\nNote this parameter is ignored for the search endpoint." }, "assertStatusCode": { "type": "number", "description": "Assert the HTTP status code of the crawled page. If the actual status code does not match the asserted one, the request is rejected with 422 Unprocessable Entity." }, "viewport": { "allOf": [ { "$ref": "#/components/schemas/Search_Viewport@0x1c" } ] }, "instruction": { "type": "string" }, "jsonSchema": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "robotsTxt": { "type": "string", "description": "Load and conform to the respective robot.txt on the target origin.\n\nOptionally specify a bot UA to check against." }, "zeroDataRetention": { "allOf": [ { "$ref": "#/components/schemas/Search_PseudoBooleanLoose@0x0d" } ] }, "markdown": { "allOf": [ { "$ref": "#/components/schemas/Search_TurnDownTweakableOptions@0x23" } ] }, "ocr": { "allOf": [ { "$ref": "#/components/schemas/Search_OCRPreferences@0x24" } ] }, "respondTiming": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x25" } ], "description": "Explicitly specify the respond timing. One of the following:\n\n- html: directly return unrendered HTML\n- visible-content: return immediately when any content becomes available\n- mutation-idle: wait for DOM mutations to settle and remain unchanged for at least 0.2s\n- resource-idle: wait for no additional resources that would affect page logic and content has SUCCEEDED loading in 0.5s\n- media-idle: wait for no additional resources, including media resources, has SUCCEEDED loading in 0.5s\n- network-idle: wait for full load of webpage, also known as networkidle0." }, "markdownChunking": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x26" } ] }, { "type": "string" } ], "description": "Opt-in markdown chunking.\n\nSupported values: \n- true\n- h1\n- h2\n- h3\n- h4\n- h5\n- structured\n- s1\n- s2\n- s3\n- s4\n- s5\n\nNote if you are expecting text return, the chunking is done by injecting character \\u001D" }, "maxTokens": { "type": "number", "description": "- Some validators will be applied on value(s): (v) => v >= 500" }, "customHeader": { "type": "object", "additionalProperties": { "type": "string" }, "properties": {} } } }, "Search_PseudoBooleanLoose@0x0d": { "title": "PseudoBooleanLoose", "anyOf": [ { "type": "boolean" }, { "type": "string", "format": "pseudo-boolean-loose" } ], "description": "A boolean value that can be represented in various formats.", "examples": [ true, false, "true", "false", "yes", "no", "1", "0", "enabled", "disabled" ] }, "Search_enum@0x0e": { "type": "string", "enum": [ "initial", "final" ], "description": "Enum<\"initial\" | \"final\">" }, "Search_FancyFile@0x0f": { "title": "FancyFile", "type": "string", "format": "binary" }, "Search_enum@0x10": { "type": "string", "enum": [ "content", "markdown", "html", "text", "pageshot", "screenshot", "vlm", "readerlm-v2", "frontmatter", "readability", "jina-ocr-v1", "jina-ocr", "pp-doclayoutv3", "pp-doclayout", "doclayout" ], "description": "Enum<\"content\" | \"markdown\" | \"html\" | \"text\" | \"pageshot\" | \"screenshot\" | \"vlm\" | \"readerlm-v2\" | \"frontmatter\" | \"readability\" | \"...>" }, "Search_PseudoBoolean@0x11": { "title": "PseudoBoolean", "anyOf": [ { "type": "boolean" }, { "type": "string", "format": "pseudo-boolean", "description": "A boolean value that can be represented in various formats.", "examples": [ true, false, "true", "false", "yes", "no", "1", "0", "enabled", "disabled" ] } ], "description": "A boolean value that can be represented in various formats.", "examples": [ true, false, "true", "false", "yes", "no", "1", "0", "enabled", "disabled" ] }, "Search_enum@0x12": { "type": "string", "enum": [ "none", "all", "alt", "all_p", "alt_p" ], "description": "Enum<\"none\" | \"all\" | \"alt\" | \"all_p\" | \"alt_p\">" }, "Search_enum@0x13": { "type": "string", "enum": [ "none", "text", "link", "image", "html" ], "description": "Enum<\"none\" | \"text\" | \"link\" | \"image\" | \"html\">" }, "Search_enum@0x14": { "type": "string", "enum": [ "reader", "index", "research", "agent", "spider", "ocr", "ocr+", "ocr++", "pdf", "pdf+", "pdf++" ], "description": "Enum<\"reader\" | \"index\" | \"research\" | \"agent\" | \"spider\" | \"ocr\" | \"ocr+\" | \"ocr++\" | \"pdf\" | \"pdf+\" | \"pdf++\">" }, "Search_enum@0x15": { "type": "string", "enum": [ "none", "all", "text", "gpt-oss" ], "description": "Enum<\"none\" | \"all\" | \"text\" | \"gpt-oss\">" }, "Search_StorageState@0x1a": { "title": "StorageState", "type": "object", "properties": { "cookies": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Search_Cookie@0x17" } ] }, "default": [] }, "origins": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Search_LocalStorageOrigin@0x19" } ] }, "default": [] } } }, "Search_Cookie@0x17": { "title": "Cookie", "type": "object", "properties": { "name": { "type": "string", "description": "[REQUIRED]" }, "value": { "type": "string", "description": "[REQUIRED]" }, "domain": { "type": "string" }, "path": { "type": "string", "default": "/" }, "expires": { "type": "string", "format": "date-time" }, "httpOnly": { "type": "boolean" }, "secure": { "type": "boolean" }, "sameSite": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x16" } ] }, { "type": "string" } ] } }, "required": [ "name", "value" ] }, "Search_enum@0x16": { "type": "string", "enum": [ "Strict", "Lax", "None" ], "description": "Enum<\"Strict\" | \"Lax\" | \"None\">" }, "Search_LocalStorageOrigin@0x19": { "title": "LocalStorageOrigin", "type": "object", "properties": { "origin": { "type": "string", "description": "[REQUIRED]" }, "localStorage": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Search_LocalStorageItem@0x18" } ] }, "default": [] } }, "required": [ "origin" ] }, "Search_LocalStorageItem@0x18": { "title": "LocalStorageItem", "type": "object", "properties": { "name": { "type": "string", "description": "[REQUIRED]" }, "value": { "type": "string", "description": "[REQUIRED]" } }, "required": [ "name", "value" ] }, "Search_enum@0x1b": { "type": "string", "enum": [ "auto", "browser", "curl", "cf-browser-rendering" ], "description": "Enum<\"auto\" | \"browser\" | \"curl\" | \"cf-browser-rendering\">" }, "Search_Viewport@0x1c": { "title": "Viewport", "type": "object", "properties": { "width": { "type": "number", "default": 1280 }, "height": { "type": "number", "default": 1280 }, "deviceScaleFactor": { "type": "number" }, "isMobile": { "type": "boolean" }, "isLandscape": { "type": "boolean" }, "hasTouch": { "type": "boolean" } } }, "Search_TurnDownTweakableOptions@0x23": { "title": "TurnDownTweakableOptions", "type": "object", "properties": { "headingStyle": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x1d" } ], "summary": "Turndown options > headingStyle", "description": "Turndown options > headingStyle" }, "hr": { "type": "string", "summary": "Turndown options > hr", "description": "Turndown options > hr\n\n- Some validators will be applied on value(s): (v) => v.length > 0 && v.length <= 128" }, "bulletListMarker": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x1e" } ], "summary": "Turndown options > bulletListMarker", "description": "Turndown options > bulletListMarker" }, "emDelimiter": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x1f" } ], "summary": "Turndown options > emDelimiter", "description": "Turndown options > emDelimiter" }, "strongDelimiter": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x20" } ], "summary": "Turndown options > strongDelimiter", "description": "Turndown options > strongDelimiter" }, "linkStyle": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x21" } ], "summary": "Turndown options > linkStyle", "description": "Turndown options > linkStyle" }, "linkReferenceStyle": { "allOf": [ { "$ref": "#/components/schemas/Search_enum@0x22" } ], "summary": "Turndown options > linkReferenceStyle", "description": "Turndown options > linkReferenceStyle" } } }, "Search_enum@0x1d": { "type": "string", "enum": [ "setext", "atx" ], "description": "Enum<\"setext\" | \"atx\">" }, "Search_enum@0x1e": { "type": "string", "enum": [ "-", "+", "*" ], "description": "Enum<\"-\" | \"+\" | \"*\">" }, "Search_enum@0x1f": { "type": "string", "enum": [ "_", "*" ], "description": "Enum<\"_\" | \"*\">" }, "Search_enum@0x20": { "type": "string", "enum": [ "__", "**" ], "description": "Enum<\"__\" | \"**\">" }, "Search_enum@0x21": { "type": "string", "enum": [ "inlined", "referenced", "discarded" ], "description": "Enum<\"inlined\" | \"referenced\" | \"discarded\">" }, "Search_enum@0x22": { "type": "string", "enum": [ "full", "collapsed", "shortcut", "discarded" ], "description": "Enum<\"full\" | \"collapsed\" | \"shortcut\" | \"discarded\">" }, "Search_OCRPreferences@0x24": { "title": "OCRPreferences", "type": "object", "properties": { "preferEndToEnd": { "type": "boolean", "summary": "Prefer end-to-end OCR mode (over PDF text)", "description": "Prefer end-to-end OCR mode (over PDF text)" }, "preferImgOrder": { "type": "boolean", "summary": "Prefer better image order over particular markdown format (only applies in end-to-end mode)", "description": "Prefer better image order over particular markdown format (only applies in end-to-end mode)" }, "inlineFormula": { "type": "boolean", "summary": "Blocks with inline formulas should go through OCR (only applies in non-end-to-end mode)", "description": "Blocks with inline formulas should go through OCR (only applies in non-end-to-end mode)" }, "blockFormula": { "type": "boolean", "summary": "Formula blocks should go through OCR (only applies in non-end-to-end mode)", "description": "Formula blocks should go through OCR (only applies in non-end-to-end mode)", "default": true }, "table": { "type": "boolean", "summary": "Table blocks should go through OCR (only applies in non-end-to-end mode)", "description": "Table blocks should go through OCR (only applies in non-end-to-end mode)", "default": true } } }, "Search_enum@0x25": { "type": "string", "enum": [ "html", "visible-content", "mutation-idle", "resource-idle", "media-idle", "network-idle" ], "description": "Enum<\"html\" | \"visible-content\" | \"mutation-idle\" | \"resource-idle\" | \"media-idle\" | \"network-idle\">" }, "Search_enum@0x26": { "type": "string", "enum": [ "true", "h1", "h2", "h3", "h4", "h5", "structured", "s1", "s2", "s3", "s4", "s5" ], "description": "Enum<\"true\" | \"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"structured\" | \"s1\" | \"s2\" | \"s3\" | \"s4\" | \"s5\">" }, "Search_GoogleSearchExplicitOperatorsDto@0x28": { "title": "GoogleSearchExplicitOperatorsDto", "type": "object", "properties": { "ext": { "type": "array", "items": { "type": "string" }, "summary": "Returns web pages with a specific file extension. Example: to find the Honda GX120 Owner’s manual in PDF, type “Honda GX120 ownners manual ext:pdf”.", "description": "Search operator `ext:` (file extension)." }, "filetype": { "type": "array", "items": { "type": "string" }, "summary": "Returns web pages created in the specified file type. Example: to find a web page created in PDF format about the evaluation of age-related cognitive changes, type “evaluation of age cognitive changes filetype:pdf”.", "description": "Search operator `filetype:`, e.g. `pdf`." }, "intitle": { "type": "array", "items": { "type": "string" }, "summary": "Returns webpages containing the specified term in the title of the page. Example: to find pages about SEO conferences making sure the results contain 2023 in the title, type “seo conference intitle:2023”.", "description": "Search operator `intitle:`: words that must appear in the page title." }, "loc": { "type": "array", "items": { "type": "string" }, "summary": "Returns web pages written in the specified language. The language code must be in the ISO 639-1 two-letter code format. Example: to find information on visas only in Spanish, type “visas lang:es”.", "description": "Search operator `loc:` (location)." }, "site": { "type": "array", "items": { "type": "string" }, "summary": "Returns web pages coming only from a specific web site. Example: to find information about Goggles only on Brave pages, type “goggles site:brave.com”.", "description": "Keep results to this domain, e.g. `https://jina.ai`. Same as the `X-Site` header." } } }, "Search_enum@0x29": { "type": "string", "enum": [ "web", "images", "news" ], "description": "Enum<\"web\" | \"images\" | \"news\">" }, "Search_enum@0x2a": { "type": "string", "enum": [ "google", "bing", "reader" ], "description": "Enum<\"google\" | \"bing\" | \"reader\">" }, "Search_enum@0x2b": { "type": "string", "enum": [ "google", "bing", "reader" ], "description": "Enum<\"google\" | \"bing\" | \"reader\">" }, "Search_Array@0x33": { "title": "Array", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Search_FormattedPageDto@0x0b" } ] } }, "Search_FormattedPageDto@0x0b": { "title": "FormattedPageDto", "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string", "description": "The URL to read. Not needed when the URL is already in the path (`https://r.jina.ai/`)." }, "content": { "type": "string" }, "chunks": { "allOf": [ { "$ref": "#/components/schemas/Search_Array@0x2c" } ] }, "publishedTime": { "type": "string" }, "html": { "type": "string", "description": "Raw HTML to convert, instead of fetching a URL. Used when no `url` is given." }, "text": { "type": "string" }, "screenshotUrl": { "type": "string" }, "pageshotUrl": { "type": "string" }, "numPages": { "type": "number" }, "links": { "oneOf": [ { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, { "allOf": [ { "$ref": "#/components/schemas/Search_Record@0x2d" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Search_Array@0x2e" } ] } ] }, "images": { "oneOf": [ { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, { "allOf": [ { "$ref": "#/components/schemas/Search_Record@0x2f" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Search_Array@0x30" } ] } ] }, "warning": { "type": "string" }, "metadata": { "oneOf": [ { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, { "allOf": [ { "$ref": "#/components/schemas/Search_Record@0x31" } ] } ] }, "external": { "oneOf": [ { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, { "allOf": [ { "$ref": "#/components/schemas/Search_Record@0x08|object>@0x09|object>@0x32" } ] } ] }, "httpStatus": { "type": "number" }, "httpStatusText": { "type": "string" }, "storageState": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true } }, "required": [ "url" ] }, "Search_Array@0x2c": { "title": "Array", "type": "array", "items": { "type": "string" } }, "Search_Record@0x2d": { "title": "Record", "type": "object", "properties": {}, "additionalProperties": { "type": "string" } }, "Search_Array@0x2e": { "title": "Array", "type": "array", "items": { "type": "string" } }, "Search_Record@0x2f": { "title": "Record", "type": "object", "properties": {}, "additionalProperties": { "type": "string" } }, "Search_Array@0x30": { "title": "Array", "type": "array", "items": { "type": "string" } }, "Search_Record@0x31": { "title": "Record", "type": "object", "properties": {}, "additionalProperties": { "type": "string" } }, "Search_Record@0x08|object>@0x09|object>@0x32": { "title": "Record@0x08|object>@0x09|object>", "type": "object", "properties": {}, "additionalProperties": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_Record@0x08|object>@0x09" } ] }, { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true } ] } }, "Search_Record@0x08|object>@0x09": { "title": "Record@0x08|object>", "type": "object", "properties": {}, "additionalProperties": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Search_Record@0x08" } ] }, { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true } ] } }, "Search_Record@0x08": { "title": "Record", "type": "object", "properties": {}, "additionalProperties": { "oneOf": [ { "type": "string" }, { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true } ] } }, "Search_OutputServerEventStream@0x34": { "type": "string", "format": "binary", "description": "Binary data (stream)" }, "Search_ParamValidationError@0x35": { "title": "ParamValidationError", "type": "object", "properties": { "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 400 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 40001 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Search_AuthenticationFailedError@0x36": { "title": "AuthenticationFailedError", "type": "object", "properties": { "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 401 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 40102 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Search_AuthenticationRequiredError@0x37": { "title": "AuthenticationRequiredError", "type": "object", "properties": { "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 401 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 40103 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Search_InsufficientBalanceError@0x38": { "title": "InsufficientBalanceError", "type": "object", "properties": { "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 402 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 40203 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Search_AbuseAlleviationError@0x39": { "title": "AbuseAlleviationError", "type": "object", "properties": { "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 403 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 40305 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Search_AssertionFailureError@0x3a": { "title": "AssertionFailureError", "type": "object", "properties": { "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 422 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 42206 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Search_RateLimitTriggeredError@0x3b": { "title": "RateLimitTriggeredError", "type": "object", "properties": { "retryAfter": { "type": "number", "summary": "Retry after seconds", "description": "Retry after seconds" }, "retryAfterDate": { "type": "string", "format": "date-time", "summary": "Retry after date", "description": "Retry after date" }, "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 429 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 42903 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Search_DownstreamServiceError@0x3c": { "title": "DownstreamServiceError", "type": "object", "properties": { "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 500 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 50002 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Search_ServiceBadAttemptError@0x3d": { "title": "ServiceBadAttemptError", "type": "object", "properties": { "code": { "type": "number", "summary": "Expect HTTP response codes", "description": "[REQUIRED]\n\nExpect HTTP response codes", "default": 503 }, "status": { "type": "number", "summary": "Application status code for the error in extension to HTTP status codes", "description": "[REQUIRED]\n\nApplication status code for the error in extension to HTTP status codes", "default": 50304 }, "message": { "type": "string", "description": "[REQUIRED]" }, "readableMessage": { "type": "string" } }, "additionalProperties": { "description": "Can be any value - string, number, boolean, array or object.", "nullable": true }, "required": [ "code", "status", "message" ] }, "Search_Array@0x3e": { "title": "Array", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Search_FormattedPageDto@0x0b" } ] } }, "AudioDoc": { "properties": { "audio": { "type": "string", "title": "Audio", "description": "Audio as a URL or base64-encoded string." } }, "type": "object", "required": [ "audio" ], "title": "AudioDoc" }, "BaseUsage": { "properties": { "total_tokens": { "type": "integer", "title": "Total Tokens", "description": "Total number of tokens processed." } }, "type": "object", "required": [ "total_tokens" ], "title": "BaseUsage" }, "BatchEmbeddingRequest": { "properties": { "model": { "type": "string", "enum": [ "jina-embeddings-v5-text-nano", "jina-embeddings-v5-text-small" ], "title": "Model", "description": "The embedding model to use for batch processing." }, "input_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Input Url", "description": "URL to input JSONL file (GCS, S3, or HTTP). Either input_url or input must be provided." }, "input": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Input", "description": "Inline JSONL lines for small batches. Either input_url or input must be provided." }, "task": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Task", "description": "Task optimization: retrieval, text-matching, clustering, or classification.", "default": "text-matching" }, "dimensions": { "anyOf": [ { "type": "integer", "maximum": 1024, "exclusiveMinimum": 0 }, { "type": "null" } ], "title": "Dimensions", "description": "Number of dimensions for output embeddings (1-1024)." }, "normalized": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Normalized", "description": "If true (default), embeddings are L2-normalized to unit length.", "default": true }, "webhook_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Webhook Url", "description": "URL to POST notification when job completes." } }, "type": "object", "required": [ "model" ], "title": "BatchEmbeddingRequest", "description": "Request to create a batch embedding job.", "examples": [ { "dimensions": 512, "input_url": "gs://my-bucket/inputs.jsonl", "model": "jina-embeddings-v5-text-small", "task": "retrieval" }, { "input": [ { "body": { "input": "Hello world" }, "custom_id": "req-1" }, { "body": { "input": "Batch embeddings" }, "custom_id": "req-2" } ], "model": "jina-embeddings-v5-text-nano", "task": "text-matching" } ] }, "BatchStats": { "properties": { "total": { "type": "integer", "title": "Total", "description": "Total number of input lines." }, "completed": { "type": "integer", "title": "Completed", "description": "Number of successfully processed lines.", "default": 0 }, "failed": { "type": "integer", "title": "Failed", "description": "Number of failed lines.", "default": 0 }, "total_tokens": { "type": "integer", "title": "Total Tokens", "description": "Total tokens consumed across all processed lines.", "default": 0 } }, "type": "object", "required": [ "total" ], "title": "BatchStats", "description": "Statistics for a batch job." }, "BatchStatus": { "properties": { "batch_id": { "type": "string", "title": "Batch Id", "description": "Unique identifier for the batch job." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "expired", "cancelled" ], "title": "Status", "description": "Current status of the batch job." }, "model": { "type": "string", "title": "Model", "description": "The model used for embedding." }, "created_at": { "type": "string", "title": "Created At", "description": "ISO 8601 timestamp when job was created." }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Completed At", "description": "ISO 8601 timestamp when job completed (if finished)." }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expires At", "description": "ISO 8601 timestamp when output URL expires (created_at + 24h)." }, "output_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Output Url", "description": "Signed URL to download output JSONL (24h expiry)." }, "error_file_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error File Url", "description": "URL to download error JSONL for failed lines." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message if job failed." }, "stats": { "anyOf": [ { "$ref": "#/components/schemas/BatchStats" }, { "type": "null" } ], "description": "Processing statistics." } }, "type": "object", "required": [ "batch_id", "status", "model", "created_at" ], "title": "BatchStatus", "description": "Status of a batch embedding job.", "examples": [ { "batch_id": "batch_abc123", "completed_at": "2024-01-15T10:35:00Z", "created_at": "2024-01-15T10:30:00Z", "expires_at": "2024-01-16T10:30:00Z", "model": "jina-embeddings-v5-text-small", "output_url": "https://storage.googleapis.com/...", "stats": { "completed": 998, "failed": 2, "total": 1000 }, "status": "completed" } ] }, "ChatCompletionRequest": { "properties": { "messages": { "items": { "$ref": "#/components/schemas/ChatMessage" }, "type": "array", "minItems": 1, "title": "Messages" }, "model": { "type": "string", "const": "jina-ocr-v1", "title": "Model", "description": "The model to use." }, "stream": { "type": "boolean", "title": "Stream", "default": false }, "stream_options": { "anyOf": [ { "$ref": "#/components/schemas/StreamOptions" }, { "type": "null" } ] }, "max_completion_tokens": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Max Completion Tokens" }, "temperature": { "anyOf": [ { "type": "number", "maximum": 2, "minimum": 0 }, { "type": "null" } ], "title": "Temperature" }, "top_p": { "anyOf": [ { "type": "number", "maximum": 1, "minimum": 0 }, { "type": "null" } ], "title": "Top P" }, "presence_penalty": { "anyOf": [ { "type": "number", "maximum": 2, "minimum": -2 }, { "type": "null" } ], "title": "Presence Penalty" }, "frequency_penalty": { "anyOf": [ { "type": "number", "maximum": 2, "minimum": -2 }, { "type": "null" } ], "title": "Frequency Penalty" }, "stop": { "anyOf": [ { "type": "string" }, { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Stop" }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Seed" }, "logprobs": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Logprobs" }, "top_logprobs": { "anyOf": [ { "type": "integer", "maximum": 20, "minimum": 0 }, { "type": "null" } ], "title": "Top Logprobs" }, "logit_bias": { "anyOf": [ { "additionalProperties": { "type": "number" }, "type": "object" }, { "type": "null" } ], "title": "Logit Bias" }, "response_format": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/ResponseFormatText" }, { "$ref": "#/components/schemas/ResponseFormatJSONObject" }, { "$ref": "#/components/schemas/ResponseFormatJSONSchema" } ], "discriminator": { "propertyName": "type", "mapping": { "json_object": "#/components/schemas/ResponseFormatJSONObject", "json_schema": "#/components/schemas/ResponseFormatJSONSchema", "text": "#/components/schemas/ResponseFormatText" } } }, { "type": "null" } ], "title": "Response Format" } }, "type": "object", "required": [ "messages", "model" ], "title": "ChatCompletionRequest", "description": "The public request body. Every field here reaches the engine." }, "ChatMessage": { "properties": { "role": { "type": "string", "enum": [ "system", "developer", "user", "assistant" ], "title": "Role" }, "content": { "anyOf": [ { "type": "string" }, { "items": { "oneOf": [ { "$ref": "#/components/schemas/TextContentPart" }, { "$ref": "#/components/schemas/ImageContentPart" } ], "discriminator": { "propertyName": "type", "mapping": { "image_url": "#/components/schemas/ImageContentPart", "text": "#/components/schemas/TextContentPart" } } }, "type": "array" }, { "type": "null" } ], "title": "Content" } }, "type": "object", "required": [ "role" ], "title": "ChatMessage" }, "ClipV1Request": { "properties": { "embedding_type": { "anyOf": [ { "type": "string", "enum": [ "float", "base64", "binary", "ubinary" ] }, { "items": { "type": "string", "enum": [ "float", "base64", "binary", "ubinary" ] }, "type": "array" }, { "type": "null" } ], "title": "Embedding Type", "description": "Output encoding format: `float`, `base64`, `binary`, `ubinary`, or a list of these." }, "normalized": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Normalized", "description": "If true (default), embeddings are L2-normalized to unit length.", "default": true }, "truncate": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Truncate", "description": "If true, truncates input exceeding the model's max token limit instead of returning an error.", "default": false }, "model": { "type": "string", "const": "jina-clip-v1", "title": "Model", "description": "The CLIP model to use." }, "input": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/TextDoc" }, { "$ref": "#/components/schemas/ImageDoc" }, { "$ref": "#/components/schemas/PDFDoc" }, { "items": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/TextDoc" }, { "$ref": "#/components/schemas/ImageDoc" } ] }, "type": "array" } ], "title": "Input", "description": "Content to embed: a string, `TextDoc`, `ImageDoc`, `PDFDoc`, or a list of items. PDFs must be sent individually. Images up to 8MB." } }, "type": "object", "required": [ "model", "input" ], "title": "ClipV1Request", "description": "CLIP v1 multimodal model for images and text in a shared vector space.", "example": { "embedding_type": "float", "input": [ { "image": "https://i.ibb.co/nQNGqL0/beach1.jpg" }, "A beautiful sunset over the beach" ], "model": "jina-clip-v1", "normalized": true } }, "ClipV2Request": { "properties": { "embedding_type": { "anyOf": [ { "type": "string", "enum": [ "float", "base64", "binary", "ubinary" ] }, { "items": { "type": "string", "enum": [ "float", "base64", "binary", "ubinary" ] }, "type": "array" }, { "type": "null" } ], "title": "Embedding Type", "description": "Output encoding format: `float`, `base64`, `binary`, `ubinary`, or a list of these." }, "normalized": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Normalized", "description": "If true (default), embeddings are L2-normalized to unit length.", "default": true }, "truncate": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Truncate", "description": "If true, truncates input exceeding the model's max token limit instead of returning an error.", "default": false }, "model": { "type": "string", "const": "jina-clip-v2", "title": "Model", "description": "The CLIP model to use." }, "input": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/TextDoc" }, { "$ref": "#/components/schemas/ImageDoc" }, { "$ref": "#/components/schemas/PDFDoc" }, { "items": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/TextDoc" }, { "$ref": "#/components/schemas/ImageDoc" } ] }, "type": "array" } ], "title": "Input", "description": "Content to embed: a string, `TextDoc`, `ImageDoc`, `PDFDoc`, or a list of items. PDFs must be sent individually. Images up to 8MB." }, "task": { "anyOf": [ { "type": "string", "const": "retrieval.query" }, { "type": "null" } ], "title": "Task", "description": "Set to `retrieval.query` to optimize for search queries. Leave unset for documents." }, "dimensions": { "anyOf": [ { "type": "integer", "maximum": 1024, "exclusiveMinimum": 0 }, { "type": "null" } ], "title": "Dimensions", "description": "Number of dimensions for the output embedding. Range: 1-1024." } }, "type": "object", "required": [ "model", "input" ], "title": "ClipV2Request", "description": "CLIP v2 with Matryoshka representation learning for flexible dimensions.", "example": { "dimensions": 512, "embedding_type": "float", "input": [ { "image": "https://i.ibb.co/nQNGqL0/beach1.jpg" }, "Jina AI - Your Search Foundation - Supercharged" ], "model": "jina-clip-v2", "normalized": true, "task": "retrieval.query" } }, "CodeEmbeddings1500MRequest": { "properties": { "embedding_type": { "anyOf": [ { "type": "string", "enum": [ "float", "base64", "binary", "ubinary" ] }, { "items": { "type": "string", "enum": [ "float", "base64", "binary", "ubinary" ] }, "type": "array" }, { "type": "null" } ], "title": "Embedding Type", "description": "Output encoding format: `float`, `base64`, `binary`, `ubinary`, or a list of these." }, "model": { "type": "string", "const": "jina-code-embeddings-1.5b", "title": "Model", "description": "The code embedding model to use." }, "input": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/TextDoc" }, { "items": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/TextDoc" } ] }, "type": "array" } ], "title": "Input", "description": "Code or text to embed: a string, `TextDoc`, or a list of items." }, "truncate": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Truncate", "description": "If true, truncates input exceeding the model's max token limit instead of returning an error.", "default": false }, "dimensions": { "anyOf": [ { "type": "integer", "maximum": 1536, "exclusiveMinimum": 0 }, { "type": "null" } ], "title": "Dimensions", "description": "Number of dimensions for the output embedding. Range: 1-1536." }, "task": { "anyOf": [ { "type": "string", "enum": [ "nl2code.query", "nl2code.passage", "qa.query", "qa.passage", "code2code.query", "code2code.passage", "code2nl.query", "code2nl.passage", "code2completion.query", "code2completion.passage" ] }, { "type": "null" } ], "title": "Task", "description": "Task type: `nl2code`, `qa`, `code2code`, `code2nl`, or `code2completion`. Use `.query` for queries, `.passage` for documents.", "default": "nl2code.query" } }, "type": "object", "required": [ "model", "input" ], "title": "CodeEmbeddings1500MRequest", "description": "Code embeddings (1.5b) for search over source, and between source and prose.", "examples": [ { "dimensions": 512, "input": [ "import * as ElementPlusIconsVue from '@element-plus/icons-vue'\nconst app = createApp(App)\nfor (const [key, component] of Object.entries(ElementPlusIconsVue)) {\n app.component(key, component)\n}" ], "model": "jina-code-embeddings-1.5b", "task": "nl2code.passage" } ] }, "CodeEmbeddings500MRequest": { "properties": { "embedding_type": { "anyOf": [ { "type": "string", "enum": [ "float", "base64", "binary", "ubinary" ] }, { "items": { "type": "string", "enum": [ "float", "base64", "binary", "ubinary" ] }, "type": "array" }, { "type": "null" } ], "title": "Embedding Type", "description": "Output encoding format: `float`, `base64`, `binary`, `ubinary`, or a list of these." }, "model": { "type": "string", "const": "jina-code-embeddings-0.5b", "title": "Model", "description": "The code embedding model to use." }, "input": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/TextDoc" }, { "items": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/TextDoc" } ] }, "type": "array" } ], "title": "Input", "description": "Code or text to embed: a string, `TextDoc`, or a list of items." }, "truncate": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Truncate", "description": "If true, truncates input exceeding the model's max token limit instead of returning an error.", "default": false }, "dimensions": { "anyOf": [ { "type": "integer", "maximum": 896, "exclusiveMinimum": 0 }, { "type": "null" } ], "title": "Dimensions", "description": "Number of dimensions for the output embedding. Range: 1-896." }, "task": { "anyOf": [ { "type": "string", "enum": [ "nl2code.query", "nl2code.passage", "qa.query", "qa.passage", "code2code.query", "code2code.passage", "code2nl.query", "code2nl.passage", "code2completion.query", "code2completion.passage" ] }, { "type": "null" } ], "title": "Task", "description": "Task type: `nl2code`, `qa`, `code2code`, `code2nl`, or `code2completion`. Use `.query` for queries, `.passage` for documents.", "default": "nl2code.query" } }, "type": "object", "required": [ "model", "input" ], "title": "CodeEmbeddings500MRequest", "description": "Code embeddings (0.5b) for search over source, and between source and prose.", "examples": [ { "dimensions": 512, "embedding_type": "float", "input": [ "import * as ElementPlusIconsVue from '@element-plus/icons-vue'\nconst app = createApp(App)\nfor (const [key, component] of Object.entries(ElementPlusIconsVue)) {\n app.component(key, component)\n}" ], "model": "jina-code-embeddings-0.5b", "task": "nl2code.passage" } ] }, "ColbertV1Request": { "properties": { "embedding_type": { "anyOf": [ { "type": "string", "enum": [ "float", "base64", "binary", "ubinary" ] }, { "items": { "type": "string", "enum": [ "float", "base64", "binary", "ubinary" ] }, "type": "array" }, { "type": "null" } ], "title": "Embedding Type", "description": "Output encoding format: `float`, `base64`, `binary`, `ubinary`, or a list of these." }, "model": { "type": "string", "const": "jina-colbert-v1-en", "title": "Model", "description": "The ColBERT model to use." }, "input": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/TextDoc" }, { "items": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/TextDoc" } ] }, "type": "array" } ], "title": "Input", "description": "Text to embed: a string, `TextDoc`, or a list of items." }, "input_type": { "anyOf": [ { "type": "string", "enum": [ "query", "document" ] }, { "type": "null" } ], "title": "Input Type", "description": "Role of the input: `query` for search queries, `document` for passages.", "default": "document" } }, "type": "object", "required": [ "model", "input" ], "title": "ColbertV1Request", "description": "ColBERT v1 for token-level late interaction retrieval.", "example": { "embedding_type": "float", "input": [ "A beautiful sunset over the beach", "Jina AI - Your Search Foundation - Supercharged" ], "input_type": "document", "model": "jina-colbert-v1-en" } }, "ColbertV2Request": { "properties": { "embedding_type": { "anyOf": [ { "type": "string", "enum": [ "float", "base64", "binary", "ubinary" ] }, { "items": { "type": "string", "enum": [ "float", "base64", "binary", "ubinary" ] }, "type": "array" }, { "type": "null" } ], "title": "Embedding Type", "description": "Output encoding format: `float`, `base64`, `binary`, `ubinary`, or a list of these." }, "model": { "type": "string", "const": "jina-colbert-v2", "title": "Model", "description": "The ColBERT model to use." }, "input": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/TextDoc" }, { "items": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/TextDoc" } ] }, "type": "array" } ], "title": "Input", "description": "Text to embed: a string, `TextDoc`, or a list of items." }, "input_type": { "anyOf": [ { "type": "string", "enum": [ "query", "document" ] }, { "type": "null" } ], "title": "Input Type", "description": "Role of the input: `query` for search queries, `document` for passages.", "default": "document" }, "dimensions": { "anyOf": [ { "type": "integer", "enum": [ 64, 96, 128 ] }, { "type": "null" } ], "title": "Dimensions", "description": "Dimensions per token: `64`, `96`, or `128`. Defaults to 128." } }, "type": "object", "required": [ "model", "input" ], "title": "ColbertV2Request", "description": "ColBERT v2 with Matryoshka representation learning for flexible dimensions.", "example": { "dimensions": 128, "embedding_type": "float", "input": [ "A beautiful sunset over the beach" ], "input_type": "query", "model": "jina-colbert-v2" } }, "ELSERV2EmbeddingUsage": { "properties": { "total_tokens": { "type": "integer", "title": "Total Tokens", "description": "Total number of tokens processed." }, "input_tokens": { "type": "integer", "title": "Input Tokens", "description": "Number of tokens in the input." }, "output_tokens": { "type": "integer", "title": "Output Tokens", "description": "Number of tokens in the output." } }, "type": "object", "required": [ "total_tokens", "input_tokens", "output_tokens" ], "title": "ELSERV2EmbeddingUsage", "description": "Token usage statistics for Elser v2 embedding requests." }, "EmbeddingResponse": { "properties": { "model": { "type": "string", "title": "Model", "description": "The model used to generate the embeddings." }, "object": { "type": "string", "title": "Object", "description": "Object type, always `list`.", "default": "list" }, "usage": { "anyOf": [ { "$ref": "#/components/schemas/EmbeddingUsage" }, { "$ref": "#/components/schemas/ELSERV2EmbeddingUsage" }, { "$ref": "#/components/schemas/BaseUsage" } ], "title": "Usage", "description": "Token usage statistics." }, "data": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SingleEmbeddingData" }, "type": "array" }, { "items": { "$ref": "#/components/schemas/MultiEmbeddingData" }, "type": "array" }, { "items": { "additionalProperties": { "type": "number" }, "type": "object" }, "type": "array" } ], "title": "Data", "description": "List of embeddings, one per input item. A sparse model returns each as a map of token to weight instead of a vector." } }, "type": "object", "required": [ "model", "usage", "data" ], "title": "EmbeddingResponse", "description": "Response containing embeddings for all input items." }, "EmbeddingUsage": { "properties": { "total_tokens": { "type": "integer", "title": "Total Tokens", "description": "Total number of tokens processed." }, "prompt_tokens": { "type": "integer", "title": "Prompt Tokens", "description": "Number of text input tokens. For multimodal responses the per-modality fields below account for non-text tokens; for text-only responses this equals `total_tokens`." }, "image_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Image Tokens", "description": "Number of tokens from image inputs." }, "audio_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Audio Tokens", "description": "Number of tokens from audio inputs." }, "video_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Video Tokens", "description": "Number of tokens from video inputs." } }, "type": "object", "required": [ "total_tokens", "prompt_tokens" ], "title": "EmbeddingUsage", "description": "Token usage statistics for embedding requests.\n\n`prompt_tokens` counts text input tokens (including the task prefix and\nany structural/special framing). For text-only models — and any response\nthat doesn't populate a per-modality breakdown — it equals `total_tokens`.\nFor multimodal v5-omni responses, `total_tokens` is the aggregate across\nall modalities and the per-modality fields (`image_tokens` /\n`audio_tokens` / `video_tokens`) are sub-counts, so the invariant holds\nexactly (absent per-modality fields count as 0):\n\n total_tokens == prompt_tokens + image_tokens + audio_tokens + video_tokens\n\nPDF pages are rendered to images and counted in `image_tokens`.\n\nAll MM fields are Optional so text-only responses don't have to populate\nthem, and serializers should drop unset fields (`exclude_none=True`)." }, "EmbeddingsV2Request": { "properties": { "embedding_type": { "anyOf": [ { "type": "string", "enum": [ "float", "base64", "binary", "ubinary" ] }, { "items": { "type": "string", "enum": [ "float", "base64", "binary", "ubinary" ] }, "type": "array" }, { "type": "null" } ], "title": "Embedding Type", "description": "Output encoding format: `float`, `base64`, `binary`, `ubinary`, or a list of these." }, "normalized": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Normalized", "description": "If true (default), embeddings are L2-normalized to unit length.", "default": true }, "truncate": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Truncate", "description": "If true, truncates input exceeding the model's max token limit instead of returning an error.", "default": false }, "model": { "type": "string", "enum": [ "jina-embeddings-v2-base-en", "jina-embeddings-v2-base-zh", "jina-embeddings-v2-base-de", "jina-embeddings-v2-base-es", "jina-embeddings-v2-base-code" ], "title": "Model", "description": "The embedding model to use." }, "input": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/TextDoc" }, { "items": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/TextDoc" } ] }, "type": "array" } ], "title": "Input", "description": "Text to embed: a string, `TextDoc`, or a list of items." } }, "type": "object", "required": [ "model", "input" ], "title": "EmbeddingsV2Request", "description": "Jina Embeddings v2 text embedding models.", "example": { "embedding_type": "float", "input": [ "A beautiful sunset over the beach", "Jina AI - Your Search Foundation - Supercharged" ], "model": "jina-embeddings-v2-base-en", "normalized": true, "truncate": false } }, "EmbeddingsV3Request": { "properties": { "embedding_type": { "anyOf": [ { "type": "string", "enum": [ "float", "base64", "binary", "ubinary" ] }, { "items": { "type": "string", "enum": [ "float", "base64", "binary", "ubinary" ] }, "type": "array" }, { "type": "null" } ], "title": "Embedding Type", "description": "Output encoding format: `float`, `base64`, `binary`, `ubinary`, or a list of these." }, "normalized": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Normalized", "description": "If true (default), embeddings are L2-normalized to unit length.", "default": true }, "truncate": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Truncate", "description": "If true, truncates input exceeding the model's max token limit instead of returning an error.", "default": false }, "model": { "type": "string", "const": "jina-embeddings-v3", "title": "Model", "description": "The embedding model to use." }, "input": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/TextDoc" }, { "items": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/TextDoc" } ] }, "type": "array" } ], "title": "Input", "description": "Text to embed: a string, `TextDoc`, or a list of items." }, "task": { "anyOf": [ { "type": "string", "enum": [ "retrieval.query", "retrieval.passage", "text-matching", "classification", "separation" ] }, { "type": "null" } ], "title": "Task", "description": "Task optimization: `retrieval.query` for queries, `retrieval.passage` for documents, `text-matching` for similarity, `classification`, or `separation` for clustering." }, "late_chunking": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Late Chunking", "description": "If true, concatenates all inputs and processes as one sequence before splitting. Useful for context across chunks." }, "dimensions": { "anyOf": [ { "type": "integer", "maximum": 1024, "exclusiveMinimum": 0 }, { "type": "null" } ], "title": "Dimensions", "description": "Number of dimensions for the output embedding. Range: 1-1024." } }, "type": "object", "required": [ "model", "input" ], "title": "EmbeddingsV3Request", "description": "Jina Embeddings v3 with task-specific optimization and flexible dimensions.", "example": { "dimensions": 512, "embedding_type": "float", "input": [ "A beautiful sunset over the beach" ], "late_chunking": false, "model": "jina-embeddings-v3", "normalized": true, "task": "retrieval.query" } }, "EmbeddingsV4Request": { "properties": { "embedding_type": { "anyOf": [ { "type": "string", "enum": [ "float", "base64", "binary", "ubinary" ] }, { "items": { "type": "string", "enum": [ "float", "base64", "binary", "ubinary" ] }, "type": "array" }, { "type": "null" } ], "title": "Embedding Type", "description": "Output encoding format: `float`, `base64`, `binary`, `ubinary`, or a list of these." }, "model": { "type": "string", "const": "jina-embeddings-v4", "title": "Model", "description": "The embedding model to use." }, "input": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/TextDoc" }, { "$ref": "#/components/schemas/ImageDoc" }, { "$ref": "#/components/schemas/PDFDoc" }, { "items": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/TextDoc" }, { "$ref": "#/components/schemas/ImageDoc" } ] }, "type": "array" } ], "title": "Input", "description": "Content to embed: a string, `TextDoc`, `ImageDoc`, `PDFDoc`, or a list of items. PDFs must be sent individually. Images up to 8MB; PDFs up to 8MB." }, "truncate": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Truncate", "description": "If true, truncates input exceeding the model's max token limit instead of returning an error.", "default": false }, "late_chunking": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Late Chunking", "description": "If true, concatenates all text inputs and processes as one sequence before splitting. Only works with text." }, "dimensions": { "anyOf": [ { "type": "integer", "maximum": 2048, "exclusiveMinimum": 0 }, { "type": "null" } ], "title": "Dimensions", "description": "Number of dimensions for the output embedding. Range: 1-2048." }, "task": { "anyOf": [ { "type": "string", "enum": [ "text-matching", "retrieval.query", "retrieval.passage", "code.query", "code.passage" ] }, { "type": "null" } ], "title": "Task", "description": "Task optimization: `text-matching` (default), `retrieval.query`, `retrieval.passage`, `code.query`, or `code.passage`.", "default": "text-matching" }, "return_multivector": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Return Multivector", "description": "If true, returns one embedding per token. Cannot be used with `dimensions`.", "default": false }, "return_tokenized_input": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Return Tokenized Input", "description": "If true, returns tokens alongside multi-vector embeddings. Requires `return_multivector=true`.", "default": false } }, "type": "object", "required": [ "model", "input" ], "title": "EmbeddingsV4Request", "description": "Jina Embeddings v4 multimodal model for text, images, and PDFs.", "examples": [ { "dimensions": 512, "embedding_type": "float", "input": [ { "image": "https://i.ibb.co/nQNGqL0/beach1.jpg" }, { "text": "A beautiful sunset over the beach" } ], "model": "jina-embeddings-v4" }, { "embedding_type": "float", "input": [ "Jina AI - Your Search Foundation - Supercharged" ], "late_chunking": true, "model": "jina-embeddings-v4", "task": "retrieval.passage" }, { "dimensions": 512, "embedding_type": "float", "input": { "pdf": "https://example.com/sample.pdf" }, "model": "jina-embeddings-v4" } ] }, "EmbeddingsV5Request": { "properties": { "embedding_type": { "anyOf": [ { "type": "string", "enum": [ "float", "base64", "binary", "ubinary" ] }, { "items": { "type": "string", "enum": [ "float", "base64", "binary", "ubinary" ] }, "type": "array" }, { "type": "null" } ], "title": "Embedding Type", "description": "Output encoding format: `float`, `base64`, `binary`, `ubinary`, or a list of these." }, "normalized": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Normalized", "description": "If true (default), embeddings are L2-normalized to unit length.", "default": true }, "truncate": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Truncate", "description": "If true, truncates input exceeding the model's max token limit instead of returning an error.", "default": false }, "model": { "type": "string", "enum": [ "jina-embeddings-v5-text-nano", "jina-embeddings-v5-text-small", "jina-embeddings-v5-omni-small", "jina-embeddings-v5-omni-nano" ], "title": "Model", "description": "The embedding model to use." }, "input": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/TextDoc" }, { "$ref": "#/components/schemas/ImageDoc" }, { "$ref": "#/components/schemas/VideoDoc" }, { "$ref": "#/components/schemas/AudioDoc" }, { "$ref": "#/components/schemas/PDFDoc" }, { "items": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/TextDoc" }, { "$ref": "#/components/schemas/ImageDoc" }, { "$ref": "#/components/schemas/VideoDoc" }, { "$ref": "#/components/schemas/AudioDoc" }, { "$ref": "#/components/schemas/MergedContentGroup" } ] }, "type": "array" } ], "title": "Input", "description": "Content to embed: a string, `TextDoc`, `ImageDoc`, `VideoDoc`, `AudioDoc`, `PDFDoc`, or a list of these. A list item may also be a `{content: [...]}` group, fused into one embedding. A PDF must be sent on its own, not inside a list." }, "task": { "anyOf": [ { "type": "string", "enum": [ "retrieval.query", "retrieval.passage", "text-matching", "clustering", "classification" ] }, { "type": "null" } ], "title": "Task", "description": "Task optimization: `retrieval.query` for queries, `retrieval.passage` for documents, `text-matching` for similarity, `clustering`, or `classification`.", "default": "text-matching" }, "dimensions": { "anyOf": [ { "type": "integer", "maximum": 1024, "exclusiveMinimum": 0 }, { "type": "null" } ], "title": "Dimensions", "description": "Number of dimensions for the output embedding. Range: 1-1024." } }, "type": "object", "required": [ "model", "input" ], "title": "EmbeddingsV5Request", "description": "Jina Embeddings v5, with task-specific adapters and truncatable\ndimensions. Text, images, video, audio and PDFs share one vector space, so\na query in any of them retrieves any other; the `omni` names are the ones\nto reach for when the corpus is not text.\n\nEach list item is one modality, except a `MergedContentGroup`\n(`{\"content\": [...]}`), which fuses several chunks into a single embedding\nin one forward pass.", "examples": [ { "dimensions": 512, "embedding_type": "float", "input": [ "A beautiful sunset over the beach" ], "model": "jina-embeddings-v5-text-small", "normalized": true, "task": "retrieval.query" }, { "embedding_type": "float", "input": [ { "image": "https://i.ibb.co/nQNGqL0/beach1.jpg" }, { "text": "A beautiful sunset over the beach" } ], "model": "jina-embeddings-v5-omni-small", "task": "retrieval.passage" } ] }, "ErrorResponse": { "properties": { "detail": { "type": "string", "title": "Detail", "description": "Human-readable error message.", "examples": [ "Invalid API key. Verify your API key at https://jina.ai/api-dashboard/key-manager or generate a new one." ] }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Code", "description": "Machine-readable error code, for programmatic handling.", "examples": [ "AUTH_INVALID_API_KEY" ] }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Request Id", "description": "Identifier for this request, quote it in support requests.", "examples": [ "03f58cd9da22fabf" ] }, "errors": { "anyOf": [ { "items": { "$ref": "#/components/schemas/FieldError" }, "type": "array" }, { "type": "null" } ], "title": "Errors", "description": "Per-field detail. Present on 422 only; `detail` summarises it." } }, "type": "object", "required": [ "detail" ], "title": "ErrorResponse", "description": "Failure shape for every endpoint except `/v1/chat/completions`." }, "FieldError": { "properties": { "field": { "type": "string", "title": "Field", "description": "Path to the field, e.g. `body -> input -> 0`." }, "message": { "type": "string", "title": "Message", "description": "Why the value was rejected." }, "type": { "type": "string", "title": "Type", "description": "Validator that rejected it, e.g. `string_type`." }, "input": { "anyOf": [ {}, { "type": "null" } ], "title": "Input", "description": "The rejected value. Long strings are truncated and containers dropped." } }, "type": "object", "required": [ "field", "message", "type" ], "title": "FieldError", "description": "One rejected field, as carried in a 422." }, "ImageContentPart": { "properties": { "type": { "type": "string", "const": "image_url", "title": "Type" }, "image_url": { "$ref": "#/components/schemas/ImageURL" } }, "type": "object", "required": [ "type", "image_url" ], "title": "ImageContentPart" }, "ImageDoc": { "properties": { "image": { "type": "string", "title": "Image", "description": "Image as a URL or base64-encoded string." } }, "type": "object", "required": [ "image" ], "title": "ImageDoc" }, "ImageURL": { "properties": { "url": { "type": "string", "title": "Url", "description": "An `http(s)` URL or a `data:image/...;base64,` URI." } }, "type": "object", "required": [ "url" ], "title": "ImageURL" }, "JSONSchemaSpec": { "properties": { "name": { "type": "string", "title": "Name" }, "schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Schema" } }, "type": "object", "required": [ "name" ], "title": "JSONSchemaSpec" }, "MergedContentGroup": { "properties": { "content": { "items": { "anyOf": [ { "$ref": "#/components/schemas/TextDoc" }, { "$ref": "#/components/schemas/ImageDoc" }, { "$ref": "#/components/schemas/VideoDoc" }, { "$ref": "#/components/schemas/AudioDoc" } ] }, "type": "array", "minItems": 1, "title": "Content", "description": "Ordered list of modality chunks (text / image / video / audio). Must contain at least one chunk." } }, "type": "object", "required": [ "content" ], "title": "MergedContentGroup", "description": "Several chunks of different modalities fused into one embedding.\n\nThe group returns a single vector, and order within `content` is part of\nthe meaning — reordering it can change the result. A PDF cannot go inside\na group; send it as its own input." }, "ModelDatacenter": { "properties": { "country_code": { "type": "string", "title": "Country Code", "description": "ISO country code of the datacenter." } }, "type": "object", "required": [ "country_code" ], "title": "ModelDatacenter", "description": "Datacenter location for a model." }, "ModelInfo": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique model identifier (e.g., `jina-ai/jina-embeddings-v3`)." }, "hugging_face_id": { "type": "string", "title": "Hugging Face Id", "description": "HuggingFace model ID." }, "name": { "type": "string", "title": "Name", "description": "Human-readable model name." }, "created": { "type": "integer", "title": "Created", "description": "Unix timestamp when the model was released." }, "input_modalities": { "items": { "type": "string" }, "type": "array", "title": "Input Modalities", "description": "Supported input modalities: `text`, `image`, `video`, `audio`." }, "output_modalities": { "items": { "type": "string" }, "type": "array", "title": "Output Modalities", "description": "Output types: `embeddings`, `text`." }, "quantization": { "type": "string", "title": "Quantization", "description": "Quantization level, if any." }, "context_length": { "type": "integer", "title": "Context Length", "description": "Maximum context length in tokens." }, "max_output_length": { "type": "integer", "title": "Max Output Length", "description": "Largest output the model produces: embedding dimensions for an embedding model, tokens for a generative one. `0` where it does not apply." }, "pricing": { "$ref": "#/components/schemas/ModelPricing", "description": "Pricing information." }, "supported_sampling_parameters": { "items": { "type": "string" }, "type": "array", "title": "Supported Sampling Parameters", "description": "Supported sampling parameters." }, "supported_features": { "items": { "type": "string" }, "type": "array", "title": "Supported Features", "description": "Supported features." }, "description": { "type": "string", "title": "Description", "description": "Model description." }, "datacenters": { "items": { "$ref": "#/components/schemas/ModelDatacenter" }, "type": "array", "title": "Datacenters", "description": "Available datacenter locations." } }, "type": "object", "required": [ "id", "hugging_face_id", "name", "created", "input_modalities", "output_modalities", "quantization", "context_length", "max_output_length", "pricing", "supported_sampling_parameters", "supported_features", "description", "datacenters" ], "title": "ModelInfo", "description": "Information about a single model." }, "ModelListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ModelInfo" }, "type": "array", "title": "Data", "description": "List of available models." } }, "type": "object", "required": [ "data" ], "title": "ModelListResponse", "description": "Response containing list of available models.", "example": { "data": [ { "context_length": 8192, "created": 1725840000, "datacenters": [ { "country_code": "US" } ], "description": "jina-embeddings-v3 is a multilingual embedding model...", "hugging_face_id": "jinaai/jina-embeddings-v3", "id": "jina-ai/jina-embeddings-v3", "input_modalities": [ "text" ], "max_output_length": 1024, "name": "Jina AI: Jina Embeddings v3", "output_modalities": [ "embeddings" ], "pricing": { "completion": "0", "image": "0", "input_cache_read": "0", "input_cache_write": "0", "prompt": "0.00000005", "request": "0" }, "quantization": "", "supported_features": [], "supported_sampling_parameters": [] } ] } }, "ModelPricing": { "properties": { "prompt": { "type": "string", "title": "Prompt", "description": "USD per input token." }, "completion": { "type": "string", "title": "Completion", "description": "USD per output token." }, "image": { "type": "string", "title": "Image", "description": "USD per image." }, "request": { "type": "string", "title": "Request", "description": "USD per request." }, "input_cache_read": { "type": "string", "title": "Input Cache Read", "description": "USD per cached input token read." }, "input_cache_write": { "type": "string", "title": "Input Cache Write", "description": "USD per cached input token written." } }, "type": "object", "required": [ "prompt", "completion", "image", "request", "input_cache_read", "input_cache_write" ], "title": "ModelPricing", "description": "Pricing information for a model." }, "MultiEmbeddingData": { "properties": { "object": { "type": "string", "title": "Object", "description": "Object type, always `embeddings` for multi-vector output.", "default": "embeddings" }, "index": { "type": "integer", "title": "Index", "description": "Position of this result in the input list." }, "embeddings": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "items": { "items": { "type": "number" }, "type": "array" }, "type": "array" } ], "title": "Embeddings", "description": "Per-token embedding vectors. Each is a list of floats or base64 string." }, "tokenized_input": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tokenized Input", "description": "Tokens corresponding to each embedding, if `return_tokenized_input=true`." } }, "type": "object", "required": [ "index", "embeddings" ], "title": "MultiEmbeddingData", "description": "Multi-vector embedding result (one vector per token)." }, "OpenAIError": { "properties": { "message": { "type": "string", "title": "Message", "description": "Human-readable error message." }, "type": { "type": "string", "title": "Type", "description": "OpenAI's error class, e.g. `invalid_request_error`.", "examples": [ "invalid_request_error" ] }, "param": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Param", "description": "The request field at fault, when one is named." }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Code", "examples": [ "INPUT_MODEL_NOT_FOUND" ] }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Request Id", "examples": [ "03f58cd9da22fabf" ] } }, "type": "object", "required": [ "message", "type" ], "title": "OpenAIError", "description": "OpenAI's error object. Our `code` and `request_id` ride inside it because\nthe OpenAI SDK keeps `body[\"error\"]` and discards everything beside it." }, "OpenAIErrorResponse": { "properties": { "error": { "$ref": "#/components/schemas/OpenAIError" } }, "type": "object", "required": [ "error" ], "title": "OpenAIErrorResponse", "description": "Failure shape for `/v1/chat/completions`, so OpenAI clients parse it." }, "PDFDoc": { "properties": { "pdf": { "type": "string", "title": "Pdf", "description": "PDF as a URL or base64-encoded string." } }, "type": "object", "required": [ "pdf" ], "title": "PDFDoc" }, "RerankerM0Request": { "properties": { "query": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/ImageDoc" } ], "title": "Query", "description": "The query to rank documents against: a text string, or an image object (`{\"image\": }`) for a visual query." }, "top_n": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Top N", "description": "Number of top results to return. If not set, returns all documents." }, "return_documents": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Return Documents", "description": "If true (default), includes document content in each result.", "default": true }, "model": { "type": "string", "const": "jina-reranker-m0", "title": "Model", "description": "The multimodal reranking model to use." }, "documents": { "items": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/TextDoc" }, { "$ref": "#/components/schemas/ImageDoc" } ] }, "type": "array", "minItems": 1, "title": "Documents", "description": "Documents to rank: strings, `TextDoc`, or `ImageDoc` objects." } }, "type": "object", "required": [ "query", "model", "documents" ], "title": "RerankerM0Request", "description": "Multimodal reranker: the query and the documents may each be text or an image.", "example": { "documents": [ { "image": "https://raw.githubusercontent.com/jina-ai/multimodal-reranker-test/main/paper-11.png" }, { "text": "Attention Is All You Need: This groundbreaking paper introduced the Transformer architecture, revolutionizing natural language processing and becoming the foundation for modern large language models like GPT and BERT." }, "Recent advances in computer vision have led to the development of vision transformers (ViTs) that achieve state-of-the-art performance on image classification tasks by treating images as sequences of patches.", { "image": "https://raw.githubusercontent.com/jina-ai/multimodal-reranker-test/main/wired-preview.png" }, { "text": "Graph Neural Networks: A Review of Methods and Applications. This comprehensive survey covers the latest developments in graph-based machine learning, including graph convolutional networks and graph attention mechanisms." }, "Traditional database systems struggle with the volume and variety of modern data workloads, leading to the adoption of distributed computing frameworks like Apache Spark and Hadoop for big data processing." ], "model": "jina-reranker-m0", "query": "innovative artificial intelligence research papers and visual data analysis", "return_documents": false, "top_n": 4 } }, "RerankerV3Request": { "properties": { "query": { "type": "string", "title": "Query", "description": "The search query to rank documents against." }, "top_n": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Top N", "description": "Number of top results to return. If not set, returns all documents." }, "return_documents": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Return Documents", "description": "If true (default), includes document content in each result.", "default": true }, "model": { "type": "string", "enum": [ "jina-reranker-v3", "jina-reranker-v3.5" ], "title": "Model", "description": "The reranking model to use." }, "documents": { "items": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/TextDoc" } ] }, "type": "array", "minItems": 1, "title": "Documents", "description": "Documents to rank: strings or `TextDoc` objects." }, "max_doc_length": { "anyOf": [ { "type": "integer", "maximum": 8192, "minimum": 1 }, { "type": "null" } ], "title": "Max Doc Length", "description": "Maximum tokens per document (1-8192). Omit to use the model's default (2048 for jina-reranker-v3, 8192 for jina-reranker-v3.5)." }, "return_embeddings": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Return Embeddings", "description": "If true, returns the document embedding alongside the relevance score." } }, "type": "object", "required": [ "query", "model", "documents" ], "title": "RerankerV3Request", "description": "Listwise multilingual reranker: scores the candidate set as a whole\nrather than one document at a time.", "example": { "documents": [ "Climate Change and Renewable Energy: A Global Perspective. Rising temperatures and extreme weather events are accelerating the transition to solar and wind power worldwide.", "Le changement climatique et l'énergie renouvelable : une perspective européenne. L'Union européenne investit massivement dans les technologies vertes pour atteindre la neutralité carbone d'ici 2050.", "Klimawandel und erneuerbare Energien: Deutsche Energiewende. Deutschland führt die Transformation des Energiesektors durch innovative Technologien und politische Maßnahmen an.", "气候变化对可再生能源的影响：中国的绿色发展战略。中国正在大力推进太阳能和风能项目，以实现碳中和目标。", "Artificial Intelligence in Healthcare: Revolutionizing Medical Diagnosis. AI-powered systems are improving accuracy in disease detection and treatment recommendations.", "Blockchain Technology: Transforming Financial Services. Decentralized finance applications are reshaping traditional banking and payment systems." ], "model": "jina-reranker-v3", "query": "Climate change impact on renewable energy adoption", "return_documents": false, "return_embeddings": false, "top_n": 4 } }, "RerankingResponse": { "properties": { "model": { "type": "string", "title": "Model", "description": "The model used for reranking." }, "object": { "type": "string", "title": "Object", "description": "Object type, always `list`.", "default": "list" }, "usage": { "$ref": "#/components/schemas/BaseUsage", "description": "Token usage statistics." }, "results": { "items": { "$ref": "#/components/schemas/RerankingResult" }, "type": "array", "title": "Results", "description": "Ranked documents, sorted by relevance score descending." } }, "type": "object", "required": [ "model", "usage", "results" ], "title": "RerankingResponse", "description": "Response containing ranked documents." }, "RerankingResult": { "properties": { "index": { "type": "integer", "title": "Index", "description": "Position of this document in the original input list." }, "relevance_score": { "type": "number", "title": "Relevance Score", "description": "Relevance score. Higher is more relevant." }, "document": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/TextDoc" }, { "$ref": "#/components/schemas/ImageDoc" }, { "type": "null" } ], "title": "Document", "description": "Document content, if `return_documents=true`." }, "embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Embedding", "description": "Document embedding, if `return_embeddings=true`." } }, "type": "object", "required": [ "index", "relevance_score" ], "title": "RerankingResult", "description": "A single reranking result." }, "ResponseFormatJSONObject": { "properties": { "type": { "type": "string", "const": "json_object", "title": "Type" } }, "type": "object", "required": [ "type" ], "title": "ResponseFormatJSONObject" }, "ResponseFormatJSONSchema": { "properties": { "type": { "type": "string", "const": "json_schema", "title": "Type" }, "json_schema": { "$ref": "#/components/schemas/JSONSchemaSpec" } }, "type": "object", "required": [ "type", "json_schema" ], "title": "ResponseFormatJSONSchema" }, "ResponseFormatText": { "properties": { "type": { "type": "string", "const": "text", "title": "Type" } }, "type": "object", "required": [ "type" ], "title": "ResponseFormatText" }, "SingleEmbeddingData": { "properties": { "object": { "type": "string", "title": "Object", "description": "Object type, always `embedding`.", "default": "embedding" }, "index": { "type": "integer", "title": "Index", "description": "Position of this embedding in the input list." }, "embedding": { "anyOf": [ { "type": "string" }, { "items": { "type": "number" }, "type": "array" }, { "additionalProperties": { "type": "number" }, "type": "object" } ], "title": "Embedding", "description": "The embedding vector: a list of floats for dense embeddings, a dict of token->score for sparse embeddings, or a base64 string for other encodings." } }, "type": "object", "required": [ "index", "embedding" ], "title": "SingleEmbeddingData", "description": "Single embedding result for one input item." }, "StreamOptions": { "properties": { "include_usage": { "type": "boolean", "title": "Include Usage", "description": "Report token usage in the stream. When set, every chunk carries `usage: null` and a final chunk carries the totals. When unset, no chunk mentions usage and the final chunk is not sent at all.", "default": false } }, "type": "object", "title": "StreamOptions" }, "TextContentPart": { "properties": { "type": { "type": "string", "const": "text", "title": "Type" }, "text": { "type": "string", "title": "Text" } }, "type": "object", "required": [ "type", "text" ], "title": "TextContentPart" }, "TextDoc": { "properties": { "text": { "type": "string", "title": "Text", "description": "Text content to process." } }, "type": "object", "required": [ "text" ], "title": "TextDoc" }, "TextRerankerRequest": { "properties": { "query": { "type": "string", "title": "Query", "description": "The search query to rank documents against." }, "top_n": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "title": "Top N", "description": "Number of top results to return. If not set, returns all documents." }, "return_documents": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Return Documents", "description": "If true (default), includes document content in each result.", "default": true }, "model": { "type": "string", "enum": [ "jina-reranker-v2-base-multilingual", "jina-reranker-v1-tiny-en", "jina-reranker-v1-turbo-en", "jina-reranker-v1-base-en", "jina-colbert-v1-en", "jina-colbert-v2" ], "title": "Model", "description": "The reranking model to use." }, "documents": { "items": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/TextDoc" } ] }, "type": "array", "minItems": 1, "title": "Documents", "description": "Documents to rank: strings or `TextDoc` objects." } }, "type": "object", "required": [ "query", "model", "documents" ], "title": "TextRerankerRequest", "description": "Pointwise text reranker: scores each document against the query.", "example": { "documents": [ "Climate Change and Renewable Energy: A Global Perspective. Rising temperatures and extreme weather events are accelerating the transition to solar and wind power worldwide.", "Le changement climatique et l'énergie renouvelable : une perspective européenne. L'Union européenne investit massivement dans les technologies vertes pour atteindre la neutralité carbone d'ici 2050.", "Klimawandel und erneuerbare Energien: Deutsche Energiewende. Deutschland führt die Transformation des Energiesektors durch innovative Technologien und politische Maßnahmen an.", "气候变化对可再生能源的影响：中国的绿色发展战略。中国正在大力推进太阳能和风能项目，以实现碳中和目标。", "Artificial Intelligence in Healthcare: Revolutionizing Medical Diagnosis. AI-powered systems are improving accuracy in disease detection and treatment recommendations.", "Blockchain Technology: Transforming Financial Services. Decentralized finance applications are reshaping traditional banking and payment systems." ], "model": "jina-reranker-v2-base-multilingual", "query": "Climate change impact on renewable energy adoption", "return_documents": false, "top_n": 4 } }, "VideoDoc": { "properties": { "video": { "type": "string", "title": "Video", "description": "Video as a URL or base64-encoded string." } }, "type": "object", "required": [ "video" ], "title": "VideoDoc" } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer" } } }, "tags": [ { "name": "Reader", "description": "Read a URL and get its content back in an LLM-friendly format." }, { "name": "Search", "description": "Search the web and get the result pages back in an LLM-friendly format." }, { "name": "Model List", "description": "Every model this API serves, in OpenRouter-compatible form: identifiers, input and output modalities, context lengths and prices. Read it before hardcoding a model name — the catalogue moves." }, { "name": "Search Foundation Models", "description": "**Embeddings** turn text, images, audio, video and PDFs into dense vectors for semantic search, RAG, clustering and classification. Task-specific variants (`retrieval.query`, `retrieval.passage`, `text-matching`, `clustering`, `classification`) are selected per request rather than per model, and `dimensions` truncates the output where a model supports it.\n\n**Reranking** scores a query against a candidate set and returns it reordered, which is more accurate than embedding similarity and slower — the usual shape is embeddings to retrieve, reranking to refine.\n\nEach endpoint's `model` field lists the models it accepts." }, { "name": "Generative Models", "description": "Document transcription over the OpenAI chat completions schema. Point any OpenAI-compatible client at the server URL above with `/v1` appended, set `model`, and send a page image; the response is the page as text or markdown, tables and layout preserved.\n\n`stream: true` returns server-sent events. `response_format` with a `json_schema` constrains the output to that schema instead of prose. Parameters outside the supported set are accepted and ignored rather than rejected, so an SDK-generated payload always works." }, { "name": "Batch Embeddings", "description": "Asynchronous embedding for large workloads: up to 50,000 inputs from a GCS file URL, or 10,000 inline.\n\nSubmit with `POST /v1/batch/embeddings`, poll `GET /v1/batch/{batch_id}` until the status is `completed`, then fetch `GET /v1/batch/{batch_id}/output`. Input is OpenAI-compatible JSONL with `custom_id` and `body.input`. Output files expire after 24 hours, and a webhook can be called on completion." } ], "x-tagGroups": [ { "name": "Reader API (r.jina.ai)", "tags": [ "Reader" ] }, { "name": "Search API (s.jina.ai)", "tags": [ "Search" ] }, { "name": "Search Foundation API (api.jina.ai)", "tags": [ "Model List", "Search Foundation Models", "Generative Models", "Batch Embeddings" ] } ] }