Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
fix(elixir-sdk): keep hand-written code when regenerating from the OpenAPI spec (#4920)
Gergő Móricz2a1f075fe52c
diff --git a/.github/workflows/publish-elixir-sdk.yml b/.github/workflows/publish-elixir-sdk.ymlindex d099619f7..8d46fca29 100644--- a/.github/workflows/publish-elixir-sdk.yml+++ b/.github/workflows/publish-elixir-sdk.yml@@ -36,6 +36,9 @@ jobs:- name: Regenerate from OpenAPI specrun: mix run generate.exs+ - name: Test regenerated code+ run: mix test+- name: Check for changesid: check_changesrun: |diff --git a/apps/elixir-sdk/README.md b/apps/elixir-sdk/README.mdindex 04814691c..445b52aa3 100644--- a/apps/elixir-sdk/README.md+++ b/apps/elixir-sdk/README.md@@ -112,7 +112,7 @@ response = Firecrawl.scrape_and_extract_from_url!(url: "https://example.com")## Regenerating from the OpenAPI Spec-The entire client is auto-generated from the Firecrawl OpenAPI specification. To regenerate after spec changes:+The client is generated from the Firecrawl OpenAPI specification. To regenerate after spec changes:```bashmix run generate.exs@@ -121,13 +121,21 @@ mix run generate.exsThis will:1. Fetch the latest OpenAPI JSON from GitHub-2. Generate all API wrapper functions in `lib/firecrawl.ex`+2. Generate all API wrapper functions in `lib/firecrawl.ex` and, if the code changed, save the spec it came from as `openapi.json`3. Bump the version in `mix.exs` using semver (only if the generated code changed):- **Major** bump if public functions were removed (breaking change)- **Minor** bump if new public functions were added- **Patch** bump for any other changes (signatures, docs, etc.)-Re-running when nothing changed is a no-op — the version is not bumped.+Re-running when nothing changed is a no-op, and the version is not bumped.++To regenerate without the network, from the vendored spec:++```bash+FIRECRAWL_OPENAPI_SPEC=openapi.json mix run generate.exs+```++Hand-written functions live between the `BEGIN HAND-WRITTEN` and `END HAND-WRITTEN` markers in `lib/firecrawl.ex`. The generator copies that region verbatim and skips the spec routes listed in `@hand_written_routes`, so edit code there rather than in generated functions. `mix test` fails if `lib/firecrawl.ex` differs from what the generator produces from `openapi.json`.## Licensediff --git a/apps/elixir-sdk/generate.exs b/apps/elixir-sdk/generate.exsindex ea421c438..ca1a28e9a 100644--- a/apps/elixir-sdk/generate.exs+++ b/apps/elixir-sdk/generate.exs@@ -2,17 +2,20 @@# generate.exs — Auto-generates the Firecrawl Elixir SDK from the OpenAPI spec.## Usage:-# mix run generate.exs+# mix run generate.exs # fetch the latest spec+# FIRECRAWL_OPENAPI_SPEC=openapi.json mix run generate.exs # offline, from the vendored copy## This script:# 1. Fetches the Firecrawl v2 OpenAPI JSON spec# 2. Parses all endpoints and generates Elixir wrapper functions with NimbleOptions validation-# 3. Writes lib/firecrawl.ex-# 4. Bumps the patch version in mix.exs if the generated code changed+# 3. If the code changed, writes lib/firecrawl.ex (keeping its HAND-WRITTEN region+# verbatim) and saves the spec it came from as openapi.json+# 4. Bumps the version in mix.exs if the generated code changeddefmodule Firecrawl.Generator do@openapi_url "https://raw.githubusercontent.com/firecrawl/firecrawl-docs/main/api-reference/v2-openapi.json"@output_file "lib/firecrawl.ex"+ @spec_file "openapi.json"@mix_file "mix.exs"# Operations to exclude from the generated client.@@ -23,9 +26,33 @@ defmodule Firecrawl.Generator do"getHistoricalTokenUsage"])- # Routes emitted by hand-written template code instead of the spec, so a- # spec entry for them never generates a second, untyped definition.- @hand_written_routes MapSet.new([{"get", "/parse/formats"}])+ # Routes implemented in the HAND-WRITTEN region of lib/firecrawl.ex, so a spec+ # entry for them never generates a second definition.+ @hand_written_routes MapSet.new([+ {"get", "/parse/formats"},+ {"get", "/agent/{jobId}/trace"},+ {"get", "/search/research/papers"},+ {"get", "/search/research/papers/{id}"},+ {"get", "/search/research/papers/{id}/similar"},+ {"get", "/search/research/github"},+ {"post", "/monitor"},+ {"get", "/monitor"},+ {"get", "/monitor/{monitorId}"},+ {"patch", "/monitor/{monitorId}"},+ {"delete", "/monitor/{monitorId}"},+ {"post", "/monitor/{monitorId}/run"},+ {"get", "/monitor/{monitorId}/checks"},+ {"get", "/monitor/{monitorId}/checks/{checkId}"}+ ])++ @hand_written_begin " # --- BEGIN HAND-WRITTEN ---"+ @hand_written_end " # --- END HAND-WRITTEN ---"++ # NimbleOptions types that deliberately differ from what the spec implies,+ # keyed by {function name, JSON property}.+ @type_overrides %{+ {"start_agent", "effort"} => ~S|{:in, ["low", "medium", "high"]}|+ }# The method key becomes the Req function name in generated code, a position# no escaping can protect, so anything else stops generation outright.@@ -33,19 +60,16 @@ defmodule Firecrawl.Generator dodef run doIO.puts("Fetching OpenAPI spec...")- {:ok, spec} = fetch_spec()+ {:ok, raw_spec} = fetch_spec()+ spec = Jason.decode!(raw_spec)- IO.puts("Generating client code...")- code = generate_module(spec)+ old_code = File.read!(@output_file)- old_code =- if File.exists?(@output_file) do- File.read!(@output_file)- else- ""- end+ IO.puts("Generating client code...")+ code = generate_module(spec, hand_written_region(old_code))if code != old_code do+ File.write!(@spec_file, raw_spec)File.write!(@output_file, code)IO.puts("Wrote #{@output_file}")@@ -62,17 +86,15 @@ defmodule Firecrawl.Generator do# Set FIRECRAWL_OPENAPI_SPEC to a local file to generate without the network.case System.get_env("FIRECRAWL_OPENAPI_SPEC") donil -> fetch_remote_spec()- path -> {:ok, path |> File.read!() |> Jason.decode!()}+ path -> {:ok, File.read!(path)}endend+ # The body is kept raw so openapi.json stays byte-identical to the published spec.defp fetch_remote_spec do- case Req.get(@openapi_url) do- {:ok, %Req.Response{status: 200, body: body}} when is_map(body) ->- {:ok, body}-+ case Req.get(@openapi_url, decode_body: false) do{:ok, %Req.Response{status: 200, body: body}} when is_binary(body) ->- {:ok, Jason.decode!(body)}+ {:ok, body}{:ok, %Req.Response{status: status}} ->{:error, "HTTP #{status}"}@@ -86,7 +108,15 @@ defmodule Firecrawl.Generator do# Module template# ---------------------------------------------------------------------------- def generate_module(spec) do+ # Returns the HAND-WRITTEN region of `source`, markers included.+ def hand_written_region(source) do+ case String.split(source, [@hand_written_begin, @hand_written_end]) do+ [_before, inner, _after] -> @hand_written_begin <> inner <> @hand_written_end+ _ -> raise "#{@output_file} must contain exactly one HAND-WRITTEN region"+ end+ end++ def generate_module(spec, hand_written) dobase_url =case get_in(spec, ["servers"]) do[%{"url" => url} | _] -> url@@ -119,11 +149,20 @@ defmodule Firecrawl.Generator do|> Enum.map(&generate_function(&1, spec))|> Enum.join("\n")+ clashes =+ MapSet.intersection(extract_public_functions(functions), extract_public_functions(hand_written))++ if MapSet.size(clashes) > 0 do+ raise "generated functions clash with the HAND-WRITTEN region: " <>+ Enum.join(clashes, ", ") <> ". Add their routes to @hand_written_routes."+ end+bt = <<96>>- headers_line = ~S' headers = if api_key, do: [{"authorization", "Bearer #{api_key}"}], else: []'+ headers_line = ~S' headers = if api_key, do: [{"authorization", "Bearer #{api_key}"}], else: []'"""- # This file is auto-generated by generate.exs — DO NOT EDIT MANUALLY.+ # This file is generated by generate.exs from openapi.json. Edit by hand only+ # inside the HAND-WRITTEN region, which regeneration keeps verbatim.# Re-generate with: mix run generate.exsdefmodule Firecrawl do@@ -177,9 +216,9 @@ defmodule Firecrawl.Generator doApplication.get_env(:firecrawl, :api_key)end)- # A nil/empty key is allowed: scrape, search, and interact fall back to- # the keyless free tier (rate-limited per IP). Other endpoints return 401- # from the API until a key is provided.+ # A nil/empty key is allowed: scrape, search, and interact fall back to the+ # keyless free tier (rate-limited per IP). Other endpoints return 401 from the+ # API until a key is provided.api_key =case api_key dokey when is_binary(key) ->@@ -217,6 +256,8 @@ defmodule Firecrawl.Generator dojson_key = Map.fetch!(key_mapping, k){json_key, to_json_value(v)}end)+ # Identify the SDK so the API can grant the keyless free tier; harmless+ # telemetry on keyed requests.|> Map.put_new("origin", @sdk_origin)end@@ -247,59 +288,33 @@ defmodule Firecrawl.Generator doEnum.join([first | Enum.map(rest, &String.capitalize/1)])end- #{parse_formats_code()}- #{functions}end- """- end-- # get_parse_formats returns typed structs rather than a raw response, so it- # is written by hand and emitted verbatim on every regeneration.- def parse_formats_code do- ~S'''- @doc """- List the file formats `parse_file/3` accepts-- `GET /parse/formats`-- Tag: Parsing-- ## Returns-- * `{:ok, [%Firecrawl.ParseFormat{}]}` on success- * `{:error, exception}` on HTTP failure or an unexpected response shape- """- @spec get_parse_formats(keyword()) ::- {:ok, [Firecrawl.ParseFormat.t()]} | {:error, Exception.t() | Firecrawl.Error.t()}- def get_parse_formats(opts \\ []) do- with {:ok, response} <- Req.get(client(opts), url: "/parse/formats") do- decode_parse_formats(response)+ defp fetch_file_field(file, key) do+ case Keyword.fetch(file, key) do+ {:ok, _value} = ok -> ok+ :error -> {:error, %ArgumentError{message: "missing required file field: \#{key}"}}endend-- @doc """- Bang variant of `get_parse_formats`. Raises on error.- """- @spec get_parse_formats!(keyword()) :: [Firecrawl.ParseFormat.t()]- def get_parse_formats!(opts \\ []) do- case get_parse_formats(opts) do- {:ok, formats} -> formats- {:error, exception} -> raise exception+ defp validate_filename(filename) do+ if is_binary(filename) and filename != "" do+ :ok+ else+ {:error, %ArgumentError{message: "filename cannot be empty"}}endend- defp decode_parse_formats(%Req.Response{body: %{"data" => %{"formats" => formats}}})- when is_list(formats) do- {:ok, Enum.map(formats, &Firecrawl.ParseFormat.from_map/1)}+ defp validate_data(data) do+ if is_nil(data) do+ {:error, %ArgumentError{message: "file data cannot be empty"}}+ else+ :ok+ endend- defp decode_parse_formats(%Req.Response{status: status, body: body}) do- {:error,- RuntimeError.exception(- "unexpected GET /parse/formats response (HTTP #{status}): #{inspect(body)}"- )}- end- '''+ #{hand_written}++ #{functions}end+ """end# ---------------------------------------------------------------------------@@ -313,7 +328,7 @@ defmodule Firecrawl.Generator dotag = operation |> Map.get("tags", []) |> List.first() || ""op_params = Map.get(operation, "parameters", [])- all_params = path_level_params ++ op_params+ all_params = Enum.map(path_level_params ++ op_params, &resolve_if_ref(&1, spec))path_params =all_params@@ -537,8 +552,6 @@ defmodule Firecrawl.Generator doreq_method = String.to_atom(method)fn_name = if bang?, do: "#{func_name}!", else: func_namereq_fn = if bang?, do: "#{req_method}!", else: "#{req_method}"- options_field = meta.options_field- file_field = meta.file_fieldsig =if has_options? do@@ -548,57 +561,63 @@ defmodule Firecrawl.Generator doendoptions_part_text =- cond do- has_options? and not is_nil(options_field) ->- "{#{inspect(options_field)}, Jason.encode!(to_body(params, @#{func_name}_key_mapping))}, "-- true ->- ""+ if has_options? and not is_nil(meta.options_field) do+ "{#{inspect(meta.options_field)}, Jason.encode!(to_body(params, @#{func_name}_key_mapping))}, "+ else+ ""end- file_part_text = "{#{inspect(file_field)}, file_part}"+ indent = if bang?, do: " ", else: " "- indent = if not bang? and has_options?, do: " ", else: " "-- core_lines = [- "#{indent}filename = Keyword.fetch!(file, :filename)",- "#{indent}data = Keyword.fetch!(file, :data)",- "#{indent}content_type = Keyword.get(file, :content_type)",- "",- "#{indent}if not is_binary(filename) or filename == \"\" do",- "#{indent} raise ArgumentError, \"filename cannot be empty\"",- "#{indent}end",- "",- "#{indent}if is_nil(data) do",- "#{indent} raise ArgumentError, \"file data cannot be empty\"",- "#{indent}end",- "",+ send_lines = ["#{indent}file_part =","#{indent} case content_type do","#{indent} nil -> {data, filename: filename}","#{indent} ct -> {data, filename: filename, content_type: ct}","#{indent} end","",- "#{indent}multipart = [#{options_part_text}#{file_part_text}]",+ "#{indent}multipart = [#{options_part_text}{#{inspect(meta.file_field)}, file_part}]","","#{indent}Req.#{req_fn}(client(opts), url: \"#{escape_string_literal(path)}\", form_multipart: multipart)"]- core = Enum.join(core_lines, "\n")-- body =- cond do- bang? and has_options? ->- " params = NimbleOptions.validate!(params, @#{func_name}_schema)\n#{core}\n end\n"+ lines =+ if bang? do+ validate = if has_options?, do: [" params = NimbleOptions.validate!(params, @#{func_name}_schema)"], else: []- not bang? and has_options? ->- " with {:ok, params} <- NimbleOptions.validate(params, @#{func_name}_schema) do\n#{core}\n end\n end\n"-- true ->- "#{core}\n end\n"+ validate +++ [+ " filename = Keyword.fetch!(file, :filename)",+ " data = Keyword.fetch!(file, :data)",+ " content_type = Keyword.get(file, :content_type)",+ "",+ " if not is_binary(filename) or filename == \"\" do",+ " raise ArgumentError, \"filename cannot be empty\"",+ " end",+ "",+ " if is_nil(data) do",+ " raise ArgumentError, \"file data cannot be empty\"",+ " end",+ ""+ ] ++ send_lines ++ [" end"]+ else+ validate =+ if has_options?, do: ["{:ok, params} <- NimbleOptions.validate(params, @#{func_name}_schema)"], else: []++ clauses =+ validate +++ [+ "{:ok, filename} <- fetch_file_field(file, :filename)",+ ":ok <- validate_filename(filename)",+ "{:ok, data} <- fetch_file_field(file, :data)",+ ":ok <- validate_data(data)"+ ]++ [" with #{Enum.join(clauses, ",\n ")} do", " content_type = Keyword.get(file, :content_type)", ""] +++ send_lines ++ [" end", " end"]end- {sig, body}+ {sig, Enum.join(lines, "\n") <> "\n"}enddefp build_multipart_typespec(func_name, has_options?, bang?) do@@ -747,7 +766,12 @@ defmodule Firecrawl.Generator dorequired = name in required_keysdoc = Map.get(prop_schema, "description", "")- parts = openapi_to_nimble_parts(name, prop_schema)+ parts =+ case Map.fetch(@type_overrides, {func_name, name}) do+ {:ok, type} -> ["type: #{type}"]+ :error -> openapi_to_nimble_parts(name, prop_schema)+ end+parts = if required, do: parts ++ ["required: true"], else: partsparts = if doc != "", do: parts ++ ["doc: #{inspect(doc)}"], else: parts@@ -1130,13 +1154,18 @@ defmodule Firecrawl.Generator doendend- defp build_elixir_path(path, []), do: escape_string_literal(path)-defp build_elixir_path(path, path_params) do- Enum.reduce(path_params, escape_string_literal(path), fn param, acc ->- snake = to_snake_case(param)- String.replace(acc, "{#{param}}", "\#{#{snake}}")- end)+ elixir_path =+ Enum.reduce(path_params, escape_string_literal(path), fn param, acc ->+ snake = to_snake_case(param)+ String.replace(acc, "{#{param}}", "\#{#{snake}}")+ end)++ if Regex.match?(~r/(?<!#)\{[^}]*\}/, elixir_path) do+ raise ArgumentError, "unresolved path parameter in #{inspect(path)}"+ end++ elixir_pathend# ---------------------------------------------------------------------------@@ -1170,7 +1199,7 @@ defmodule Firecrawl.Generator doenddefp extract_public_functions(code) do- Regex.scan(~r/^\s+def\s+([a-z_][a-z0-9_]*!?)\(/, code, capture: :all_but_first)+ Regex.scan(~r/^ +def +([a-z_][a-z0-9_]*!?)\(/m, code, capture: :all_but_first)|> List.flatten()|> MapSet.new()enddiff --git a/apps/elixir-sdk/lib/firecrawl.ex b/apps/elixir-sdk/lib/firecrawl.exindex 39eacacce..6e144aaab 100644--- a/apps/elixir-sdk/lib/firecrawl.ex+++ b/apps/elixir-sdk/lib/firecrawl.ex@@ -1,4 +1,5 @@-# This file is auto-generated by generate.exs — DO NOT EDIT MANUALLY.+# This file is generated by generate.exs from openapi.json. Edit by hand only+# inside the HAND-WRITTEN region, which regeneration keeps verbatim.# Re-generate with: mix run generate.exsdefmodule Firecrawl do@@ -124,6 +125,33 @@ defmodule Firecrawl doEnum.join([first | Enum.map(rest, &String.capitalize/1)])end+ defp fetch_file_field(file, key) do+ case Keyword.fetch(file, key) do+ {:ok, _value} = ok -> ok+ :error -> {:error, %ArgumentError{message: "missing required file field: #{key}"}}+ end+ end++ defp validate_filename(filename) do+ if is_binary(filename) and filename != "" do+ :ok+ else+ {:error, %ArgumentError{message: "filename cannot be empty"}}+ end+ end++ defp validate_data(data) do+ if is_nil(data) do+ {:error, %ArgumentError{message: "file data cannot be empty"}}+ else+ :ok+ end+ end++ # --- BEGIN HAND-WRITTEN ---+ # generate.exs keeps everything between these markers verbatim. Any route+ # defined here must be listed in @hand_written_routes in generate.exs.+@doc """List the file formats `parse_file/3` accepts@@ -168,211 +196,719 @@ defmodule Firecrawl do)}end- defp fetch_file_field(file, key) do- case Keyword.fetch(file, key) do- {:ok, _value} = ok -> ok- :error -> {:error, %ArgumentError{message: "missing required file field: #{key}"}}- end- end-- defp validate_filename(filename) do- if is_binary(filename) and filename != "" do- :ok- else- {:error, %ArgumentError{message: "filename cannot be empty"}}- end- end-- defp validate_data(data) do- if is_nil(data) do- {:error, %ArgumentError{message: "file data cannot be empty"}}- else- :ok- end- end-@doc """- Cancel an agent job+ Get the execution trace of an agent job- `DELETE /agent/{jobId}`+ `GET /agent/{jobId}/trace`Tag: Agent+ The trace is only available for agent runs on spark-2.+## Path Parameters* `job_id` - Path parameter `jobId`+ ## Options++ * `:live_view` - when `true`, the query parameter `liveView=true` is sent and+ the response may additionally carry `activeBrowserSessions`, a list of+ `%{"id" => "...", "liveViewUrl" => "...", "viewport" => %{"width" => 1280, "height" => 720}}`+ entries for the run's live browser sessions.+## Returns* `{:ok, %Req.Response{}}` on success* `{:error, exception}` on HTTP or validation failure- """- @spec cancel_agent(String.t(), keyword()) :: response()- def cancel_agent(job_id, opts \\ []) do- Req.delete(client(opts), url: "/agent/#{job_id}")- end+ Success JSON: `%{"success" => true, "id" => "...", "events" => [...], "creditsUsed" => 5}`.- @doc """- Bang variant of `cancel_agent`. Raises on error.+ Each event has a `type` field (e.g. `"run.started"`, `"tool_call.started"`,+ `"artifact.updated"`) plus the base fields `schemaVersion`, `eventId`, `runId`,+ `occurredAt`, `producerSequence`, and `agent`."""- @spec cancel_agent!(String.t(), keyword()) :: Req.Response.t()- def cancel_agent!(job_id, opts \\ []) do- Req.delete!(client(opts), url: "/agent/#{job_id}")+ @spec get_agent_trace(String.t(), keyword()) :: response()+ def get_agent_trace(job_id, opts \\ []) do+ {live_view, opts} = Keyword.pop(opts, :live_view, false)+ params = if live_view, do: [{"liveView", "true"}], else: []+ Req.get(client(opts), url: "/agent/#{job_id}/trace", params: params)end@doc """- Cancel a batch scrape job-- `DELETE /batch/scrape/{id}`-- Tag: Scraping+ Bang variant of `get_agent_trace`. Raises on error.+ """+ @spec get_agent_trace!(String.t(), keyword()) :: Req.Response.t()+ def get_agent_trace!(job_id, opts \\ []) do+ {live_view, opts} = Keyword.pop(opts, :live_view, false)+ params = if live_view, do: [{"liveView", "true"}], else: []+ Req.get!(client(opts), url: "/agent/#{job_id}/trace", params: params)+ end- ## Path Parameters+ @research_search_papers_schema NimbleOptions.new!([+ authors: [type: {:list, :string}],+ categories: [type: {:list, :string}],+ from: [type: :string],+ k: [type: :integer],+ query: [type: :string, required: true],+ to: [type: :string]+ ])- * `id` - Path parameter `id`+ @research_search_papers_key_mapping %{authors: "authors", categories: "categories", from: "from", k: "k", query: "query", to: "to"}- ## Returns+ @doc """+ Search research papers.- * `{:ok, %Req.Response{}}` on success- * `{:error, exception}` on HTTP or validation failure+ `GET /search/research/papers`"""- @spec cancel_batch_scrape(String.t(), keyword()) :: response()- def cancel_batch_scrape(id, opts \\ []) do- Req.delete(client(opts), url: "/batch/scrape/#{id}")+ @spec search_papers(keyword(), keyword()) :: response()+ def search_papers(params \\ [], opts \\ []) do+ with {:ok, params} <- NimbleOptions.validate(params, @research_search_papers_schema) do+ Req.get(client(opts), url: "/search/research/papers", params: [{"origin", @sdk_origin} | to_query(params, @research_search_papers_key_mapping)])+ endend-@doc """- Bang variant of `cancel_batch_scrape`. Raises on error.+ Bang variant of `search_papers`. Raises on error."""- @spec cancel_batch_scrape!(String.t(), keyword()) :: Req.Response.t()- def cancel_batch_scrape!(id, opts \\ []) do- Req.delete!(client(opts), url: "/batch/scrape/#{id}")+ @spec search_papers!(keyword(), keyword()) :: Req.Response.t()+ def search_papers!(params \\ [], opts \\ []) do+ params = NimbleOptions.validate!(params, @research_search_papers_schema)+ Req.get!(client(opts), url: "/search/research/papers", params: [{"origin", @sdk_origin} | to_query(params, @research_search_papers_key_mapping)])end-@doc """- Cancel a crawl job-- `DELETE /crawl/{id}`-- Tag: Crawling-- ## Path Parameters-- * `id` - Path parameter `id`-- ## Returns+ Inspect paper metadata.- * `{:ok, %Req.Response{}}` on success- * `{:error, exception}` on HTTP or validation failure+ `GET /search/research/papers/{id}`"""- @spec cancel_crawl(String.t(), keyword()) :: response()- def cancel_crawl(id, opts \\ []) do- Req.delete(client(opts), url: "/crawl/#{id}")+ @spec inspect_paper(String.t(), keyword()) :: response()+ def inspect_paper(id, opts \\ []) do+ Req.get(client(opts),+ url: "/search/research/papers/#{URI.encode_www_form(id)}",+ params: [{"origin", @sdk_origin}]+ )end-@doc """- Bang variant of `cancel_crawl`. Raises on error.+ Bang variant of `inspect_paper`. Raises on error."""- @spec cancel_crawl!(String.t(), keyword()) :: Req.Response.t()- def cancel_crawl!(id, opts \\ []) do- Req.delete!(client(opts), url: "/crawl/#{id}")+ @spec inspect_paper!(String.t(), keyword()) :: Req.Response.t()+ def inspect_paper!(id, opts \\ []) do+ Req.get!(client(opts),+ url: "/search/research/papers/#{URI.encode_www_form(id)}",+ params: [{"origin", @sdk_origin}]+ )end-- @crawl_params_preview_schema NimbleOptions.new!([- prompt: [type: :string, required: true, doc: "Natural language prompt describing what you want to crawl"],- url: [type: :string, required: true, doc: "The URL to crawl"]+ @research_read_paper_schema NimbleOptions.new!([+ k: [type: :integer],+ query: [type: :string, required: true]])- @crawl_params_preview_key_mapping %{prompt: "prompt", url: "url"}+ @research_read_paper_key_mapping %{k: "k", query: "query"}@doc """- Preview crawl parameters generated from natural language prompt-- `POST /crawl/params-preview`-- Tag: Crawling-- ## Parameters-- Validated by `NimbleOptions`. Pass params as a keyword list with snake_case keys.- See `@crawl_params_preview_schema` for the full schema.-- ## Returns+ Read a paper with query-guided passages.- * `{:ok, %Req.Response{}}` on success- * `{:error, exception}` on HTTP or validation failure+ `GET /search/research/papers/{id}`"""- @spec crawl_params_preview(keyword(), keyword()) :: response()- def crawl_params_preview(params \\ [], opts \\ []) do- with {:ok, params} <- NimbleOptions.validate(params, @crawl_params_preview_schema) do- Req.post(client(opts), url: "/crawl/params-preview", json: to_body(params, @crawl_params_preview_key_mapping))+ @spec read_paper(String.t(), keyword(), keyword()) :: response()+ def read_paper(id, params \\ [], opts \\ []) do+ with {:ok, params} <- NimbleOptions.validate(params, @research_read_paper_schema) do+ Req.get(client(opts), url: "/search/research/papers/#{URI.encode_www_form(id)}", params: [{"origin", @sdk_origin} | to_query(params, @research_read_paper_key_mapping)])endend-@doc """- Bang variant of `crawl_params_preview`. Raises on error.+ Bang variant of `read_paper`. Raises on error."""- @spec crawl_params_preview!(keyword(), keyword()) :: Req.Response.t()- def crawl_params_preview!(params \\ [], opts \\ []) do- params = NimbleOptions.validate!(params, @crawl_params_preview_schema)- Req.post!(client(opts), url: "/crawl/params-preview", json: to_body(params, @crawl_params_preview_key_mapping))+ @spec read_paper!(String.t(), keyword(), keyword()) :: Req.Response.t()+ def read_paper!(id, params \\ [], opts \\ []) do+ params = NimbleOptions.validate!(params, @research_read_paper_schema)+ Req.get!(client(opts), url: "/search/research/papers/#{URI.encode_www_form(id)}", params: [{"origin", @sdk_origin} | to_query(params, @research_read_paper_key_mapping)])end-- @crawl_urls_schema NimbleOptions.new!([- allow_external_links: [type: :boolean, doc: "Allows the crawler to follow links to external websites."],- allow_subdomains: [type: :boolean, doc: "Allows the crawler to follow links to subdomains of the main domain."],- crawl_entire_domain: [type: :boolean, doc: "Allows the crawler to follow internal links to sibling or parent URLs, not just child paths.\n\nfalse: Only crawls deeper (child) URLs.\n→ e.g. /features/feature-1 → /features/feature-1/tips ✅\n→ Won't follow /pricing or / ❌\n\ntrue: Crawls any internal links, including siblings and parents.\n→ e.g. /features/feature-1 → /pricing, /, etc. ✅\n\nUse true for broader internal coverage beyond nested paths."],- delay: [type: {:or, [:integer, :float]}, doc: "Delay in seconds between scrapes. This helps respect website rate limits. Setting this forces concurrency to 1."],- exclude_paths: [type: {:list, :string}, doc: "URL pathname regex patterns that exclude matching URLs from the crawl. For example, if you set \"excludePaths\": [\"blog/.*\"] for the base URL firecrawl.dev, any results matching that pattern will be excluded, such as https://www.firecrawl.dev/blog/firecrawl-launch-week-1-recap."],- ignore_query_parameters: [type: :boolean, doc: "Do not re-scrape the same path with different (or none) query parameters"],- include_paths: [type: {:list, :string}, doc: "URL pathname regex patterns that include matching URLs in the crawl. Only the paths that match the specified patterns will be included in the response. Note: the starting URL is also checked against these patterns — if it does not match, the crawl may return 0 pages. For example, if you set \"includePaths\": [\"blog/.*\"] for the base URL firecrawl.dev/blog, only pages under /blog/ will be included in the results, such as https://www.firecrawl.dev/blog/firecrawl-launch-week-1-recap."],- limit: [type: :integer, doc: "Maximum number of pages to crawl. Default limit is 10000."],- max_concurrency: [type: :integer, doc: "Maximum number of concurrent scrapes. This parameter allows you to set a concurrency limit for this crawl. If not specified, the crawl adheres to your team's concurrency limit."],- max_discovery_depth: [type: :integer, doc: "Maximum depth to crawl based on discovery order. The root site and sitemapped pages has a discovery depth of 0. For example, if you set it to 1, and you set `sitemap: 'skip'`, you will only crawl the entered URL and all URLs that are linked on that page."],- prompt: [type: :string, doc: "A prompt to use to generate the crawler options (all the parameters below) from natural language. Explicitly set parameters will override the generated equivalents."],- regex_on_full_url: [type: :boolean, doc: "When true, includePaths and excludePaths regex patterns are matched against the full URL (including query parameters) instead of just the URL pathname. Useful when you need to filter URLs based on query strings."],- scrape_options: [type: :keyword_list],- sitemap: [type: {:or, [{:in, [:skip, :include, :only]}, :string]}, doc: "Sitemap mode when crawling. If you set it to 'skip', the crawler will ignore the website sitemap and only crawl the entered URL and discover pages from there onwards. If you set it to 'only', the crawler will only crawl URLs from the sitemap (plus the start URL) and will not discover links from HTML."],- url: [type: :string, required: true, doc: "The base URL to start crawling from"],- webhook: [type: :keyword_list, doc: "A webhook specification object."],- zero_data_retention: [type: :boolean, doc: "If true, this will enable zero data retention for this crawl. To enable this feature, please contact [email protected]"]+ @research_related_papers_schema NimbleOptions.new!([+ anchor: [type: {:list, :string}],+ intent: [type: :string, required: true],+ k: [type: :integer],+ mode: [type: {:in, [:similar, :citers, :references, "similar", "citers", "references"]}],+ rerank: [type: :boolean]])- @crawl_urls_key_mapping %{allow_external_links: "allowExternalLinks", allow_subdomains: "allowSubdomains", crawl_entire_domain: "crawlEntireDomain", delay: "delay", exclude_paths: "excludePaths", ignore_query_parameters: "ignoreQueryParameters", include_paths: "includePaths", limit: "limit", max_concurrency: "maxConcurrency", max_discovery_depth: "maxDiscoveryDepth", prompt: "prompt", regex_on_full_url: "regexOnFullURL", scrape_options: "scrapeOptions", sitemap: "sitemap", url: "url", webhook: "webhook", zero_data_retention: "zeroDataRetention"}+ @research_related_papers_key_mapping %{anchor: "anchor", intent: "intent", k: "k", mode: "mode", rerank: "rerank"}@doc """- Crawl multiple URLs based on options-- `POST /crawl`-- Tag: Crawling-- ## Parameters-- Validated by `NimbleOptions`. Pass params as a keyword list with snake_case keys.- See `@crawl_urls_schema` for the full schema.-- ## Returns+ Find papers related to a paper.- * `{:ok, %Req.Response{}}` on success- * `{:error, exception}` on HTTP or validation failure+ `GET /search/research/papers/{id}/similar`"""- @spec crawl_urls(keyword(), keyword()) :: response()- def crawl_urls(params \\ [], opts \\ []) do- with {:ok, params} <- NimbleOptions.validate(params, @crawl_urls_schema) do- Req.post(client(opts), url: "/crawl", json: to_body(params, @crawl_urls_key_mapping))+ @spec related_papers(String.t(), keyword(), keyword()) :: response()+ def related_papers(id, params \\ [], opts \\ []) do+ with {:ok, params} <- NimbleOptions.validate(params, @research_related_papers_schema) do+ Req.get(client(opts), url: "/search/research/papers/#{URI.encode_www_form(id)}/similar", params: [{"origin", @sdk_origin} | to_query(params, @research_related_papers_key_mapping)])endend-+ @doc """+ Bang variant of `related_papers`. Raises on error.+ """+ @spec related_papers!(String.t(), keyword(), keyword()) :: Req.Response.t()+ def related_papers!(id, params \\ [], opts \\ []) do+ params = NimbleOptions.validate!(params, @research_related_papers_schema)+ Req.get!(client(opts), url: "/search/research/papers/#{URI.encode_www_form(id)}/similar", params: [{"origin", @sdk_origin} | to_query(params, @research_related_papers_key_mapping)])+ end++ @research_search_github_schema NimbleOptions.new!([+ k: [type: :integer],+ query: [type: :string, required: true]+ ])++ @research_search_github_key_mapping %{k: "k", query: "query"}++ @doc """+ Search GitHub research content.++ `GET /search/research/github`+ """+ @spec search_github(keyword(), keyword()) :: response()+ def search_github(params \\ [], opts \\ []) do+ with {:ok, params} <- NimbleOptions.validate(params, @research_search_github_schema) do+ Req.get(client(opts), url: "/search/research/github", params: [{"origin", @sdk_origin} | to_query(params, @research_search_github_key_mapping)])+ end+ end++ @doc """+ Bang variant of `search_github`. Raises on error.+ """+ @spec search_github!(keyword(), keyword()) :: Req.Response.t()+ def search_github!(params \\ [], opts \\ []) do+ params = NimbleOptions.validate!(params, @research_search_github_schema)+ Req.get!(client(opts), url: "/search/research/github", params: [{"origin", @sdk_origin} | to_query(params, @research_search_github_key_mapping)])+ end++ @monitor_key_mapping %{+ name: "name",+ schedule: "schedule",+ targets: "targets",+ webhook: "webhook",+ notification: "notification",+ retention_days: "retentionDays",+ status: "status",+ goal: "goal",+ judge_enabled: "judgeEnabled"+ }++ @monitor_list_key_mapping %{limit: "limit", offset: "offset"}+ @monitor_check_list_key_mapping %{limit: "limit", offset: "offset", status: "status"}+ @monitor_check_key_mapping %{limit: "limit", skip: "skip", status: "status"}++ @monitor_schema NimbleOptions.new!([+ name: [type: :string],+ schedule: [type: :any],+ targets: [type: {:list, :any}],+ webhook: [type: :any],+ notification: [type: :any],+ retention_days: [type: :integer],+ status: [type: :any],+ goal: [type: :any],+ judge_enabled: [type: :boolean]+ ])++ @monitor_list_schema NimbleOptions.new!([+ limit: [type: :integer],+ offset: [type: :integer]+ ])++ @monitor_check_list_schema NimbleOptions.new!([+ limit: [type: :integer],+ offset: [type: :integer],+ status: [type: :any]+ ])++ @monitor_check_schema NimbleOptions.new!([+ limit: [type: :integer],+ skip: [type: :integer],+ status: [type: :any]+ ])++ @doc """+ Create a scheduled monitor.++ `POST /monitor`++ ## Targets++ `targets` is a list of maps/keyword lists. Each target is sent as-is (keys are+ camelCased), so the supported target shapes are:++ * Scrape: `[type: "scrape", url: "https://example.com", ...]`+ * Crawl: `[type: "crawl", url: "https://example.com", ...]`+ * Search:+ `[type: "search", queries: ["term"], search_window: "24h",+ include_domains: ["example.com"], exclude_domains: [],+ max_results: 10]`+ (`search_window` is one of `"5m"`, `"15m"`, `"1h"`, `"6h"`, `"24h"`,+ `"7d"`; only `queries` is required.)++ Optionally pass `goal` and `judge_enabled: true` to enable AI judging.+ """+ @spec create_monitor(keyword(), keyword()) :: response()+ def create_monitor(params \\ [], opts \\ []) do+ with {:ok, params} <- NimbleOptions.validate(params, @monitor_schema) do+ Req.post(client(opts), url: "/monitor", json: to_body(params, @monitor_key_mapping))+ end+ end++ @doc """+ Bang variant of `create_monitor`. Raises on error.+ """+ @spec create_monitor!(keyword(), keyword()) :: Req.Response.t()+ def create_monitor!(params \\ [], opts \\ []) do+ params = NimbleOptions.validate!(params, @monitor_schema)+ Req.post!(client(opts), url: "/monitor", json: to_body(params, @monitor_key_mapping))+ end++ @doc """+ List monitors for the authenticated team.++ `GET /monitor`+ """+ @spec list_monitors(keyword(), keyword()) :: response()+ def list_monitors(params \\ [], opts \\ []) do+ with {:ok, params} <- NimbleOptions.validate(params, @monitor_list_schema) do+ Req.get(client(opts), url: "/monitor", params: to_query(params, @monitor_list_key_mapping))+ end+ end++ @doc """+ Bang variant of `list_monitors`. Raises on error.+ """+ @spec list_monitors!(keyword(), keyword()) :: Req.Response.t()+ def list_monitors!(params \\ [], opts \\ []) do+ params = NimbleOptions.validate!(params, @monitor_list_schema)+ Req.get!(client(opts), url: "/monitor", params: to_query(params, @monitor_list_key_mapping))+ end++ @doc """+ Get a monitor by ID.++ `GET /monitor/{monitorId}`+ """+ @spec get_monitor(String.t(), keyword()) :: response()+ def get_monitor(monitor_id, opts \\ []) do+ Req.get(client(opts), url: "/monitor/#{monitor_id}")+ end++ @doc """+ Bang variant of `get_monitor`. Raises on error.+ """+ @spec get_monitor!(String.t(), keyword()) :: Req.Response.t()+ def get_monitor!(monitor_id, opts \\ []) do+ Req.get!(client(opts), url: "/monitor/#{monitor_id}")+ end++ @doc """+ Update a monitor.++ `PATCH /monitor/{monitorId}`+ """+ @spec update_monitor(String.t(), keyword(), keyword()) :: response()+ def update_monitor(monitor_id, params \\ [], opts \\ []) do+ with {:ok, params} <- NimbleOptions.validate(params, @monitor_schema) do+ Req.patch(client(opts), url: "/monitor/#{monitor_id}", json: to_body(params, @monitor_key_mapping))+ end+ end++ @doc """+ Bang variant of `update_monitor`. Raises on error.+ """+ @spec update_monitor!(String.t(), keyword(), keyword()) :: Req.Response.t()+ def update_monitor!(monitor_id, params \\ [], opts \\ []) do+ params = NimbleOptions.validate!(params, @monitor_schema)+ Req.patch!(client(opts), url: "/monitor/#{monitor_id}", json: to_body(params, @monitor_key_mapping))+ end++ @doc """+ Delete a monitor.++ `DELETE /monitor/{monitorId}`+ """+ @spec delete_monitor(String.t(), keyword()) :: response()+ def delete_monitor(monitor_id, opts \\ []) do+ Req.delete(client(opts), url: "/monitor/#{monitor_id}")+ end++ @doc """+ Bang variant of `delete_monitor`. Raises on error.+ """+ @spec delete_monitor!(String.t(), keyword()) :: Req.Response.t()+ def delete_monitor!(monitor_id, opts \\ []) do+ Req.delete!(client(opts), url: "/monitor/#{monitor_id}")+ end++ @doc """+ Trigger a manual monitor check.++ `POST /monitor/{monitorId}/run`+ """+ @spec run_monitor(String.t(), keyword()) :: response()+ def run_monitor(monitor_id, opts \\ []) do+ Req.post(client(opts), url: "/monitor/#{monitor_id}/run", json: %{})+ end++ @doc """+ Bang variant of `run_monitor`. Raises on error.+ """+ @spec run_monitor!(String.t(), keyword()) :: Req.Response.t()+ def run_monitor!(monitor_id, opts \\ []) do+ Req.post!(client(opts), url: "/monitor/#{monitor_id}/run", json: %{})+ end++ @doc """+ List checks for a monitor.++ `GET /monitor/{monitorId}/checks`+ """+ @spec list_monitor_checks(String.t(), keyword(), keyword()) :: response()+ def list_monitor_checks(monitor_id, params \\ [], opts \\ []) do+ with {:ok, params} <- NimbleOptions.validate(params, @monitor_check_list_schema) do+ Req.get(client(opts),+ url: "/monitor/#{monitor_id}/checks",+ params: to_query(params, @monitor_check_list_key_mapping)+ )+ end+ end++ @doc """+ Bang variant of `list_monitor_checks`. Raises on error.+ """+ @spec list_monitor_checks!(String.t(), keyword(), keyword()) :: Req.Response.t()+ def list_monitor_checks!(monitor_id, params \\ [], opts \\ []) do+ params = NimbleOptions.validate!(params, @monitor_check_list_schema)+ Req.get!(client(opts),+ url: "/monitor/#{monitor_id}/checks",+ params: to_query(params, @monitor_check_list_key_mapping)+ )+ end++ @doc """+ Get a monitor check with paginated page results and inline diffs.++ `GET /monitor/{monitorId}/checks/{checkId}`+ """+ @spec get_monitor_check(String.t(), String.t(), keyword(), keyword()) :: response()+ def get_monitor_check(monitor_id, check_id, params \\ [], opts \\ []) do+ {auto_paginate, opts} = Keyword.pop(opts, :auto_paginate, true)++ with {:ok, params} <- NimbleOptions.validate(params, @monitor_check_schema) do+ case Req.get(client(opts),+ url: "/monitor/#{monitor_id}/checks/#{check_id}",+ params: to_query(params, @monitor_check_key_mapping)+ ) do+ {:ok, response} when auto_paginate -> {:ok, paginate_monitor_check_response(response, opts)}+ result -> result+ end+ end+ end++ @doc """+ Bang variant of `get_monitor_check`. Raises on error.+ """+ @spec get_monitor_check!(String.t(), String.t(), keyword(), keyword()) :: Req.Response.t()+ def get_monitor_check!(monitor_id, check_id, params \\ [], opts \\ []) do+ {auto_paginate, opts} = Keyword.pop(opts, :auto_paginate, true)+ params = NimbleOptions.validate!(params, @monitor_check_schema)+ response = Req.get!(client(opts),+ url: "/monitor/#{monitor_id}/checks/#{check_id}",+ params: to_query(params, @monitor_check_key_mapping)+ )++ if auto_paginate, do: paginate_monitor_check_response!(response, opts), else: response+ end++ defp paginate_monitor_check_response(%Req.Response{body: body} = response, opts) when is_map(body) do+ data = Map.get(body, "data") || %{}+ pages = Map.get(data, "pages") || []+ next = Map.get(body, "next") || Map.get(data, "next")+ pages = fetch_monitor_check_pages(next, pages, opts)+ data = data |> Map.put("pages", pages) |> Map.put("next", nil)+ %{response | body: body |> Map.put("data", data) |> Map.put("next", nil)}+ end++ defp paginate_monitor_check_response(response, _opts), do: response++ defp paginate_monitor_check_response!(%Req.Response{body: body} = response, opts) when is_map(body) do+ data = Map.get(body, "data") || %{}+ pages = Map.get(data, "pages") || []+ next = Map.get(body, "next") || Map.get(data, "next")+ pages = fetch_monitor_check_pages!(next, pages, opts)+ data = data |> Map.put("pages", pages) |> Map.put("next", nil)+ %{response | body: body |> Map.put("data", data) |> Map.put("next", nil)}+ end++ defp paginate_monitor_check_response!(response, _opts), do: response++ defp fetch_monitor_check_pages(nil, pages, _opts), do: pages+ defp fetch_monitor_check_pages("", pages, _opts), do: pages++ defp fetch_monitor_check_pages(next, pages, opts) do+ req = client(opts)++ case Req.get(req, url: Firecrawl.ApiOrigin.pin(next, req.options.base_url)) do+ {:ok, %Req.Response{body: body}} when is_map(body) ->+ data = Map.get(body, "data") || %{}+ next_pages = Map.get(data, "pages") || []+ next_url = Map.get(body, "next") || Map.get(data, "next")+ fetch_monitor_check_pages(next_url, pages ++ next_pages, opts)++ _ ->+ pages+ end+ end++ defp fetch_monitor_check_pages!(nil, pages, _opts), do: pages+ defp fetch_monitor_check_pages!("", pages, _opts), do: pages++ defp fetch_monitor_check_pages!(next, pages, opts) do+ req = client(opts)+ response = Req.get!(req, url: Firecrawl.ApiOrigin.pin(next, req.options.base_url))+ body = response.body+ data = if is_map(body), do: Map.get(body, "data") || %{}, else: %{}+ next_pages = Map.get(data, "pages") || []+ next_url = if is_map(body), do: Map.get(body, "next") || Map.get(data, "next"), else: nil+ fetch_monitor_check_pages!(next_url, pages ++ next_pages, opts)+ end++ # --- END HAND-WRITTEN ---++ @ask_support_agent_schema NimbleOptions.new!([+ question: [type: :string, required: true, doc: "Question or issue for the support agent to diagnose."],+ rationale: [type: :string, doc: "Optional context about what the end user is trying to accomplish."]+ ])++ @ask_support_agent_key_mapping %{question: "question", rationale: "rationale"}++ @doc """+ Ask the Firecrawl support agent++ `POST /support/ask`++ Tag: Support++ ## Parameters++ Validated by `NimbleOptions`. Pass params as a keyword list with snake_case keys.+ See `@ask_support_agent_schema` for the full schema.++ ## Returns++ * `{:ok, %Req.Response{}}` on success+ * `{:error, exception}` on HTTP or validation failure+ """+ @spec ask_support_agent(keyword(), keyword()) :: response()+ def ask_support_agent(params \\ [], opts \\ []) do+ with {:ok, params} <- NimbleOptions.validate(params, @ask_support_agent_schema) do+ Req.post(client(opts), url: "/support/ask", json: to_body(params, @ask_support_agent_key_mapping))+ end+ end+++ @doc """+ Bang variant of `ask_support_agent`. Raises on error.+ """+ @spec ask_support_agent!(keyword(), keyword()) :: Req.Response.t()+ def ask_support_agent!(params \\ [], opts \\ []) do+ params = NimbleOptions.validate!(params, @ask_support_agent_schema)+ Req.post!(client(opts), url: "/support/ask", json: to_body(params, @ask_support_agent_key_mapping))+ end+++ @doc """+ Cancel an agent job++ `DELETE /agent/{jobId}`++ Tag: Agent++ ## Path Parameters++ * `job_id` - Path parameter `jobId`++ ## Returns++ * `{:ok, %Req.Response{}}` on success+ * `{:error, exception}` on HTTP or validation failure+ """+ @spec cancel_agent(String.t(), keyword()) :: response()+ def cancel_agent(job_id, opts \\ []) do+ Req.delete(client(opts), url: "/agent/#{job_id}")+ end+++ @doc """+ Bang variant of `cancel_agent`. Raises on error.+ """+ @spec cancel_agent!(String.t(), keyword()) :: Req.Response.t()+ def cancel_agent!(job_id, opts \\ []) do+ Req.delete!(client(opts), url: "/agent/#{job_id}")+ end+++ @doc """+ Cancel a batch scrape job++ `DELETE /batch/scrape/{id}`++ Tag: Scraping++ ## Path Parameters++ * `id` - Path parameter `id`++ ## Returns++ * `{:ok, %Req.Response{}}` on success+ * `{:error, exception}` on HTTP or validation failure+ """+ @spec cancel_batch_scrape(String.t(), keyword()) :: response()+ def cancel_batch_scrape(id, opts \\ []) do+ Req.delete(client(opts), url: "/batch/scrape/#{id}")+ end+++ @doc """+ Bang variant of `cancel_batch_scrape`. Raises on error.+ """+ @spec cancel_batch_scrape!(String.t(), keyword()) :: Req.Response.t()+ def cancel_batch_scrape!(id, opts \\ []) do+ Req.delete!(client(opts), url: "/batch/scrape/#{id}")+ end+++ @doc """+ Cancel a crawl job++ `DELETE /crawl/{id}`++ Tag: Crawling++ ## Path Parameters++ * `id` - Path parameter `id`++ ## Returns++ * `{:ok, %Req.Response{}}` on success+ * `{:error, exception}` on HTTP or validation failure+ """+ @spec cancel_crawl(String.t(), keyword()) :: response()+ def cancel_crawl(id, opts \\ []) do+ Req.delete(client(opts), url: "/crawl/#{id}")+ end+++ @doc """+ Bang variant of `cancel_crawl`. Raises on error.+ """+ @spec cancel_crawl!(String.t(), keyword()) :: Req.Response.t()+ def cancel_crawl!(id, opts \\ []) do+ Req.delete!(client(opts), url: "/crawl/#{id}")+ end+++ @crawl_params_preview_schema NimbleOptions.new!([+ prompt: [type: :string, required: true, doc: "Natural language prompt describing what you want to crawl"],+ url: [type: :string, required: true, doc: "The URL to crawl"]+ ])++ @crawl_params_preview_key_mapping %{prompt: "prompt", url: "url"}++ @doc """+ Preview crawl parameters generated from natural language prompt++ `POST /crawl/params-preview`++ Tag: Crawling++ ## Parameters++ Validated by `NimbleOptions`. Pass params as a keyword list with snake_case keys.+ See `@crawl_params_preview_schema` for the full schema.++ ## Returns++ * `{:ok, %Req.Response{}}` on success+ * `{:error, exception}` on HTTP or validation failure+ """+ @spec crawl_params_preview(keyword(), keyword()) :: response()+ def crawl_params_preview(params \\ [], opts \\ []) do+ with {:ok, params} <- NimbleOptions.validate(params, @crawl_params_preview_schema) do+ Req.post(client(opts), url: "/crawl/params-preview", json: to_body(params, @crawl_params_preview_key_mapping))+ end+ end+++ @doc """+ Bang variant of `crawl_params_preview`. Raises on error.+ """+ @spec crawl_params_preview!(keyword(), keyword()) :: Req.Response.t()+ def crawl_params_preview!(params \\ [], opts \\ []) do+ params = NimbleOptions.validate!(params, @crawl_params_preview_schema)+ Req.post!(client(opts), url: "/crawl/params-preview", json: to_body(params, @crawl_params_preview_key_mapping))+ end+++ @crawl_urls_schema NimbleOptions.new!([+ allow_external_links: [type: :boolean, doc: "Allows the crawler to follow links to external websites. External links are followed one hop (the links found on those external pages are not crawled). Links pointing to an external site's homepage (a root URL with no path) are skipped and reported in Get Crawl Errors with the code EXTERNAL_LINK; redirects to an external homepage are skipped for the same reason."],+ allow_subdomains: [type: :boolean, doc: "Allows the crawler to follow links to subdomains of the main domain."],+ crawl_entire_domain: [type: :boolean, doc: "Allows the crawler to follow internal links to sibling or parent URLs, not just child paths.\n\nfalse: Only crawls deeper (child) URLs.\n→ e.g. /features/feature-1 → /features/feature-1/tips ✅\n→ Won't follow /pricing or / ❌\n\ntrue: Crawls any internal links, including siblings and parents.\n→ e.g. /features/feature-1 → /pricing, /, etc. ✅\n\nUse true for broader internal coverage beyond nested paths."],+ delay: [type: {:or, [:integer, :float]}, doc: "Delay in seconds between scrapes. This helps respect website rate limits. Setting this forces concurrency to 1."],+ exclude_paths: [type: {:list, :string}, doc: "URL pathname regex patterns that exclude matching URLs from the crawl. For example, if you set \"excludePaths\": [\"blog/.*\"] for the base URL firecrawl.dev, any results matching that pattern will be excluded, such as https://www.firecrawl.dev/blog/firecrawl-launch-week-1-recap. Patterns use Rust regex (RE2-style) syntax: look-around and backreferences are not supported, and a pattern that does not compile is rejected with a 400. Each field accepts at most 1000 patterns of at most 2000 characters each, and includePaths and excludePaths together may contain at most 1000 patterns and 100,000 characters in total. For keyword-style filtering, send one short pattern per term rather than combining terms into a single long alternation."],+ ignore_query_parameters: [type: :boolean, doc: "Do not re-scrape the same path with different (or none) query parameters"],+ ignore_robots_txt: [type: :boolean, doc: "Ignore the website's robots.txt rules. Enterprise only — contact [email protected] to enable."],+ include_paths: [type: {:list, :string}, doc: "URL pathname regex patterns that include matching URLs in the crawl. Only the paths that match the specified patterns will be included in the response. Note: the starting URL is also checked against these patterns — if it does not match, the crawl may return 0 pages. For example, if you set \"includePaths\": [\"blog/.*\"] for the base URL firecrawl.dev/blog, only pages under /blog/ will be included in the results, such as https://www.firecrawl.dev/blog/firecrawl-launch-week-1-recap. Patterns use Rust regex (RE2-style) syntax: look-around and backreferences are not supported, and a pattern that does not compile is rejected with a 400. Each field accepts at most 1000 patterns of at most 2000 characters each, and includePaths and excludePaths together may contain at most 1000 patterns and 100,000 characters in total. For keyword-style filtering, send one short pattern per term rather than combining terms into a single long alternation."],+ limit: [type: :integer, doc: "Maximum number of pages to crawl. Default limit is 10000."],+ max_concurrency: [type: :integer, doc: "Maximum number of concurrent scrapes. This parameter allows you to set a concurrency limit for this crawl. If not specified, the crawl adheres to your team's concurrency limit."],+ max_discovery_depth: [type: :integer, doc: "Maximum depth to crawl based on discovery order. The root site and sitemapped pages has a discovery depth of 0. For example, if you set it to 1, and you set `sitemap: 'skip'`, you will only crawl the entered URL and all URLs that are linked on that page."],+ prompt: [type: :string, doc: "A prompt to use to generate the crawler options (all the parameters below) from natural language. Explicitly set parameters will override the generated equivalents."],+ regex_on_full_url: [type: :boolean, doc: "When true, includePaths and excludePaths regex patterns are matched against the full URL (including query parameters) instead of just the URL pathname. Useful when you need to filter URLs based on query strings."],+ robots_user_agent: [type: :string, doc: "Custom User-Agent string for robots.txt evaluation. When set, robots.txt is fetched with this User-Agent and allow/disallow rules are matched against it instead of the default. Enterprise only — contact [email protected] to enable."],+ scrape_options: [type: :keyword_list],+ sitemap: [type: {:or, [{:in, [:skip, :include, :only]}, :string]}, doc: "Sitemap mode when crawling. If you set it to 'skip', the crawler will ignore the website sitemap and only crawl the entered URL and discover pages from there onwards. If you set it to 'only', the crawler will only crawl URLs from the sitemap (plus the start URL) and will not discover links from HTML."],+ url: [type: :string, required: true, doc: "The base URL to start crawling from"],+ webhook: [type: :keyword_list, doc: "A webhook specification object."],+ zero_data_retention: [type: :boolean, doc: "If true, this will enable zero data retention for this crawl. To enable this feature, please contact [email protected]"]+ ])++ @crawl_urls_key_mapping %{allow_external_links: "allowExternalLinks", allow_subdomains: "allowSubdomains", crawl_entire_domain: "crawlEntireDomain", delay: "delay", exclude_paths: "excludePaths", ignore_query_parameters: "ignoreQueryParameters", ignore_robots_txt: "ignoreRobotsTxt", include_paths: "includePaths", limit: "limit", max_concurrency: "maxConcurrency", max_discovery_depth: "maxDiscoveryDepth", prompt: "prompt", regex_on_full_url: "regexOnFullURL", robots_user_agent: "robotsUserAgent", scrape_options: "scrapeOptions", sitemap: "sitemap", url: "url", webhook: "webhook", zero_data_retention: "zeroDataRetention"}++ @doc """+ Crawl multiple URLs based on options++ `POST /crawl`++ Tag: Crawling++ ## Parameters++ Validated by `NimbleOptions`. Pass params as a keyword list with snake_case keys.+ See `@crawl_urls_schema` for the full schema.++ ## Returns++ * `{:ok, %Req.Response{}}` on success+ * `{:error, exception}` on HTTP or validation failure+ """+ @spec crawl_urls(keyword(), keyword()) :: response()+ def crawl_urls(params \\ [], opts \\ []) do+ with {:ok, params} <- NimbleOptions.validate(params, @crawl_urls_schema) do+ Req.post(client(opts), url: "/crawl", json: to_body(params, @crawl_urls_key_mapping))+ end+ end++@doc """Bang variant of `crawl_urls`. Raises on error."""@@ -385,19 +921,19 @@ defmodule Firecrawl do@create_browser_session_schema NimbleOptions.new!([activity_ttl: [type: :integer, doc: "Time in seconds before the session is destroyed due to inactivity"],- profile: [type: :keyword_list, doc: "Enable persistent storage across browser sessions. Data saved in one session can be loaded in a later session using the same name."],+ profile: [type: :keyword_list, doc: "Enable persistent storage across interact sessions. Data saved in one session can be loaded in a later session using the same name."],stream_web_view: [type: :boolean, doc: "Whether to stream a live view of the browser"],- ttl: [type: :integer, doc: "Total time-to-live in seconds for the browser session"]+ ttl: [type: :integer, doc: "Total time-to-live in seconds for the interact session"]])@create_browser_session_key_mapping %{activity_ttl: "activityTtl", profile: "profile", stream_web_view: "streamWebView", ttl: "ttl"}@doc """- Create a browser session+ Create an interact session- `POST /browser`+ `POST /interact`- Tag: Browser+ Tag: Interact## Parameters@@ -412,7 +948,7 @@ defmodule Firecrawl do@spec create_browser_session(keyword(), keyword()) :: response()def create_browser_session(params \\ [], opts \\ []) dowith {:ok, params} <- NimbleOptions.validate(params, @create_browser_session_schema) do- Req.post(client(opts), url: "/browser", json: to_body(params, @create_browser_session_key_mapping))+ Req.post(client(opts), url: "/interact", json: to_body(params, @create_browser_session_key_mapping))endend@@ -423,16 +959,16 @@ defmodule Firecrawl do@spec create_browser_session!(keyword(), keyword()) :: Req.Response.t()def create_browser_session!(params \\ [], opts \\ []) doparams = NimbleOptions.validate!(params, @create_browser_session_schema)- Req.post!(client(opts), url: "/browser", json: to_body(params, @create_browser_session_key_mapping))+ Req.post!(client(opts), url: "/interact", json: to_body(params, @create_browser_session_key_mapping))end@doc """- Delete a browser session+ Delete an interact session- `DELETE /browser/{sessionId}`+ `DELETE /interact/{sessionId}`- Tag: Browser+ Tag: Interact## Path Parameters@@ -445,7 +981,7 @@ defmodule Firecrawl do"""@spec delete_browser_session(String.t(), keyword()) :: response()def delete_browser_session(session_id, opts \\ []) do- Req.delete(client(opts), url: "/browser/#{session_id}")+ Req.delete(client(opts), url: "/interact/#{session_id}")end@@ -454,24 +990,144 @@ defmodule Firecrawl do"""@spec delete_browser_session!(String.t(), keyword()) :: Req.Response.t()def delete_browser_session!(session_id, opts \\ []) do- Req.delete!(client(opts), url: "/browser/#{session_id}")+ Req.delete!(client(opts), url: "/interact/#{session_id}")+ end+++ @developer_search_query_schema NimbleOptions.new!([+ query: [type: :string, required: true, doc: "Natural-language question or search phrase."],+ k: [type: :integer, doc: "Number of ranked results to return."],+ types: [type: {:list, :string}, doc: "Result kinds to search. Defaults to all four. Accepts a repeated parameter (`types=issue&types=pull_request`) or one comma-separated value (`types=issue,pull_request`)."],+ repos: [type: {:list, :string}, doc: "Repository slugs to scope the repository half of the index to, such as `firecrawl/firecrawl`. Applies to the `issue`, `pull_request`, and `readme` types only. Sent together with `sources`, the two halves are combined rather than intersected, so matching results come back from either. Returns 400 when no repository type is in `types`, reporting that `repos` cannot match any requested type and that you should add repository types or drop `repos`."],+ sources: [type: {:list, :string}, doc: "Documentation source ids to scope the documentation half to, at most 20. Applies to the `doc` type only. Not a fixed enum: ids reflect the documentation sites in the index and the set grows over time, so confirm an id resolves by sending it and reading the `sources` array on the response. Returns 400 with `sources cannot match any requested type; add doc or drop sources` when `doc` is not in `types`."],+ skills: [type: {:or, [{:in, [:only]}, :string]}, doc: "Set to `only` to limit the search to indexed agent-skill files."],+ passages: [type: :integer, doc: "Matched passages to return per result."],+ language: [type: :string, doc: "Repository primary language, such as `Rust`. Applies to repository results only; sending it with no `sources` scope returns no `doc` results. See [how the repository filters scope a search](/api-reference/endpoint/developer-search#how-the-repository-filters-scope-a-search)."],+ topic: [type: :string, doc: "Repository topic, such as `async`. Applies to repository results only; sending it with no `sources` scope returns no `doc` results."],+ license: [type: :string, doc: "Repository license, such as `MIT`. Applies to repository results only; sending it with no `sources` scope returns no `doc` results."],+ min_stars: [type: :integer, doc: "Lower bound on repository stars. Applies to repository results only; sending it with no `sources` scope returns no `doc` results."],+ max_stars: [type: :integer, doc: "Upper bound on repository stars. Applies to repository results only; sending it with no `sources` scope returns no `doc` results."],+ archived: [type: :boolean, doc: "Include or exclude archived repositories. Applies to repository results only; sending it with no `sources` scope returns no `doc` results."],+ fork: [type: :boolean, doc: "Include or exclude forks. Applies to repository results only; sending it with no `sources` scope returns no `doc` results."]+ ])++ @developer_search_query_key_mapping %{query: "query", k: "k", types: "types", repos: "repos", sources: "sources", skills: "skills", passages: "passages", language: "language", topic: "topic", license: "license", min_stars: "min_stars", max_stars: "max_stars", archived: "archived", fork: "fork"}++ @doc """+ Search the developer index++ `GET /search/developer`++ Tag: Developer++ ## Query Parameters++ * `query` — query parameter `query`+ * `k` — query parameter `k`+ * `types` — query parameter `types`+ * `repos` — query parameter `repos`+ * `sources` — query parameter `sources`+ * `skills` — query parameter `skills`+ * `passages` — query parameter `passages`+ * `language` — query parameter `language`+ * `topic` — query parameter `topic`+ * `license` — query parameter `license`+ * `min_stars` — query parameter `min_stars`+ * `max_stars` — query parameter `max_stars`+ * `archived` — query parameter `archived`+ * `fork` — query parameter `fork`++ ## Returns++ * `{:ok, %Req.Response{}}` on success+ * `{:error, exception}` on HTTP or validation failure+ """+ @spec developer_search(keyword(), keyword()) :: response()+ def developer_search(params \\ [], opts \\ []) do+ with {:ok, params} <- NimbleOptions.validate(params, @developer_search_query_schema) do+ Req.get(client(opts), url: "/search/developer", params: to_query(params, @developer_search_query_key_mapping))+ end+ end+++ @doc """+ Bang variant of `developer_search`. Raises on error.+ """+ @spec developer_search!(keyword(), keyword()) :: Req.Response.t()+ def developer_search!(params \\ [], opts \\ []) do+ params = NimbleOptions.validate!(params, @developer_search_query_schema)+ Req.get!(client(opts), url: "/search/developer", params: to_query(params, @developer_search_query_key_mapping))+ end+++ @developer_search_post_schema NimbleOptions.new!([+ archived: [type: :boolean, doc: "Include or exclude archived repositories. Applies to repository results only; sending it with no `sources` scope returns no `doc` results."],+ fork: [type: :boolean, doc: "Include or exclude forks. Applies to repository results only; sending it with no `sources` scope returns no `doc` results."],+ k: [type: :integer],+ language: [type: :string, doc: "Repository primary language, such as `Rust`. Applies to repository results only; sending it with no `sources` scope returns no `doc` results. See [how the repository filters scope a search](/api-reference/endpoint/developer-search#how-the-repository-filters-scope-a-search)."],+ license: [type: :string, doc: "Repository license, such as `MIT`. Applies to repository results only; sending it with no `sources` scope returns no `doc` results."],+ max_stars: [type: :integer, doc: "Upper bound on repository stars. Applies to repository results only; sending it with no `sources` scope returns no `doc` results."],+ min_stars: [type: :integer, doc: "Lower bound on repository stars. Applies to repository results only; sending it with no `sources` scope returns no `doc` results."],+ passages: [type: :integer],+ query: [type: :string, required: true],+ repos: [type: {:list, :string}, doc: "Repository slugs to scope the repository half of the index to. Applies to the `issue`, `pull_request`, and `readme` types only. Sent together with `sources`, the two halves are combined rather than intersected. Returns 400 when no repository type is in `types`, reporting that `repos` cannot match any requested type and that you should add repository types or drop `repos`."],+ skills: [type: {:or, [{:in, [:only]}, :string]}, doc: "Set to `only` to limit the search to indexed agent-skill files."],+ sources: [type: {:list, :string}, doc: "Documentation source ids to scope the documentation half to, at most 20. Applies to the `doc` type only. Not a fixed enum: ids reflect the documentation sites in the index and the set grows over time. Returns 400 with `sources cannot match any requested type; add doc or drop sources` when `doc` is not in `types`."],+ topic: [type: :string, doc: "Repository topic, such as `async`. Applies to repository results only; sending it with no `sources` scope returns no `doc` results."],+ types: [type: {:list, :string}]+ ])++ @developer_search_post_key_mapping %{archived: "archived", fork: "fork", k: "k", language: "language", license: "license", max_stars: "max_stars", min_stars: "min_stars", passages: "passages", query: "query", repos: "repos", skills: "skills", sources: "sources", topic: "topic", types: "types"}++ @doc """+ Search the developer index++ `POST /search/developer`++ Tag: Developer++ ## Parameters++ Validated by `NimbleOptions`. Pass params as a keyword list with snake_case keys.+ See `@developer_search_post_schema` for the full schema.++ ## Returns++ * `{:ok, %Req.Response{}}` on success+ * `{:error, exception}` on HTTP or validation failure+ """+ @spec developer_search_post(keyword(), keyword()) :: response()+ def developer_search_post(params \\ [], opts \\ []) do+ with {:ok, params} <- NimbleOptions.validate(params, @developer_search_post_schema) do+ Req.post(client(opts), url: "/search/developer", json: to_body(params, @developer_search_post_key_mapping))+ end+ end+++ @doc """+ Bang variant of `developer_search_post`. Raises on error.+ """+ @spec developer_search_post!(keyword(), keyword()) :: Req.Response.t()+ def developer_search_post!(params \\ [], opts \\ []) do+ params = NimbleOptions.validate!(params, @developer_search_post_schema)+ Req.post!(client(opts), url: "/search/developer", json: to_body(params, @developer_search_post_key_mapping))end@execute_browser_code_schema NimbleOptions.new!([code: [type: :string, required: true, doc: "Code to execute in the browser sandbox"],- language: [type: {:in, [:python, :node, :bash]}, doc: "Language of the code to execute. Use `node` for JavaScript or `bash` for agent-browser CLI commands."],+ language: [type: {:or, [{:in, [:python, :node, :bash]}, :string]}, doc: "Language of the code to execute. Use `node` for JavaScript or `bash` for agent-browser CLI commands."],timeout: [type: :integer, doc: "Execution timeout in seconds"]])@execute_browser_code_key_mapping %{code: "code", language: "language", timeout: "timeout"}@doc """- Execute code in a browser session+ Execute code in an interact session- `POST /browser/{sessionId}/execute`+ `POST /interact/{sessionId}/execute`- Tag: Browser+ Tag: Interact## Path Parameters@@ -490,7 +1146,7 @@ defmodule Firecrawl do@spec execute_browser_code(String.t(), keyword(), keyword()) :: response()def execute_browser_code(session_id, params \\ [], opts \\ []) dowith {:ok, params} <- NimbleOptions.validate(params, @execute_browser_code_schema) do- Req.post(client(opts), url: "/browser/#{session_id}/execute", json: to_body(params, @execute_browser_code_key_mapping))+ Req.post(client(opts), url: "/interact/#{session_id}/execute", json: to_body(params, @execute_browser_code_key_mapping))endend@@ -501,7 +1157,7 @@ defmodule Firecrawl do@spec execute_browser_code!(String.t(), keyword(), keyword()) :: Req.Response.t()def execute_browser_code!(session_id, params \\ [], opts \\ []) doparams = NimbleOptions.validate!(params, @execute_browser_code_schema)- Req.post!(client(opts), url: "/browser/#{session_id}/execute", json: to_body(params, @execute_browser_code_key_mapping))+ Req.post!(client(opts), url: "/interact/#{session_id}/execute", json: to_body(params, @execute_browser_code_key_mapping))end@@ -533,7 +1189,7 @@ defmodule Firecrawl do@get_activity_query_schema NimbleOptions.new!([- endpoint: [type: {:in, [:scrape, :crawl, :batch_scrape, :search, :extract, :llmstxt, :deep_research, :map, :agent, :browser, :interact]}, doc: "Filter by endpoint"],+ endpoint: [type: {:or, [{:in, [:scrape, :crawl, :batch_scrape, :search, :extract, :llmstxt, :deep_research, :map, :agent, :browser, :interact]}, :string]}, doc: "Filter by endpoint"],limit: [type: :integer, doc: "Maximum number of results per page"],cursor: [type: :string, doc: "Cursor for pagination. Use the cursor value from the previous response."]])@@ -577,7 +1233,7 @@ defmodule Firecrawl do@doc """- Get a snapshot of an agent job+ Get an output snapshot of an agent job`GET /agent/{jobId}/snapshots/{snapshotId}`@@ -592,8 +1248,6 @@ defmodule Firecrawl do* `{:ok, %Req.Response{}}` on success* `{:error, exception}` on HTTP or validation failure-- Success JSON: `%{"success" => true, "id" => "...", "snapshotId" => "...", "snapshot" => "<string content>"}`."""@spec get_agent_snapshot(String.t(), String.t(), keyword()) :: response()def get_agent_snapshot(job_id, snapshot_id, opts \\ []) do@@ -624,70 +1278,20 @@ defmodule Firecrawl do## Returns* `{:ok, %Req.Response{}}` on success- * `{:error, exception}` on HTTP or validation failure- """- @spec get_agent_status(String.t(), keyword()) :: response()- def get_agent_status(job_id, opts \\ []) do- Req.get(client(opts), url: "/agent/#{job_id}")- end--- @doc """- Bang variant of `get_agent_status`. Raises on error.- """- @spec get_agent_status!(String.t(), keyword()) :: Req.Response.t()- def get_agent_status!(job_id, opts \\ []) do- Req.get!(client(opts), url: "/agent/#{job_id}")- end--- @doc """- Get the execution trace of an agent job-- `GET /agent/{jobId}/trace`-- Tag: Agent-- The trace is only available for agent runs on spark-2.-- ## Path Parameters-- * `job_id` - Path parameter `jobId`-- ## Options-- * `:live_view` - when `true`, the query parameter `liveView=true` is sent and- the response may additionally carry `activeBrowserSessions`, a list of- `%{"id" => "...", "liveViewUrl" => "...", "viewport" => %{"width" => 1280, "height" => 720}}`- entries for the run's live browser sessions.-- ## Returns-- * `{:ok, %Req.Response{}}` on success- * `{:error, exception}` on HTTP or validation failure-- Success JSON: `%{"success" => true, "id" => "...", "events" => [...], "creditsUsed" => 5}`.-- Each event has a `type` field (e.g. `"run.started"`, `"tool_call.started"`,- `"artifact.updated"`) plus the base fields `schemaVersion`, `eventId`, `runId`,- `occurredAt`, `producerSequence`, and `agent`.- """- @spec get_agent_trace(String.t(), keyword()) :: response()- def get_agent_trace(job_id, opts \\ []) do- {live_view, opts} = Keyword.pop(opts, :live_view, false)- params = if live_view, do: [{"liveView", "true"}], else: []- Req.get(client(opts), url: "/agent/#{job_id}/trace", params: params)+ * `{:error, exception}` on HTTP or validation failure+ """+ @spec get_agent_status(String.t(), keyword()) :: response()+ def get_agent_status(job_id, opts \\ []) do+ Req.get(client(opts), url: "/agent/#{job_id}")end@doc """- Bang variant of `get_agent_trace`. Raises on error.+ Bang variant of `get_agent_status`. Raises on error."""- @spec get_agent_trace!(String.t(), keyword()) :: Req.Response.t()- def get_agent_trace!(job_id, opts \\ []) do- {live_view, opts} = Keyword.pop(opts, :live_view, false)- params = if live_view, do: [{"liveView", "true"}], else: []- Req.get!(client(opts), url: "/agent/#{job_id}/trace", params: params)+ @spec get_agent_status!(String.t(), keyword()) :: Req.Response.t()+ def get_agent_status!(job_id, opts \\ []) do+ Req.get!(client(opts), url: "/agent/#{job_id}")end@@ -909,19 +1513,10 @@ defmodule Firecrawl doend- @interact_with_scrape_browser_session_schema NimbleOptions.new!([- code: [type: :string, required: true, doc: "Code to execute in the scrape-bound browser sandbox"],- language: [type: {:in, [:python, :node, :bash]}, doc: "Language of the code to execute. Use `node` for JavaScript or `bash` for agent-browser CLI commands."],- origin: [type: :string, doc: "Optional origin label used for execution telemetry"],- timeout: [type: :integer, doc: "Execution timeout in seconds"]- ])-- @interact_with_scrape_browser_session_key_mapping %{code: "code", language: "language", origin: "origin", timeout: "timeout"}-@doc """- Interact with the browser session associated with a scrape job+ Get the status of a scrape job- `POST /scrape/{jobId}/interact`+ `GET /scrape/{jobId}`Tag: Scraping@@ -929,965 +1524,797 @@ defmodule Firecrawl do* `job_id` - Path parameter `jobId`- ## Parameters-- Validated by `NimbleOptions`. Pass params as a keyword list with snake_case keys.- See `@interact_with_scrape_browser_session_schema` for the full schema.-- ## Returns-- * `{:ok, %Req.Response{}}` on success- * `{:error, exception}` on HTTP or validation failure- """- @spec interact_with_scrape_browser_session(String.t(), keyword(), keyword()) :: response()- def interact_with_scrape_browser_session(job_id, params \\ [], opts \\ []) do- with {:ok, params} <- NimbleOptions.validate(params, @interact_with_scrape_browser_session_schema) do- Req.post(client(opts), url: "/scrape/#{job_id}/interact", json: to_body(params, @interact_with_scrape_browser_session_key_mapping))- end- end--- @doc """- Bang variant of `interact_with_scrape_browser_session`. Raises on error.- """- @spec interact_with_scrape_browser_session!(String.t(), keyword(), keyword()) :: Req.Response.t()- def interact_with_scrape_browser_session!(job_id, params \\ [], opts \\ []) do- params = NimbleOptions.validate!(params, @interact_with_scrape_browser_session_schema)- Req.post!(client(opts), url: "/scrape/#{job_id}/interact", json: to_body(params, @interact_with_scrape_browser_session_key_mapping))- end--- @list_agents_query_schema NimbleOptions.new!([- before: [type: :integer, doc: "Only return agent runs created before this unix millisecond timestamp"]- ])-- @list_agents_query_key_mapping %{before: "before"}-- @doc """- List agent runs, most recent first-- `GET /agent`-- Tag: Agent-- Pages are fixed at 20 runs. To fetch the next page, pass the `before` value- from the previous page's `next` URL. This function does not auto-paginate.-- ## Query Parameters-- * `before` — query parameter `before`-- ## Returns-- * `{:ok, %Req.Response{}}` on success- * `{:error, exception}` on HTTP or validation failure- """- @spec list_agents(keyword(), keyword()) :: response()- def list_agents(params \\ [], opts \\ []) do- with {:ok, params} <- NimbleOptions.validate(params, @list_agents_query_schema) do- Req.get(client(opts), url: "/agent", params: to_query(params, @list_agents_query_key_mapping))- end- end--- @doc """- Bang variant of `list_agents`. Raises on error.- """- @spec list_agents!(keyword(), keyword()) :: Req.Response.t()- def list_agents!(params \\ [], opts \\ []) do- params = NimbleOptions.validate!(params, @list_agents_query_schema)- Req.get!(client(opts), url: "/agent", params: to_query(params, @list_agents_query_key_mapping))- end--- @list_browser_sessions_query_schema NimbleOptions.new!([- status: [type: {:in, [:active, :destroyed]}, doc: "Filter sessions by status"]- ])-- @list_browser_sessions_query_key_mapping %{status: "status"}-- @doc """- List browser sessions-- `GET /browser`-- Tag: Browser-- ## Query Parameters-- * `status` — query parameter `status`-## Returns* `{:ok, %Req.Response{}}` on success* `{:error, exception}` on HTTP or validation failure"""- @spec list_browser_sessions(keyword(), keyword()) :: response()- def list_browser_sessions(params \\ [], opts \\ []) do- with {:ok, params} <- NimbleOptions.validate(params, @list_browser_sessions_query_schema) do- Req.get(client(opts), url: "/browser", params: to_query(params, @list_browser_sessions_query_key_mapping))- end+ @spec get_scrape_status(String.t(), keyword()) :: response()+ def get_scrape_status(job_id, opts \\ []) do+ Req.get(client(opts), url: "/scrape/#{job_id}")end@doc """- Bang variant of `list_browser_sessions`. Raises on error.+ Bang variant of `get_scrape_status`. Raises on error."""- @spec list_browser_sessions!(keyword(), keyword()) :: Req.Response.t()- def list_browser_sessions!(params \\ [], opts \\ []) do- params = NimbleOptions.validate!(params, @list_browser_sessions_query_schema)- Req.get!(client(opts), url: "/browser", params: to_query(params, @list_browser_sessions_query_key_mapping))+ @spec get_scrape_status!(String.t(), keyword()) :: Req.Response.t()+ def get_scrape_status!(job_id, opts \\ []) do+ Req.get!(client(opts), url: "/scrape/#{job_id}")end- @map_urls_schema NimbleOptions.new!([- audit_metadata: [type: :keyword_list, keys: [username: [type: :string, required: true]], doc: "User attribution to include with SIEM logging events."],- ignore_cache: [type: :boolean, doc: "Bypass the sitemap cache to retrieve fresh URLs. Sitemap data is cached for up to 7 days; use this parameter when your sitemap has been recently updated."],- ignore_query_parameters: [type: :boolean, doc: "Do not return URLs with query parameters"],- include_subdomains: [type: :boolean, doc: "Include subdomains of the website"],- limit: [type: :integer, doc: "Maximum number of links to return"],- location: [type: :keyword_list, doc: "Location settings for the request. When specified, this will use an appropriate proxy if available and emulate the corresponding language and timezone settings. Defaults to 'US' if not specified."],- search: [type: :string, doc: "Specify a search query to order the results by relevance. Example: 'blog' will return URLs that contain the word 'blog' in the URL ordered by relevance."],- sitemap: [type: {:or, [{:in, [:skip, :include, :only]}, :string]}, doc: "Sitemap mode when mapping. If you set it to `skip`, the sitemap won't be used to find URLs. If you set it to `only`, only URLs that are in the sitemap will be returned. By default (`include`), the sitemap and other methods will be used together to find URLs."],- timeout: [type: :integer, doc: "Timeout in milliseconds. There is no timeout by default."],- url: [type: :string, required: true, doc: "The base URL to start crawling from"]- ])-- @map_urls_key_mapping %{audit_metadata: "auditMetadata", ignore_cache: "ignoreCache", ignore_query_parameters: "ignoreQueryParameters", include_subdomains: "includeSubdomains", limit: "limit", location: "location", search: "search", sitemap: "sitemap", timeout: "timeout", url: "url"}-@doc """- Map multiple URLs based on options-- `POST /map`-- Tag: Mapping+ Get the team's threat protection policy- ## Parameters+ `GET /team/threat-protection`- Validated by `NimbleOptions`. Pass params as a keyword list with snake_case keys.- See `@map_urls_schema` for the full schema.+ Tag: Threat Protection## Returns* `{:ok, %Req.Response{}}` on success* `{:error, exception}` on HTTP or validation failure"""- @spec map_urls(keyword(), keyword()) :: response()- def map_urls(params \\ [], opts \\ []) do- with {:ok, params} <- NimbleOptions.validate(params, @map_urls_schema) do- Req.post(client(opts), url: "/map", json: to_body(params, @map_urls_key_mapping))- end+ @spec get_threat_protection(keyword()) :: response()+ def get_threat_protection(opts \\ []) do+ Req.get(client(opts), url: "/team/threat-protection")end@doc """- Bang variant of `map_urls`. Raises on error.+ Bang variant of `get_threat_protection`. Raises on error."""- @spec map_urls!(keyword(), keyword()) :: Req.Response.t()- def map_urls!(params \\ [], opts \\ []) do- params = NimbleOptions.validate!(params, @map_urls_schema)- Req.post!(client(opts), url: "/map", json: to_body(params, @map_urls_key_mapping))+ @spec get_threat_protection!(keyword()) :: Req.Response.t()+ def get_threat_protection!(opts \\ []) do+ Req.get!(client(opts), url: "/team/threat-protection")end- @parse_file_schema NimbleOptions.new!([- audit_metadata: [type: :keyword_list, keys: [username: [type: :string, required: true]], doc: "User attribution to include with SIEM logging events."],- block_ads: [type: :boolean, doc: "Enable ad and cookie popup blocking."],- exclude_tags: [type: {:list, :string}, doc: "Tags to exclude from the output."],- formats: [type: {:list, :any}, doc: "Output formats supported for `/parse` uploads. Browser-rendering formats and change tracking are not supported."],- headers: [type: :any, doc: "Headers to send when additional network requests are required."],- include_tags: [type: {:list, :string}, doc: "Tags to include in the output."],- integration: [type: :string, doc: "Optional integration identifier."],- only_main_content: [type: :boolean, doc: "Only return the main content of the page excluding headers, navs, footers, etc."],- origin: [type: :string, doc: "Origin identifier for analytics and logging."],- parsers: [type: {:list, :any}, doc: "Controls file parser behavior when relevant (for example PDF parser mode)."],- proxy: [type: {:or, [{:in, [:basic, :auto]}, :string]}, doc: "Proxy mode for parse uploads. `/parse` supports only `basic` and `auto`."],- redact_pii: [type: :boolean, doc: "Redact personally identifiable information from returned content."],- remove_base64_images: [type: :boolean, doc: "Remove base64-encoded images from output and keep alt text placeholders."],- skip_tls_verification: [type: :boolean, doc: "Skip TLS certificate verification when making requests."],- timeout: [type: :integer, doc: "Timeout in milliseconds for the request. Default is 30000 (30 seconds). Maximum is 300000 (300 seconds)."],- zero_data_retention: [type: :boolean, doc: "If true, this will enable zero data retention for this parse. To enable this feature, please contact [email protected]"]+ @interact_with_scrape_browser_session_schema NimbleOptions.new!([+ code: [type: :string, required: true, doc: "Code to execute in the scrape-bound browser sandbox"],+ language: [type: {:or, [{:in, [:python, :node, :bash]}, :string]}, doc: "Language of the code to execute. Use `node` for JavaScript or `bash` for agent-browser CLI commands."],+ origin: [type: :string, doc: "Optional origin label used for execution telemetry"],+ timeout: [type: :integer, doc: "Execution timeout in seconds"]])- @parse_file_key_mapping %{audit_metadata: "auditMetadata", block_ads: "blockAds", exclude_tags: "excludeTags", formats: "formats", headers: "headers", include_tags: "includeTags", integration: "integration", only_main_content: "onlyMainContent", origin: "origin", parsers: "parsers", proxy: "proxy", redact_pii: "redactPII", remove_base64_images: "removeBase64Images", skip_tls_verification: "skipTlsVerification", timeout: "timeout", zero_data_retention: "zeroDataRetention"}+ @interact_with_scrape_browser_session_key_mapping %{code: "code", language: "language", origin: "origin", timeout: "timeout"}@doc """- Upload and parse a file-- `POST /parse`+ Interact with the browser session associated with a scrape job- Sends a `multipart/form-data` request.+ `POST /scrape/{jobId}/interact`Tag: Scraping- ## File-- Pass `file` as a keyword list:+ ## Path Parameters- * `:filename` (required) - The filename to send.- * `:data` (required) - The file contents as a binary.- * `:content_type` (optional) - The MIME type of the file.+ * `job_id` - Path parameter `jobId`## Parameters- Validated by `NimbleOptions`. Pass options as a keyword list with snake_case keys.- These are JSON-encoded and sent as the `options` multipart field.- See `@parse_file_schema` for the full schema.+ Validated by `NimbleOptions`. Pass params as a keyword list with snake_case keys.+ See `@interact_with_scrape_browser_session_schema` for the full schema.## Returns* `{:ok, %Req.Response{}}` on success* `{:error, exception}` on HTTP or validation failure"""- @spec parse_file(keyword(), keyword(), keyword()) :: response()- def parse_file(file, params \\ [], opts \\ []) do- with {:ok, params} <- NimbleOptions.validate(params, @parse_file_schema),- {:ok, filename} <- fetch_file_field(file, :filename),- :ok <- validate_filename(filename),- {:ok, data} <- fetch_file_field(file, :data),- :ok <- validate_data(data) do- content_type = Keyword.get(file, :content_type)-- file_part =- case content_type do- nil -> {data, filename: filename}- ct -> {data, filename: filename, content_type: ct}- end-- multipart = [{"options", Jason.encode!(to_body(params, @parse_file_key_mapping))}, {"file", file_part}]-- Req.post(client(opts), url: "/parse", form_multipart: multipart)+ @spec interact_with_scrape_browser_session(String.t(), keyword(), keyword()) :: response()+ def interact_with_scrape_browser_session(job_id, params \\ [], opts \\ []) do+ with {:ok, params} <- NimbleOptions.validate(params, @interact_with_scrape_browser_session_schema) do+ Req.post(client(opts), url: "/scrape/#{job_id}/interact", json: to_body(params, @interact_with_scrape_browser_session_key_mapping))endend@doc """- Bang variant of `parse_file`. Raises on error.+ Bang variant of `interact_with_scrape_browser_session`. Raises on error."""- @spec parse_file!(keyword(), keyword(), keyword()) :: Req.Response.t()- def parse_file!(file, params \\ [], opts \\ []) do- params = NimbleOptions.validate!(params, @parse_file_schema)- filename = Keyword.fetch!(file, :filename)- data = Keyword.fetch!(file, :data)- content_type = Keyword.get(file, :content_type)-- if not is_binary(filename) or filename == "" do- raise ArgumentError, "filename cannot be empty"- end-- if is_nil(data) do- raise ArgumentError, "file data cannot be empty"- end-- file_part =- case content_type do- nil -> {data, filename: filename}- ct -> {data, filename: filename, content_type: ct}- end-- multipart = [{"options", Jason.encode!(to_body(params, @parse_file_key_mapping))}, {"file", file_part}]-- Req.post!(client(opts), url: "/parse", form_multipart: multipart)- end--- @scrape_and_extract_from_url_schema NimbleOptions.new!([- url: [type: :string, required: true, doc: "The URL to scrape"],- audit_metadata: [type: :keyword_list, keys: [username: [type: :string, required: true]], doc: "User attribution to include with SIEM logging events."],- actions: [type: {:list, :any}, doc: "Actions to perform on the page before grabbing the content"],- block_ads: [type: :boolean, doc: "Enables ad-blocking and cookie popup blocking."],- exclude_tags: [type: {:list, :string}, doc: "Tags to exclude from the output."],- formats: [type: {:list, :any}, doc: "Output formats to include in the response. You can specify one or more formats, either as strings (e.g., `'markdown'`) or as objects with additional options (e.g., `{ type: 'json', schema: {...}, check_prompt_injection: true }`, `{ type: 'question', question: '...' }`, `{ type: 'highlights', query: '...' }`). For the `json` format, set `check_prompt_injection: true` (serialized as `checkPromptInjection`) to run a prompt-injection safety check on the scraped page content before extraction runs; it defaults to false. The legacy `{ type: 'query', prompt: '...', mode: 'freeform' | 'directQuote' }` format is deprecated."],- headers: [type: :any, doc: "Headers to send with the request. Can be used to send cookies, user-agent, etc."],- include_tags: [type: {:list, :string}, doc: "Tags to include in the output."],- location: [type: :keyword_list, doc: "Location settings for the request. When specified, this will use an appropriate proxy if available and emulate the corresponding language and timezone settings. Defaults to 'US' if not specified."],- max_age: [type: :integer, doc: "Returns a cached version of the page if it is younger than this age in milliseconds. If a cached version of the page is older than this value, the page will be scraped. If you do not need extremely fresh data, enabling this can speed up your scrapes by 500%. Defaults to 2 days."],- min_age: [type: :integer, doc: "When set, the request only checks the cache and never triggers a fresh scrape. The value is in milliseconds and specifies the minimum age the cached data must be. If matching cached data exists, it is returned instantly. If no cached data is found, a 404 with error code SCRAPE_NO_CACHED_DATA is returned. Set to 1 to accept any cached data regardless of age."],- mobile: [type: :boolean, doc: "Set to true if you want to emulate scraping from a mobile device. Useful for testing responsive pages and taking mobile screenshots."],- only_main_content: [type: :boolean, doc: "Only return the main content of the page excluding headers, navs, footers, etc."],- parsers: [type: {:list, :any}, doc: "Controls how files are processed during scraping. When \"pdf\" is included (default), the PDF content is extracted and converted to markdown format, with billing based on the number of pages (1 credit per page). When an empty array is passed, the PDF file is returned in base64 encoding with a flat rate of 1 credit for the entire PDF."],- profile: [type: :keyword_list, doc: "Enable persistent browser storage across scrape and interact sessions. Pass a profile when scraping to preserve cookies, localStorage, and session data. Sessions with the same profile name share browser state."],- proxy: [type: {:in, [:basic, :enhanced, :auto]}, doc: "Specifies the type of proxy to use.\n\n - **basic**: Proxies for scraping sites with none to basic anti-bot solutions. Fast and usually works.\n - **enhanced**: Enhanced proxies for scraping sites with advanced anti-bot solutions. Slower, but more reliable on certain sites. Billed at the same credit cost as basic.\n - **auto**: Firecrawl will automatically retry scraping with enhanced proxies if the basic proxy fails. Enhanced proxies carry no credit surcharge, so either way only the regular cost is billed."],- redact_pii: [type: :boolean, doc: "Redact personally identifiable information from returned content."],- remove_base64_images: [type: :boolean, doc: "Removes all base 64 images from the markdown output, which may be overwhelmingly long. This does not affect html or rawHtml formats. The image's alt text remains in the output, but the URL is replaced with a placeholder."],- skip_tls_verification: [type: :boolean, doc: "Skip TLS certificate verification when making requests."],- store_in_cache: [type: :boolean, doc: "If true, the page will be stored in the Firecrawl index and cache. Setting this to false is useful if your scraping activity may have data protection concerns. Using some parameters associated with sensitive scraping (e.g. actions, headers) will force this parameter to be false."],- lockdown: [type: :boolean, doc: "If true, only previously cached results are served and no outbound request is ever made. If nothing is cached for the URL, a 404 with error code SCRAPE_LOCKDOWN_CACHE_MISS is returned. Other options are accepted but ignored in lockdown mode."],- timeout: [type: :integer, doc: "Timeout in milliseconds for the request. Minimum is 1000 (1 second). Default is 60000 (60 seconds). Maximum is 300000 (300 seconds)."],- wait_for: [type: :integer, doc: "Specify a delay in milliseconds before fetching the content, allowing the page sufficient time to load. This waiting time is in addition to Firecrawl's smart wait feature."],- zero_data_retention: [type: :boolean, doc: "If true, this will enable zero data retention for this scrape. To enable this feature, please contact [email protected]"]+ @spec interact_with_scrape_browser_session!(String.t(), keyword(), keyword()) :: Req.Response.t()+ def interact_with_scrape_browser_session!(job_id, params \\ [], opts \\ []) do+ params = NimbleOptions.validate!(params, @interact_with_scrape_browser_session_schema)+ Req.post!(client(opts), url: "/scrape/#{job_id}/interact", json: to_body(params, @interact_with_scrape_browser_session_key_mapping))+ end+++ @list_agents_query_schema NimbleOptions.new!([+ before: [type: :integer, doc: "Only return agent runs created before this unix millisecond timestamp. Pages are fixed at 20 runs; use the `before` value from the previous page's `next` URL to fetch the next page."]])- @scrape_and_extract_from_url_key_mapping %{url: "url", audit_metadata: "auditMetadata", actions: "actions", block_ads: "blockAds", exclude_tags: "excludeTags", formats: "formats", headers: "headers", include_tags: "includeTags", location: "location", max_age: "maxAge", min_age: "minAge", mobile: "mobile", only_main_content: "onlyMainContent", parsers: "parsers", profile: "profile", proxy: "proxy", redact_pii: "redactPII", remove_base64_images: "removeBase64Images", skip_tls_verification: "skipTlsVerification", store_in_cache: "storeInCache", lockdown: "lockdown", timeout: "timeout", wait_for: "waitFor", zero_data_retention: "zeroDataRetention"}+ @list_agents_query_key_mapping %{before: "before"}@doc """- Scrape a single URL and optionally extract information using an LLM+ List agent runs- `POST /scrape`+ `GET /agent`- Tag: Scraping+ Tag: Agent- ## Parameters+ ## Query Parameters- Validated by `NimbleOptions`. Pass params as a keyword list with snake_case keys.- See `@scrape_and_extract_from_url_schema` for the full schema.+ * `before` — query parameter `before`## Returns* `{:ok, %Req.Response{}}` on success* `{:error, exception}` on HTTP or validation failure"""- @spec scrape_and_extract_from_url(keyword(), keyword()) :: response()- def scrape_and_extract_from_url(params \\ [], opts \\ []) do- with {:ok, params} <- NimbleOptions.validate(params, @scrape_and_extract_from_url_schema) do- Req.post(client(opts), url: "/scrape", json: to_body(params, @scrape_and_extract_from_url_key_mapping))+ @spec list_agents(keyword(), keyword()) :: response()+ def list_agents(params \\ [], opts \\ []) do+ with {:ok, params} <- NimbleOptions.validate(params, @list_agents_query_schema) do+ Req.get(client(opts), url: "/agent", params: to_query(params, @list_agents_query_key_mapping))endend@doc """- Bang variant of `scrape_and_extract_from_url`. Raises on error.+ Bang variant of `list_agents`. Raises on error."""- @spec scrape_and_extract_from_url!(keyword(), keyword()) :: Req.Response.t()- def scrape_and_extract_from_url!(params \\ [], opts \\ []) do- params = NimbleOptions.validate!(params, @scrape_and_extract_from_url_schema)- Req.post!(client(opts), url: "/scrape", json: to_body(params, @scrape_and_extract_from_url_key_mapping))+ @spec list_agents!(keyword(), keyword()) :: Req.Response.t()+ def list_agents!(params \\ [], opts \\ []) do+ params = NimbleOptions.validate!(params, @list_agents_query_schema)+ Req.get!(client(opts), url: "/agent", params: to_query(params, @list_agents_query_key_mapping))end- @scrape_and_extract_from_urls_schema NimbleOptions.new!([- audit_metadata: [type: :keyword_list, keys: [username: [type: :string, required: true]], doc: "User attribution to include with SIEM logging events."],- ignore_invalid_urls: [type: :boolean, doc: "If invalid URLs are specified in the urls array, they will be ignored. Instead of them failing the entire request, a batch scrape using the remaining valid URLs will be created, and the invalid URLs will be returned in the invalidURLs field of the response."],- max_concurrency: [type: :integer, doc: "Maximum number of concurrent scrapes. This parameter allows you to set a concurrency limit for this batch scrape. If not specified, the batch scrape adheres to your team's concurrency limit."],- urls: [type: {:list, :string}, required: true],- webhook: [type: :keyword_list, doc: "A webhook specification object."],- actions: [type: {:list, :any}, doc: "Actions to perform on the page before grabbing the content"],- block_ads: [type: :boolean, doc: "Enables ad-blocking and cookie popup blocking."],- exclude_tags: [type: {:list, :string}, doc: "Tags to exclude from the output."],- formats: [type: {:list, :any}, doc: "Output formats to include in the response. You can specify one or more formats, either as strings (e.g., `'markdown'`) or as objects with additional options (e.g., `{ type: 'json', schema: {...}, check_prompt_injection: true }`, `{ type: 'question', question: '...' }`, `{ type: 'highlights', query: '...' }`). For the `json` format, set `check_prompt_injection: true` (serialized as `checkPromptInjection`) to run a prompt-injection safety check on the scraped page content before extraction runs; it defaults to false. The legacy `{ type: 'query', prompt: '...', mode: 'freeform' | 'directQuote' }` format is deprecated."],- headers: [type: :any, doc: "Headers to send with the request. Can be used to send cookies, user-agent, etc."],- include_tags: [type: {:list, :string}, doc: "Tags to include in the output."],- location: [type: :keyword_list, doc: "Location settings for the request. When specified, this will use an appropriate proxy if available and emulate the corresponding language and timezone settings. Defaults to 'US' if not specified."],- max_age: [type: :integer, doc: "Returns a cached version of the page if it is younger than this age in milliseconds. If a cached version of the page is older than this value, the page will be scraped. If you do not need extremely fresh data, enabling this can speed up your scrapes by 500%. Defaults to 2 days."],- min_age: [type: :integer, doc: "When set, the request only checks the cache and never triggers a fresh scrape. The value is in milliseconds and specifies the minimum age the cached data must be. If matching cached data exists, it is returned instantly. If no cached data is found, a 404 with error code SCRAPE_NO_CACHED_DATA is returned. Set to 1 to accept any cached data regardless of age."],- mobile: [type: :boolean, doc: "Set to true if you want to emulate scraping from a mobile device. Useful for testing responsive pages and taking mobile screenshots."],- only_main_content: [type: :boolean, doc: "Only return the main content of the page excluding headers, navs, footers, etc."],- parsers: [type: {:list, :any}, doc: "Controls how files are processed during scraping. When \"pdf\" is included (default), the PDF content is extracted and converted to markdown format, with billing based on the number of pages (1 credit per page). When an empty array is passed, the PDF file is returned in base64 encoding with a flat rate of 1 credit for the entire PDF."],- profile: [type: :keyword_list, doc: "Enable persistent browser storage across scrape and interact sessions. Pass a profile when scraping to preserve cookies, localStorage, and session data. Sessions with the same profile name share browser state."],- proxy: [type: {:in, [:basic, :enhanced, :auto]}, doc: "Specifies the type of proxy to use.\n\n - **basic**: Proxies for scraping sites with none to basic anti-bot solutions. Fast and usually works.\n - **enhanced**: Enhanced proxies for scraping sites with advanced anti-bot solutions. Slower, but more reliable on certain sites. Billed at the same credit cost as basic.\n - **auto**: Firecrawl will automatically retry scraping with enhanced proxies if the basic proxy fails. Enhanced proxies carry no credit surcharge, so either way only the regular cost is billed."],- redact_pii: [type: :boolean, doc: "Redact personally identifiable information from returned content."],- remove_base64_images: [type: :boolean, doc: "Removes all base 64 images from the markdown output, which may be overwhelmingly long. This does not affect html or rawHtml formats. The image's alt text remains in the output, but the URL is replaced with a placeholder."],- skip_tls_verification: [type: :boolean, doc: "Skip TLS certificate verification when making requests."],- store_in_cache: [type: :boolean, doc: "If true, the page will be stored in the Firecrawl index and cache. Setting this to false is useful if your scraping activity may have data protection concerns. Using some parameters associated with sensitive scraping (e.g. actions, headers) will force this parameter to be false."],- lockdown: [type: :boolean, doc: "If true, only previously cached results are served and no outbound request is ever made. If nothing is cached for the URL, a 404 with error code SCRAPE_LOCKDOWN_CACHE_MISS is returned. Other options are accepted but ignored in lockdown mode."],- timeout: [type: :integer, doc: "Timeout in milliseconds for the request. Minimum is 1000 (1 second). Default is 60000 (60 seconds). Maximum is 300000 (300 seconds)."],- wait_for: [type: :integer, doc: "Specify a delay in milliseconds before fetching the content, allowing the page sufficient time to load. This waiting time is in addition to Firecrawl's smart wait feature."],- zero_data_retention: [type: :boolean, doc: "If true, this will enable zero data retention for this batch scrape. To enable this feature, please contact [email protected]"]+ @list_browser_sessions_query_schema NimbleOptions.new!([+ status: [type: {:or, [{:in, [:active, :destroyed]}, :string]}, doc: "Filter sessions by status"]])- @scrape_and_extract_from_urls_key_mapping %{audit_metadata: "auditMetadata", ignore_invalid_urls: "ignoreInvalidURLs", max_concurrency: "maxConcurrency", urls: "urls", webhook: "webhook", actions: "actions", block_ads: "blockAds", exclude_tags: "excludeTags", formats: "formats", headers: "headers", include_tags: "includeTags", location: "location", max_age: "maxAge", min_age: "minAge", mobile: "mobile", only_main_content: "onlyMainContent", parsers: "parsers", profile: "profile", proxy: "proxy", redact_pii: "redactPII", remove_base64_images: "removeBase64Images", skip_tls_verification: "skipTlsVerification", store_in_cache: "storeInCache", lockdown: "lockdown", timeout: "timeout", wait_for: "waitFor", zero_data_retention: "zeroDataRetention"}+ @list_browser_sessions_query_key_mapping %{status: "status"}@doc """- Scrape multiple URLs and optionally extract information using an LLM+ List interact sessions- `POST /batch/scrape`+ `GET /interact`- Tag: Scraping+ Tag: Interact- ## Parameters+ ## Query Parameters- Validated by `NimbleOptions`. Pass params as a keyword list with snake_case keys.- See `@scrape_and_extract_from_urls_schema` for the full schema.+ * `status` — query parameter `status`## Returns* `{:ok, %Req.Response{}}` on success* `{:error, exception}` on HTTP or validation failure"""- @spec scrape_and_extract_from_urls(keyword(), keyword()) :: response()- def scrape_and_extract_from_urls(params \\ [], opts \\ []) do- with {:ok, params} <- NimbleOptions.validate(params, @scrape_and_extract_from_urls_schema) do- Req.post(client(opts), url: "/batch/scrape", json: to_body(params, @scrape_and_extract_from_urls_key_mapping))+ @spec list_browser_sessions(keyword(), keyword()) :: response()+ def list_browser_sessions(params \\ [], opts \\ []) do+ with {:ok, params} <- NimbleOptions.validate(params, @list_browser_sessions_query_schema) do+ Req.get(client(opts), url: "/interact", params: to_query(params, @list_browser_sessions_query_key_mapping))endend@doc """- Bang variant of `scrape_and_extract_from_urls`. Raises on error.+ Bang variant of `list_browser_sessions`. Raises on error."""- @spec scrape_and_extract_from_urls!(keyword(), keyword()) :: Req.Response.t()- def scrape_and_extract_from_urls!(params \\ [], opts \\ []) do- params = NimbleOptions.validate!(params, @scrape_and_extract_from_urls_schema)- Req.post!(client(opts), url: "/batch/scrape", json: to_body(params, @scrape_and_extract_from_urls_key_mapping))+ @spec list_browser_sessions!(keyword(), keyword()) :: Req.Response.t()+ def list_browser_sessions!(params \\ [], opts \\ []) do+ params = NimbleOptions.validate!(params, @list_browser_sessions_query_schema)+ Req.get!(client(opts), url: "/interact", params: to_query(params, @list_browser_sessions_query_key_mapping))end- @search_and_scrape_schema NimbleOptions.new!([- categories: [type: {:list, :any}, doc: "Categories to filter results by. Defaults to [], which means results will not be filtered by any categories."],- country: [type: :string, doc: "ISO country code for geo-targeting search results (e.g. `US`). For best results, set both this and the `location` parameter."],- enterprise: [type: {:list, :string}, doc: "Enterprise search options for Zero Data Retention (ZDR). Use `[\"zdr\"]` for end-to-end ZDR (10 credits / 10 results) or `[\"anon\"]` for anonymized ZDR (2 credits / 10 results). Must be enabled for your team."],- exclude_domains: [type: {:list, :string}, doc: "Domains to exclude from search results."],- ignore_invalid_urls: [type: :boolean, doc: "Excludes URLs from the search results that are invalid for other Firecrawl endpoints. This helps reduce errors if you are piping data from search into other Firecrawl API endpoints."],- highlights: [type: :boolean, doc: "Generate query-relevant highlights for search results. Defaults to true."],- include_domains: [type: {:list, :string}, doc: "Domains to include in search results."],- limit: [type: :integer, doc: "Maximum number of results to return"],- location: [type: :string, doc: "Location parameter for search results (e.g. `San Francisco,California,United States`). For best results, set both this and the `country` parameter."],- query: [type: :string, required: true, doc: "The search query"],- scrape_options: [type: :keyword_list, doc: "Options for scraping search results"],- sources: [type: {:list, :any}, doc: "Sources to search. Will determine the arrays available in the response. Defaults to ['web']."],- tbs: [type: :string, doc: "Time-based search parameter. Supports predefined time ranges (`qdr:h`, `qdr:d`, `qdr:w`, `qdr:m`, `qdr:y`), custom date ranges (`cdr:1,cd_min:MM/DD/YYYY,cd_max:MM/DD/YYYY`), and sort by date (`sbd:1`). Values can be combined, e.g. `sbd:1,qdr:w`."],- timeout: [type: :integer, doc: "Timeout in milliseconds"]+ @map_urls_schema NimbleOptions.new!([+ audit_metadata: [type: :keyword_list, keys: [username: [type: :string, required: true]], doc: "User attribution included with SIEM logging events when SIEM Logging is enabled for the organization."],+ ignore_cache: [type: :boolean, doc: "Bypass the sitemap cache to retrieve fresh URLs. Sitemap data is cached for up to 7 days; use this parameter when your sitemap has been recently updated."],+ ignore_query_parameters: [type: :boolean, doc: "Do not return URLs with query parameters"],+ include_subdomains: [type: :boolean, doc: "Include subdomains of the website"],+ limit: [type: :integer, doc: "Maximum number of links to return"],+ location: [type: :keyword_list, doc: "Location settings for the request. When specified, this will use an appropriate proxy if available and emulate the corresponding language and timezone settings. Defaults to 'US' if not specified."],+ search: [type: :string, doc: "Specify a search query to order the results by relevance. Example: 'blog' will return URLs that contain the word 'blog' in the URL ordered by relevance."],+ sitemap: [type: {:or, [{:in, [:skip, :include, :only]}, :string]}, doc: "Sitemap mode when mapping. If you set it to `skip`, the sitemap won't be used to find URLs. If you set it to `only`, only URLs that are in the sitemap will be returned. By default (`include`), the sitemap and other methods will be used together to find URLs."],+ threat_protection: [type: :keyword_list, doc: "Per-request [Threat Protection](https://docs.firecrawl.dev/features/threat-protection) override. Fields you provide replace the corresponding fields of your organization's policy for this request only; omitted fields keep their organization-level values. Requires Threat Protection to be enabled for your team (enterprise feature) — otherwise the request is rejected with a 403. If your organization has disabled request overrides, any request that includes this object is rejected with a 403. If Threat Protection is enforced for your team, `mode` may not be set to `off`."],+ timeout: [type: :integer, doc: "Timeout in milliseconds. There is no timeout by default."],+ url: [type: :string, required: true, doc: "The base URL to start crawling from"]])- @search_and_scrape_key_mapping %{categories: "categories", country: "country", enterprise: "enterprise", exclude_domains: "excludeDomains", highlights: "highlights", ignore_invalid_urls: "ignoreInvalidURLs", include_domains: "includeDomains", limit: "limit", location: "location", query: "query", scrape_options: "scrapeOptions", sources: "sources", tbs: "tbs", timeout: "timeout"}+ @map_urls_key_mapping %{audit_metadata: "auditMetadata", ignore_cache: "ignoreCache", ignore_query_parameters: "ignoreQueryParameters", include_subdomains: "includeSubdomains", limit: "limit", location: "location", search: "search", sitemap: "sitemap", threat_protection: "threatProtection", timeout: "timeout", url: "url"}@doc """- Search and optionally scrape search results+ Map multiple URLs based on options- `POST /search`+ `POST /map`- Tag: Search+ Tag: Mapping## ParametersValidated by `NimbleOptions`. Pass params as a keyword list with snake_case keys.- See `@search_and_scrape_schema` for the full schema.+ See `@map_urls_schema` for the full schema.## Returns* `{:ok, %Req.Response{}}` on success* `{:error, exception}` on HTTP or validation failure"""- @spec search_and_scrape(keyword(), keyword()) :: response()- def search_and_scrape(params \\ [], opts \\ []) do- with {:ok, params} <- NimbleOptions.validate(params, @search_and_scrape_schema) do- Req.post(client(opts), url: "/search", json: to_body(params, @search_and_scrape_key_mapping))+ @spec map_urls(keyword(), keyword()) :: response()+ def map_urls(params \\ [], opts \\ []) do+ with {:ok, params} <- NimbleOptions.validate(params, @map_urls_schema) do+ Req.post(client(opts), url: "/map", json: to_body(params, @map_urls_key_mapping))endend@doc """- Bang variant of `search_and_scrape`. Raises on error.+ Bang variant of `map_urls`. Raises on error."""- @spec search_and_scrape!(keyword(), keyword()) :: Req.Response.t()- def search_and_scrape!(params \\ [], opts \\ []) do- params = NimbleOptions.validate!(params, @search_and_scrape_schema)- Req.post!(client(opts), url: "/search", json: to_body(params, @search_and_scrape_key_mapping))+ @spec map_urls!(keyword(), keyword()) :: Req.Response.t()+ def map_urls!(params \\ [], opts \\ []) do+ params = NimbleOptions.validate!(params, @map_urls_schema)+ Req.post!(client(opts), url: "/map", json: to_body(params, @map_urls_key_mapping))end- @research_search_papers_schema NimbleOptions.new!([- authors: [type: {:list, :string}],- categories: [type: {:list, :string}],- from: [type: :string],- k: [type: :integer],- query: [type: :string, required: true],- to: [type: :string]++ @parse_file_schema NimbleOptions.new!([+ audit_metadata: [type: :keyword_list, keys: [username: [type: :string, required: true]], doc: "User attribution included with SIEM logging events when SIEM Logging is enabled for the organization."],+ block_ads: [type: :boolean, doc: "Enable ad and cookie popup blocking."],+ exclude_tags: [type: {:list, :string}, doc: "Tags to exclude from the output."],+ formats: [type: {:list, :any}, doc: "Output formats supported for `/parse` uploads. Browser-rendering formats and change tracking are not supported."],+ headers: [type: :any, doc: "Headers to send when additional network requests are required."],+ include_tags: [type: {:list, :string}, doc: "Tags to include in the output."],+ integration: [type: :string, doc: "Optional integration identifier."],+ only_main_content: [type: :boolean, doc: "Only return the main content of the page excluding headers, navs, footers, etc."],+ origin: [type: :string, doc: "Origin identifier for analytics and logging."],+ parsers: [type: {:list, :any}, doc: "Controls file parser behavior when relevant (for example PDF parser mode)."],+ proxy: [type: {:or, [{:in, [:basic, :auto]}, :string]}, doc: "Proxy mode for parse uploads. `/parse` supports only `basic` and `auto`."],+ redact_pii: [type: :any, doc: "Redact personally identifiable information from returned markdown. Pass `true` to use defaults, or an object to tune mode, entities, and replacement style."],+ remove_base64_images: [type: :boolean, doc: "Remove base64-encoded images from output and keep alt text placeholders."],+ skip_tls_verification: [type: :boolean, doc: "Skip TLS certificate verification when making requests."],+ timeout: [type: :integer, doc: "Timeout in milliseconds for the request. Default is 30000 (30 seconds). Maximum is 300000 (300 seconds)."],+ zero_data_retention: [type: :boolean, doc: "If true, this will enable zero data retention for this parse. To enable this feature, please contact [email protected]"]])- @research_search_papers_key_mapping %{authors: "authors", categories: "categories", from: "from", k: "k", query: "query", to: "to"}+ @parse_file_key_mapping %{audit_metadata: "auditMetadata", block_ads: "blockAds", exclude_tags: "excludeTags", formats: "formats", headers: "headers", include_tags: "includeTags", integration: "integration", only_main_content: "onlyMainContent", origin: "origin", parsers: "parsers", proxy: "proxy", redact_pii: "redactPII", remove_base64_images: "removeBase64Images", skip_tls_verification: "skipTlsVerification", timeout: "timeout", zero_data_retention: "zeroDataRetention"}@doc """- Search research papers.+ Upload and parse a file- `GET /search/research/papers`- """- @spec search_papers(keyword(), keyword()) :: response()- def search_papers(params \\ [], opts \\ []) do- with {:ok, params} <- NimbleOptions.validate(params, @research_search_papers_schema) do- Req.get(client(opts), url: "/search/research/papers", params: [{"origin", @sdk_origin} | to_query(params, @research_search_papers_key_mapping)])- end- end+ `POST /parse`- @doc """- Bang variant of `search_papers`. Raises on error.- """- @spec search_papers!(keyword(), keyword()) :: Req.Response.t()- def search_papers!(params \\ [], opts \\ []) do- params = NimbleOptions.validate!(params, @research_search_papers_schema)- Req.get!(client(opts), url: "/search/research/papers", params: [{"origin", @sdk_origin} | to_query(params, @research_search_papers_key_mapping)])- end+ Sends a `multipart/form-data` request.- @doc """- Inspect paper metadata.+ Tag: Scraping- `GET /search/research/papers/{id}`- """- @spec inspect_paper(String.t(), keyword()) :: response()- def inspect_paper(id, opts \\ []) do- Req.get(client(opts),- url: "/search/research/papers/#{URI.encode_www_form(id)}",- params: [{"origin", @sdk_origin}]- )- end+ ## File- @doc """- Bang variant of `inspect_paper`. Raises on error.- """- @spec inspect_paper!(String.t(), keyword()) :: Req.Response.t()- def inspect_paper!(id, opts \\ []) do- Req.get!(client(opts),- url: "/search/research/papers/#{URI.encode_www_form(id)}",- params: [{"origin", @sdk_origin}]- )- end+ Pass `file` as a keyword list:- @research_read_paper_schema NimbleOptions.new!([- k: [type: :integer],- query: [type: :string, required: true]- ])+ * `:filename` (required) - The filename to send.+ * `:data` (required) - The file contents as a binary.+ * `:content_type` (optional) - The MIME type of the file.- @research_read_paper_key_mapping %{k: "k", query: "query"}+ ## Parameters- @doc """- Read a paper with query-guided passages.+ Validated by `NimbleOptions`. Pass options as a keyword list with snake_case keys.+ These are JSON-encoded and sent as the `options` multipart field.+ See `@parse_file_schema` for the full schema.- `GET /search/research/papers/{id}`- """- @spec read_paper(String.t(), keyword(), keyword()) :: response()- def read_paper(id, params \\ [], opts \\ []) do- with {:ok, params} <- NimbleOptions.validate(params, @research_read_paper_schema) do- Req.get(client(opts), url: "/search/research/papers/#{URI.encode_www_form(id)}", params: [{"origin", @sdk_origin} | to_query(params, @research_read_paper_key_mapping)])- end- end+ ## Returns- @doc """- Bang variant of `read_paper`. Raises on error.+ * `{:ok, %Req.Response{}}` on success+ * `{:error, exception}` on HTTP or validation failure"""- @spec read_paper!(String.t(), keyword(), keyword()) :: Req.Response.t()- def read_paper!(id, params \\ [], opts \\ []) do- params = NimbleOptions.validate!(params, @research_read_paper_schema)- Req.get!(client(opts), url: "/search/research/papers/#{URI.encode_www_form(id)}", params: [{"origin", @sdk_origin} | to_query(params, @research_read_paper_key_mapping)])- end-- @research_related_papers_schema NimbleOptions.new!([- anchor: [type: {:list, :string}],- intent: [type: :string, required: true],- k: [type: :integer],- mode: [type: {:in, [:similar, :citers, :references, "similar", "citers", "references"]}],- rerank: [type: :boolean]- ])-- @research_related_papers_key_mapping %{anchor: "anchor", intent: "intent", k: "k", mode: "mode", rerank: "rerank"}+ @spec parse_file(keyword(), keyword(), keyword()) :: response()+ def parse_file(file, params \\ [], opts \\ []) do+ with {:ok, params} <- NimbleOptions.validate(params, @parse_file_schema),+ {:ok, filename} <- fetch_file_field(file, :filename),+ :ok <- validate_filename(filename),+ {:ok, data} <- fetch_file_field(file, :data),+ :ok <- validate_data(data) do+ content_type = Keyword.get(file, :content_type)- @doc """- Find papers related to a paper.+ file_part =+ case content_type do+ nil -> {data, filename: filename}+ ct -> {data, filename: filename, content_type: ct}+ end- `GET /search/research/papers/{id}/similar`- """- @spec related_papers(String.t(), keyword(), keyword()) :: response()- def related_papers(id, params \\ [], opts \\ []) do- with {:ok, params} <- NimbleOptions.validate(params, @research_related_papers_schema) do- Req.get(client(opts), url: "/search/research/papers/#{URI.encode_www_form(id)}/similar", params: [{"origin", @sdk_origin} | to_query(params, @research_related_papers_key_mapping)])+ multipart = [{"options", Jason.encode!(to_body(params, @parse_file_key_mapping))}, {"file", file_part}]++ Req.post(client(opts), url: "/parse", form_multipart: multipart)endend+@doc """- Bang variant of `related_papers`. Raises on error.+ Bang variant of `parse_file`. Raises on error."""- @spec related_papers!(String.t(), keyword(), keyword()) :: Req.Response.t()- def related_papers!(id, params \\ [], opts \\ []) do- params = NimbleOptions.validate!(params, @research_related_papers_schema)- Req.get!(client(opts), url: "/search/research/papers/#{URI.encode_www_form(id)}/similar", params: [{"origin", @sdk_origin} | to_query(params, @research_related_papers_key_mapping)])- end+ @spec parse_file!(keyword(), keyword(), keyword()) :: Req.Response.t()+ def parse_file!(file, params \\ [], opts \\ []) do+ params = NimbleOptions.validate!(params, @parse_file_schema)+ filename = Keyword.fetch!(file, :filename)+ data = Keyword.fetch!(file, :data)+ content_type = Keyword.get(file, :content_type)- @research_search_github_schema NimbleOptions.new!([- k: [type: :integer],- query: [type: :string, required: true]- ])+ if not is_binary(filename) or filename == "" do+ raise ArgumentError, "filename cannot be empty"+ end- @research_search_github_key_mapping %{k: "k", query: "query"}+ if is_nil(data) do+ raise ArgumentError, "file data cannot be empty"+ end- @doc """- Search GitHub research content.+ file_part =+ case content_type do+ nil -> {data, filename: filename}+ ct -> {data, filename: filename, content_type: ct}+ end- `GET /search/research/github`- """- @spec search_github(keyword(), keyword()) :: response()- def search_github(params \\ [], opts \\ []) do- with {:ok, params} <- NimbleOptions.validate(params, @research_search_github_schema) do- Req.get(client(opts), url: "/search/research/github", params: [{"origin", @sdk_origin} | to_query(params, @research_search_github_key_mapping)])- end- end+ multipart = [{"options", Jason.encode!(to_body(params, @parse_file_key_mapping))}, {"file", file_part}]- @doc """- Bang variant of `search_github`. Raises on error.- """- @spec search_github!(keyword(), keyword()) :: Req.Response.t()- def search_github!(params \\ [], opts \\ []) do- params = NimbleOptions.validate!(params, @research_search_github_schema)- Req.get!(client(opts), url: "/search/research/github", params: [{"origin", @sdk_origin} | to_query(params, @research_search_github_key_mapping)])+ Req.post!(client(opts), url: "/parse", form_multipart: multipart)end- @start_agent_schema NimbleOptions.new!([- audit_metadata: [type: :keyword_list, keys: [username: [type: :string, required: true]], doc: "User attribution to include with SIEM logging events."],- effort: [type: {:in, ["low", "medium", "high"]}, doc: "Reasoning effort for the agent task. Every level runs spark-2."],- max_credits: [type: {:or, [:integer, :float]}, doc: "Maximum credits to spend on this agent task. Defaults to 2500 if not set. Values above 2,500 are always billed as paid requests."],- model: [type: {:or, [{:in, [:"spark-1-mini", :"spark-1-pro", :"spark-2"]}, :string]}, doc: "The model to use for the agent task. spark-1-pro (default) offers higher accuracy for complex tasks, spark-1-mini is 60% cheaper than spark-1-pro, spark-2 handles most tasks"],- prompt: [type: :string, required: true, doc: "The prompt describing what data to extract"],- schema: [type: :any, doc: "Optional JSON schema to structure the extracted data"],- strict_constrain_to_urls: [type: :boolean, doc: "If true, agent will only visit URLs provided in the urls array"],- urls: [type: {:list, :string}, doc: "Optional list of URLs to constrain the agent to"]+ @scrape_and_extract_from_url_schema NimbleOptions.new!([+ url: [type: :string, required: true, doc: "The URL to scrape"],+ actions: [type: {:list, :any}, doc: "Actions to perform on the page before grabbing the content"],+ audit_metadata: [type: :keyword_list, keys: [username: [type: :string, required: true]], doc: "User attribution included with SIEM logging events when SIEM Logging is enabled for the organization."],+ block_ads: [type: :boolean, doc: "Enables ad-blocking and cookie popup blocking."],+ exclude_tags: [type: {:list, :string}, doc: "Tags to exclude from the output."],+ formats: [type: {:list, :any}, doc: "Output formats to include in the response. You can specify one or more formats, either as strings (e.g., `'markdown'`) or as objects with additional options (e.g., `{ type: 'json', schema: {...} }`). Some formats require specific options to be set. Example: `['markdown', { type: 'json', schema: {...} }]`."],+ headers: [type: :any, doc: "Headers to send with the request. Can be used to send cookies, user-agent, etc."],+ include_tags: [type: {:list, :string}, doc: "Tags to include in the output."],+ location: [type: :keyword_list, doc: "Location settings for the request. When specified, this will use an appropriate proxy if available and emulate the corresponding language and timezone settings. Defaults to 'US' if not specified."],+ lockdown: [type: :boolean, doc: "If true, serves the request from Firecrawl's cache only and never makes an outbound request to the target URL. Designed for compliance-constrained or air-gapped environments where the scrape request itself could leak sensitive information. On cache miss, returns a 404 with error code SCRAPE_LOCKDOWN_CACHE_MISS (the URL is never logged on miss). Lockdown requests are treated as zero data retention. Default maxAge is extended to 2 years so existing cached pages remain eligible. Billed at 5 credits on hit, 1 credit on cache miss."],+ max_age: [type: :integer, doc: "Returns a cached version of the page if it is younger than this age in milliseconds. If a cached version of the page is older than this value, the page will be scraped. If you do not need extremely fresh data, enabling this can speed up your scrapes by 500%. Defaults to 2 days."],+ min_age: [type: :integer, doc: "When set, the request only checks the cache and never triggers a fresh scrape. The value is in milliseconds and specifies the minimum age the cached data must be. If matching cached data exists, it is returned instantly. If no cached data is found, a 404 with error code SCRAPE_NO_CACHED_DATA is returned. Set to 1 to accept any cached data regardless of age."],+ mobile: [type: :boolean, doc: "Set to true if you want to emulate scraping from a mobile device. Useful for testing responsive pages and taking mobile screenshots."],+ only_clean_content: [type: :boolean, doc: "Beta. Run an additional LLM-based pass over the generated markdown to remove residual boilerplate that `onlyMainContent` can miss (cookie banners, ad blocks, social share widgets, breadcrumbs, newsletter signups, comment sections, related-article lists). Headings, lists, tables, code blocks, image references, and inline links are preserved. Can be combined with `onlyMainContent` (the most common setup) or used on its own. Skipped with a warning when the markdown exceeds the cleaning model's output token limit (the original markdown is preserved). Not supported on zero-data-retention requests."],+ only_main_content: [type: :boolean, doc: "Only return the main content of the page excluding headers, navs, footers, etc. This is a deterministic HTML-level filter applied before markdown is generated; no LLM is involved."],+ parsers: [type: {:list, :any}, doc: "Controls how files are processed during scraping. When \"pdf\" is included (default), the PDF content is extracted and converted to markdown format, with billing based on the number of pages (1 credit per page). When an empty array is passed, the PDF file is returned in base64 encoding with a flat rate of 1 credit for the entire PDF."],+ profile: [type: :keyword_list, doc: "Enable persistent browser storage across scrape and interact sessions. Pass a profile when scraping to preserve cookies, localStorage, and session data. Sessions with the same profile name share browser state."],+ proxy: [type: {:or, [{:in, [:basic, :enhanced, :auto]}, :string]}, doc: "Specifies the type of proxy to use.\n\n - **basic**: Proxies for scraping sites with none to basic anti-bot solutions. Fast and usually works.\n - **enhanced**: Enhanced proxies for scraping sites with advanced anti-bot solutions. Slower, but more reliable on certain sites. Billed at the same credit cost as basic.\n - **auto**: Firecrawl will automatically retry scraping with enhanced proxies if the basic proxy fails. Enhanced proxies carry no credit surcharge, so either way only the regular cost is billed."],+ redact_pii: [type: :any, doc: "Redact personally identifiable information from returned markdown. Pass `true` to use defaults, or an object to tune mode, entities, and replacement style."],+ remove_base64_images: [type: :boolean, doc: "Removes all base 64 images from the markdown output, which may be overwhelmingly long. This does not affect html or rawHtml formats. The image's alt text remains in the output, but the URL is replaced with a placeholder."],+ skip_tls_verification: [type: :boolean, doc: "Skip TLS certificate verification when making requests."],+ store_in_cache: [type: :boolean, doc: "If true, the page will be stored in the Firecrawl index and cache. Setting this to false is useful if your scraping activity may have data protection concerns. Using some parameters associated with sensitive scraping (e.g. actions, headers) will force this parameter to be false."],+ threat_protection: [type: :keyword_list, doc: "Per-request [Threat Protection](https://docs.firecrawl.dev/features/threat-protection) override. Fields you provide replace the corresponding fields of your organization's policy for this request only; omitted fields keep their organization-level values. Requires Threat Protection to be enabled for your team (enterprise feature) — otherwise the request is rejected with a 403. If your organization has disabled request overrides, any request that includes this object is rejected with a 403. If Threat Protection is enforced for your team, `mode` may not be set to `off`."],+ timeout: [type: :integer, doc: "Timeout in milliseconds for the request. Minimum is 1000 (1 second). Default is 60000 (60 seconds). Maximum is 300000 (300 seconds)."],+ wait_for: [type: :integer, doc: "Specify a delay in milliseconds before fetching the content, allowing the page sufficient time to load. This waiting time is in addition to Firecrawl's smart wait feature."],+ zero_data_retention: [type: :boolean, doc: "If true, this will enable zero data retention for this scrape. To enable this feature, please contact [email protected]"],+ alexandria: [type: :any, doc: "Execute one or more catalogued provider tools instead of scraping a URL. Cannot be combined with `url`, `formats`, or other scrape options (400); the only allowed sibling keys are `timeout`, `origin`, and `integration`. Use the `x-request-id` request header as a client-chosen idempotency key (1 to 128 characters of letters, digits, `.`, `_`, `:`, `-`) — it is echoed back, and a completed request with the same key replays its original response and `scrape_id` instead of re-executing."],+ domain_tools: [type: :boolean, doc: "When true on an ordinary URL scrape, `data.tools` lists tool contracts matched to the scraped page's domain (same `DiscoveredTool` shape as search). Requires the team's Alexandria access to be enabled and no zero data retention (403 otherwise). Free."]])- @start_agent_key_mapping %{audit_metadata: "auditMetadata", effort: "effort", max_credits: "maxCredits", model: "model", prompt: "prompt", schema: "schema", strict_constrain_to_urls: "strictConstrainToURLs", urls: "urls"}+ @scrape_and_extract_from_url_key_mapping %{url: "url", actions: "actions", audit_metadata: "auditMetadata", block_ads: "blockAds", exclude_tags: "excludeTags", formats: "formats", headers: "headers", include_tags: "includeTags", location: "location", lockdown: "lockdown", max_age: "maxAge", min_age: "minAge", mobile: "mobile", only_clean_content: "onlyCleanContent", only_main_content: "onlyMainContent", parsers: "parsers", profile: "profile", proxy: "proxy", redact_pii: "redactPII", remove_base64_images: "removeBase64Images", skip_tls_verification: "skipTlsVerification", store_in_cache: "storeInCache", threat_protection: "threatProtection", timeout: "timeout", wait_for: "waitFor", zero_data_retention: "zeroDataRetention", alexandria: "alexandria", domain_tools: "domainTools"}@doc """- Start an agent task for agentic data extraction+ Scrape a single URL and optionally extract information using an LLM- `POST /agent`+ `POST /scrape`- Tag: Agent+ Tag: Scraping## ParametersValidated by `NimbleOptions`. Pass params as a keyword list with snake_case keys.- See `@start_agent_schema` for the full schema.+ See `@scrape_and_extract_from_url_schema` for the full schema.## Returns* `{:ok, %Req.Response{}}` on success* `{:error, exception}` on HTTP or validation failure"""- @spec start_agent(keyword(), keyword()) :: response()- def start_agent(params \\ [], opts \\ []) do- with {:ok, params} <- NimbleOptions.validate(params, @start_agent_schema) do- Req.post(client(opts), url: "/agent", json: to_body(params, @start_agent_key_mapping))+ @spec scrape_and_extract_from_url(keyword(), keyword()) :: response()+ def scrape_and_extract_from_url(params \\ [], opts \\ []) do+ with {:ok, params} <- NimbleOptions.validate(params, @scrape_and_extract_from_url_schema) do+ Req.post(client(opts), url: "/scrape", json: to_body(params, @scrape_and_extract_from_url_key_mapping))endend@doc """- Bang variant of `start_agent`. Raises on error.+ Bang variant of `scrape_and_extract_from_url`. Raises on error."""- @spec start_agent!(keyword(), keyword()) :: Req.Response.t()- def start_agent!(params \\ [], opts \\ []) do- params = NimbleOptions.validate!(params, @start_agent_schema)- Req.post!(client(opts), url: "/agent", json: to_body(params, @start_agent_key_mapping))+ @spec scrape_and_extract_from_url!(keyword(), keyword()) :: Req.Response.t()+ def scrape_and_extract_from_url!(params \\ [], opts \\ []) do+ params = NimbleOptions.validate!(params, @scrape_and_extract_from_url_schema)+ Req.post!(client(opts), url: "/scrape", json: to_body(params, @scrape_and_extract_from_url_key_mapping))end+ @scrape_and_extract_from_urls_schema NimbleOptions.new!([+ ignore_invalid_urls: [type: :boolean, doc: "If invalid URLs are specified in the urls array, they will be ignored. Instead of them failing the entire request, a batch scrape using the remaining valid URLs will be created, and the invalid URLs will be returned in the invalidURLs field of the response."],+ max_concurrency: [type: :integer, doc: "Maximum number of concurrent scrapes. This parameter allows you to set a concurrency limit for this batch scrape. If not specified, the batch scrape adheres to your team's concurrency limit."],+ urls: [type: {:list, :string}, required: true],+ webhook: [type: :keyword_list, doc: "A webhook specification object."],+ actions: [type: {:list, :any}, doc: "Actions to perform on the page before grabbing the content"],+ audit_metadata: [type: :keyword_list, keys: [username: [type: :string, required: true]], doc: "User attribution included with SIEM logging events when SIEM Logging is enabled for the organization."],+ block_ads: [type: :boolean, doc: "Enables ad-blocking and cookie popup blocking."],+ exclude_tags: [type: {:list, :string}, doc: "Tags to exclude from the output."],+ formats: [type: {:list, :any}, doc: "Output formats to include in the response. You can specify one or more formats, either as strings (e.g., `'markdown'`) or as objects with additional options (e.g., `{ type: 'json', schema: {...} }`). Some formats require specific options to be set. Example: `['markdown', { type: 'json', schema: {...} }]`."],+ headers: [type: :any, doc: "Headers to send with the request. Can be used to send cookies, user-agent, etc."],+ include_tags: [type: {:list, :string}, doc: "Tags to include in the output."],+ location: [type: :keyword_list, doc: "Location settings for the request. When specified, this will use an appropriate proxy if available and emulate the corresponding language and timezone settings. Defaults to 'US' if not specified."],+ lockdown: [type: :boolean, doc: "If true, serves the request from Firecrawl's cache only and never makes an outbound request to the target URL. Designed for compliance-constrained or air-gapped environments where the scrape request itself could leak sensitive information. On cache miss, returns a 404 with error code SCRAPE_LOCKDOWN_CACHE_MISS (the URL is never logged on miss). Lockdown requests are treated as zero data retention. Default maxAge is extended to 2 years so existing cached pages remain eligible. Billed at 5 credits on hit, 1 credit on cache miss."],+ max_age: [type: :integer, doc: "Returns a cached version of the page if it is younger than this age in milliseconds. If a cached version of the page is older than this value, the page will be scraped. If you do not need extremely fresh data, enabling this can speed up your scrapes by 500%. Defaults to 2 days."],+ min_age: [type: :integer, doc: "When set, the request only checks the cache and never triggers a fresh scrape. The value is in milliseconds and specifies the minimum age the cached data must be. If matching cached data exists, it is returned instantly. If no cached data is found, a 404 with error code SCRAPE_NO_CACHED_DATA is returned. Set to 1 to accept any cached data regardless of age."],+ mobile: [type: :boolean, doc: "Set to true if you want to emulate scraping from a mobile device. Useful for testing responsive pages and taking mobile screenshots."],+ only_clean_content: [type: :boolean, doc: "Beta. Run an additional LLM-based pass over the generated markdown to remove residual boilerplate that `onlyMainContent` can miss (cookie banners, ad blocks, social share widgets, breadcrumbs, newsletter signups, comment sections, related-article lists). Headings, lists, tables, code blocks, image references, and inline links are preserved. Can be combined with `onlyMainContent` (the most common setup) or used on its own. Skipped with a warning when the markdown exceeds the cleaning model's output token limit (the original markdown is preserved). Not supported on zero-data-retention requests."],+ only_main_content: [type: :boolean, doc: "Only return the main content of the page excluding headers, navs, footers, etc. This is a deterministic HTML-level filter applied before markdown is generated; no LLM is involved."],+ parsers: [type: {:list, :any}, doc: "Controls how files are processed during scraping. When \"pdf\" is included (default), the PDF content is extracted and converted to markdown format, with billing based on the number of pages (1 credit per page). When an empty array is passed, the PDF file is returned in base64 encoding with a flat rate of 1 credit for the entire PDF."],+ profile: [type: :keyword_list, doc: "Enable persistent browser storage across scrape and interact sessions. Pass a profile when scraping to preserve cookies, localStorage, and session data. Sessions with the same profile name share browser state."],+ proxy: [type: {:or, [{:in, [:basic, :enhanced, :auto]}, :string]}, doc: "Specifies the type of proxy to use.\n\n - **basic**: Proxies for scraping sites with none to basic anti-bot solutions. Fast and usually works.\n - **enhanced**: Enhanced proxies for scraping sites with advanced anti-bot solutions. Slower, but more reliable on certain sites. Billed at the same credit cost as basic.\n - **auto**: Firecrawl will automatically retry scraping with enhanced proxies if the basic proxy fails. Enhanced proxies carry no credit surcharge, so either way only the regular cost is billed."],+ redact_pii: [type: :any, doc: "Redact personally identifiable information from returned markdown. Pass `true` to use defaults, or an object to tune mode, entities, and replacement style."],+ remove_base64_images: [type: :boolean, doc: "Removes all base 64 images from the markdown output, which may be overwhelmingly long. This does not affect html or rawHtml formats. The image's alt text remains in the output, but the URL is replaced with a placeholder."],+ skip_tls_verification: [type: :boolean, doc: "Skip TLS certificate verification when making requests."],+ store_in_cache: [type: :boolean, doc: "If true, the page will be stored in the Firecrawl index and cache. Setting this to false is useful if your scraping activity may have data protection concerns. Using some parameters associated with sensitive scraping (e.g. actions, headers) will force this parameter to be false."],+ threat_protection: [type: :keyword_list, doc: "Per-request [Threat Protection](https://docs.firecrawl.dev/features/threat-protection) override. Fields you provide replace the corresponding fields of your organization's policy for this request only; omitted fields keep their organization-level values. Requires Threat Protection to be enabled for your team (enterprise feature) — otherwise the request is rejected with a 403. If your organization has disabled request overrides, any request that includes this object is rejected with a 403. If Threat Protection is enforced for your team, `mode` may not be set to `off`."],+ timeout: [type: :integer, doc: "Timeout in milliseconds for the request. Minimum is 1000 (1 second). Default is 60000 (60 seconds). Maximum is 300000 (300 seconds)."],+ wait_for: [type: :integer, doc: "Specify a delay in milliseconds before fetching the content, allowing the page sufficient time to load. This waiting time is in addition to Firecrawl's smart wait feature."],+ zero_data_retention: [type: :boolean, doc: "If true, this will enable zero data retention for this batch scrape. To enable this feature, please contact [email protected]"]+ ])++ @scrape_and_extract_from_urls_key_mapping %{ignore_invalid_urls: "ignoreInvalidURLs", max_concurrency: "maxConcurrency", urls: "urls", webhook: "webhook", actions: "actions", audit_metadata: "auditMetadata", block_ads: "blockAds", exclude_tags: "excludeTags", formats: "formats", headers: "headers", include_tags: "includeTags", location: "location", lockdown: "lockdown", max_age: "maxAge", min_age: "minAge", mobile: "mobile", only_clean_content: "onlyCleanContent", only_main_content: "onlyMainContent", parsers: "parsers", profile: "profile", proxy: "proxy", redact_pii: "redactPII", remove_base64_images: "removeBase64Images", skip_tls_verification: "skipTlsVerification", store_in_cache: "storeInCache", threat_protection: "threatProtection", timeout: "timeout", wait_for: "waitFor", zero_data_retention: "zeroDataRetention"}+@doc """- Stop the interactive browser session associated with a scrape job+ Scrape multiple URLs and optionally extract information using an LLM- `DELETE /scrape/{jobId}/interact`+ `POST /batch/scrape`Tag: Scraping- ## Path Parameters+ ## Parameters- * `job_id` - Path parameter `jobId`+ Validated by `NimbleOptions`. Pass params as a keyword list with snake_case keys.+ See `@scrape_and_extract_from_urls_schema` for the full schema.## Returns* `{:ok, %Req.Response{}}` on success* `{:error, exception}` on HTTP or validation failure"""- @spec stop_interactive_scrape_browser_session(String.t(), keyword()) :: response()- def stop_interactive_scrape_browser_session(job_id, opts \\ []) do- Req.delete(client(opts), url: "/scrape/#{job_id}/interact")+ @spec scrape_and_extract_from_urls(keyword(), keyword()) :: response()+ def scrape_and_extract_from_urls(params \\ [], opts \\ []) do+ with {:ok, params} <- NimbleOptions.validate(params, @scrape_and_extract_from_urls_schema) do+ Req.post(client(opts), url: "/batch/scrape", json: to_body(params, @scrape_and_extract_from_urls_key_mapping))+ endend@doc """- Bang variant of `stop_interactive_scrape_browser_session`. Raises on error.+ Bang variant of `scrape_and_extract_from_urls`. Raises on error."""- @spec stop_interactive_scrape_browser_session!(String.t(), keyword()) :: Req.Response.t()- def stop_interactive_scrape_browser_session!(job_id, opts \\ []) do- Req.delete!(client(opts), url: "/scrape/#{job_id}/interact")+ @spec scrape_and_extract_from_urls!(keyword(), keyword()) :: Req.Response.t()+ def scrape_and_extract_from_urls!(params \\ [], opts \\ []) do+ params = NimbleOptions.validate!(params, @scrape_and_extract_from_urls_schema)+ Req.post!(client(opts), url: "/batch/scrape", json: to_body(params, @scrape_and_extract_from_urls_key_mapping))end- @monitor_key_mapping %{- name: "name",- schedule: "schedule",- targets: "targets",- webhook: "webhook",- notification: "notification",- retention_days: "retentionDays",- status: "status",- goal: "goal",- judge_enabled: "judgeEnabled"- }-- @monitor_list_key_mapping %{limit: "limit", offset: "offset"}- @monitor_check_list_key_mapping %{limit: "limit", offset: "offset", status: "status"}- @monitor_check_key_mapping %{limit: "limit", skip: "skip", status: "status"}-- @monitor_schema NimbleOptions.new!([- name: [type: :string],- schedule: [type: :any],- targets: [type: {:list, :any}],- webhook: [type: :any],- notification: [type: :any],- retention_days: [type: :integer],- status: [type: :any],- goal: [type: :any],- judge_enabled: [type: :boolean]- ])-- @monitor_list_schema NimbleOptions.new!([- limit: [type: :integer],- offset: [type: :integer]- ])- @monitor_check_list_schema NimbleOptions.new!([- limit: [type: :integer],- offset: [type: :integer],- status: [type: :any]+ @search_and_scrape_schema NimbleOptions.new!([+ categories: [type: {:list, :any}, doc: "Categories to filter results by. Defaults to [], which means results will not be filtered by any categories."],+ country: [type: :string, doc: "ISO country code for geo-targeting search results (e.g. `US`). For best results, set both this and the `location` parameter."],+ domain_tools: [type: :boolean, doc: "Include tool contracts whose provider matches the domains of the returned web results. Defaults to on when `alexandria` is among the sources; set `false` to disable, or `true` alone to add domain-matched tools beside ordinary web results. Free."],+ enterprise: [type: {:list, :string}, doc: "Enterprise search options for Zero Data Retention (ZDR). Use `[\"zdr\"]` for end-to-end ZDR (10 credits / 10 results) or `[\"anon\"]` for anonymized ZDR (2 credits / 10 results). Must be enabled for your team."],+ exclude_domains: [type: {:list, :string}, doc: "Excludes search results from the specified domains. Domains should be hostnames only, without protocol or path. Cannot be used with includeDomains."],+ highlights: [type: :boolean, doc: "Generate query-relevant highlights for search results. Set to false to return provider descriptions or snippets without highlighting."],+ ignore_invalid_urls: [type: :boolean, doc: "Excludes URLs from the search results that are invalid for other Firecrawl endpoints. This helps reduce errors if you are piping data from search into other Firecrawl API endpoints."],+ include_domains: [type: {:list, :string}, doc: "Restricts search results to the specified domains. Domains should be hostnames only, without protocol or path. Cannot be used with excludeDomains."],+ limit: [type: :integer, doc: "Maximum number of results to return (per source type when using multiple sources)"],+ location: [type: :string, doc: "Location parameter for search results (e.g. `San Francisco,California,United States`). For best results, set both this and the `country` parameter."],+ query: [type: :string, required: true, doc: "The search query"],+ safe: [type: :boolean, doc: "When `true`, filters explicit content from search results (SafeSearch). Omit to keep the default behavior, which does not apply the filter."],+ scrape_options: [type: :keyword_list, doc: "Options for scraping search results"],+ sources: [type: {:list, :any}, doc: "Sources to search. Will determine the arrays available in the response. Defaults to ['web']. The plain string form (e.g. `[\"web\", \"alexandria\"]`) is also accepted. The `alexandria` source returns tool contracts discovered from the Alexandria catalogue in `data.tools` instead of search results; it is free and is never counted in `creditsUsed`. Requires the team's Alexandria access to be enabled (403 otherwise)."],+ tbs: [type: :string, doc: "Time-based search parameter. Supports predefined time ranges (`qdr:h`, `qdr:d`, `qdr:w`, `qdr:m`, `qdr:y`), custom date ranges (`cdr:1,cd_min:MM/DD/YYYY,cd_max:MM/DD/YYYY`), and sort by date (`sbd:1`). Values can be combined, e.g. `sbd:1,qdr:w`."],+ threat_protection: [type: :keyword_list, doc: "Per-request [Threat Protection](https://docs.firecrawl.dev/features/threat-protection) override. Fields you provide replace the corresponding fields of your organization's policy for this request only; omitted fields keep their organization-level values. Requires Threat Protection to be enabled for your team (enterprise feature) — otherwise the request is rejected with a 403. If your organization has disabled request overrides, any request that includes this object is rejected with a 403. If Threat Protection is enforced for your team, `mode` may not be set to `off`."],+ timeout: [type: :integer, doc: "Timeout in milliseconds"]])- @monitor_check_schema NimbleOptions.new!([- limit: [type: :integer],- skip: [type: :integer],- status: [type: :any]- ])+ @search_and_scrape_key_mapping %{categories: "categories", country: "country", domain_tools: "domainTools", enterprise: "enterprise", exclude_domains: "excludeDomains", highlights: "highlights", ignore_invalid_urls: "ignoreInvalidURLs", include_domains: "includeDomains", limit: "limit", location: "location", query: "query", safe: "safe", scrape_options: "scrapeOptions", sources: "sources", tbs: "tbs", threat_protection: "threatProtection", timeout: "timeout"}@doc """- Create a scheduled monitor.-- `POST /monitor`-- ## Targets+ Search and optionally scrape search results- `targets` is a list of maps/keyword lists. Each target is sent as-is (keys are- camelCased), so the supported target shapes are:+ `POST /search`- * Scrape: `[type: "scrape", url: "https://example.com", ...]`- * Crawl: `[type: "crawl", url: "https://example.com", ...]`- * Search:- `[type: "search", queries: ["term"], search_window: "24h",- include_domains: ["example.com"], exclude_domains: [],- max_results: 10]`- (`search_window` is one of `"5m"`, `"15m"`, `"1h"`, `"6h"`, `"24h"`,- `"7d"`; only `queries` is required.)+ Tag: Search- Optionally pass `goal` and `judge_enabled: true` to enable AI judging.- """- @spec create_monitor(keyword(), keyword()) :: response()- def create_monitor(params \\ [], opts \\ []) do- with {:ok, params} <- NimbleOptions.validate(params, @monitor_schema) do- Req.post(client(opts), url: "/monitor", json: to_body(params, @monitor_key_mapping))- end- end+ ## Parameters- @doc """- Bang variant of `create_monitor`. Raises on error.- """- @spec create_monitor!(keyword(), keyword()) :: Req.Response.t()- def create_monitor!(params \\ [], opts \\ []) do- params = NimbleOptions.validate!(params, @monitor_schema)- Req.post!(client(opts), url: "/monitor", json: to_body(params, @monitor_key_mapping))- end+ Validated by `NimbleOptions`. Pass params as a keyword list with snake_case keys.+ See `@search_and_scrape_schema` for the full schema.- @doc """- List monitors for the authenticated team.+ ## Returns- `GET /monitor`+ * `{:ok, %Req.Response{}}` on success+ * `{:error, exception}` on HTTP or validation failure"""- @spec list_monitors(keyword(), keyword()) :: response()- def list_monitors(params \\ [], opts \\ []) do- with {:ok, params} <- NimbleOptions.validate(params, @monitor_list_schema) do- Req.get(client(opts), url: "/monitor", params: to_query(params, @monitor_list_key_mapping))+ @spec search_and_scrape(keyword(), keyword()) :: response()+ def search_and_scrape(params \\ [], opts \\ []) do+ with {:ok, params} <- NimbleOptions.validate(params, @search_and_scrape_schema) do+ Req.post(client(opts), url: "/search", json: to_body(params, @search_and_scrape_key_mapping))endend+@doc """- Bang variant of `list_monitors`. Raises on error.+ Bang variant of `search_and_scrape`. Raises on error."""- @spec list_monitors!(keyword(), keyword()) :: Req.Response.t()- def list_monitors!(params \\ [], opts \\ []) do- params = NimbleOptions.validate!(params, @monitor_list_schema)- Req.get!(client(opts), url: "/monitor", params: to_query(params, @monitor_list_key_mapping))+ @spec search_and_scrape!(keyword(), keyword()) :: Req.Response.t()+ def search_and_scrape!(params \\ [], opts \\ []) do+ params = NimbleOptions.validate!(params, @search_and_scrape_schema)+ Req.post!(client(opts), url: "/search", json: to_body(params, @search_and_scrape_key_mapping))end- @doc """- Get a monitor by ID.- `GET /monitor/{monitorId}`- """- @spec get_monitor(String.t(), keyword()) :: response()- def get_monitor(monitor_id, opts \\ []) do- Req.get(client(opts), url: "/monitor/#{monitor_id}")- end+ @search_support_docs_schema NimbleOptions.new!([+ question: [type: :string, required: true, doc: "Documentation question to answer."]+ ])- @doc """- Bang variant of `get_monitor`. Raises on error.- """- @spec get_monitor!(String.t(), keyword()) :: Req.Response.t()- def get_monitor!(monitor_id, opts \\ []) do- Req.get!(client(opts), url: "/monitor/#{monitor_id}")- end+ @search_support_docs_key_mapping %{question: "question"}@doc """- Update a monitor.+ Search Firecrawl docs with citations- `PATCH /monitor/{monitorId}`+ `POST /support/docs-search`++ Tag: Support++ ## Parameters++ Validated by `NimbleOptions`. Pass params as a keyword list with snake_case keys.+ See `@search_support_docs_schema` for the full schema.++ ## Returns++ * `{:ok, %Req.Response{}}` on success+ * `{:error, exception}` on HTTP or validation failure"""- @spec update_monitor(String.t(), keyword(), keyword()) :: response()- def update_monitor(monitor_id, params \\ [], opts \\ []) do- with {:ok, params} <- NimbleOptions.validate(params, @monitor_schema) do- Req.patch(client(opts), url: "/monitor/#{monitor_id}", json: to_body(params, @monitor_key_mapping))+ @spec search_support_docs(keyword(), keyword()) :: response()+ def search_support_docs(params \\ [], opts \\ []) do+ with {:ok, params} <- NimbleOptions.validate(params, @search_support_docs_schema) do+ Req.post(client(opts), url: "/support/docs-search", json: to_body(params, @search_support_docs_key_mapping))endend+@doc """- Bang variant of `update_monitor`. Raises on error.+ Bang variant of `search_support_docs`. Raises on error."""- @spec update_monitor!(String.t(), keyword(), keyword()) :: Req.Response.t()- def update_monitor!(monitor_id, params \\ [], opts \\ []) do- params = NimbleOptions.validate!(params, @monitor_schema)- Req.patch!(client(opts), url: "/monitor/#{monitor_id}", json: to_body(params, @monitor_key_mapping))+ @spec search_support_docs!(keyword(), keyword()) :: Req.Response.t()+ def search_support_docs!(params \\ [], opts \\ []) do+ params = NimbleOptions.validate!(params, @search_support_docs_schema)+ Req.post!(client(opts), url: "/support/docs-search", json: to_body(params, @search_support_docs_key_mapping))end++ @start_agent_schema NimbleOptions.new!([+ audit_metadata: [type: :keyword_list, keys: [username: [type: :string, required: true]], doc: "User attribution included with SIEM logging events when SIEM Logging is enabled for the organization."],+ effort: [type: {:in, ["low", "medium", "high"]}, doc: "Reasoning budget for the agent task. Every run executes on spark-2, so effort can be sent with or without model."],+ max_credits: [type: {:or, [:integer, :float]}, doc: "Maximum credits to spend on this agent task. Defaults to 2500 if not set. Values above 2,500 are always billed as paid requests."],+ model: [type: {:or, [{:in, [:"spark-2", :"spark-1-mini", :"spark-1-pro"]}, :string]}, doc: "The model to use for the agent task. spark-2 is the default and the model every run executes on. The Spark 1 model names remain accepted for backwards compatibility but are deprecated and route to spark-2."],+ prompt: [type: :string, required: true, doc: "The prompt describing what data to extract"],+ schema: [type: :any, doc: "Optional JSON schema to structure the extracted data"],+ strict_constrain_to_urls: [type: :boolean, doc: "If true, agent will only visit URLs provided in the urls array"],+ threat_protection: [type: :keyword_list, doc: "Per-request [Threat Protection](https://docs.firecrawl.dev/features/threat-protection) override. Fields you provide replace the corresponding fields of your organization's policy for this request only; omitted fields keep their organization-level values. Requires Threat Protection to be enabled for your team (enterprise feature) — otherwise the request is rejected with a 403. If your organization has disabled request overrides, any request that includes this object is rejected with a 403. If Threat Protection is enforced for your team, `mode` may not be set to `off`."],+ urls: [type: {:list, :string}, doc: "Optional list of URLs to constrain the agent to"],+ webhook: [type: :keyword_list, doc: "A webhook specification object. Subscribes to agent lifecycle events (agent.started, agent.action, agent.completed, agent.failed, agent.cancelled)."]+ ])++ @start_agent_key_mapping %{audit_metadata: "auditMetadata", effort: "effort", max_credits: "maxCredits", model: "model", prompt: "prompt", schema: "schema", strict_constrain_to_urls: "strictConstrainToURLs", threat_protection: "threatProtection", urls: "urls", webhook: "webhook"}+@doc """- Delete a monitor.+ Start an agent task for agentic data extraction- `DELETE /monitor/{monitorId}`+ `POST /agent`++ Tag: Agent++ ## Parameters++ Validated by `NimbleOptions`. Pass params as a keyword list with snake_case keys.+ See `@start_agent_schema` for the full schema.++ ## Returns++ * `{:ok, %Req.Response{}}` on success+ * `{:error, exception}` on HTTP or validation failure"""- @spec delete_monitor(String.t(), keyword()) :: response()- def delete_monitor(monitor_id, opts \\ []) do- Req.delete(client(opts), url: "/monitor/#{monitor_id}")+ @spec start_agent(keyword(), keyword()) :: response()+ def start_agent(params \\ [], opts \\ []) do+ with {:ok, params} <- NimbleOptions.validate(params, @start_agent_schema) do+ Req.post(client(opts), url: "/agent", json: to_body(params, @start_agent_key_mapping))+ endend+@doc """- Bang variant of `delete_monitor`. Raises on error.+ Bang variant of `start_agent`. Raises on error."""- @spec delete_monitor!(String.t(), keyword()) :: Req.Response.t()- def delete_monitor!(monitor_id, opts \\ []) do- Req.delete!(client(opts), url: "/monitor/#{monitor_id}")+ @spec start_agent!(keyword(), keyword()) :: Req.Response.t()+ def start_agent!(params \\ [], opts \\ []) do+ params = NimbleOptions.validate!(params, @start_agent_schema)+ Req.post!(client(opts), url: "/agent", json: to_body(params, @start_agent_key_mapping))end+@doc """- Trigger a manual monitor check.+ Stop the interactive browser session associated with a scrape job- `POST /monitor/{monitorId}/run`+ `DELETE /scrape/{jobId}/interact`++ Tag: Scraping++ ## Path Parameters++ * `job_id` - Path parameter `jobId`++ ## Returns++ * `{:ok, %Req.Response{}}` on success+ * `{:error, exception}` on HTTP or validation failure"""- @spec run_monitor(String.t(), keyword()) :: response()- def run_monitor(monitor_id, opts \\ []) do- Req.post(client(opts), url: "/monitor/#{monitor_id}/run", json: %{})+ @spec stop_interactive_scrape_browser_session(String.t(), keyword()) :: response()+ def stop_interactive_scrape_browser_session(job_id, opts \\ []) do+ Req.delete(client(opts), url: "/scrape/#{job_id}/interact")end+@doc """- Bang variant of `run_monitor`. Raises on error.+ Bang variant of `stop_interactive_scrape_browser_session`. Raises on error."""- @spec run_monitor!(String.t(), keyword()) :: Req.Response.t()- def run_monitor!(monitor_id, opts \\ []) do- Req.post!(client(opts), url: "/monitor/#{monitor_id}/run", json: %{})+ @spec stop_interactive_scrape_browser_session!(String.t(), keyword()) :: Req.Response.t()+ def stop_interactive_scrape_browser_session!(job_id, opts \\ []) do+ Req.delete!(client(opts), url: "/scrape/#{job_id}/interact")end++ @submit_endpoint_feedback_schema NimbleOptions.new!([+ integration: [type: :string],+ missing_content: [type: {:list, :any}],+ origin: [type: :string],+ query_suggestions: [type: :string],+ rating: [type: {:or, [{:in, [:good, :partial, :bad]}, :string]}, required: true],+ valuable_sources: [type: {:list, :any}],+ endpoint: [type: {:or, [{:in, [:search, :scrape, :parse, :map]}, :string]}, required: true],+ issues: [type: {:list, :string}],+ job_id: [type: :string, required: true],+ metadata: [type: :any, doc: "Small endpoint-specific metadata object. Must be 8KB or smaller; do not include full endpoint results."],+ note: [type: :string],+ page_numbers: [type: {:list, :any}],+ tags: [type: {:list, :string}],+ url: [type: :string]+ ])++ @submit_endpoint_feedback_key_mapping %{integration: "integration", missing_content: "missingContent", origin: "origin", query_suggestions: "querySuggestions", rating: "rating", valuable_sources: "valuableSources", endpoint: "endpoint", issues: "issues", job_id: "jobId", metadata: "metadata", note: "note", page_numbers: "pageNumbers", tags: "tags", url: "url"}+@doc """- List checks for a monitor.+ Submit feedback for a v2 job- `GET /monitor/{monitorId}/checks`+ `POST /feedback`++ Tag: Feedback++ ## Parameters++ Validated by `NimbleOptions`. Pass params as a keyword list with snake_case keys.+ See `@submit_endpoint_feedback_schema` for the full schema.++ ## Returns++ * `{:ok, %Req.Response{}}` on success+ * `{:error, exception}` on HTTP or validation failure"""- @spec list_monitor_checks(String.t(), keyword(), keyword()) :: response()- def list_monitor_checks(monitor_id, params \\ [], opts \\ []) do- with {:ok, params} <- NimbleOptions.validate(params, @monitor_check_list_schema) do- Req.get(client(opts),- url: "/monitor/#{monitor_id}/checks",- params: to_query(params, @monitor_check_list_key_mapping)- )+ @spec submit_endpoint_feedback(keyword(), keyword()) :: response()+ def submit_endpoint_feedback(params \\ [], opts \\ []) do+ with {:ok, params} <- NimbleOptions.validate(params, @submit_endpoint_feedback_schema) do+ Req.post(client(opts), url: "/feedback", json: to_body(params, @submit_endpoint_feedback_key_mapping))endend+@doc """- Bang variant of `list_monitor_checks`. Raises on error.+ Bang variant of `submit_endpoint_feedback`. Raises on error."""- @spec list_monitor_checks!(String.t(), keyword(), keyword()) :: Req.Response.t()- def list_monitor_checks!(monitor_id, params \\ [], opts \\ []) do- params = NimbleOptions.validate!(params, @monitor_check_list_schema)- Req.get!(client(opts),- url: "/monitor/#{monitor_id}/checks",- params: to_query(params, @monitor_check_list_key_mapping)- )+ @spec submit_endpoint_feedback!(keyword(), keyword()) :: Req.Response.t()+ def submit_endpoint_feedback!(params \\ [], opts \\ []) do+ params = NimbleOptions.validate!(params, @submit_endpoint_feedback_schema)+ Req.post!(client(opts), url: "/feedback", json: to_body(params, @submit_endpoint_feedback_key_mapping))end++ @submit_search_feedback_schema NimbleOptions.new!([+ integration: [type: :string],+ missing_content: [type: {:list, :any}],+ origin: [type: :string],+ query_suggestions: [type: :string],+ rating: [type: {:or, [{:in, [:good, :partial, :bad]}, :string]}, required: true],+ valuable_sources: [type: {:list, :any}]+ ])++ @submit_search_feedback_key_mapping %{integration: "integration", missing_content: "missingContent", origin: "origin", query_suggestions: "querySuggestions", rating: "rating", valuable_sources: "valuableSources"}+@doc """- Get a monitor check with paginated page results and inline diffs.+ Submit feedback for a search job- `GET /monitor/{monitorId}/checks/{checkId}`- """- @spec get_monitor_check(String.t(), String.t(), keyword(), keyword()) :: response()- def get_monitor_check(monitor_id, check_id, params \\ [], opts \\ []) do- {auto_paginate, opts} = Keyword.pop(opts, :auto_paginate, true)+ `POST /search/{jobId}/feedback`- with {:ok, params} <- NimbleOptions.validate(params, @monitor_check_schema) do- case Req.get(client(opts),- url: "/monitor/#{monitor_id}/checks/#{check_id}",- params: to_query(params, @monitor_check_key_mapping)- ) do- {:ok, response} when auto_paginate -> {:ok, paginate_monitor_check_response(response, opts)}- result -> result- end+ Tag: Search++ ## Path Parameters++ * `job_id` - Path parameter `jobId`++ ## Parameters++ Validated by `NimbleOptions`. Pass params as a keyword list with snake_case keys.+ See `@submit_search_feedback_schema` for the full schema.++ ## Returns++ * `{:ok, %Req.Response{}}` on success+ * `{:error, exception}` on HTTP or validation failure+ """+ @spec submit_search_feedback(String.t(), keyword(), keyword()) :: response()+ def submit_search_feedback(job_id, params \\ [], opts \\ []) do+ with {:ok, params} <- NimbleOptions.validate(params, @submit_search_feedback_schema) do+ Req.post(client(opts), url: "/search/#{job_id}/feedback", json: to_body(params, @submit_search_feedback_key_mapping))endend+@doc """- Bang variant of `get_monitor_check`. Raises on error.+ Bang variant of `submit_search_feedback`. Raises on error."""- @spec get_monitor_check!(String.t(), String.t(), keyword(), keyword()) :: Req.Response.t()- def get_monitor_check!(monitor_id, check_id, params \\ [], opts \\ []) do- {auto_paginate, opts} = Keyword.pop(opts, :auto_paginate, true)- params = NimbleOptions.validate!(params, @monitor_check_schema)- response = Req.get!(client(opts),- url: "/monitor/#{monitor_id}/checks/#{check_id}",- params: to_query(params, @monitor_check_key_mapping)- )-- if auto_paginate, do: paginate_monitor_check_response!(response, opts), else: response+ @spec submit_search_feedback!(String.t(), keyword(), keyword()) :: Req.Response.t()+ def submit_search_feedback!(job_id, params \\ [], opts \\ []) do+ params = NimbleOptions.validate!(params, @submit_search_feedback_schema)+ Req.post!(client(opts), url: "/search/#{job_id}/feedback", json: to_body(params, @submit_search_feedback_key_mapping))end- defp paginate_monitor_check_response(%Req.Response{body: body} = response, opts) when is_map(body) do- data = Map.get(body, "data") || %{}- pages = Map.get(data, "pages") || []- next = Map.get(body, "next") || Map.get(data, "next")- pages = fetch_monitor_check_pages(next, pages, opts)- data = data |> Map.put("pages", pages) |> Map.put("next", nil)- %{response | body: body |> Map.put("data", data) |> Map.put("next", nil)}- end- defp paginate_monitor_check_response(response, _opts), do: response+ @update_threat_protection_schema NimbleOptions.new!([+ allow_request_overrides: [type: :boolean, doc: "Whether individual requests may pass a `threatProtection` object. When false, such requests are rejected with 403."],+ blacklist: [type: {:list, :string}, doc: "Exact domains or globs (e.g. `*.example.com`) always blocked, without a classifier call."],+ blocked_tlds: [type: {:list, :string}, doc: "Top-level domains to block outright, lowercase without a leading dot."],+ failure_policy: [type: {:or, [{:in, [:open, :closed]}, :string]}, doc: "Behavior when the classifier is unreachable: `closed` blocks (default), `open` allows."],+ mode: [type: {:or, [{:in, [:off, :normal]}, :string]}, required: true, doc: "Threat protection mode. `off` disables checks; `normal` checks URLs against Google Web Risk (+2 credits per URL scanned)."],+ risk_score_threshold: [type: :integer, doc: "Normalized score (0-100) at or above which a classifier verdict is blocked. Lower is stricter."],+ whitelist: [type: {:list, :string}, doc: "Exact domains or globs always allowed. Wins over every other rule."]+ ])- defp paginate_monitor_check_response!(%Req.Response{body: body} = response, opts) when is_map(body) do- data = Map.get(body, "data") || %{}- pages = Map.get(data, "pages") || []- next = Map.get(body, "next") || Map.get(data, "next")- pages = fetch_monitor_check_pages!(next, pages, opts)- data = data |> Map.put("pages", pages) |> Map.put("next", nil)- %{response | body: body |> Map.put("data", data) |> Map.put("next", nil)}- end+ @update_threat_protection_key_mapping %{allow_request_overrides: "allowRequestOverrides", blacklist: "blacklist", blocked_tlds: "blockedTlds", failure_policy: "failurePolicy", mode: "mode", risk_score_threshold: "riskScoreThreshold", whitelist: "whitelist"}- defp paginate_monitor_check_response!(response, _opts), do: response+ @doc """+ Update the team's threat protection policy- defp fetch_monitor_check_pages(nil, pages, _opts), do: pages- defp fetch_monitor_check_pages("", pages, _opts), do: pages+ `PUT /team/threat-protection`- defp fetch_monitor_check_pages(next, pages, opts) do- req = client(opts)+ Tag: Threat Protection- case Req.get(req, url: Firecrawl.ApiOrigin.pin(next, req.options.base_url)) do- {:ok, %Req.Response{body: body}} when is_map(body) ->- data = Map.get(body, "data") || %{}- next_pages = Map.get(data, "pages") || []- next_url = Map.get(body, "next") || Map.get(data, "next")- fetch_monitor_check_pages(next_url, pages ++ next_pages, opts)+ ## Parameters- _ ->- pages+ Validated by `NimbleOptions`. Pass params as a keyword list with snake_case keys.+ See `@update_threat_protection_schema` for the full schema.++ ## Returns++ * `{:ok, %Req.Response{}}` on success+ * `{:error, exception}` on HTTP or validation failure+ """+ @spec update_threat_protection(keyword(), keyword()) :: response()+ def update_threat_protection(params \\ [], opts \\ []) do+ with {:ok, params} <- NimbleOptions.validate(params, @update_threat_protection_schema) do+ Req.put(client(opts), url: "/team/threat-protection", json: to_body(params, @update_threat_protection_key_mapping))endend- defp fetch_monitor_check_pages!(nil, pages, _opts), do: pages- defp fetch_monitor_check_pages!("", pages, _opts), do: pages- defp fetch_monitor_check_pages!(next, pages, opts) do- req = client(opts)- response = Req.get!(req, url: Firecrawl.ApiOrigin.pin(next, req.options.base_url))- body = response.body- data = if is_map(body), do: Map.get(body, "data") || %{}, else: %{}- next_pages = Map.get(data, "pages") || []- next_url = if is_map(body), do: Map.get(body, "next") || Map.get(data, "next"), else: nil- fetch_monitor_check_pages!(next_url, pages ++ next_pages, opts)+ @doc """+ Bang variant of `update_threat_protection`. Raises on error.+ """+ @spec update_threat_protection!(keyword(), keyword()) :: Req.Response.t()+ def update_threat_protection!(params \\ [], opts \\ []) do+ params = NimbleOptions.validate!(params, @update_threat_protection_schema)+ Req.put!(client(opts), url: "/team/threat-protection", json: to_body(params, @update_threat_protection_key_mapping))endenddiff --git a/apps/elixir-sdk/openapi.json b/apps/elixir-sdk/openapi.jsonnew file mode 100644index 000000000..4f6bbc8a5--- /dev/null+++ b/apps/elixir-sdk/openapi.json@@ -0,0 +1,12353 @@+{+ "openapi": "3.0.0",+ "info": {+ "title": "Firecrawl API",+ "version": "v2",+ "description": "API for interacting with Firecrawl services to perform web scraping and crawling tasks.",+ "contact": {+ "name": "Firecrawl Support",+ "url": "https://firecrawl.dev/support",+ "email": "[email protected]"+ }+ },+ "servers": [+ {+ "url": "https://api.firecrawl.dev/v2"+ }+ ],+ "paths": {+ "/monitor": {+ "post": {+ "summary": "Create a monitor",+ "operationId": "createMonitor",+ "tags": [+ "Monitoring"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/MonitorCreateRequest"+ },+ "examples": {+ "scrapeMonitor": {+ "summary": "Scrape a URL every 30 minutes",+ "value": {+ "name": "Blog monitor",+ "schedule": {+ "text": "every 30 minutes",+ "timezone": "UTC"+ },+ "goal": "Notify me when a new blog post is published or the headline changes",+ "notification": {+ "email": {+ "enabled": true,+ "recipients": [+ ],+ "includeDiffs": true+ }+ },+ "targets": [+ {+ "type": "scrape",+ "urls": [+ "https://example.com/blog"+ ]+ }+ ]+ }+ },+ "crawlMonitor": {+ "summary": "Crawl a site on a cron schedule",+ "value": {+ "name": "Docs monitor",+ "schedule": {+ "cron": "7-59/15 * * * *",+ "timezone": "UTC"+ },+ "webhook": {+ "url": "https://example.com/webhooks/firecrawl",+ "events": [+ "monitor.page",+ "monitor.check.completed"+ ]+ },+ "goal": "Notify me when docs pages add, remove, or materially change API behavior",+ "targets": [+ {+ "type": "crawl",+ "url": "https://example.com/docs",+ "crawlOptions": {+ "limit": 100+ }+ }+ ]+ }+ }+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Monitor created",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/MonitorResponse"+ }+ }+ }+ },+ "400": {+ "description": "Invalid monitor request"+ }+ }+ },+ "get": {+ "summary": "List monitors",+ "operationId": "listMonitors",+ "tags": [+ "Monitoring"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "parameters": [+ {+ "name": "limit",+ "in": "query",+ "schema": {+ "type": "integer",+ "minimum": 1,+ "maximum": 100,+ "default": 25+ }+ },+ {+ "name": "offset",+ "in": "query",+ "schema": {+ "type": "integer",+ "minimum": 0,+ "default": 0+ }+ }+ ],+ "responses": {+ "200": {+ "description": "List of monitors",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/MonitorListResponse"+ }+ }+ }+ }+ }+ }+ },+ "/monitor/{monitorId}": {+ "get": {+ "summary": "Get a monitor",+ "operationId": "getMonitor",+ "tags": [+ "Monitoring"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "parameters": [+ {+ "$ref": "#/components/parameters/MonitorId"+ }+ ],+ "responses": {+ "200": {+ "description": "Monitor details",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/MonitorResponse"+ }+ }+ }+ },+ "404": {+ "description": "Monitor not found"+ }+ }+ },+ "patch": {+ "summary": "Update a monitor",+ "operationId": "updateMonitor",+ "tags": [+ "Monitoring"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "parameters": [+ {+ "$ref": "#/components/parameters/MonitorId"+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/MonitorUpdateRequest"+ },+ "example": {+ "schedule": {+ "text": "every 15 minutes starting at :07"+ },+ "status": "active"+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Monitor updated",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/MonitorResponse"+ }+ }+ }+ },+ "404": {+ "description": "Monitor not found"+ }+ }+ },+ "delete": {+ "summary": "Delete a monitor",+ "operationId": "deleteMonitor",+ "tags": [+ "Monitoring"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "parameters": [+ {+ "$ref": "#/components/parameters/MonitorId"+ }+ ],+ "responses": {+ "200": {+ "description": "Monitor deleted",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/SuccessResponse"+ }+ }+ }+ },+ "404": {+ "description": "Monitor not found"+ }+ }+ }+ },+ "/monitor/{monitorId}/run": {+ "post": {+ "summary": "Run a monitor",+ "operationId": "runMonitor",+ "tags": [+ "Monitoring"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "parameters": [+ {+ "$ref": "#/components/parameters/MonitorId"+ }+ ],+ "responses": {+ "200": {+ "description": "Monitor check queued",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/MonitorRunResponse"+ }+ }+ }+ },+ "409": {+ "description": "A monitor check is already running"+ }+ }+ }+ },+ "/monitor/{monitorId}/checks": {+ "get": {+ "summary": "List monitor checks",+ "operationId": "listMonitorChecks",+ "tags": [+ "Monitoring"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "parameters": [+ {+ "$ref": "#/components/parameters/MonitorId"+ },+ {+ "name": "limit",+ "in": "query",+ "schema": {+ "type": "integer",+ "minimum": 1,+ "maximum": 100,+ "default": 25+ }+ },+ {+ "name": "offset",+ "in": "query",+ "schema": {+ "type": "integer",+ "minimum": 0,+ "default": 0+ }+ },+ {+ "name": "status",+ "in": "query",+ "schema": {+ "type": "string",+ "enum": [+ "queued",+ "running",+ "completed",+ "failed",+ "partial",+ "skipped_overlap",+ "skipped_no_credits"+ ]+ },+ "description": "Filter checks by status."+ }+ ],+ "responses": {+ "200": {+ "description": "Monitor checks",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/MonitorCheckListResponse"+ }+ }+ }+ }+ }+ }+ },+ "/monitor/{monitorId}/checks/{checkId}": {+ "get": {+ "summary": "Get a monitor check",+ "operationId": "getMonitorCheck",+ "tags": [+ "Monitoring"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "parameters": [+ {+ "$ref": "#/components/parameters/MonitorId"+ },+ {+ "name": "checkId",+ "in": "path",+ "required": true,+ "schema": {+ "type": "string",+ "format": "uuid"+ },+ "description": "The monitor check ID"+ },+ {+ "name": "limit",+ "in": "query",+ "schema": {+ "type": "integer",+ "minimum": 1,+ "maximum": 100,+ "default": 25+ }+ },+ {+ "name": "skip",+ "in": "query",+ "schema": {+ "type": "integer",+ "minimum": 0,+ "default": 0+ },+ "description": "Number of page results to skip. Use the `next` URL from the previous response for pagination."+ },+ {+ "name": "status",+ "in": "query",+ "schema": {+ "type": "string",+ "enum": [+ "same",+ "new",+ "changed",+ "removed",+ "error"+ ]+ }+ }+ ],+ "responses": {+ "200": {+ "description": "Monitor check details",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/MonitorCheckDetailResponse"+ }+ }+ }+ },+ "404": {+ "description": "Monitor check not found"+ }+ }+ }+ },+ "/scrape": {+ "post": {+ "summary": "Scrape a single URL and optionally extract information using an LLM",+ "operationId": "scrapeAndExtractFromUrl",+ "tags": [+ "Scraping"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "allOf": [+ {+ "type": "object",+ "properties": {+ "url": {+ "type": "string",+ "format": "uri",+ "description": "The URL to scrape"+ }+ },+ "required": [+ "url"+ ]+ },+ {+ "$ref": "#/components/schemas/ScrapeOptions"+ },+ {+ "type": "object",+ "properties": {+ "zeroDataRetention": {+ "type": "boolean",+ "default": false,+ "description": "If true, this will enable zero data retention for this scrape. To enable this feature, please contact [email protected]"+ }+ }+ },+ {+ "type": "object",+ "properties": {+ "alexandria": {+ "oneOf": [+ {+ "$ref": "#/components/schemas/AlexandriaCall"+ },+ {+ "type": "array",+ "minItems": 1,+ "maxItems": 10,+ "items": {+ "$ref": "#/components/schemas/AlexandriaCall"+ }+ }+ ],+ "description": "Execute one or more catalogued provider tools instead of scraping a URL. Cannot be combined with `url`, `formats`, or other scrape options (400); the only allowed sibling keys are `timeout`, `origin`, and `integration`. Use the `x-request-id` request header as a client-chosen idempotency key (1 to 128 characters of letters, digits, `.`, `_`, `:`, `-`) — it is echoed back, and a completed request with the same key replays its original response and `scrape_id` instead of re-executing."+ },+ "domainTools": {+ "type": "boolean",+ "default": false,+ "description": "When true on an ordinary URL scrape, `data.tools` lists tool contracts matched to the scraped page's domain (same `DiscoveredTool` shape as search). Requires the team's Alexandria access to be enabled and no zero data retention (403 otherwise). Free."+ }+ }+ }+ ]+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successful response",+ "content": {+ "application/json": {+ "schema": {+ "oneOf": [+ {+ "$ref": "#/components/schemas/ScrapeResponse"+ },+ {+ "$ref": "#/components/schemas/AlexandriaScrapeResponse"+ }+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string",+ "example": "Bad request. `alexandria` cannot be combined with `url`, `formats`, or other scrape options, and only recognizes `provider`, `capability`, and `options`."+ },+ "code": {+ "type": "string"+ },+ "chargeId": {+ "type": "string"+ }+ }+ }+ }+ }+ },+ "402": {+ "description": "Payment required. Also returned as `insufficient_credits` when the team lacks the credits to execute an `alexandria` request; in that case nothing is executed.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string",+ "example": "Payment required to access this resource."+ },+ "code": {+ "type": "string",+ "example": "insufficient_credits"+ },+ "chargeId": {+ "type": "string"+ }+ }+ }+ }+ }+ },+ "403": {+ "description": "Forbidden. Returned when `alexandria` execution or `domainTools` is not enabled for the team, when zero data retention is active, or when third-party data terms have not been accepted (`THIRD_PARTY_DATA_TERMS_REQUIRED`, which includes `requiresAction`).",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string"+ },+ "code": {+ "type": "string",+ "example": "THIRD_PARTY_DATA_TERMS_REQUIRED"+ },+ "requiresAction": {+ "type": "boolean",+ "description": "Present when the team must take action (e.g. accept third-party data terms) before this request can be retried."+ },+ "chargeId": {+ "type": "string"+ }+ }+ }+ }+ }+ },+ "404": {+ "description": "Not found. Returned as `unknown_provider` when an `alexandria` call references a provider or capability that does not exist; nothing is executed.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string"+ },+ "code": {+ "type": "string",+ "example": "unknown_provider"+ },+ "chargeId": {+ "type": "string"+ }+ }+ }+ }+ }+ },+ "409": {+ "description": "Conflict. Returned as `duplicate_request` or `request_in_flight` when the same `x-request-id` is reused while the original request is still being processed or was already completed with different parameters.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string"+ },+ "code": {+ "type": "string",+ "example": "duplicate_request"+ },+ "chargeId": {+ "type": "string",+ "description": "The charge ID of the in-flight or original request."+ }+ }+ }+ }+ }+ },+ "429": {+ "description": "Too many requests",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Request rate limit exceeded. Please wait and try again later."+ }+ }+ }+ }+ }+ },+ "500": {+ "description": "Server error",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "code": {+ "type": "string",+ "example": "UNKNOWN_ERROR"+ },+ "error": {+ "type": "string",+ "example": "An unexpected error occurred on the server."+ }+ }+ }+ }+ }+ },+ "503": {+ "description": "Service unavailable. Returned as `request_unresolved` when the outcome of an in-flight `alexandria` request with this `x-request-id` could not be determined — keep the same `x-request-id` and retry rather than issuing a new request. Also returned as `billing_unavailable` when credits could not be charged.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string"+ },+ "code": {+ "type": "string",+ "example": "request_unresolved"+ },+ "chargeId": {+ "type": "string",+ "description": "The charge ID of the unresolved request. Reuse the same `x-request-id` to retry; do not create a new request."+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/scrape/{jobId}/interact": {+ "post": {+ "summary": "Interact with the browser session associated with a scrape job",+ "operationId": "interactWithScrapeBrowserSession",+ "tags": [+ "Scraping"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "parameters": [+ {+ "name": "jobId",+ "in": "path",+ "required": true,+ "schema": {+ "type": "string",+ "format": "uuid"+ },+ "description": "The scrape job ID"+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "required": [+ "code"+ ],+ "properties": {+ "code": {+ "type": "string",+ "minLength": 1,+ "maxLength": 100000,+ "description": "Code to execute in the scrape-bound browser sandbox"+ },+ "language": {+ "type": "string",+ "enum": [+ "python",+ "node",+ "bash"+ ],+ "default": "node",+ "description": "Language of the code to execute. Use `node` for JavaScript or `bash` for agent-browser CLI commands."+ },+ "timeout": {+ "type": "integer",+ "minimum": 1,+ "maximum": 300,+ "default": 30,+ "description": "Execution timeout in seconds"+ },+ "origin": {+ "type": "string",+ "description": "Optional origin label used for execution telemetry"+ }+ }+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Code executed successfully",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ },+ "cdpUrl": {+ "type": "string",+ "nullable": true,+ "description": "Raw Chrome DevTools Protocol (CDP) WebSocket URL for the browser session. Use it to connect directly with Playwright, Puppeteer, or any CDP client."+ },+ "liveViewUrl": {+ "type": "string",+ "nullable": true,+ "description": "Read-only live view URL for the browser session"+ },+ "interactiveLiveViewUrl": {+ "type": "string",+ "nullable": true,+ "description": "Interactive live view URL (viewers can control the browser)"+ },+ "output": {+ "type": "string",+ "nullable": true,+ "description": "AI agent's final response (only present when using prompt)"+ },+ "stdout": {+ "type": "string",+ "nullable": true,+ "description": "Standard output from the code execution"+ },+ "result": {+ "type": "string",+ "nullable": true,+ "description": "Standard output (alias for stdout)"+ },+ "stderr": {+ "type": "string",+ "nullable": true,+ "description": "Standard error output from the code execution"+ },+ "exitCode": {+ "type": "integer",+ "nullable": true,+ "description": "Exit code of the executed process"+ },+ "killed": {+ "type": "boolean",+ "description": "Whether the process was killed due to timeout"+ },+ "error": {+ "type": "string",+ "nullable": true,+ "description": "Error message if the code raised an exception"+ }+ }+ }+ }+ }+ },+ "400": {+ "description": "Invalid job ID",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string",+ "example": "Invalid job ID format."+ }+ }+ }+ }+ }+ },+ "402": {+ "description": "Payment required",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string",+ "example": "Payment required to access this resource."+ }+ }+ }+ }+ }+ },+ "403": {+ "description": "Forbidden",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string",+ "example": "Forbidden."+ }+ }+ }+ }+ }+ },+ "404": {+ "description": "Scrape job not found",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string",+ "example": "Job not found."+ }+ }+ }+ }+ }+ },+ "409": {+ "description": "Scrape replay context is unavailable or session could not be initialized",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string",+ "example": "Replay context is unavailable for this scrape job. Please rerun the scrape."+ }+ }+ }+ }+ }+ },+ "410": {+ "description": "Scrape browser session has already been destroyed",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string",+ "example": "Browser session has been destroyed."+ }+ }+ }+ }+ }+ },+ "429": {+ "description": "Too many active browser sessions",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string",+ "example": "You have reached the maximum number of active browser sessions."+ }+ }+ }+ }+ }+ },+ "502": {+ "description": "Failed to communicate with browser service",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string",+ "example": "Failed to execute code in browser session."+ }+ }+ }+ }+ }+ }+ }+ },+ "delete": {+ "summary": "Stop the interactive browser session associated with a scrape job",+ "operationId": "stopInteractiveScrapeBrowserSession",+ "tags": [+ "Scraping"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "parameters": [+ {+ "name": "jobId",+ "in": "path",+ "required": true,+ "schema": {+ "type": "string",+ "format": "uuid"+ },+ "description": "The scrape job ID"+ }+ ],+ "responses": {+ "200": {+ "description": "Interactive scrape browser session stopped successfully",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ }+ }+ }+ }+ }+ },+ "403": {+ "description": "Forbidden",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string",+ "example": "Forbidden."+ }+ }+ }+ }+ }+ },+ "404": {+ "description": "Interactive scrape browser session not found",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string",+ "example": "Browser session not found."+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/parse": {+ "post": {+ "summary": "Upload and parse a file",+ "operationId": "parseFile",+ "tags": [+ "Scraping"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "multipart/form-data": {+ "schema": {+ "type": "object",+ "properties": {+ "file": {+ "type": "string",+ "format": "binary",+ "description": "The file bytes to parse. Supported extensions: .html, .htm, .xhtml, .pdf, .docx, .doc, .docm, .odt, .ods, .odp, .rtf, .xlsx, .xls, .xlsm, .xlsb, .pptx, .ppt, .pptm, .epub, .csv."+ },+ "options": {+ "$ref": "#/components/schemas/ParseOptions"+ }+ },+ "required": [+ "file"+ ]+ },+ "encoding": {+ "options": {+ "contentType": "application/json"+ }+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successful response",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ScrapeResponse"+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "code": {+ "type": "string",+ "example": "BAD_REQUEST"+ },+ "error": {+ "type": "string",+ "example": "Invalid multipart form-data request."+ }+ }+ }+ }+ }+ },+ "402": {+ "description": "Payment required",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Payment required to access this resource."+ }+ }+ }+ }+ }+ },+ "429": {+ "description": "Too many requests",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Request rate limit exceeded. Please wait and try again later."+ }+ }+ }+ }+ }+ },+ "500": {+ "description": "Server error",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "code": {+ "type": "string",+ "example": "UNKNOWN_ERROR"+ },+ "error": {+ "type": "string",+ "example": "An unexpected error occurred on the server."+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/parse/formats": {+ "get": {+ "summary": "List file formats supported by /parse",+ "operationId": "getParseFormats",+ "tags": [+ "Scraping"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "Supported formats. Responses can be cached for up to an hour (`Cache-Control: private, max-age=3600`).",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": true+ },+ "data": {+ "type": "object",+ "properties": {+ "formats": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "format": {+ "type": "string",+ "description": "Short name of the format, the canonical extension without the dot.",+ "example": "docx"+ },+ "kind": {+ "type": "string",+ "enum": [+ "document",+ "image"+ ],+ "description": "Whether the format is parsed as a document or OCR'd as an image.",+ "example": "document"+ },+ "extensions": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "File extensions accepted for this format, canonical first.",+ "example": [+ ".docx"+ ]+ },+ "mimeTypes": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "MIME types accepted for this format.",+ "example": [+ "application/vnd.openxmlformats-officedocument.wordprocessingml.document"+ ]+ },+ "available": {+ "type": "boolean",+ "description": "Whether `/parse` accepts this format for your requests right now. Always `true` for documents; image formats are `false` where image OCR is not enabled.",+ "example": true+ }+ }+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "401": {+ "description": "Missing or invalid API key",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string",+ "example": "Unauthorized: Invalid token"+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/batch/scrape": {+ "post": {+ "summary": "Scrape multiple URLs and optionally extract information using an LLM",+ "operationId": "scrapeAndExtractFromUrls",+ "tags": [+ "Scraping"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "allOf": [+ {+ "type": "object",+ "properties": {+ "urls": {+ "type": "array",+ "items": {+ "type": "string",+ "format": "uri",+ "description": "The URL to scrape"+ }+ },+ "webhook": {+ "type": "object",+ "description": "A webhook specification object.",+ "properties": {+ "url": {+ "type": "string",+ "description": "The URL to send the webhook to. This will trigger for batch scrape started (batch_scrape.started), every page scraped (batch_scrape.page) and when the batch scrape is completed (batch_scrape.completed or batch_scrape.failed). The response will be the same as the `/scrape` endpoint."+ },+ "headers": {+ "type": "object",+ "description": "Headers to send to the webhook URL.",+ "additionalProperties": {+ "type": "string"+ }+ },+ "metadata": {+ "type": "object",+ "description": "Custom metadata that will be included in all webhook payloads for this crawl",+ "additionalProperties": true+ },+ "events": {+ "type": "array",+ "description": "Type of events that should be sent to the webhook URL. (default: all)",+ "items": {+ "type": "string",+ "enum": [+ "completed",+ "page",+ "failed",+ "started"+ ]+ }+ }+ },+ "required": [+ "url"+ ]+ },+ "maxConcurrency": {+ "type": "integer",+ "description": "Maximum number of concurrent scrapes. This parameter allows you to set a concurrency limit for this batch scrape. If not specified, the batch scrape adheres to your team's concurrency limit."+ },+ "ignoreInvalidURLs": {+ "type": "boolean",+ "default": true,+ "description": "If invalid URLs are specified in the urls array, they will be ignored. Instead of them failing the entire request, a batch scrape using the remaining valid URLs will be created, and the invalid URLs will be returned in the invalidURLs field of the response."+ }+ },+ "required": [+ "urls"+ ]+ },+ {+ "$ref": "#/components/schemas/ScrapeOptions"+ },+ {+ "type": "object",+ "properties": {+ "zeroDataRetention": {+ "type": "boolean",+ "default": false,+ "description": "If true, this will enable zero data retention for this batch scrape. To enable this feature, please contact [email protected]"+ }+ }+ }+ ]+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successful response",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/BatchScrapeResponseObj"+ }+ }+ }+ },+ "402": {+ "description": "Payment required",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Payment required to access this resource."+ }+ }+ }+ }+ }+ },+ "429": {+ "description": "Too many requests",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Request rate limit exceeded. Please wait and try again later."+ }+ }+ }+ }+ }+ },+ "500": {+ "description": "Server error",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "An unexpected error occurred on the server."+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/batch/scrape/{id}": {+ "parameters": [+ {+ "name": "id",+ "in": "path",+ "description": "The ID of the batch scrape job",+ "required": true,+ "schema": {+ "type": "string",+ "format": "uuid"+ }+ }+ ],+ "get": {+ "summary": "Get the status of a batch scrape job",+ "operationId": "getBatchScrapeStatus",+ "tags": [+ "Scraping"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "Successful response",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/BatchScrapeStatusResponseObj"+ }+ }+ }+ },+ "402": {+ "description": "Payment required",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Payment required to access this resource."+ }+ }+ }+ }+ }+ },+ "429": {+ "description": "Too many requests",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Request rate limit exceeded. Please wait and try again later."+ }+ }+ }+ }+ }+ },+ "500": {+ "description": "Server error",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "An unexpected error occurred on the server."+ }+ }+ }+ }+ }+ }+ }+ },+ "delete": {+ "summary": "Cancel a batch scrape job",+ "operationId": "cancelBatchScrape",+ "tags": [+ "Scraping"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "Successful cancellation",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "status": {+ "type": "string",+ "enum": [+ "cancelled"+ ],+ "example": "cancelled"+ }+ }+ }+ }+ }+ },+ "404": {+ "description": "Batch scrape job not found",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Batch scrape job not found."+ }+ }+ }+ }+ }+ },+ "500": {+ "description": "Server error",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "An unexpected error occurred on the server."+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/batch/scrape/{id}/errors": {+ "parameters": [+ {+ "name": "id",+ "in": "path",+ "description": "The ID of the batch scrape job",+ "required": true,+ "schema": {+ "type": "string",+ "format": "uuid"+ }+ }+ ],+ "get": {+ "summary": "Get the errors of a batch scrape job",+ "operationId": "getBatchScrapeErrors",+ "tags": [+ "Scraping"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "Successful response",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/CrawlErrorsResponseObj"+ }+ }+ }+ },+ "402": {+ "description": "Payment required",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Payment required to access this resource."+ }+ }+ }+ }+ }+ },+ "429": {+ "description": "Too many requests",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Request rate limit exceeded. Please wait and try again later."+ }+ }+ }+ }+ }+ },+ "500": {+ "description": "Server error",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "An unexpected error occurred on the server."+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/crawl/{id}": {+ "parameters": [+ {+ "name": "id",+ "in": "path",+ "description": "The ID of the crawl job",+ "required": true,+ "schema": {+ "type": "string",+ "format": "uuid"+ }+ }+ ],+ "get": {+ "summary": "Get the status of a crawl job",+ "operationId": "getCrawlStatus",+ "tags": [+ "Crawling"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "Successful response",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/CrawlStatusResponseObj"+ }+ }+ }+ },+ "402": {+ "description": "Payment required",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Payment required to access this resource."+ }+ }+ }+ }+ }+ },+ "429": {+ "description": "Too many requests",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Request rate limit exceeded. Please wait and try again later."+ }+ }+ }+ }+ }+ },+ "500": {+ "description": "Server error",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "An unexpected error occurred on the server."+ }+ }+ }+ }+ }+ }+ }+ },+ "delete": {+ "summary": "Cancel a crawl job",+ "operationId": "cancelCrawl",+ "tags": [+ "Crawling"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "Successful cancellation",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "status": {+ "type": "string",+ "enum": [+ "cancelled"+ ],+ "example": "cancelled"+ }+ }+ }+ }+ }+ },+ "404": {+ "description": "Crawl job not found",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Crawl job not found."+ }+ }+ }+ }+ }+ },+ "500": {+ "description": "Server error",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "An unexpected error occurred on the server."+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/crawl/{id}/errors": {+ "parameters": [+ {+ "name": "id",+ "in": "path",+ "description": "The ID of the crawl job",+ "required": true,+ "schema": {+ "type": "string",+ "format": "uuid"+ }+ }+ ],+ "get": {+ "summary": "Get the errors of a crawl job",+ "operationId": "getCrawlErrors",+ "tags": [+ "Crawling"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "Successful response",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/CrawlErrorsResponseObj"+ }+ }+ }+ },+ "402": {+ "description": "Payment required",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Payment required to access this resource."+ }+ }+ }+ }+ }+ },+ "429": {+ "description": "Too many requests",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Request rate limit exceeded. Please wait and try again later."+ }+ }+ }+ }+ }+ },+ "500": {+ "description": "Server error",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "An unexpected error occurred on the server."+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/crawl": {+ "post": {+ "summary": "Crawl multiple URLs based on options",+ "operationId": "crawlUrls",+ "tags": [+ "Crawling"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "url": {+ "type": "string",+ "format": "uri",+ "description": "The base URL to start crawling from"+ },+ "prompt": {+ "type": "string",+ "description": "A prompt to use to generate the crawler options (all the parameters below) from natural language. Explicitly set parameters will override the generated equivalents."+ },+ "excludePaths": {+ "type": "array",+ "maxItems": 1000,+ "items": {+ "type": "string",+ "maxLength": 2000+ },+ "description": "URL pathname regex patterns that exclude matching URLs from the crawl. For example, if you set \"excludePaths\": [\"blog/.*\"] for the base URL firecrawl.dev, any results matching that pattern will be excluded, such as https://www.firecrawl.dev/blog/firecrawl-launch-week-1-recap. Patterns use Rust regex (RE2-style) syntax: look-around and backreferences are not supported, and a pattern that does not compile is rejected with a 400. Each field accepts at most 1000 patterns of at most 2000 characters each, and includePaths and excludePaths together may contain at most 1000 patterns and 100,000 characters in total. For keyword-style filtering, send one short pattern per term rather than combining terms into a single long alternation."+ },+ "includePaths": {+ "type": "array",+ "maxItems": 1000,+ "items": {+ "type": "string",+ "maxLength": 2000+ },+ "description": "URL pathname regex patterns that include matching URLs in the crawl. Only the paths that match the specified patterns will be included in the response. Note: the starting URL is also checked against these patterns — if it does not match, the crawl may return 0 pages. For example, if you set \"includePaths\": [\"blog/.*\"] for the base URL firecrawl.dev/blog, only pages under /blog/ will be included in the results, such as https://www.firecrawl.dev/blog/firecrawl-launch-week-1-recap. Patterns use Rust regex (RE2-style) syntax: look-around and backreferences are not supported, and a pattern that does not compile is rejected with a 400. Each field accepts at most 1000 patterns of at most 2000 characters each, and includePaths and excludePaths together may contain at most 1000 patterns and 100,000 characters in total. For keyword-style filtering, send one short pattern per term rather than combining terms into a single long alternation."+ },+ "maxDiscoveryDepth": {+ "type": "integer",+ "description": "Maximum depth to crawl based on discovery order. The root site and sitemapped pages has a discovery depth of 0. For example, if you set it to 1, and you set `sitemap: 'skip'`, you will only crawl the entered URL and all URLs that are linked on that page."+ },+ "sitemap": {+ "type": "string",+ "enum": [+ "skip",+ "include",+ "only"+ ],+ "description": "Sitemap mode when crawling. If you set it to 'skip', the crawler will ignore the website sitemap and only crawl the entered URL and discover pages from there onwards. If you set it to 'only', the crawler will only crawl URLs from the sitemap (plus the start URL) and will not discover links from HTML.",+ "default": "include"+ },+ "ignoreQueryParameters": {+ "type": "boolean",+ "description": "Do not re-scrape the same path with different (or none) query parameters",+ "default": false+ },+ "regexOnFullURL": {+ "type": "boolean",+ "description": "When true, includePaths and excludePaths regex patterns are matched against the full URL (including query parameters) instead of just the URL pathname. Useful when you need to filter URLs based on query strings.",+ "default": false+ },+ "limit": {+ "type": "integer",+ "description": "Maximum number of pages to crawl. Default limit is 10000.",+ "default": 10000+ },+ "crawlEntireDomain": {+ "type": "boolean",+ "description": "Allows the crawler to follow internal links to sibling or parent URLs, not just child paths.\n\nfalse: Only crawls deeper (child) URLs.\n→ e.g. /features/feature-1 → /features/feature-1/tips ✅\n→ Won't follow /pricing or / ❌\n\ntrue: Crawls any internal links, including siblings and parents.\n→ e.g. /features/feature-1 → /pricing, /, etc. ✅\n\nUse true for broader internal coverage beyond nested paths.",+ "default": false+ },+ "allowExternalLinks": {+ "type": "boolean",+ "description": "Allows the crawler to follow links to external websites. External links are followed one hop (the links found on those external pages are not crawled). Links pointing to an external site's homepage (a root URL with no path) are skipped and reported in Get Crawl Errors with the code EXTERNAL_LINK; redirects to an external homepage are skipped for the same reason.",+ "default": false+ },+ "allowSubdomains": {+ "type": "boolean",+ "description": "Allows the crawler to follow links to subdomains of the main domain.",+ "default": false+ },+ "ignoreRobotsTxt": {+ "type": "boolean",+ "description": "Ignore the website's robots.txt rules. Enterprise only — contact [email protected] to enable.",+ "default": false+ },+ "robotsUserAgent": {+ "type": "string",+ "description": "Custom User-Agent string for robots.txt evaluation. When set, robots.txt is fetched with this User-Agent and allow/disallow rules are matched against it instead of the default. Enterprise only — contact [email protected] to enable."+ },+ "delay": {+ "type": "number",+ "description": "Delay in seconds between scrapes. This helps respect website rate limits. Setting this forces concurrency to 1."+ },+ "maxConcurrency": {+ "type": "integer",+ "description": "Maximum number of concurrent scrapes. This parameter allows you to set a concurrency limit for this crawl. If not specified, the crawl adheres to your team's concurrency limit."+ },+ "webhook": {+ "type": "object",+ "description": "A webhook specification object.",+ "properties": {+ "url": {+ "type": "string",+ "description": "The URL to send the webhook to. This will trigger for crawl started (crawl.started), every page crawled (crawl.page) and when the crawl is completed (crawl.completed or crawl.failed). The response will be the same as the `/scrape` endpoint."+ },+ "headers": {+ "type": "object",+ "description": "Headers to send to the webhook URL.",+ "additionalProperties": {+ "type": "string"+ }+ },+ "metadata": {+ "type": "object",+ "description": "Custom metadata that will be included in all webhook payloads for this crawl",+ "additionalProperties": true+ },+ "events": {+ "type": "array",+ "description": "Type of events that should be sent to the webhook URL. (default: all)",+ "items": {+ "type": "string",+ "enum": [+ "completed",+ "page",+ "failed",+ "started"+ ]+ }+ }+ },+ "required": [+ "url"+ ]+ },+ "scrapeOptions": {+ "$ref": "#/components/schemas/ScrapeOptions"+ },+ "zeroDataRetention": {+ "type": "boolean",+ "default": false,+ "description": "If true, this will enable zero data retention for this crawl. To enable this feature, please contact [email protected]"+ }+ },+ "required": [+ "url"+ ]+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successful response",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/CrawlResponse"+ }+ }+ }+ },+ "402": {+ "description": "Payment required",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Payment required to access this resource."+ }+ }+ }+ }+ }+ },+ "429": {+ "description": "Too many requests",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Request rate limit exceeded. Please wait and try again later."+ }+ }+ }+ }+ }+ },+ "500": {+ "description": "Server error",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "An unexpected error occurred on the server."+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/crawl/params-preview": {+ "post": {+ "summary": "Preview crawl parameters generated from natural language prompt",+ "operationId": "crawlParamsPreview",+ "tags": [+ "Crawling"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "url": {+ "type": "string",+ "format": "uri",+ "description": "The URL to crawl"+ },+ "prompt": {+ "type": "string",+ "maxLength": 10000,+ "description": "Natural language prompt describing what you want to crawl"+ }+ },+ "required": [+ "url",+ "prompt"+ ]+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successful response with generated crawl parameters",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": true+ },+ "data": {+ "type": "object",+ "properties": {+ "url": {+ "type": "string",+ "format": "uri",+ "description": "The URL to crawl"+ },+ "includePaths": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "URL patterns to include"+ },+ "excludePaths": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "URL patterns to exclude"+ },+ "maxDepth": {+ "type": "integer",+ "description": "Maximum crawl depth"+ },+ "maxDiscoveryDepth": {+ "type": "integer",+ "description": "Maximum discovery depth"+ },+ "crawlEntireDomain": {+ "type": "boolean",+ "description": "Whether to crawl the entire domain"+ },+ "allowExternalLinks": {+ "type": "boolean",+ "description": "Whether to allow external links"+ },+ "allowSubdomains": {+ "type": "boolean",+ "description": "Whether to allow subdomains"+ },+ "sitemap": {+ "type": "string",+ "enum": [+ "skip",+ "include"+ ],+ "description": "Sitemap handling strategy"+ },+ "ignoreQueryParameters": {+ "type": "boolean",+ "description": "Whether to ignore query parameters"+ },+ "ignoreRobotsTxt": {+ "type": "boolean",+ "description": "Whether robots.txt rules are ignored"+ },+ "robotsUserAgent": {+ "type": "string",+ "description": "Custom User-Agent string used for robots.txt evaluation"+ },+ "deduplicateSimilarURLs": {+ "type": "boolean",+ "description": "Whether to deduplicate similar URLs"+ },+ "delay": {+ "type": "number",+ "description": "Delay between requests in milliseconds"+ },+ "limit": {+ "type": "integer",+ "description": "Maximum number of pages to crawl"+ }+ }+ }+ }+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string",+ "example": "Invalid request parameters"+ }+ }+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string",+ "example": "Unauthorized"+ }+ }+ }+ }+ }+ },+ "500": {+ "description": "Server error",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string",+ "example": "Failed to process natural language prompt"+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/map": {+ "post": {+ "summary": "Map multiple URLs based on options",+ "operationId": "mapUrls",+ "tags": [+ "Mapping"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "url": {+ "type": "string",+ "format": "uri",+ "description": "The base URL to start crawling from"+ },+ "search": {+ "type": "string",+ "description": "Specify a search query to order the results by relevance. Example: 'blog' will return URLs that contain the word 'blog' in the URL ordered by relevance."+ },+ "sitemap": {+ "type": "string",+ "enum": [+ "skip",+ "include",+ "only"+ ],+ "description": "Sitemap mode when mapping. If you set it to `skip`, the sitemap won't be used to find URLs. If you set it to `only`, only URLs that are in the sitemap will be returned. By default (`include`), the sitemap and other methods will be used together to find URLs.",+ "default": "include"+ },+ "includeSubdomains": {+ "type": "boolean",+ "description": "Include subdomains of the website",+ "default": true+ },+ "ignoreQueryParameters": {+ "type": "boolean",+ "description": "Do not return URLs with query parameters",+ "default": true+ },+ "ignoreCache": {+ "type": "boolean",+ "description": "Bypass the sitemap cache to retrieve fresh URLs. Sitemap data is cached for up to 7 days; use this parameter when your sitemap has been recently updated.",+ "default": false+ },+ "limit": {+ "type": "integer",+ "description": "Maximum number of links to return",+ "default": 5000,+ "maximum": 100000+ },+ "timeout": {+ "type": "integer",+ "description": "Timeout in milliseconds. There is no timeout by default."+ },+ "location": {+ "type": "object",+ "description": "Location settings for the request. When specified, this will use an appropriate proxy if available and emulate the corresponding language and timezone settings. Defaults to 'US' if not specified.",+ "properties": {+ "country": {+ "type": "string",+ "description": "ISO 3166-1 alpha-2 country code (e.g., 'US', 'AU', 'DE', 'JP')",+ "pattern": "^[A-Z]{2}$",+ "default": "US"+ },+ "languages": {+ "type": "array",+ "description": "Preferred languages and locales for the request in order of priority. Defaults to the language of the specified location. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language",+ "items": {+ "type": "string",+ "example": "en-US"+ }+ }+ }+ },+ "auditMetadata": {+ "$ref": "#/components/schemas/AuditMetadata"+ },+ "threatProtection": {+ "$ref": "#/components/schemas/ThreatProtectionOverride"+ }+ },+ "required": [+ "url"+ ]+ },+ "examples": {+ "example1": {+ "summary": "Example 1",+ "value": {+ "url": "<string>",+ "search": "<string>",+ "sitemap": "include",+ "includeSubdomains": true,+ "ignoreQueryParameters": true,+ "ignoreCache": false,+ "limit": 5000,+ "location": {+ "country": "US",+ "languages": [+ "en-US"+ ]+ },+ "timeout": 60000+ }+ }+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successful response",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/MapResponse"+ }+ }+ }+ },+ "402": {+ "description": "Payment required",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Payment required to access this resource."+ }+ }+ }+ }+ }+ },+ "429": {+ "description": "Too many requests",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Request rate limit exceeded. Please wait and try again later."+ }+ }+ }+ }+ }+ },+ "500": {+ "description": "Server error",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "An unexpected error occurred on the server."+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/extract": {+ "post": {+ "summary": "Extract structured data from pages using LLMs",+ "operationId": "extractData",+ "tags": [+ "Extraction"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "urls": {+ "type": "array",+ "items": {+ "type": "string",+ "format": "uri",+ "description": "The URLs to extract data from. URLs should be in glob format."+ }+ },+ "prompt": {+ "type": "string",+ "description": "Prompt to guide the extraction process"+ },+ "schema": {+ "type": "object",+ "description": "Schema to define the structure of the extracted data. Must conform to [JSON Schema](https://json-schema.org/)."+ },+ "enableWebSearch": {+ "type": "boolean",+ "description": "When true, the extraction will use web search to find additional data",+ "default": false+ },+ "ignoreSitemap": {+ "type": "boolean",+ "description": "When true, sitemap.xml files will be ignored during website scanning",+ "default": false+ },+ "includeSubdomains": {+ "type": "boolean",+ "description": "When true, subdomains of the provided URLs will also be scanned",+ "default": true+ },+ "showSources": {+ "type": "boolean",+ "description": "When true, the sources used to extract the data will be included in the response as `sources` key",+ "default": false+ },+ "scrapeOptions": {+ "$ref": "#/components/schemas/ScrapeOptions"+ },+ "ignoreInvalidURLs": {+ "type": "boolean",+ "default": true,+ "description": "If invalid URLs are specified in the urls array, they will be ignored. Instead of them failing the entire request, an extract using the remaining valid URLs will be performed, and the invalid URLs will be returned in the invalidURLs field of the response."+ },+ "threatProtection": {+ "$ref": "#/components/schemas/ThreatProtectionOverride"+ }+ },+ "required": [+ "urls"+ ]+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successful extraction",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ExtractResponse"+ }+ }+ }+ },+ "400": {+ "description": "Invalid request",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Invalid input data."+ }+ }+ }+ }+ }+ },+ "500": {+ "description": "Server error",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "An unexpected error occurred on the server."+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/extract/{id}": {+ "parameters": [+ {+ "name": "id",+ "in": "path",+ "description": "The ID of the extract job",+ "required": true,+ "schema": {+ "type": "string",+ "format": "uuid"+ }+ }+ ],+ "get": {+ "summary": "Get the status of an extract job",+ "operationId": "getExtractStatus",+ "tags": [+ "Extraction"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "Successful response",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ExtractStatusResponse"+ }+ }+ }+ }+ }+ }+ },+ "/agent": {+ "get": {+ "summary": "List agent runs",+ "operationId": "listAgents",+ "tags": [+ "Agent"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "parameters": [+ {+ "name": "before",+ "in": "query",+ "required": false,+ "schema": {+ "type": "integer",+ "minimum": 0+ },+ "description": "Only return agent runs created before this unix millisecond timestamp. Pages are fixed at 20 runs; use the `before` value from the previous page's `next` URL to fetch the next page."+ }+ ],+ "responses": {+ "200": {+ "description": "List of agent runs, most recent first",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ },+ "agents": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "uuid"+ },+ "createdAt": {+ "type": "string",+ "format": "date-time"+ },+ "targetHint": {+ "type": "string",+ "description": "Short hint describing the run's target (first URL or prompt)"+ },+ "origin": {+ "type": "string",+ "description": "Origin of the run (e.g. \"api\")"+ },+ "integration": {+ "type": "string",+ "description": "Integration identifier, if the run was started with one"+ },+ "settings": {+ "type": "object",+ "properties": {+ "hidden": {+ "type": "boolean"+ },+ "starred": {+ "type": "boolean"+ },+ "label": {+ "type": "string"+ }+ }+ },+ "status": {+ "type": "string",+ "enum": [+ "processing",+ "completed",+ "failed"+ ]+ },+ "options": {+ "type": "object",+ "description": "Options the run was started with",+ "properties": {+ "urls": {+ "type": "array",+ "items": {+ "type": "string",+ "format": "uri"+ }+ },+ "prompt": {+ "type": "string"+ },+ "schema": {+ "type": "object"+ },+ "model": {+ "type": "string",+ "enum": [+ "spark-2",+ "spark-1-pro",+ "spark-1-mini"+ ],+ "description": "Model preset used for the agent run. Every new run executes on spark-2; Spark 1 names only appear on legacy runs."+ },+ "effort": {+ "type": "string",+ "enum": [+ "low",+ "medium",+ "high"+ ],+ "description": "Reasoning budget used for the agent run (only present for runs that set effort)"+ }+ }+ }+ }+ }+ },+ "next": {+ "type": "string",+ "description": "Absolute URL of the next page. Only present when more pages exist."+ }+ }+ }+ }+ }+ },+ "400": {+ "description": "Bad request — the before timestamp is invalid.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Invalid before timestamp."+ }+ }+ }+ }+ }+ }+ }+ },+ "post": {+ "summary": "Start an agent task for agentic data extraction",+ "operationId": "startAgent",+ "tags": [+ "Agent"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "urls": {+ "type": "array",+ "items": {+ "type": "string",+ "format": "uri"+ },+ "description": "Optional list of URLs to constrain the agent to"+ },+ "prompt": {+ "type": "string",+ "description": "The prompt describing what data to extract",+ "maxLength": 10000+ },+ "schema": {+ "type": "object",+ "description": "Optional JSON schema to structure the extracted data"+ },+ "maxCredits": {+ "type": "number",+ "description": "Maximum credits to spend on this agent task. Defaults to 2500 if not set. Values above 2,500 are always billed as paid requests."+ },+ "strictConstrainToURLs": {+ "type": "boolean",+ "description": "If true, agent will only visit URLs provided in the urls array"+ },+ "model": {+ "type": "string",+ "enum": [+ "spark-2",+ "spark-1-mini",+ "spark-1-pro"+ ],+ "default": "spark-2",+ "description": "The model to use for the agent task. spark-2 is the default and the model every run executes on. The Spark 1 model names remain accepted for backwards compatibility but are deprecated and route to spark-2."+ },+ "effort": {+ "type": "string",+ "enum": [+ "low",+ "medium",+ "high"+ ],+ "description": "Reasoning budget for the agent task. Every run executes on spark-2, so effort can be sent with or without model."+ },+ "webhook": {+ "type": "object",+ "description": "A webhook specification object. Subscribes to agent lifecycle events (agent.started, agent.action, agent.completed, agent.failed, agent.cancelled).",+ "properties": {+ "url": {+ "type": "string",+ "format": "uri",+ "description": "The URL to send webhook events to."+ },+ "headers": {+ "type": "object",+ "description": "Headers to send to the webhook URL.",+ "additionalProperties": {+ "type": "string"+ }+ },+ "metadata": {+ "type": "object",+ "description": "Custom metadata that will be included in all webhook payloads for this agent job.",+ "additionalProperties": {+ "type": "string"+ }+ },+ "events": {+ "type": "array",+ "description": "The events to send to the webhook URL. Defaults to all events.",+ "items": {+ "type": "string",+ "enum": [+ "started",+ "action",+ "completed",+ "failed",+ "cancelled"+ ]+ },+ "default": [+ "started",+ "action",+ "completed",+ "failed",+ "cancelled"+ ]+ }+ },+ "required": [+ "url"+ ]+ },+ "auditMetadata": {+ "$ref": "#/components/schemas/AuditMetadata"+ },+ "threatProtection": {+ "$ref": "#/components/schemas/ThreatProtectionOverride"+ }+ },+ "required": [+ "prompt"+ ]+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Agent task started successfully",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ },+ "id": {+ "type": "string",+ "format": "uuid"+ }+ }+ }+ }+ }+ },+ "400": {+ "description": "Bad request — the request body failed validation (for example an invalid JSON schema).",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Invalid JSON schema: ..."+ }+ }+ }+ }+ }+ },+ "402": {+ "description": "Payment required",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Payment required to access this resource."+ }+ }+ }+ }+ }+ },+ "403": {+ "description": "Forbidden — a provided URL is blocked by the team's threat protection policy.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "This URL (https://example.com) is blocked by your organization's threat protection policy (rule: blocklist). If you believe this is a mistake, contact your organization administrator to adjust the policy (e.g. whitelist the domain)."+ }+ }+ }+ }+ }+ },+ "429": {+ "description": "Too many requests",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Rate limit exceeded."+ }+ }+ }+ }+ }+ },+ "500": {+ "description": "Internal server error — the agent service could not be reached.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Failed to passthrough agent request."+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/agent/{jobId}": {+ "parameters": [+ {+ "name": "jobId",+ "in": "path",+ "description": "The ID of the agent job",+ "required": true,+ "schema": {+ "type": "string",+ "format": "uuid"+ }+ }+ ],+ "get": {+ "summary": "Get the status of an agent job",+ "operationId": "getAgentStatus",+ "tags": [+ "Agent"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "Successful response",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ },+ "status": {+ "type": "string",+ "enum": [+ "processing",+ "completed",+ "failed"+ ]+ },+ "data": {+ "type": "object",+ "description": "The extracted data (only present when status is completed)"+ },+ "model": {+ "type": "string",+ "enum": [+ "spark-2",+ "spark-1-pro",+ "spark-1-mini"+ ],+ "default": "spark-2",+ "description": "Model preset used for the agent run. Every new run executes on spark-2; Spark 1 names only appear on legacy runs."+ },+ "effort": {+ "type": "string",+ "enum": [+ "low",+ "medium",+ "high"+ ],+ "description": "Reasoning budget used for the agent run (only present for runs that set effort)"+ },+ "error": {+ "type": "string",+ "description": "Error message (only present when status is failed)"+ },+ "expiresAt": {+ "type": "string",+ "format": "date-time"+ },+ "creditsUsed": {+ "type": "number"+ }+ }+ }+ }+ }+ },+ "400": {+ "description": "Bad request — the job ID is not a valid UUID.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Invalid job ID format. Job ID must be a valid UUID."+ }+ }+ }+ }+ }+ },+ "404": {+ "description": "Agent job not found",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Agent job not found"+ }+ }+ }+ }+ }+ }+ }+ },+ "delete": {+ "summary": "Cancel an agent job",+ "operationId": "cancelAgent",+ "tags": [+ "Agent"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "Agent job cancelled successfully",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ }+ }+ }+ }+ }+ },+ "400": {+ "description": "Bad request — the job ID is not a valid UUID.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Invalid job ID format. Job ID must be a valid UUID."+ }+ }+ }+ }+ }+ },+ "404": {+ "description": "Agent job not found",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Agent job not found"+ }+ }+ }+ }+ }+ },+ "409": {+ "description": "Conflict — the agent job has already finished or has already been cancelled.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Agent already finished"+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/agent/{jobId}/trace": {+ "parameters": [+ {+ "name": "jobId",+ "in": "path",+ "description": "The ID of the agent job",+ "required": true,+ "schema": {+ "type": "string",+ "format": "uuid"+ }+ }+ ],+ "get": {+ "summary": "Get the execution trace of an agent job",+ "operationId": "getAgentTrace",+ "tags": [+ "Agent"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "parameters": [+ {+ "name": "liveView",+ "in": "query",+ "description": "If \"true\", include the currently active browser sessions with live view URLs.",+ "required": false,+ "schema": {+ "type": "string",+ "enum": [+ "true",+ "false"+ ]+ }+ }+ ],+ "responses": {+ "200": {+ "description": "Successful response",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ },+ "id": {+ "type": "string",+ "format": "uuid"+ },+ "events": {+ "type": "array",+ "description": "Canonical execution events for the run; group by agent.id, then order each group by producerSequence, which is monotonic per emitting agent. artifact.updated events carry the snapshotId values used by the snapshots endpoint.",+ "items": {+ "$ref": "#/components/schemas/AgentTraceEvent"+ }+ },+ "creditsUsed": {+ "type": "number",+ "description": "Credits consumed so far, capped at maxCredits if one was set."+ },+ "activeBrowserSessions": {+ "type": "array",+ "description": "Currently active browser sessions (only present when liveView=true).",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string"+ },+ "liveViewUrl": {+ "type": "string"+ },+ "viewport": {+ "type": "object",+ "properties": {+ "width": {+ "type": "number"+ },+ "height": {+ "type": "number"+ }+ }+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "400": {+ "description": "Bad request — the job ID is not a valid UUID, or the job did not run on spark-2 (traces are only available for spark-2 agent jobs).",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Trace is only available for Spark 2 extracts"+ }+ }+ }+ }+ }+ },+ "404": {+ "description": "Agent job not found",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Agent job not found"+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/agent/{jobId}/snapshots/{snapshotId}": {+ "parameters": [+ {+ "name": "jobId",+ "in": "path",+ "description": "The ID of the agent job",+ "required": true,+ "schema": {+ "type": "string",+ "format": "uuid"+ }+ },+ {+ "name": "snapshotId",+ "in": "path",+ "description": "The ID of the snapshot, from an artifact.updated trace event",+ "required": true,+ "schema": {+ "type": "string",+ "format": "uuid"+ }+ }+ ],+ "get": {+ "summary": "Get an output snapshot of an agent job",+ "operationId": "getAgentSnapshot",+ "tags": [+ "Agent"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "Successful response",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ },+ "id": {+ "type": "string",+ "format": "uuid"+ },+ "snapshotId": {+ "type": "string",+ "format": "uuid"+ },+ "snapshot": {+ "type": "string",+ "description": "The snapshot content as a JSON-encoded string — the agent's working output artifact at that point in the run."+ }+ }+ }+ }+ }+ },+ "400": {+ "description": "Bad request — the job ID or snapshot ID is not a valid UUID, or the job did not run on spark-2 (snapshots are only available for spark-2 agent jobs).",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Snapshots are only available for Spark 2 extracts"+ }+ }+ }+ }+ }+ },+ "404": {+ "description": "Agent job not found",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Agent job not found"+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/crawl/active": {+ "get": {+ "summary": "Get all active crawls for the authenticated team",+ "operationId": "getActiveCrawls",+ "tags": [+ "Crawling"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "Successful response",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": true+ },+ "crawls": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "uuid",+ "description": "The unique identifier of the crawl"+ },+ "teamId": {+ "type": "string",+ "description": "The ID of the team that owns the crawl"+ },+ "url": {+ "type": "string",+ "format": "uri",+ "description": "The origin URL of the crawl"+ },+ "options": {+ "type": "object",+ "description": "The crawler options used for this crawl",+ "properties": {+ "scrapeOptions": {+ "$ref": "#/components/schemas/ScrapeOptions"+ }+ }+ }+ },+ "required": [+ "id",+ "teamId",+ "url",+ "status",+ "options"+ ]+ }+ }+ },+ "required": [+ "success",+ "data"+ ]+ }+ }+ }+ },+ "402": {+ "description": "Payment required",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string",+ "example": "Payment required to access this resource."+ }+ }+ }+ }+ }+ },+ "429": {+ "description": "Too many requests",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string",+ "example": "Request rate limit exceeded. Please wait and try again later."+ }+ }+ }+ }+ }+ },+ "500": {+ "description": "Server error",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string",+ "example": "An unexpected error occurred on the server."+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/team/credit-usage": {+ "get": {+ "summary": "Get remaining credits for the authenticated team",+ "operationId": "getCreditUsage",+ "tags": [+ "Billing"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "Successful response",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": true+ },+ "data": {+ "type": "object",+ "properties": {+ "remainingCredits": {+ "type": "number",+ "description": "Number of credits remaining for the team",+ "example": 1000+ },+ "planCredits": {+ "type": "number",+ "description": "Number of credits in the plan. This does not include coupon credits or credits added by pay-as-you-go.",+ "example": 500000+ },+ "billingPeriodStart": {+ "type": "string",+ "format": "date-time",+ "description": "Start date of the current billing period.",+ "example": "2025-01-01T00:00:00Z",+ "nullable": true+ },+ "billingPeriodEnd": {+ "type": "string",+ "format": "date-time",+ "description": "End date of the current billing period.",+ "example": "2025-01-31T23:59:59Z",+ "nullable": true+ }+ }+ }+ }+ }+ }+ }+ },+ "404": {+ "description": "Credit usage information not found",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string",+ "example": "Could not find credit usage information"+ }+ }+ }+ }+ }+ },+ "500": {+ "description": "Server error",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string",+ "example": "Internal server error while fetching credit usage"+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/team/credit-usage/historical": {+ "get": {+ "summary": "Get historical credit usage for the authenticated team",+ "operationId": "getHistoricalCreditUsage",+ "tags": [+ "Billing"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "parameters": [+ {+ "name": "byApiKey",+ "in": "query",+ "description": "Get historical credit usage by API key",+ "required": false,+ "schema": {+ "type": "boolean",+ "default": false+ }+ }+ ],+ "responses": {+ "200": {+ "description": "Successful response",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": true+ },+ "periods": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "startDate": {+ "type": "string",+ "format": "date-time",+ "description": "Start date of the billing period",+ "example": "2025-01-01T00:00:00Z"+ },+ "endDate": {+ "type": "string",+ "format": "date-time",+ "description": "End date of the billing period",+ "example": "2025-01-31T23:59:59Z"+ },+ "apiKey": {+ "type": "string",+ "description": "Name of the API key used for the billing period. null if byApiKey is false (default)",+ "nullable": true+ },+ "totalCredits": {+ "type": "integer",+ "description": "Total number of credits used in the billing period",+ "example": 1000+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "500": {+ "description": "Server error",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string",+ "example": "Internal server error while fetching historical credit usage"+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/team/token-usage": {+ "get": {+ "summary": "Get remaining tokens for the authenticated team (Extract only)",+ "operationId": "getTokenUsage",+ "tags": [+ "Billing"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "Successful response",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": true+ },+ "data": {+ "type": "object",+ "properties": {+ "remainingTokens": {+ "type": "number",+ "description": "Number of tokens remaining for the team",+ "example": 1000+ },+ "planTokens": {+ "type": "number",+ "description": "Number of tokens in the plan. This does not include coupon tokens.",+ "example": 500000+ },+ "billingPeriodStart": {+ "type": "string",+ "format": "date-time",+ "description": "Start date of the current billing period.",+ "example": "2025-01-01T00:00:00Z",+ "nullable": true+ },+ "billingPeriodEnd": {+ "type": "string",+ "format": "date-time",+ "description": "End date of the current billing period.",+ "example": "2025-01-31T23:59:59Z",+ "nullable": true+ }+ }+ }+ }+ }+ }+ }+ },+ "404": {+ "description": "Token usage information not found",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string",+ "example": "Could not find token usage information"+ }+ }+ }+ }+ }+ },+ "500": {+ "description": "Server error",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string",+ "example": "Internal server error while fetching token usage"+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/team/token-usage/historical": {+ "get": {+ "summary": "Get historical token usage for the authenticated team (Extract only)",+ "operationId": "getHistoricalTokenUsage",+ "tags": [+ "Billing"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "parameters": [+ {+ "name": "byApiKey",+ "in": "query",+ "description": "Get historical token usage by API key",+ "required": false,+ "schema": {+ "type": "boolean",+ "default": false+ }+ }+ ],+ "responses": {+ "200": {+ "description": "Successful response",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": true+ },+ "periods": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "startDate": {+ "type": "string",+ "format": "date-time",+ "description": "Start date of the billing period",+ "example": "2025-01-01T00:00:00Z"+ },+ "endDate": {+ "type": "string",+ "format": "date-time",+ "description": "End date of the billing period",+ "example": "2025-01-31T23:59:59Z"+ },+ "apiKey": {+ "type": "string",+ "description": "Name of the API key used for the billing period. null if byApiKey is false (default)",+ "nullable": true+ },+ "totalTokens": {+ "type": "integer",+ "description": "Total number of tokens used in the billing period",+ "example": 1000+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "500": {+ "description": "Server error",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string",+ "example": "Internal server error while fetching historical token usage"+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/team/queue-status": {+ "get": {+ "summary": "Metrics about your team's scrape queue",+ "operationId": "getQueueStatus",+ "tags": [+ "Miscellaneous"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "Successful response",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": true+ },+ "jobsInQueue": {+ "type": "number",+ "description": "Number of jobs currently in your queue"+ },+ "activeJobsInQueue": {+ "type": "number",+ "description": "Number of jobs currently active"+ },+ "waitingJobsInQueue": {+ "type": "number",+ "description": "Number of jobs currently waiting"+ },+ "maxConcurrency": {+ "type": "number",+ "description": "Maximum number of concurrent active jobs based on your plan"+ },+ "mostRecentSuccess": {+ "type": "string",+ "format": "date-time",+ "description": "Timestamp of the most recent successful job",+ "nullable": true+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/team/activity": {+ "get": {+ "summary": "List recent API activity",+ "operationId": "getActivity",+ "description": "Lists your team's recent API activity from the last 24 hours. Returns metadata about each job including the job ID, which can be used with the corresponding GET endpoint (e.g. GET /crawl/{id}) to retrieve full results. Supports cursor-based pagination and filtering by endpoint.",+ "tags": [+ "Account"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "parameters": [+ {+ "name": "endpoint",+ "in": "query",+ "required": false,+ "schema": {+ "type": "string",+ "enum": [+ "scrape",+ "crawl",+ "batch_scrape",+ "search",+ "extract",+ "llmstxt",+ "deep_research",+ "map",+ "agent",+ "browser",+ "interact"+ ]+ },+ "description": "Filter by endpoint"+ },+ {+ "name": "limit",+ "in": "query",+ "required": false,+ "schema": {+ "type": "integer",+ "default": 50,+ "minimum": 1,+ "maximum": 100+ },+ "description": "Maximum number of results per page"+ },+ {+ "name": "cursor",+ "in": "query",+ "required": false,+ "schema": {+ "type": "string"+ },+ "description": "Cursor for pagination. Use the cursor value from the previous response."+ }+ ],+ "responses": {+ "200": {+ "description": "Successful response",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": true+ },+ "data": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "The job ID. Use this with the corresponding GET endpoint to retrieve results."+ },+ "endpoint": {+ "type": "string",+ "enum": [+ "scrape",+ "crawl",+ "batch_scrape",+ "search",+ "extract",+ "llmstxt",+ "deep_research",+ "map",+ "agent",+ "browser",+ "interact"+ ],+ "description": "The endpoint used for this job"+ },+ "api_version": {+ "type": "string",+ "description": "The API version used for this request",+ "example": "v1"+ },+ "created_at": {+ "type": "string",+ "format": "date-time",+ "description": "When the job was created"+ },+ "target": {+ "type": "string",+ "nullable": true,+ "description": "The URL or query that was submitted"+ }+ }+ }+ },+ "cursor": {+ "type": "string",+ "nullable": true,+ "description": "Cursor to use for the next page. Null if there are no more results."+ },+ "has_more": {+ "type": "boolean",+ "description": "Whether there are more results available"+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/search": {+ "post": {+ "summary": "Search and optionally scrape search results",+ "operationId": "searchAndScrape",+ "tags": [+ "Search"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "query": {+ "type": "string",+ "description": "The search query",+ "maxLength": 500+ },+ "limit": {+ "type": "integer",+ "description": "Maximum number of results to return (per source type when using multiple sources)",+ "default": 10,+ "maximum": 100,+ "minimum": 1+ },+ "sources": {+ "type": "array",+ "items": {+ "oneOf": [+ {+ "type": "object",+ "title": "Web",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "web"+ ]+ },+ "tbs": {+ "type": "string",+ "description": "Time-based search parameter. Supports predefined time ranges (`qdr:h`, `qdr:d`, `qdr:w`, `qdr:m`, `qdr:y`), custom date ranges (`cdr:1,cd_min:MM/DD/YYYY,cd_max:MM/DD/YYYY`), and sort by date (`sbd:1`). Values can be combined, e.g. `sbd:1,qdr:w`."+ },+ "location": {+ "type": "string",+ "description": "Location parameter for search results"+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "Images",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "images"+ ]+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "News",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "news"+ ]+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "Alexandria",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "alexandria"+ ]+ }+ },+ "required": [+ "type"+ ],+ "additionalProperties": false+ }+ ]+ },+ "description": "Sources to search. Will determine the arrays available in the response. Defaults to ['web']. The plain string form (e.g. `[\"web\", \"alexandria\"]`) is also accepted. The `alexandria` source returns tool contracts discovered from the Alexandria catalogue in `data.tools` instead of search results; it is free and is never counted in `creditsUsed`. Requires the team's Alexandria access to be enabled (403 otherwise).",+ "default": [+ "web"+ ]+ },+ "domainTools": {+ "type": "boolean",+ "description": "Include tool contracts whose provider matches the domains of the returned web results. Defaults to on when `alexandria` is among the sources; set `false` to disable, or `true` alone to add domain-matched tools beside ordinary web results. Free."+ },+ "categories": {+ "type": "array",+ "items": {+ "oneOf": [+ {+ "type": "object",+ "title": "Developer",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "developer"+ ]+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "Research",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "research"+ ]+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "PDF",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "pdf"+ ]+ }+ },+ "required": [+ "type"+ ]+ }+ ]+ },+ "description": "Categories to filter results by. Defaults to [], which means results will not be filtered by any categories."+ },+ "includeDomains": {+ "type": "array",+ "items": {+ "type": "string",+ "format": "hostname"+ },+ "description": "Restricts search results to the specified domains. Domains should be hostnames only, without protocol or path. Cannot be used with excludeDomains."+ },+ "excludeDomains": {+ "type": "array",+ "items": {+ "type": "string",+ "format": "hostname"+ },+ "description": "Excludes search results from the specified domains. Domains should be hostnames only, without protocol or path. Cannot be used with includeDomains."+ },+ "tbs": {+ "type": "string",+ "description": "Time-based search parameter. Supports predefined time ranges (`qdr:h`, `qdr:d`, `qdr:w`, `qdr:m`, `qdr:y`), custom date ranges (`cdr:1,cd_min:MM/DD/YYYY,cd_max:MM/DD/YYYY`), and sort by date (`sbd:1`). Values can be combined, e.g. `sbd:1,qdr:w`."+ },+ "location": {+ "type": "string",+ "description": "Location parameter for search results (e.g. `San Francisco,California,United States`). For best results, set both this and the `country` parameter."+ },+ "country": {+ "type": "string",+ "description": "ISO country code for geo-targeting search results (e.g. `US`). For best results, set both this and the `location` parameter.",+ "default": "US"+ },+ "safe": {+ "type": "boolean",+ "description": "When `true`, filters explicit content from search results (SafeSearch). Omit to keep the default behavior, which does not apply the filter."+ },+ "timeout": {+ "type": "integer",+ "description": "Timeout in milliseconds",+ "default": 60000+ },+ "ignoreInvalidURLs": {+ "type": "boolean",+ "description": "Excludes URLs from the search results that are invalid for other Firecrawl endpoints. This helps reduce errors if you are piping data from search into other Firecrawl API endpoints.",+ "default": false+ },+ "highlights": {+ "type": "boolean",+ "description": "Generate query-relevant highlights for search results. Set to false to return provider descriptions or snippets without highlighting.",+ "default": true+ },+ "enterprise": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "anon",+ "zdr"+ ]+ },+ "description": "Enterprise search options for Zero Data Retention (ZDR). Use `[\"zdr\"]` for end-to-end ZDR (10 credits / 10 results) or `[\"anon\"]` for anonymized ZDR (2 credits / 10 results). Must be enabled for your team."+ },+ "scrapeOptions": {+ "allOf": [+ {+ "$ref": "#/components/schemas/ScrapeOptions"+ }+ ],+ "description": "Options for scraping search results",+ "default": {}+ },+ "threatProtection": {+ "$ref": "#/components/schemas/ThreatProtectionOverride"+ }+ },+ "required": [+ "query"+ ]+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successful response",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ },+ "data": {+ "type": "object",+ "properties": {+ "web": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "title": {+ "type": "string",+ "description": "Title from search result"+ },+ "description": {+ "type": "string",+ "description": "Description from search result"+ },+ "url": {+ "type": "string",+ "description": "URL of the search result"+ },+ "markdown": {+ "type": "string",+ "nullable": true,+ "description": "Markdown content if scraping was requested"+ },+ "html": {+ "type": "string",+ "nullable": true,+ "description": "HTML content if requested in formats"+ },+ "rawHtml": {+ "type": "string",+ "nullable": true,+ "description": "Raw HTML content if requested in formats"+ },+ "links": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Links found if requested in formats"+ },+ "screenshot": {+ "type": "string",+ "nullable": true,+ "description": "Screenshot URL if requested in formats. Screenshots expire after 24 hours and can no longer be downloaded."+ },+ "audio": {+ "type": "string",+ "nullable": true,+ "description": "Signed URL to the extracted MP3 audio file if `audio` is in `formats`. The signed URL expires after 1 hour."+ },+ "video": {+ "type": "string",+ "nullable": true,+ "description": "Signed URL to the extracted video file if `video` is in `formats`. The signed URL expires after 1 hour."+ },+ "metadata": {+ "type": "object",+ "properties": {+ "title": {+ "type": "string"+ },+ "description": {+ "type": "string"+ },+ "sourceURL": {+ "type": "string",+ "description": "The original URL that was requested. May differ from the page's final URL if redirects occurred."+ },+ "url": {+ "type": "string",+ "description": "The final URL of the page after all redirects have been followed."+ },+ "statusCode": {+ "type": "integer"+ },+ "numPages": {+ "type": "integer",+ "description": "For PDF inputs, the number of pages parsed (capped by the parsers maxPages option)."+ },+ "totalPages": {+ "type": "integer",+ "description": "For PDF inputs, the document's true page count before any maxPages capping. Omitted when it cannot be determined; a totalPages greater than numPages indicates the result was truncated."+ },+ "error": {+ "type": "string",+ "nullable": true+ }+ }+ }+ }+ }+ },+ "images": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "title": {+ "type": "string",+ "description": "Title from search result"+ },+ "imageUrl": {+ "type": "string",+ "description": "URL of the image"+ },+ "imageWidth": {+ "type": "integer",+ "description": "Width of the image"+ },+ "imageHeight": {+ "type": "integer",+ "description": "Height of the image"+ },+ "url": {+ "type": "string",+ "description": "URL of the search result"+ },+ "position": {+ "type": "integer",+ "description": "Position of the search result"+ }+ }+ }+ },+ "news": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "title": {+ "type": "string",+ "description": "Title of the article"+ },+ "snippet": {+ "type": "string",+ "description": "Snippet from the article"+ },+ "url": {+ "type": "string",+ "description": "URL of the article"+ },+ "date": {+ "type": "string",+ "description": "Date of the article"+ },+ "imageUrl": {+ "type": "string",+ "description": "Image URL of the article"+ },+ "position": {+ "type": "integer",+ "description": "Position of the article"+ },+ "markdown": {+ "type": "string",+ "nullable": true,+ "description": "Markdown content if scraping was requested"+ },+ "html": {+ "type": "string",+ "nullable": true,+ "description": "HTML content if requested in formats"+ },+ "rawHtml": {+ "type": "string",+ "nullable": true,+ "description": "Raw HTML content if requested in formats"+ },+ "links": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Links found if requested in formats"+ },+ "screenshot": {+ "type": "string",+ "nullable": true,+ "description": "Screenshot URL if requested in formats. Screenshots expire after 24 hours and can no longer be downloaded."+ },+ "audio": {+ "type": "string",+ "nullable": true,+ "description": "Signed URL to the extracted MP3 audio file if `audio` is in `formats`. The signed URL expires after 1 hour."+ },+ "video": {+ "type": "string",+ "nullable": true,+ "description": "Signed URL to the extracted video file if `video` is in `formats`. The signed URL expires after 1 hour."+ },+ "metadata": {+ "type": "object",+ "properties": {+ "title": {+ "type": "string"+ },+ "description": {+ "type": "string"+ },+ "sourceURL": {+ "type": "string",+ "description": "The original URL that was requested. May differ from the page's final URL if redirects occurred."+ },+ "url": {+ "type": "string",+ "description": "The final URL of the page after all redirects have been followed."+ },+ "statusCode": {+ "type": "integer"+ },+ "numPages": {+ "type": "integer",+ "description": "For PDF inputs, the number of pages parsed (capped by the parsers maxPages option)."+ },+ "totalPages": {+ "type": "integer",+ "description": "For PDF inputs, the document's true page count before any maxPages capping. Omitted when it cannot be determined; a totalPages greater than numPages indicates the result was truncated."+ },+ "error": {+ "type": "string",+ "nullable": true+ }+ }+ }+ }+ }+ },+ "tools": {+ "type": "array",+ "description": "Tool contracts discovered from the Alexandria catalogue. Present when `alexandria` is among the sources or when `domainTools` was requested; up to `limit` results per discovery source (semantic matches from the `alexandria` source, domain matches from `domainTools`).",+ "items": {+ "$ref": "#/components/schemas/DiscoveredTool"+ }+ }+ },+ "description": "The search results. The arrays available will depend on the sources you specified in the request. By default, the `web` array will be returned."+ },+ "warning": {+ "type": "string",+ "nullable": true,+ "description": "Warning message if any issues occurred. Includes `Some tool discovery results are unavailable.` when Alexandria or domain tool discovery partially failed."+ },+ "id": {+ "type": "string",+ "description": "The ID of the search job"+ },+ "creditsUsed": {+ "type": "integer",+ "description": "The number of credits used for the search"+ }+ }+ }+ }+ }+ },+ "408": {+ "description": "Request timeout",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string",+ "example": "Request timed out"+ }+ }+ }+ }+ }+ },+ "500": {+ "description": "Server error",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "code": {+ "type": "string",+ "example": "UNKNOWN_ERROR"+ },+ "error": {+ "type": "string",+ "example": "An unexpected error occurred on the server."+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/interact": {+ "post": {+ "summary": "Create an interact session",+ "operationId": "createBrowserSession",+ "tags": [+ "Interact"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "ttl": {+ "type": "integer",+ "default": 300,+ "minimum": 30,+ "maximum": 3600,+ "description": "Total time-to-live in seconds for the interact session"+ },+ "activityTtl": {+ "type": "integer",+ "minimum": 10,+ "maximum": 3600,+ "description": "Time in seconds before the session is destroyed due to inactivity"+ },+ "streamWebView": {+ "type": "boolean",+ "default": true,+ "description": "Whether to stream a live view of the browser"+ },+ "profile": {+ "type": "object",+ "description": "Enable persistent storage across interact sessions. Data saved in one session can be loaded in a later session using the same name.",+ "properties": {+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 128,+ "description": "A name for the profile. Sessions with the same name share storage."+ },+ "saveChanges": {+ "type": "boolean",+ "default": true,+ "description": "When true, browser state is saved back to the profile on close. Set to false to load existing data without writing. Multiple non-saving sessions are allowed but only one saving session at a time."+ }+ },+ "required": [+ "name"+ ]+ }+ }+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Interact session created successfully",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ },+ "id": {+ "type": "string",+ "description": "The unique session identifier"+ },+ "cdpUrl": {+ "type": "string",+ "description": "WebSocket URL for Chrome DevTools Protocol access"+ },+ "liveViewUrl": {+ "type": "string",+ "description": "URL to view the interact session in real time"+ },+ "interactiveLiveViewUrl": {+ "type": "string",+ "description": "URL to interact with the interact session in real time (click, type, scroll)"+ },+ "expiresAt": {+ "type": "string",+ "format": "date-time",+ "description": "When the session will expire based on TTL"+ }+ }+ }+ }+ }+ },+ "402": {+ "description": "Payment required",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Payment required to access this resource."+ }+ }+ }+ }+ }+ }+ }+ },+ "get": {+ "summary": "List interact sessions",+ "operationId": "listBrowserSessions",+ "tags": [+ "Interact"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "parameters": [+ {+ "name": "status",+ "in": "query",+ "required": false,+ "schema": {+ "type": "string",+ "enum": [+ "active",+ "destroyed"+ ]+ },+ "description": "Filter sessions by status"+ }+ ],+ "responses": {+ "200": {+ "description": "List of interact sessions",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ },+ "sessions": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string"+ },+ "status": {+ "type": "string",+ "enum": [+ "active",+ "destroyed"+ ]+ },+ "cdpUrl": {+ "type": "string"+ },+ "liveViewUrl": {+ "type": "string"+ },+ "interactiveLiveViewUrl": {+ "type": "string",+ "description": "URL to interact with the interact session in real time (click, type, scroll)"+ },+ "streamWebView": {+ "type": "boolean"+ },+ "createdAt": {+ "type": "string",+ "format": "date-time"+ },+ "lastActivity": {+ "type": "string",+ "format": "date-time"+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "402": {+ "description": "Payment required",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Payment required to access this resource."+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/interact/{sessionId}/execute": {+ "post": {+ "summary": "Execute code in an interact session",+ "operationId": "executeBrowserCode",+ "tags": [+ "Interact"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "parameters": [+ {+ "name": "sessionId",+ "in": "path",+ "required": true,+ "schema": {+ "type": "string"+ },+ "description": "The interact session ID"+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "required": [+ "code"+ ],+ "properties": {+ "code": {+ "type": "string",+ "minLength": 1,+ "maxLength": 100000,+ "description": "Code to execute in the browser sandbox"+ },+ "language": {+ "type": "string",+ "enum": [+ "python",+ "node",+ "bash"+ ],+ "default": "node",+ "description": "Language of the code to execute. Use `node` for JavaScript or `bash` for agent-browser CLI commands."+ },+ "timeout": {+ "type": "integer",+ "minimum": 1,+ "maximum": 300,+ "description": "Execution timeout in seconds"+ }+ }+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Code executed successfully",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ },+ "stdout": {+ "type": "string",+ "nullable": true,+ "description": "Standard output from the code execution"+ },+ "result": {+ "type": "string",+ "nullable": true,+ "description": "Standard output (alias for stdout)"+ },+ "stderr": {+ "type": "string",+ "nullable": true,+ "description": "Standard error output from the code execution"+ },+ "exitCode": {+ "type": "integer",+ "nullable": true,+ "description": "Exit code of the executed process"+ },+ "killed": {+ "type": "boolean",+ "description": "Whether the process was killed due to timeout"+ },+ "error": {+ "type": "string",+ "nullable": true,+ "description": "Error message if the code raised an exception"+ }+ }+ }+ }+ }+ },+ "402": {+ "description": "Payment required",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Payment required to access this resource."+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/interact/{sessionId}": {+ "delete": {+ "summary": "Delete an interact session",+ "operationId": "deleteBrowserSession",+ "tags": [+ "Interact"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "parameters": [+ {+ "name": "sessionId",+ "in": "path",+ "required": true,+ "schema": {+ "type": "string"+ },+ "description": "The interact session ID"+ }+ ],+ "responses": {+ "200": {+ "description": "Interact session deleted successfully",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ },+ "sessionDurationMs": {+ "type": "integer",+ "description": "Total session duration in milliseconds"+ },+ "creditsBilled": {+ "type": "number",+ "description": "Number of credits billed for the session"+ }+ }+ }+ }+ }+ },+ "402": {+ "description": "Payment required",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "example": "Payment required to access this resource."+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/scrape/{jobId}": {+ "parameters": [+ {+ "name": "jobId",+ "in": "path",+ "required": true,+ "schema": {+ "type": "string",+ "format": "uuid"+ },+ "description": "The ID of the job"+ }+ ],+ "get": {+ "summary": "Get the status of a scrape job",+ "operationId": "getScrapeStatus",+ "tags": [+ "Scraping"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "Scrape job status",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ScrapeResponse"+ }+ }+ }+ },+ "402": {+ "description": "Payment required",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string"+ }+ }+ }+ }+ }+ },+ "429": {+ "description": "Too many requests",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string"+ }+ }+ }+ }+ }+ },+ "500": {+ "description": "Server error",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string"+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "/search/{jobId}/feedback": {+ "post": {+ "summary": "Submit feedback for a search job",+ "operationId": "submitSearchFeedback",+ "tags": [+ "Search",+ "Feedback"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "parameters": [+ {+ "name": "jobId",+ "in": "path",+ "required": true,+ "schema": {+ "type": "string",+ "format": "uuid"+ },+ "description": "Search job id returned by /search."+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/SearchFeedbackRequest"+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Feedback recorded",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/FeedbackResponse"+ }+ }+ }+ },+ "400": {+ "description": "Invalid request body",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/FeedbackErrorResponse"+ }+ }+ }+ },+ "403": {+ "description": "Feedback is not available for this team",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/FeedbackErrorResponse"+ }+ }+ }+ },+ "404": {+ "description": "Search not found for this team",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/FeedbackErrorResponse"+ }+ }+ }+ },+ "409": {+ "description": "Feedback cannot be recorded for this search",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/FeedbackErrorResponse"+ }+ }+ }+ },+ "500": {+ "description": "Server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/FeedbackErrorResponse"+ }+ }+ }+ }+ }+ }+ },+ "/support/ask": {+ "post": {+ "summary": "Ask the Firecrawl support agent",+ "description": "Diagnose Firecrawl job, account, and API usage issues with an AI support agent.",+ "operationId": "askSupportAgent",+ "tags": [+ "Support"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/SupportAskRequest"+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Support agent answer",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/SupportAskResponse"+ }+ }+ }+ },+ "400": {+ "description": "Invalid request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/SupportProxyErrorResponse"+ }+ }+ }+ },+ "401": {+ "description": "Missing or invalid bearer token",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/SupportProxyErrorResponse"+ }+ }+ }+ },+ "503": {+ "description": "Support agent unavailable",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/SupportProxyErrorResponse"+ }+ }+ }+ },+ "504": {+ "description": "Support agent timeout",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/SupportProxyErrorResponse"+ }+ }+ }+ }+ }+ }+ },+ "/support/docs-search": {+ "post": {+ "summary": "Search Firecrawl docs with citations",+ "description": "Answer Firecrawl documentation questions using the public docs corpus.",+ "operationId": "searchSupportDocs",+ "tags": [+ "Support"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/SupportDocsSearchRequest"+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Docs-grounded answer",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/SupportDocsSearchResponse"+ }+ }+ }+ },+ "400": {+ "description": "Invalid request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/SupportProxyErrorResponse"+ }+ }+ }+ },+ "401": {+ "description": "Missing or invalid bearer token",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/SupportProxyErrorResponse"+ }+ }+ }+ },+ "503": {+ "description": "Support agent unavailable",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/SupportProxyErrorResponse"+ }+ }+ }+ },+ "504": {+ "description": "Support agent timeout",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/SupportProxyErrorResponse"+ }+ }+ }+ }+ }+ }+ },+ "/search/research/papers": {+ "get": {+ "summary": "Search papers",+ "operationId": "researchSearchPapers",+ "tags": [+ "Research"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "parameters": [+ {+ "name": "query",+ "in": "query",+ "required": true,+ "description": "Natural-language paper search query.",+ "schema": {+ "type": "string",+ "minLength": 1+ }+ },+ {+ "name": "k",+ "in": "query",+ "required": false,+ "description": "Maximum number of ranked papers to return.",+ "schema": {+ "type": "integer",+ "minimum": 1,+ "maximum": 500,+ "default": 40+ }+ },+ {+ "name": "authors",+ "in": "query",+ "required": false,+ "description": "Author substring filter. Repeat or pass a comma-separated value; all filters must match.",+ "schema": {+ "type": "string"+ }+ },+ {+ "name": "categories",+ "in": "query",+ "required": false,+ "description": "Paper category filter. Repeat or pass a comma-separated value; all filters must match.",+ "schema": {+ "type": "string"+ }+ },+ {+ "name": "from",+ "in": "query",+ "required": false,+ "description": "Inclusive lower bound on created/updated date.",+ "schema": {+ "type": "string",+ "format": "date"+ }+ },+ {+ "name": "to",+ "in": "query",+ "required": false,+ "description": "Inclusive upper bound on created/updated date.",+ "schema": {+ "type": "string",+ "format": "date"+ }+ }+ ],+ "responses": {+ "200": {+ "description": "Ranked paper results.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ResearchSearchPapersResponse"+ },+ "example": {+ "success": true,+ "results": [+ {+ "paperId": "2014215642691656232",+ "primaryId": "arxiv:2105.05233",+ "ids": {+ "arxiv": [+ "2105.05233"+ ]+ },+ "title": "Diffusion Models Beat GANs on Image Synthesis",+ "abstract": "We show that diffusion models can achieve image sample quality superior to the current state-of-the-art generative models...",+ "score": 0.0163934+ }+ ]+ }+ }+ }+ },+ "400": {+ "description": "Invalid request"+ },+ "401": {+ "description": "Missing or invalid bearer token"+ },+ "429": {+ "description": "Rate limit exceeded"+ },+ "500": {+ "description": "Internal server error"+ }+ }+ }+ },+ "/search/research/papers/{id}": {+ "get": {+ "summary": "Inspect or read a paper",+ "operationId": "researchGetPaper",+ "tags": [+ "Research"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "parameters": [+ {+ "name": "id",+ "in": "path",+ "required": true,+ "description": "Paper reference: a canonical paperId or source-specific primaryId.",+ "schema": {+ "type": "string"+ },+ "examples": {+ "paperId": {+ "summary": "Canonical paperId",+ "value": "2014215642691656232"+ },+ "sourceId": {+ "summary": "Source-specific primaryId",+ "value": "arxiv:2105.05233"+ }+ }+ },+ {+ "name": "query",+ "in": "query",+ "required": false,+ "description": "When present, returns the top matching full-text passages for this question. Omit it to inspect metadata only.",+ "schema": {+ "type": "string",+ "minLength": 1+ }+ },+ {+ "name": "k",+ "in": "query",+ "required": false,+ "description": "Passage count for read mode. Only valid when query is present.",+ "schema": {+ "type": "integer",+ "minimum": 1,+ "maximum": 50,+ "default": 4+ }+ }+ ],+ "responses": {+ "200": {+ "description": "Paper metadata or read-mode passages.",+ "content": {+ "application/json": {+ "schema": {+ "oneOf": [+ {+ "$ref": "#/components/schemas/ResearchPaperMetadataResponse"+ },+ {+ "$ref": "#/components/schemas/ResearchReadPaperResponse"+ }+ ]+ },+ "example": {+ "success": true,+ "paper": {+ "paperId": "2014215642691656232",+ "ids": {+ "arxiv": [+ "2105.05233"+ ]+ },+ "title": "Diffusion Models Beat GANs on Image Synthesis",+ "abstract": "We show that diffusion models can achieve image sample quality superior to the current state-of-the-art generative models...",+ "authors": "Prafulla Dhariwal, Alexander Nichol",+ "categories": [+ "cs.LG"+ ],+ "createdDate": "Wed, 11 May 2021 18:01:01 GMT",+ "updateDate": "2021-06-01"+ }+ }+ }+ }+ },+ "400": {+ "description": "Invalid request"+ },+ "401": {+ "description": "Missing or invalid bearer token"+ },+ "404": {+ "description": "Paper not found"+ },+ "429": {+ "description": "Rate limit exceeded"+ },+ "500": {+ "description": "Internal server error"+ }+ }+ }+ },+ "/search/research/papers/{id}/similar": {+ "get": {+ "summary": "Find related papers",+ "operationId": "researchRelatedPapers",+ "tags": [+ "Research"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "parameters": [+ {+ "name": "id",+ "in": "path",+ "required": true,+ "description": "Primary seed paper reference.",+ "schema": {+ "type": "string"+ },+ "examples": {+ "paperId": {+ "summary": "Canonical paperId",+ "value": "2014215642691656232"+ },+ "sourceId": {+ "summary": "Source-specific primaryId",+ "value": "arxiv:2105.05233"+ }+ }+ },+ {+ "name": "intent",+ "in": "query",+ "required": true,+ "description": "Natural-language ranking/filtering intent used for semantic ranking.",+ "schema": {+ "type": "string",+ "minLength": 1+ }+ },+ {+ "name": "mode",+ "in": "query",+ "required": false,+ "description": "Structural expansion mode.",+ "schema": {+ "type": "string",+ "enum": [+ "similar",+ "citers",+ "references"+ ],+ "default": "similar"+ }+ },+ {+ "name": "k",+ "in": "query",+ "required": false,+ "description": "Maximum number of related papers to return.",+ "schema": {+ "type": "integer",+ "minimum": 1,+ "maximum": 500,+ "default": 40+ }+ },+ {+ "name": "rerank",+ "in": "query",+ "required": false,+ "description": "Apply an additional rerank over fused candidates.",+ "schema": {+ "type": "boolean"+ }+ },+ {+ "name": "anchor",+ "in": "query",+ "required": false,+ "description": "Additional seed paper reference. Repeat this parameter for multiple anchors.",+ "schema": {+ "type": "string"+ }+ }+ ],+ "responses": {+ "200": {+ "description": "Ranked related papers.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ResearchSimilarPapersResponse"+ },+ "example": {+ "success": true,+ "results": [+ {+ "paperId": "482107036680302043",+ "primaryId": "arxiv:2006.11239",+ "ids": {+ "arxiv": [+ "2006.11239"+ ]+ },+ "title": "Denoising Diffusion Probabilistic Models",+ "abstract": "We present high quality image synthesis results using diffusion probabilistic models...",+ "score": 0.032119,+ "signals": {+ "structural": 12,+ "semantic": 0.61,+ "articleRank": 0.00031,+ "seedOverlap": 2+ }+ }+ ],+ "poolSize": 40,+ "truncated": false+ }+ }+ }+ },+ "400": {+ "description": "Invalid request"+ },+ "401": {+ "description": "Missing or invalid bearer token"+ },+ "429": {+ "description": "Rate limit exceeded"+ },+ "500": {+ "description": "Internal server error"+ }+ }+ }+ },+ "/search/developer": {+ "get": {+ "summary": "Search the developer index",+ "operationId": "developerSearch",+ "tags": [+ "Developer"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "parameters": [+ {+ "name": "query",+ "in": "query",+ "required": true,+ "description": "Natural-language question or search phrase.",+ "schema": {+ "type": "string",+ "minLength": 1+ }+ },+ {+ "name": "k",+ "in": "query",+ "required": false,+ "description": "Number of ranked results to return.",+ "schema": {+ "type": "integer",+ "minimum": 1,+ "maximum": 100,+ "default": 10+ }+ },+ {+ "name": "types",+ "in": "query",+ "required": false,+ "description": "Result kinds to search. Defaults to all four. Accepts a repeated parameter (`types=issue&types=pull_request`) or one comma-separated value (`types=issue,pull_request`).",+ "schema": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "doc",+ "issue",+ "pull_request",+ "readme"+ ]+ }+ }+ },+ {+ "name": "repos",+ "in": "query",+ "required": false,+ "description": "Repository slugs to scope the repository half of the index to, such as `firecrawl/firecrawl`. Applies to the `issue`, `pull_request`, and `readme` types only. Sent together with `sources`, the two halves are combined rather than intersected, so matching results come back from either. Returns 400 when no repository type is in `types`, reporting that `repos` cannot match any requested type and that you should add repository types or drop `repos`.",+ "schema": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ },+ {+ "name": "sources",+ "in": "query",+ "required": false,+ "description": "Documentation source ids to scope the documentation half to, at most 20. Applies to the `doc` type only. Not a fixed enum: ids reflect the documentation sites in the index and the set grows over time, so confirm an id resolves by sending it and reading the `sources` array on the response. Returns 400 with `sources cannot match any requested type; add doc or drop sources` when `doc` is not in `types`.",+ "schema": {+ "type": "array",+ "maxItems": 20,+ "items": {+ "type": "string",+ "minLength": 1,+ "maxLength": 512+ }+ }+ },+ {+ "name": "skills",+ "in": "query",+ "required": false,+ "description": "Set to `only` to limit the search to indexed agent-skill files.",+ "schema": {+ "type": "string",+ "enum": [+ "only"+ ]+ }+ },+ {+ "name": "passages",+ "in": "query",+ "required": false,+ "description": "Matched passages to return per result.",+ "schema": {+ "type": "integer",+ "minimum": 1,+ "maximum": 5,+ "default": 1+ }+ },+ {+ "name": "language",+ "in": "query",+ "required": false,+ "description": "Repository primary language, such as `Rust`. Applies to repository results only; sending it with no `sources` scope returns no `doc` results. See [how the repository filters scope a search](/api-reference/endpoint/developer-search#how-the-repository-filters-scope-a-search).",+ "schema": {+ "type": "string",+ "example": "Rust"+ }+ },+ {+ "name": "topic",+ "in": "query",+ "required": false,+ "description": "Repository topic, such as `async`. Applies to repository results only; sending it with no `sources` scope returns no `doc` results.",+ "schema": {+ "type": "string",+ "example": "async"+ }+ },+ {+ "name": "license",+ "in": "query",+ "required": false,+ "description": "Repository license, such as `MIT`. Applies to repository results only; sending it with no `sources` scope returns no `doc` results.",+ "schema": {+ "type": "string",+ "example": "MIT"+ }+ },+ {+ "name": "min_stars",+ "in": "query",+ "required": false,+ "description": "Lower bound on repository stars. Applies to repository results only; sending it with no `sources` scope returns no `doc` results.",+ "schema": {+ "type": "integer",+ "minimum": 0+ }+ },+ {+ "name": "max_stars",+ "in": "query",+ "required": false,+ "description": "Upper bound on repository stars. Applies to repository results only; sending it with no `sources` scope returns no `doc` results.",+ "schema": {+ "type": "integer",+ "minimum": 0+ }+ },+ {+ "name": "archived",+ "in": "query",+ "required": false,+ "description": "Include or exclude archived repositories. Applies to repository results only; sending it with no `sources` scope returns no `doc` results.",+ "schema": {+ "type": "boolean"+ }+ },+ {+ "name": "fork",+ "in": "query",+ "required": false,+ "description": "Include or exclude forks. Applies to repository results only; sending it with no `sources` scope returns no `doc` results.",+ "schema": {+ "type": "boolean"+ }+ }+ ],+ "responses": {+ "200": {+ "description": "Ranked developer results with matched passages.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/DeveloperSearchResponse"+ },+ "example": {+ "success": true,+ "results": [+ {+ "id": "issue:firecrawl/firecrawl#1234",+ "type": "issue",+ "url": "https://github.com/firecrawl/firecrawl/issues/1234",+ "title": "Retries are not applied to 429 responses",+ "passages": [+ {+ "text": "The client treats 429 as a terminal status, so the backoff never runs."+ }+ ]+ }+ ],+ "coverage": {+ "doc": "ok",+ "issue": "ok",+ "pull_request": "ok",+ "readme": "ok"+ },+ "reranked": true+ }+ }+ }+ },+ "400": {+ "description": "Invalid request, including a filter that cannot match any requested type"+ },+ "401": {+ "description": "Missing or invalid bearer token"+ },+ "429": {+ "description": "Rate limit exceeded"+ },+ "500": {+ "description": "Internal server error"+ }+ }+ },+ "post": {+ "summary": "Search the developer index",+ "operationId": "developerSearchPost",+ "tags": [+ "Developer"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "required": [+ "query"+ ],+ "properties": {+ "query": {+ "type": "string",+ "minLength": 1+ },+ "k": {+ "type": "integer",+ "minimum": 1,+ "maximum": 100,+ "default": 10+ },+ "types": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "doc",+ "issue",+ "pull_request",+ "readme"+ ]+ }+ },+ "repos": {+ "type": "array",+ "description": "Repository slugs to scope the repository half of the index to. Applies to the `issue`, `pull_request`, and `readme` types only. Sent together with `sources`, the two halves are combined rather than intersected. Returns 400 when no repository type is in `types`, reporting that `repos` cannot match any requested type and that you should add repository types or drop `repos`.",+ "items": {+ "type": "string"+ }+ },+ "sources": {+ "type": "array",+ "description": "Documentation source ids to scope the documentation half to, at most 20. Applies to the `doc` type only. Not a fixed enum: ids reflect the documentation sites in the index and the set grows over time. Returns 400 with `sources cannot match any requested type; add doc or drop sources` when `doc` is not in `types`.",+ "maxItems": 20,+ "items": {+ "type": "string",+ "minLength": 1,+ "maxLength": 512+ }+ },+ "skills": {+ "type": "string",+ "description": "Set to `only` to limit the search to indexed agent-skill files.",+ "enum": [+ "only"+ ]+ },+ "passages": {+ "type": "integer",+ "minimum": 1,+ "maximum": 5,+ "default": 1+ },+ "language": {+ "type": "string",+ "description": "Repository primary language, such as `Rust`. Applies to repository results only; sending it with no `sources` scope returns no `doc` results. See [how the repository filters scope a search](/api-reference/endpoint/developer-search#how-the-repository-filters-scope-a-search).",+ "example": "Rust"+ },+ "topic": {+ "type": "string",+ "description": "Repository topic, such as `async`. Applies to repository results only; sending it with no `sources` scope returns no `doc` results.",+ "example": "async"+ },+ "license": {+ "type": "string",+ "description": "Repository license, such as `MIT`. Applies to repository results only; sending it with no `sources` scope returns no `doc` results.",+ "example": "MIT"+ },+ "min_stars": {+ "type": "integer",+ "minimum": 0,+ "description": "Lower bound on repository stars. Applies to repository results only; sending it with no `sources` scope returns no `doc` results."+ },+ "max_stars": {+ "type": "integer",+ "minimum": 0,+ "description": "Upper bound on repository stars. Applies to repository results only; sending it with no `sources` scope returns no `doc` results."+ },+ "archived": {+ "type": "boolean",+ "description": "Include or exclude archived repositories. Applies to repository results only; sending it with no `sources` scope returns no `doc` results."+ },+ "fork": {+ "type": "boolean",+ "description": "Include or exclude forks. Applies to repository results only; sending it with no `sources` scope returns no `doc` results."+ }+ }+ },+ "example": {+ "query": "how do I configure retries",+ "k": 10,+ "types": [+ "issue",+ "pull_request"+ ]+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Ranked developer results with matched passages.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/DeveloperSearchResponse"+ }+ }+ }+ },+ "400": {+ "description": "Invalid request, including a filter that cannot match any requested type"+ },+ "401": {+ "description": "Missing or invalid bearer token"+ },+ "429": {+ "description": "Rate limit exceeded"+ },+ "500": {+ "description": "Internal server error"+ }+ }+ }+ },+ "/feedback": {+ "post": {+ "summary": "Submit feedback for a v2 job",+ "operationId": "submitEndpointFeedback",+ "tags": [+ "Feedback"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/EndpointFeedbackRequest"+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Feedback recorded",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/FeedbackResponse"+ }+ }+ }+ },+ "400": {+ "description": "Invalid request body",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/FeedbackErrorResponse"+ }+ }+ }+ },+ "403": {+ "description": "Feedback is not available for this team",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/FeedbackErrorResponse"+ }+ }+ }+ },+ "404": {+ "description": "Job not found for this team",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/FeedbackErrorResponse"+ }+ }+ }+ },+ "409": {+ "description": "Feedback cannot be recorded for this job",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/FeedbackErrorResponse"+ }+ }+ }+ },+ "500": {+ "description": "Server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/FeedbackErrorResponse"+ }+ }+ }+ }+ }+ }+ },+ "/team/threat-protection": {+ "get": {+ "summary": "Get the team's threat protection policy",+ "operationId": "getThreatProtection",+ "tags": [+ "Threat Protection"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "responses": {+ "200": {+ "description": "Effective threat protection policy for the team's organization.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": true+ },+ "data": {+ "type": "object",+ "properties": {+ "mode": {+ "type": "string",+ "enum": [+ "off",+ "normal"+ ],+ "description": "Threat protection mode. `off` disables checks; `normal` checks URLs against Google Web Risk (+2 credits per URL scanned).",+ "example": "normal"+ },+ "riskScoreThreshold": {+ "type": "integer",+ "minimum": 0,+ "maximum": 100,+ "description": "Normalized score (0-100) at or above which a classifier verdict is blocked. Lower is stricter.",+ "example": 75+ },+ "blacklist": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Exact domains or globs (e.g. `*.example.com`) always blocked, without a classifier call.",+ "example": [+ "*.risky.example"+ ]+ },+ "whitelist": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Exact domains or globs always allowed. Wins over every other rule.",+ "example": [+ "*.trusted.example"+ ]+ },+ "blockedTlds": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Top-level domains to block outright, lowercase without a leading dot.",+ "example": [+ "zip"+ ]+ },+ "failurePolicy": {+ "type": "string",+ "enum": [+ "open",+ "closed"+ ],+ "description": "Behavior when the classifier is unreachable: `closed` blocks (default), `open` allows.",+ "example": "closed"+ },+ "allowRequestOverrides": {+ "type": "boolean",+ "description": "Whether individual requests may pass a `threatProtection` object. When false, such requests are rejected with 403.",+ "example": true+ },+ "configured": {+ "type": "boolean",+ "description": "Whether the organization has saved a policy (vs. serving defaults).",+ "example": true+ },+ "updatedAt": {+ "type": "string",+ "format": "date-time",+ "nullable": true+ }+ }+ }+ }+ }+ }+ }+ },+ "403": {+ "description": "Threat protection is not enabled for this team, or a request override was sent while overrides are disabled."+ }+ }+ },+ "put": {+ "summary": "Update the team's threat protection policy",+ "description": "Full-document update. Unspecified fields reset to defaults. Enterprise feature, team admins only.",+ "operationId": "updateThreatProtection",+ "tags": [+ "Threat Protection"+ ],+ "security": [+ {+ "bearerAuth": []+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "required": [+ "mode"+ ],+ "properties": {+ "mode": {+ "type": "string",+ "enum": [+ "off",+ "normal"+ ],+ "description": "Threat protection mode. `off` disables checks; `normal` checks URLs against Google Web Risk (+2 credits per URL scanned).",+ "example": "normal"+ },+ "riskScoreThreshold": {+ "type": "integer",+ "minimum": 0,+ "maximum": 100,+ "description": "Normalized score (0-100) at or above which a classifier verdict is blocked. Lower is stricter.",+ "example": 75+ },+ "blacklist": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Exact domains or globs (e.g. `*.example.com`) always blocked, without a classifier call.",+ "example": [+ "*.risky.example"+ ]+ },+ "whitelist": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Exact domains or globs always allowed. Wins over every other rule.",+ "example": [+ "*.trusted.example"+ ]+ },+ "blockedTlds": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Top-level domains to block outright, lowercase without a leading dot.",+ "example": [+ "zip"+ ]+ },+ "failurePolicy": {+ "type": "string",+ "enum": [+ "open",+ "closed"+ ],+ "description": "Behavior when the classifier is unreachable: `closed` blocks (default), `open` allows.",+ "example": "closed"+ },+ "allowRequestOverrides": {+ "type": "boolean",+ "description": "Whether individual requests may pass a `threatProtection` object. When false, such requests are rejected with 403.",+ "example": true+ }+ }+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Effective threat protection policy for the team's organization.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": true+ },+ "data": {+ "type": "object",+ "properties": {+ "mode": {+ "type": "string",+ "enum": [+ "off",+ "normal"+ ],+ "description": "Threat protection mode. `off` disables checks; `normal` checks URLs against Google Web Risk (+2 credits per URL scanned).",+ "example": "normal"+ },+ "riskScoreThreshold": {+ "type": "integer",+ "minimum": 0,+ "maximum": 100,+ "description": "Normalized score (0-100) at or above which a classifier verdict is blocked. Lower is stricter.",+ "example": 75+ },+ "blacklist": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Exact domains or globs (e.g. `*.example.com`) always blocked, without a classifier call.",+ "example": [+ "*.risky.example"+ ]+ },+ "whitelist": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Exact domains or globs always allowed. Wins over every other rule.",+ "example": [+ "*.trusted.example"+ ]+ },+ "blockedTlds": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Top-level domains to block outright, lowercase without a leading dot.",+ "example": [+ "zip"+ ]+ },+ "failurePolicy": {+ "type": "string",+ "enum": [+ "open",+ "closed"+ ],+ "description": "Behavior when the classifier is unreachable: `closed` blocks (default), `open` allows.",+ "example": "closed"+ },+ "allowRequestOverrides": {+ "type": "boolean",+ "description": "Whether individual requests may pass a `threatProtection` object. When false, such requests are rejected with 403.",+ "example": true+ },+ "configured": {+ "type": "boolean",+ "description": "Whether the organization has saved a policy (vs. serving defaults).",+ "example": true+ },+ "updatedAt": {+ "type": "string",+ "format": "date-time",+ "nullable": true+ }+ }+ }+ }+ }+ }+ }+ },+ "400": {+ "description": "Invalid policy document."+ },+ "403": {+ "description": "Threat protection is not enabled for this team, or a request override was sent while overrides are disabled."+ }+ }+ }+ }+ },+ "components": {+ "securitySchemes": {+ "bearerAuth": {+ "type": "http",+ "scheme": "bearer"+ }+ },+ "parameters": {+ "MonitorId": {+ "name": "monitorId",+ "in": "path",+ "required": true,+ "schema": {+ "type": "string",+ "format": "uuid"+ },+ "description": "The monitor ID"+ }+ },+ "schemas": {+ "AuditMetadata": {+ "type": "object",+ "description": "User attribution included with SIEM logging events when SIEM Logging is enabled for the organization.",+ "additionalProperties": false,+ "required": [+ "username"+ ],+ "properties": {+ "username": {+ "type": "string",+ "maxLength": 1024,+ "description": "The username associated with the request."+ }+ }+ },+ "AgentTraceAgent": {+ "type": "object",+ "description": "Identity of the agent that emitted the event.",+ "required": [+ "id",+ "role",+ "name"+ ],+ "properties": {+ "id": {+ "type": "string",+ "format": "uuid"+ },+ "role": {+ "type": "string",+ "enum": [+ "orchestrator",+ "subagent",+ "system"+ ]+ },+ "name": {+ "type": "string"+ },+ "parentId": {+ "type": "string",+ "format": "uuid",+ "description": "ID of the parent agent (present on subagents)."+ }+ }+ },+ "AgentTraceError": {+ "type": "object",+ "description": "Structured error attached to terminal and error events.",+ "required": [+ "code",+ "source",+ "retryable",+ "message"+ ],+ "properties": {+ "code": {+ "type": "string",+ "enum": [+ "cancelled",+ "credit_limit_reached",+ "parent_finished",+ "refused",+ "internal"+ ]+ },+ "source": {+ "type": "string",+ "enum": [+ "agent",+ "tool",+ "billing",+ "system"+ ]+ },+ "retryable": {+ "type": "boolean"+ },+ "message": {+ "type": "string"+ }+ }+ },+ "AgentTraceArtifact": {+ "type": "object",+ "description": "Descriptor for a change to an output artifact.",+ "required": [+ "kind",+ "artifactId",+ "snapshotId",+ "change"+ ],+ "properties": {+ "kind": {+ "type": "string",+ "enum": [+ "json",+ "markdown",+ "html",+ "screenshot",+ "text"+ ]+ },+ "artifactId": {+ "type": "string"+ },+ "path": {+ "type": "string",+ "description": "Workspace path of the artifact, e.g. /workspace/data.json."+ },+ "snapshotId": {+ "type": "string",+ "format": "uuid",+ "description": "Pass to GET /agent/{jobId}/snapshots/{snapshotId} to fetch this snapshot's content."+ },+ "change": {+ "type": "string",+ "enum": [+ "init",+ "partial",+ "append",+ "modify",+ "update"+ ]+ },+ "changedFields": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "itemCount": {+ "type": "integer"+ },+ "sourceToolCallId": {+ "type": "string",+ "description": "The tool call that produced this change, when applicable."+ }+ }+ },+ "AgentTraceEvent": {+ "description": "A canonical execution event from an agent run. Every event carries the envelope fields schemaVersion, eventId, runId, occurredAt, producerSequence and agent; the type field discriminates the variant. usage.recorded events are internal and never exposed, and agent.started events omit the model field.",+ "oneOf": [+ {+ "title": "run.started",+ "type": "object",+ "required": [+ "schemaVersion",+ "eventId",+ "runId",+ "occurredAt",+ "producerSequence",+ "agent",+ "type"+ ],+ "properties": {+ "schemaVersion": {+ "type": "integer",+ "enum": [+ 1+ ]+ },+ "eventId": {+ "type": "string",+ "format": "uuid",+ "description": "Unique ID of this event."+ },+ "runId": {+ "type": "string",+ "format": "uuid",+ "description": "The agent job ID this event belongs to."+ },+ "occurredAt": {+ "type": "string",+ "format": "date-time"+ },+ "producerSequence": {+ "type": "integer",+ "description": "Monotonic sequence number from the emitting agent; order events by it."+ },+ "agent": {+ "$ref": "#/components/schemas/AgentTraceAgent"+ },+ "type": {+ "type": "string",+ "enum": [+ "run.started"+ ],+ "description": "Emitted when the run starts."+ }+ }+ },+ {+ "title": "run.cancel_requested",+ "type": "object",+ "required": [+ "schemaVersion",+ "eventId",+ "runId",+ "occurredAt",+ "producerSequence",+ "agent",+ "type",+ "reason"+ ],+ "properties": {+ "schemaVersion": {+ "type": "integer",+ "enum": [+ 1+ ]+ },+ "eventId": {+ "type": "string",+ "format": "uuid",+ "description": "Unique ID of this event."+ },+ "runId": {+ "type": "string",+ "format": "uuid",+ "description": "The agent job ID this event belongs to."+ },+ "occurredAt": {+ "type": "string",+ "format": "date-time"+ },+ "producerSequence": {+ "type": "integer",+ "description": "Monotonic sequence number from the emitting agent; order events by it."+ },+ "agent": {+ "$ref": "#/components/schemas/AgentTraceAgent"+ },+ "type": {+ "type": "string",+ "enum": [+ "run.cancel_requested"+ ],+ "description": "Emitted when cancellation is requested (via DELETE /agent/{jobId})."+ },+ "reason": {+ "type": "string",+ "enum": [+ "user"+ ]+ }+ }+ },+ {+ "title": "run.finished",+ "type": "object",+ "required": [+ "schemaVersion",+ "eventId",+ "runId",+ "occurredAt",+ "producerSequence",+ "agent",+ "type",+ "outcome",+ "error"+ ],+ "properties": {+ "schemaVersion": {+ "type": "integer",+ "enum": [+ 1+ ]+ },+ "eventId": {+ "type": "string",+ "format": "uuid",+ "description": "Unique ID of this event."+ },+ "runId": {+ "type": "string",+ "format": "uuid",+ "description": "The agent job ID this event belongs to."+ },+ "occurredAt": {+ "type": "string",+ "format": "date-time"+ },+ "producerSequence": {+ "type": "integer",+ "description": "Monotonic sequence number from the emitting agent; order events by it."+ },+ "agent": {+ "$ref": "#/components/schemas/AgentTraceAgent"+ },+ "type": {+ "type": "string",+ "enum": [+ "run.finished"+ ],+ "description": "Terminal event for the run."+ },+ "outcome": {+ "type": "string",+ "enum": [+ "succeeded",+ "failed",+ "cancelled",+ "refused",+ "credit_limit_reached"+ ]+ },+ "error": {+ "nullable": true,+ "allOf": [+ {+ "$ref": "#/components/schemas/AgentTraceError"+ }+ ],+ "description": "Null when outcome is succeeded; otherwise the structured error."+ }+ }+ },+ {+ "title": "agent.started",+ "type": "object",+ "required": [+ "schemaVersion",+ "eventId",+ "runId",+ "occurredAt",+ "producerSequence",+ "agent",+ "type"+ ],+ "properties": {+ "schemaVersion": {+ "type": "integer",+ "enum": [+ 1+ ]+ },+ "eventId": {+ "type": "string",+ "format": "uuid",+ "description": "Unique ID of this event."+ },+ "runId": {+ "type": "string",+ "format": "uuid",+ "description": "The agent job ID this event belongs to."+ },+ "occurredAt": {+ "type": "string",+ "format": "date-time"+ },+ "producerSequence": {+ "type": "integer",+ "description": "Monotonic sequence number from the emitting agent; order events by it."+ },+ "agent": {+ "$ref": "#/components/schemas/AgentTraceAgent"+ },+ "type": {+ "type": "string",+ "enum": [+ "agent.started"+ ],+ "description": "Emitted when an agent (orchestrator or subagent) starts."+ }+ }+ },+ {+ "title": "agent.finished",+ "type": "object",+ "required": [+ "schemaVersion",+ "eventId",+ "runId",+ "occurredAt",+ "producerSequence",+ "agent",+ "type",+ "outcome",+ "durationMs",+ "error"+ ],+ "properties": {+ "schemaVersion": {+ "type": "integer",+ "enum": [+ 1+ ]+ },+ "eventId": {+ "type": "string",+ "format": "uuid",+ "description": "Unique ID of this event."+ },+ "runId": {+ "type": "string",+ "format": "uuid",+ "description": "The agent job ID this event belongs to."+ },+ "occurredAt": {+ "type": "string",+ "format": "date-time"+ },+ "producerSequence": {+ "type": "integer",+ "description": "Monotonic sequence number from the emitting agent; order events by it."+ },+ "agent": {+ "$ref": "#/components/schemas/AgentTraceAgent"+ },+ "type": {+ "type": "string",+ "enum": [+ "agent.finished"+ ],+ "description": "Emitted when an agent finishes."+ },+ "outcome": {+ "type": "string",+ "enum": [+ "succeeded",+ "failed",+ "cancelled",+ "refused"+ ]+ },+ "durationMs": {+ "type": "integer"+ },+ "error": {+ "nullable": true,+ "allOf": [+ {+ "$ref": "#/components/schemas/AgentTraceError"+ }+ ],+ "description": "Null when outcome is succeeded; otherwise the structured error."+ }+ }+ },+ {+ "title": "browser.session.started",+ "type": "object",+ "required": [+ "schemaVersion",+ "eventId",+ "runId",+ "occurredAt",+ "producerSequence",+ "agent",+ "type",+ "sessionId"+ ],+ "properties": {+ "schemaVersion": {+ "type": "integer",+ "enum": [+ 1+ ]+ },+ "eventId": {+ "type": "string",+ "format": "uuid",+ "description": "Unique ID of this event."+ },+ "runId": {+ "type": "string",+ "format": "uuid",+ "description": "The agent job ID this event belongs to."+ },+ "occurredAt": {+ "type": "string",+ "format": "date-time"+ },+ "producerSequence": {+ "type": "integer",+ "description": "Monotonic sequence number from the emitting agent; order events by it."+ },+ "agent": {+ "$ref": "#/components/schemas/AgentTraceAgent"+ },+ "type": {+ "type": "string",+ "enum": [+ "browser.session.started"+ ],+ "description": "Emitted when a browser session starts."+ },+ "sessionId": {+ "type": "string"+ }+ }+ },+ {+ "title": "browser.session.finished",+ "type": "object",+ "required": [+ "schemaVersion",+ "eventId",+ "runId",+ "occurredAt",+ "producerSequence",+ "agent",+ "type",+ "sessionId",+ "durationMs"+ ],+ "properties": {+ "schemaVersion": {+ "type": "integer",+ "enum": [+ 1+ ]+ },+ "eventId": {+ "type": "string",+ "format": "uuid",+ "description": "Unique ID of this event."+ },+ "runId": {+ "type": "string",+ "format": "uuid",+ "description": "The agent job ID this event belongs to."+ },+ "occurredAt": {+ "type": "string",+ "format": "date-time"+ },+ "producerSequence": {+ "type": "integer",+ "description": "Monotonic sequence number from the emitting agent; order events by it."+ },+ "agent": {+ "$ref": "#/components/schemas/AgentTraceAgent"+ },+ "type": {+ "type": "string",+ "enum": [+ "browser.session.finished"+ ],+ "description": "Emitted when a browser session finishes."+ },+ "sessionId": {+ "type": "string"+ },+ "durationMs": {+ "type": "integer"+ }+ }+ },+ {+ "title": "progress.reported",+ "type": "object",+ "required": [+ "schemaVersion",+ "eventId",+ "runId",+ "occurredAt",+ "producerSequence",+ "agent",+ "type",+ "phase",+ "message"+ ],+ "properties": {+ "schemaVersion": {+ "type": "integer",+ "enum": [+ 1+ ]+ },+ "eventId": {+ "type": "string",+ "format": "uuid",+ "description": "Unique ID of this event."+ },+ "runId": {+ "type": "string",+ "format": "uuid",+ "description": "The agent job ID this event belongs to."+ },+ "occurredAt": {+ "type": "string",+ "format": "date-time"+ },+ "producerSequence": {+ "type": "integer",+ "description": "Monotonic sequence number from the emitting agent; order events by it."+ },+ "agent": {+ "$ref": "#/components/schemas/AgentTraceAgent"+ },+ "type": {+ "type": "string",+ "enum": [+ "progress.reported"+ ],+ "description": "Emitted when the orchestrator reports progress."+ },+ "phase": {+ "type": "string",+ "enum": [+ "planning",+ "working",+ "finalizing"+ ]+ },+ "message": {+ "type": "string"+ }+ }+ },+ {+ "title": "reasoning.summary",+ "type": "object",+ "required": [+ "schemaVersion",+ "eventId",+ "runId",+ "occurredAt",+ "producerSequence",+ "agent",+ "type",+ "text"+ ],+ "properties": {+ "schemaVersion": {+ "type": "integer",+ "enum": [+ 1+ ]+ },+ "eventId": {+ "type": "string",+ "format": "uuid",+ "description": "Unique ID of this event."+ },+ "runId": {+ "type": "string",+ "format": "uuid",+ "description": "The agent job ID this event belongs to."+ },+ "occurredAt": {+ "type": "string",+ "format": "date-time"+ },+ "producerSequence": {+ "type": "integer",+ "description": "Monotonic sequence number from the emitting agent; order events by it."+ },+ "agent": {+ "$ref": "#/components/schemas/AgentTraceAgent"+ },+ "type": {+ "type": "string",+ "enum": [+ "reasoning.summary"+ ],+ "description": "A summary of the agent's reasoning."+ },+ "text": {+ "type": "string"+ }+ }+ },+ {+ "title": "tool_call.started",+ "type": "object",+ "required": [+ "schemaVersion",+ "eventId",+ "runId",+ "occurredAt",+ "producerSequence",+ "agent",+ "type",+ "toolCallId",+ "toolName",+ "parameters"+ ],+ "properties": {+ "schemaVersion": {+ "type": "integer",+ "enum": [+ 1+ ]+ },+ "eventId": {+ "type": "string",+ "format": "uuid",+ "description": "Unique ID of this event."+ },+ "runId": {+ "type": "string",+ "format": "uuid",+ "description": "The agent job ID this event belongs to."+ },+ "occurredAt": {+ "type": "string",+ "format": "date-time"+ },+ "producerSequence": {+ "type": "integer",+ "description": "Monotonic sequence number from the emitting agent; order events by it."+ },+ "agent": {+ "$ref": "#/components/schemas/AgentTraceAgent"+ },+ "type": {+ "type": "string",+ "enum": [+ "tool_call.started"+ ],+ "description": "Emitted when a tool call starts."+ },+ "toolCallId": {+ "type": "string"+ },+ "toolName": {+ "type": "string"+ },+ "parameters": {+ "description": "The input passed to the tool (arbitrary JSON)."+ }+ }+ },+ {+ "title": "tool_call.finished",+ "type": "object",+ "required": [+ "schemaVersion",+ "eventId",+ "runId",+ "occurredAt",+ "producerSequence",+ "agent",+ "type",+ "toolCallId",+ "toolName",+ "result"+ ],+ "properties": {+ "schemaVersion": {+ "type": "integer",+ "enum": [+ 1+ ]+ },+ "eventId": {+ "type": "string",+ "format": "uuid",+ "description": "Unique ID of this event."+ },+ "runId": {+ "type": "string",+ "format": "uuid",+ "description": "The agent job ID this event belongs to."+ },+ "occurredAt": {+ "type": "string",+ "format": "date-time"+ },+ "producerSequence": {+ "type": "integer",+ "description": "Monotonic sequence number from the emitting agent; order events by it."+ },+ "agent": {+ "$ref": "#/components/schemas/AgentTraceAgent"+ },+ "type": {+ "type": "string",+ "enum": [+ "tool_call.finished"+ ],+ "description": "Emitted when a tool call finishes."+ },+ "toolCallId": {+ "type": "string"+ },+ "toolName": {+ "type": "string"+ },+ "result": {+ "description": "The result returned by the tool (arbitrary JSON)."+ }+ }+ },+ {+ "title": "artifact.updated",+ "type": "object",+ "required": [+ "schemaVersion",+ "eventId",+ "runId",+ "occurredAt",+ "producerSequence",+ "agent",+ "type",+ "artifact"+ ],+ "properties": {+ "schemaVersion": {+ "type": "integer",+ "enum": [+ 1+ ]+ },+ "eventId": {+ "type": "string",+ "format": "uuid",+ "description": "Unique ID of this event."+ },+ "runId": {+ "type": "string",+ "format": "uuid",+ "description": "The agent job ID this event belongs to."+ },+ "occurredAt": {+ "type": "string",+ "format": "date-time"+ },+ "producerSequence": {+ "type": "integer",+ "description": "Monotonic sequence number from the emitting agent; order events by it."+ },+ "agent": {+ "$ref": "#/components/schemas/AgentTraceAgent"+ },+ "type": {+ "type": "string",+ "enum": [+ "artifact.updated"+ ],+ "description": "Emitted when an output artifact changes."+ },+ "artifact": {+ "$ref": "#/components/schemas/AgentTraceArtifact"+ }+ }+ },+ {+ "title": "error.occurred",+ "type": "object",+ "required": [+ "schemaVersion",+ "eventId",+ "runId",+ "occurredAt",+ "producerSequence",+ "agent",+ "type",+ "error"+ ],+ "properties": {+ "schemaVersion": {+ "type": "integer",+ "enum": [+ 1+ ]+ },+ "eventId": {+ "type": "string",+ "format": "uuid",+ "description": "Unique ID of this event."+ },+ "runId": {+ "type": "string",+ "format": "uuid",+ "description": "The agent job ID this event belongs to."+ },+ "occurredAt": {+ "type": "string",+ "format": "date-time"+ },+ "producerSequence": {+ "type": "integer",+ "description": "Monotonic sequence number from the emitting agent; order events by it."+ },+ "agent": {+ "$ref": "#/components/schemas/AgentTraceAgent"+ },+ "type": {+ "type": "string",+ "enum": [+ "error.occurred"+ ],+ "description": "Emitted when a non-fatal error occurs during the run."+ },+ "error": {+ "$ref": "#/components/schemas/AgentTraceError"+ }+ }+ }+ ],+ "discriminator": {+ "propertyName": "type"+ }+ },+ "SuccessResponse": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": true+ }+ }+ },+ "MonitorSchedule": {+ "type": "object",+ "description": "Schedule for monitor checks. Provide either `cron` or `text`.",+ "properties": {+ "cron": {+ "type": "string",+ "description": "Five-field cron expression. Minimum interval is 5 minutes.",+ "example": "*/30 * * * *"+ },+ "text": {+ "type": "string",+ "description": "Natural language schedule. Supported examples include `every 30 minutes`, `every 15 minutes starting at :07`, `hourly`, `every 2 hours`, `daily`, `daily at 9:00`, `daily at 9am`, `daily at 5:30 PM`, and `weekly`.",+ "example": "every 30 minutes"+ },+ "timezone": {+ "type": "string",+ "default": "UTC",+ "description": "IANA timezone for the schedule.",+ "example": "UTC"+ }+ }+ },+ "MonitorWebhook": {+ "type": "object",+ "description": "Webhook destination for monitor page and check completion events.",+ "properties": {+ "url": {+ "type": "string",+ "format": "uri",+ "description": "The URL to send monitor webhooks to."+ },+ "headers": {+ "type": "object",+ "description": "Headers to send to the webhook URL.",+ "additionalProperties": {+ "type": "string"+ }+ },+ "metadata": {+ "type": "object",+ "description": "Custom metadata included in webhook payloads.",+ "additionalProperties": true+ },+ "events": {+ "type": "array",+ "description": "Monitor webhook events to receive. Defaults to all monitor events.",+ "items": {+ "type": "string",+ "enum": [+ "monitor.page",+ "monitor.check.completed"+ ]+ }+ }+ },+ "required": [+ "url"+ ]+ },+ "MonitorNotification": {+ "type": "object",+ "properties": {+ "email": {+ "type": "object",+ "properties": {+ "enabled": {+ "type": "boolean",+ "default": false+ },+ "recipients": {+ "type": "array",+ "maxItems": 25,+ "items": {+ "type": "string",+ "format": "email"+ }+ },+ "includeDiffs": {+ "type": "boolean",+ "default": false,+ "description": "Include changed page details in email summaries."+ }+ }+ }+ }+ },+ "MonitorTarget": {+ "oneOf": [+ {+ "type": "object",+ "title": "Scrape target",+ "properties": {+ "id": {+ "type": "string",+ "format": "uuid",+ "description": "Optional stable ID for this target. Generated if omitted."+ },+ "type": {+ "type": "string",+ "enum": [+ "scrape"+ ]+ },+ "urls": {+ "type": "array",+ "minItems": 1,+ "items": {+ "type": "string",+ "format": "uri"+ }+ },+ "scrapeOptions": {+ "$ref": "#/components/schemas/ScrapeOptions"+ }+ },+ "required": [+ "type",+ "urls"+ ]+ },+ {+ "type": "object",+ "title": "Crawl target",+ "properties": {+ "id": {+ "type": "string",+ "format": "uuid",+ "description": "Optional stable ID for this target. Generated if omitted."+ },+ "type": {+ "type": "string",+ "enum": [+ "crawl"+ ]+ },+ "url": {+ "type": "string",+ "format": "uri"+ },+ "crawlOptions": {+ "type": "object",+ "description": "Crawl options such as `limit`, `maxDepth`, `includePaths`, and `excludePaths`."+ },+ "scrapeOptions": {+ "$ref": "#/components/schemas/ScrapeOptions"+ }+ },+ "required": [+ "type",+ "url"+ ]+ },+ {+ "type": "object",+ "title": "Search target",+ "description": "Runs web search queries on each check and alerts on new results that match the monitor's goal. Requires a non-empty top-level `goal` on the monitor unless `judgeEnabled` is `false`.",+ "properties": {+ "id": {+ "type": "string",+ "format": "uuid",+ "description": "Optional stable ID for this target. Generated if omitted."+ },+ "type": {+ "type": "string",+ "enum": [+ "search"+ ]+ },+ "queries": {+ "type": "array",+ "minItems": 1,+ "maxItems": 12,+ "items": {+ "type": "string",+ "minLength": 1,+ "maxLength": 256+ },+ "description": "Search queries to run on each check (1-12)."+ },+ "searchWindow": {+ "type": "string",+ "enum": [+ "5m",+ "15m",+ "1h",+ "6h",+ "24h",+ "7d"+ ],+ "default": "24h",+ "description": "Recency filter — only consider results published within this window."+ },+ "maxResults": {+ "type": "integer",+ "minimum": 1,+ "maximum": 50,+ "default": 10,+ "description": "Total results to evaluate per check, merged and deduped across all queries (a combined cap, not per-query)."+ },+ "includeDomains": {+ "type": "array",+ "maxItems": 50,+ "items": {+ "type": "string"+ },+ "description": "Optional. Restrict results to these domains."+ },+ "excludeDomains": {+ "type": "array",+ "maxItems": 50,+ "items": {+ "type": "string"+ },+ "description": "Optional. Drop results from these domains."+ }+ },+ "required": [+ "type",+ "queries"+ ]+ }+ ]+ },+ "MonitorCreateRequest": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "maxLength": 256+ },+ "schedule": {+ "$ref": "#/components/schemas/MonitorSchedule"+ },+ "webhook": {+ "$ref": "#/components/schemas/MonitorWebhook"+ },+ "notification": {+ "$ref": "#/components/schemas/MonitorNotification"+ },+ "targets": {+ "type": "array",+ "minItems": 1,+ "maxItems": 50,+ "items": {+ "$ref": "#/components/schemas/MonitorTarget"+ }+ },+ "retentionDays": {+ "type": "integer",+ "minimum": 1,+ "maximum": 365,+ "default": 30+ },+ "goal": {+ "type": "string",+ "maxLength": 2000,+ "nullable": true,+ "description": "Plain-language goal used to judge whether changed pages are meaningful. If provided and `judgeEnabled` is omitted, judging is enabled automatically. Required (non-empty) when any target is a `search` target, unless `judgeEnabled` is `false`."+ },+ "judgeEnabled": {+ "type": "boolean",+ "description": "Whether to judge changed pages against `goal`. Requires a non-empty `goal` to run."+ }+ },+ "required": [+ "name",+ "schedule",+ "targets"+ ]+ },+ "MonitorUpdateRequest": {+ "type": "object",+ "description": "Partial monitor update payload. Include at least one field.",+ "properties": {+ "name": {+ "type": "string",+ "maxLength": 256+ },+ "schedule": {+ "$ref": "#/components/schemas/MonitorSchedule"+ },+ "webhook": {+ "$ref": "#/components/schemas/MonitorWebhook"+ },+ "notification": {+ "$ref": "#/components/schemas/MonitorNotification"+ },+ "targets": {+ "type": "array",+ "minItems": 1,+ "maxItems": 50,+ "items": {+ "$ref": "#/components/schemas/MonitorTarget"+ }+ },+ "retentionDays": {+ "type": "integer",+ "minimum": 1,+ "maximum": 365+ },+ "goal": {+ "type": "string",+ "maxLength": 2000,+ "nullable": true,+ "description": "Plain-language goal used to judge whether changed pages are meaningful. If provided and `judgeEnabled` is omitted, judging is enabled automatically. Required (non-empty) when any target is a `search` target, unless `judgeEnabled` is `false`."+ },+ "judgeEnabled": {+ "type": "boolean",+ "description": "Whether to judge changed pages against `goal`. Requires a non-empty `goal` to run."+ },+ "status": {+ "type": "string",+ "enum": [+ "active",+ "paused"+ ]+ }+ }+ },+ "MonitorSummary": {+ "type": "object",+ "properties": {+ "totalPages": {+ "type": "integer"+ },+ "same": {+ "type": "integer"+ },+ "changed": {+ "type": "integer"+ },+ "new": {+ "type": "integer"+ },+ "removed": {+ "type": "integer"+ },+ "error": {+ "type": "integer"+ }+ }+ },+ "Monitor": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "uuid"+ },+ "name": {+ "type": "string"+ },+ "status": {+ "type": "string",+ "enum": [+ "active",+ "paused",+ "deleted"+ ]+ },+ "schedule": {+ "type": "object",+ "properties": {+ "cron": {+ "type": "string"+ },+ "timezone": {+ "type": "string"+ }+ }+ },+ "nextRunAt": {+ "type": "string",+ "format": "date-time",+ "nullable": true+ },+ "lastRunAt": {+ "type": "string",+ "format": "date-time",+ "nullable": true+ },+ "currentCheckId": {+ "type": "string",+ "format": "uuid",+ "nullable": true+ },+ "targets": {+ "type": "array",+ "items": {+ "$ref": "#/components/schemas/MonitorTarget"+ }+ },+ "webhook": {+ "$ref": "#/components/schemas/MonitorWebhook"+ },+ "notification": {+ "$ref": "#/components/schemas/MonitorNotification"+ },+ "retentionDays": {+ "type": "integer"+ },+ "estimatedCreditsPerMonth": {+ "type": "integer",+ "nullable": true,+ "description": "Upper-bound monthly credit estimate. When judging is enabled, actual usage may be lower because judge credits are only charged for changed pages that are judged."+ },+ "lastCheckSummary": {+ "$ref": "#/components/schemas/MonitorSummary"+ },+ "goal": {+ "type": "string",+ "nullable": true+ },+ "judgeEnabled": {+ "type": "boolean"+ },+ "createdAt": {+ "type": "string",+ "format": "date-time"+ },+ "updatedAt": {+ "type": "string",+ "format": "date-time"+ }+ }+ },+ "MonitorCheck": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "uuid"+ },+ "monitorId": {+ "type": "string",+ "format": "uuid"+ },+ "status": {+ "type": "string",+ "enum": [+ "queued",+ "running",+ "completed",+ "failed",+ "partial",+ "skipped_overlap",+ "skipped_no_credits"+ ]+ },+ "trigger": {+ "type": "string",+ "enum": [+ "scheduled",+ "manual"+ ]+ },+ "scheduledFor": {+ "type": "string",+ "format": "date-time",+ "nullable": true+ },+ "startedAt": {+ "type": "string",+ "format": "date-time",+ "nullable": true+ },+ "finishedAt": {+ "type": "string",+ "format": "date-time",+ "nullable": true+ },+ "estimatedCredits": {+ "type": "integer",+ "nullable": true,+ "description": "Upper-bound credits reserved for this check before Firecrawl knows how many pages changed and require judging."+ },+ "reservedCredits": {+ "type": "integer",+ "nullable": true+ },+ "actualCredits": {+ "type": "integer",+ "nullable": true,+ "description": "Final credits charged for this check after scrapes, crawls, and any changed-page judge calls complete."+ },+ "billingStatus": {+ "type": "string"+ },+ "summary": {+ "$ref": "#/components/schemas/MonitorSummary"+ },+ "targetResults": {+ "type": "array",+ "nullable": true+ },+ "notificationStatus": {+ "type": "object",+ "nullable": true+ },+ "error": {+ "type": "string",+ "nullable": true+ },+ "createdAt": {+ "type": "string",+ "format": "date-time"+ },+ "updatedAt": {+ "type": "string",+ "format": "date-time"+ }+ }+ },+ "MonitorCheckPage": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "format": "uuid"+ },+ "targetId": {+ "type": "string"+ },+ "url": {+ "type": "string",+ "format": "uri"+ },+ "status": {+ "type": "string",+ "enum": [+ "same",+ "new",+ "changed",+ "removed",+ "error"+ ]+ },+ "previousScrapeId": {+ "type": "string",+ "format": "uuid",+ "nullable": true+ },+ "currentScrapeId": {+ "type": "string",+ "format": "uuid",+ "nullable": true+ },+ "statusCode": {+ "type": "integer",+ "nullable": true+ },+ "error": {+ "type": "string",+ "nullable": true+ },+ "metadata": {+ "type": "object",+ "nullable": true,+ "description": "Extra per-page metadata. For search monitors this includes `searchStatus`, the finer-grained search disposition behind the top-level `status`: `alert` (maps to `new`), `already_seen`, `watching`, `ignored` (all map to `same`), or `skipped` (maps to `error`)."+ },+ "judgment": {+ "$ref": "#/components/schemas/MonitorPageJudgment"+ },+ "diff": {+ "type": "object",+ "nullable": true,+ "description": "Inline diff artifact when the page changed. The shape depends on what the monitor's scrapeOptions.formats asked for. Markdown-only monitors populate both `text` (unified diff) and `json` (parseDiff AST). JSON-extraction monitors populate `json` as a per-field `{previous, current}` map keyed by JSON path. Mixed-mode monitors (`changeTracking` with both `json` and `git-diff` modes) populate both `text` (markdown sidecar) and `json` (per-field diff).",+ "properties": {+ "text": {+ "type": "string",+ "description": "Unified markdown diff. Present on markdown-only and mixed-mode monitors."+ },+ "json": {+ "type": "object",+ "description": "For markdown-only monitors, a parseDiff AST `{ files: [...] }`. For JSON-extraction (and mixed-mode) monitors, a per-field `{ previous, current }` map keyed by the JSON path into the extraction (e.g. `plans[0].price`)."+ }+ }+ },+ "snapshot": {+ "type": "object",+ "nullable": true,+ "description": "Snapshot of the current JSON extraction at this run. Present on JSON-extraction and mixed-mode monitors; absent for markdown-only monitors.",+ "properties": {+ "json": {+ "type": "object",+ "description": "The full structured JSON extracted on this run, matching the schema/prompt declared on the target's `changeTracking` format."+ }+ }+ },+ "createdAt": {+ "type": "string",+ "format": "date-time"+ }+ }+ },+ "MonitorPageJudgment": {+ "type": "object",+ "nullable": true,+ "properties": {+ "meaningful": {+ "type": "boolean",+ "description": "Whether the changed page is meaningful for the monitor goal."+ },+ "confidence": {+ "type": "string",+ "enum": [+ "high",+ "medium",+ "low"+ ]+ },+ "reason": {+ "type": "string"+ },+ "meaningfulChanges": {+ "type": "array",+ "description": "Goal-relevant changes selected by the judge from the page diff.",+ "items": {+ "type": "object",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "added",+ "removed",+ "changed"+ ]+ },+ "before": {+ "type": "string",+ "nullable": true+ },+ "after": {+ "type": "string",+ "nullable": true+ },+ "reason": {+ "type": "string"+ }+ }+ }+ }+ }+ },+ "MonitorResponse": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ },+ "data": {+ "$ref": "#/components/schemas/Monitor"+ }+ }+ },+ "MonitorListResponse": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ },+ "data": {+ "type": "array",+ "items": {+ "$ref": "#/components/schemas/Monitor"+ }+ }+ }+ },+ "MonitorRunResponse": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ },+ "id": {+ "type": "string",+ "format": "uuid"+ },+ "data": {+ "$ref": "#/components/schemas/MonitorCheck"+ }+ }+ },+ "MonitorCheckListResponse": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ },+ "data": {+ "type": "array",+ "items": {+ "$ref": "#/components/schemas/MonitorCheck"+ }+ }+ }+ },+ "MonitorCheckDetailResponse": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ },+ "next": {+ "type": "string",+ "nullable": true,+ "description": "URL to fetch the next page of monitor check page results, if any."+ },+ "data": {+ "allOf": [+ {+ "$ref": "#/components/schemas/MonitorCheck"+ },+ {+ "type": "object",+ "properties": {+ "pages": {+ "type": "array",+ "items": {+ "$ref": "#/components/schemas/MonitorCheckPage"+ }+ },+ "next": {+ "type": "string",+ "nullable": true,+ "description": "URL to fetch the next page of monitor check page results, if any."+ }+ }+ }+ ]+ }+ }+ },+ "Formats": {+ "type": "array",+ "items": {+ "oneOf": [+ {+ "type": "object",+ "title": "Markdown",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "markdown"+ ]+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "Summary",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "summary"+ ]+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "HTML",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "html"+ ]+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "Raw HTML",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "rawHtml"+ ]+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "Raw Base64",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "rawBase64"+ ]+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "Links",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "links"+ ]+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "Images",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "images"+ ]+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "Screenshot",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "screenshot"+ ]+ },+ "fullPage": {+ "type": "boolean",+ "description": "Whether to capture a full-page screenshot (ignores viewport.height) or limit to the current viewport.",+ "default": false+ },+ "quality": {+ "type": "integer",+ "description": "The quality of the screenshot, from 1 to 100. 100 is the highest quality."+ },+ "viewport": {+ "type": "object",+ "properties": {+ "width": {+ "type": "integer",+ "description": "The width of the viewport in pixels"+ },+ "height": {+ "type": "integer",+ "description": "The height of the viewport in pixels"+ }+ },+ "required": [+ "width",+ "height"+ ]+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "JSON",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "json"+ ]+ },+ "schema": {+ "type": "object",+ "description": "The schema to use for the JSON output. Must conform to [JSON Schema](https://json-schema.org/)."+ },+ "prompt": {+ "type": "string",+ "description": "The prompt to use for the JSON output"+ },+ "checkPromptInjection": {+ "type": "boolean",+ "description": "When enabled, scans the scraped page content for prompt injection attempts before running the extraction. If an injection is detected, the request fails with a 403 and error code SCRAPE_PROMPT_INJECTION_DETECTED. Adds 4 credits when the check runs. Defaults to false.",+ "default": false+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "Change Tracking",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "changeTracking"+ ]+ },+ "modes": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "git-diff",+ "json"+ ]+ },+ "description": "The mode to use for change tracking. 'git-diff' provides a detailed diff, and 'json' compares extracted JSON data."+ },+ "schema": {+ "type": "object",+ "description": "Schema for JSON extraction when using 'json' mode. Defines the structure of data to extract and compare. Must conform to [JSON Schema](https://json-schema.org/)."+ },+ "prompt": {+ "type": "string",+ "description": "Prompt to use for change tracking when using 'json' mode. If not provided, the default prompt will be used."+ },+ "tag": {+ "type": "string",+ "nullable": true,+ "default": null,+ "description": "Tag to use for change tracking. Tags can separate change tracking history into separate \"branches\", where change tracking with a specific tagwill only compare to scrapes made in the same tag. If not provided, the default tag (null) will be used."+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "Branding",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "branding"+ ]+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "Product",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "product"+ ]+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "Menu",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "menu"+ ]+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "Audio",+ "description": "Extract audio (MP3) from supported video URLs, e.g. YouTube. Returns a signed GCS URL.",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "audio"+ ]+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "Video",+ "description": "Extract best-quality video from supported video URLs, e.g. YouTube. Returns a signed GCS URL.",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "video"+ ]+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "Question",+ "description": "Ask a natural-language question about the page. Returns the answer in the response `answer` field.",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "question"+ ]+ },+ "question": {+ "type": "string",+ "maxLength": 10000,+ "description": "The question to answer about the page. Maximum 10,000 characters."+ }+ },+ "required": [+ "type",+ "question"+ ]+ },+ {+ "type": "object",+ "title": "Highlights",+ "description": "Find relevant source text from the page. Returns the selected text in the response `highlights` field.",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "highlights"+ ]+ },+ "query": {+ "type": "string",+ "maxLength": 10000,+ "description": "The text-selection query to run against the page. Maximum 10,000 characters."+ }+ },+ "required": [+ "type",+ "query"+ ]+ }+ ]+ },+ "description": "Output formats to include in the response. You can specify one or more formats, either as strings (e.g., `'markdown'`) or as objects with additional options (e.g., `{ type: 'json', schema: {...} }`). Some formats require specific options to be set. Example: `['markdown', { type: 'json', schema: {...} }]`.",+ "default": [+ "markdown"+ ]+ },+ "ParseFormats": {+ "type": "array",+ "items": {+ "oneOf": [+ {+ "type": "object",+ "title": "Markdown",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "markdown"+ ]+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "Summary",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "summary"+ ]+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "HTML",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "html"+ ]+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "Raw HTML",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "rawHtml"+ ]+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "Links",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "links"+ ]+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "Images",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "images"+ ]+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "JSON",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "json"+ ]+ },+ "schema": {+ "type": "object",+ "description": "The schema to use for the JSON output. Must conform to [JSON Schema](https://json-schema.org/)."+ },+ "prompt": {+ "type": "string",+ "description": "The prompt to use for the JSON output"+ }+ },+ "required": [+ "type"+ ]+ }+ ]+ },+ "description": "Output formats supported for `/parse` uploads. Browser-rendering formats and change tracking are not supported.",+ "default": [+ "markdown"+ ]+ },+ "ParseOptions": {+ "type": "object",+ "description": "Optional parse options sent as JSON in the multipart `options` field.",+ "properties": {+ "formats": {+ "$ref": "#/components/schemas/ParseFormats"+ },+ "onlyMainContent": {+ "type": "boolean",+ "description": "Only return the main content of the page excluding headers, navs, footers, etc.",+ "default": true+ },+ "includeTags": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Tags to include in the output."+ },+ "excludeTags": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Tags to exclude from the output."+ },+ "headers": {+ "type": "object",+ "description": "Headers to send when additional network requests are required."+ },+ "timeout": {+ "type": "integer",+ "description": "Timeout in milliseconds for the request. Default is 30000 (30 seconds). Maximum is 300000 (300 seconds).",+ "default": 30000,+ "maximum": 300000+ },+ "parsers": {+ "type": "array",+ "description": "Controls file parser behavior when relevant (for example PDF parser mode).",+ "items": {+ "oneOf": [+ {+ "type": "object",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "pdf"+ ]+ },+ "mode": {+ "type": "string",+ "enum": [+ "fast",+ "auto",+ "ocr"+ ],+ "default": "auto",+ "description": "PDF parsing mode. \"fast\": text-only extraction. \"auto\": text-first with OCR fallback. \"ocr\": OCR on every page."+ },+ "maxPages": {+ "type": "integer",+ "minimum": 1,+ "maximum": 10000,+ "description": "Maximum number of pages to parse from the PDF."+ },+ "pages": {+ "type": "boolean",+ "default": false,+ "description": "Include physical per-page markdown alongside the document markdown. Populates the `pages` field on the document as an array of { pageNumber, markdown }. No additional cost."+ },+ "blocks": {+ "type": "boolean",+ "default": false,+ "description": "Include per-page typed layout blocks alongside the document markdown. Populates the `blocks` field on the document: typed blocks (title, section_header, text, table, formula, figure, caption, ...) with normalized bounding boxes, reading order, character-span links into the markdown, and per-block confidence. No additional cost."+ },+ "pageMarkers": {+ "type": "boolean",+ "default": false,+ "description": "Annotate page breaks in the document markdown: pages are joined with `\\n\\n---\\n\\n<!-- page N -->\\n\\n`, where N is the 1-based physical page of the content that follows. Markers appear between pages only (no leading marker for page 1), and numbering may skip pages merged across a page break — use `pages: true` when every physical page is needed. No new response field; no additional cost."+ }+ },+ "required": [+ "type"+ ],+ "additionalProperties": false+ }+ ]+ },+ "default": [+ "pdf"+ ]+ },+ "skipTlsVerification": {+ "type": "boolean",+ "description": "Skip TLS certificate verification when making requests.",+ "default": true+ },+ "removeBase64Images": {+ "type": "boolean",+ "description": "Remove base64-encoded images from output and keep alt text placeholders.",+ "default": true+ },+ "blockAds": {+ "type": "boolean",+ "description": "Enable ad and cookie popup blocking.",+ "default": true+ },+ "redactPII": {+ "oneOf": [+ {+ "type": "boolean"+ },+ {+ "$ref": "#/components/schemas/RedactPIIOptions"+ }+ ],+ "default": false,+ "description": "Redact personally identifiable information from returned markdown. Pass `true` to use defaults, or an object to tune mode, entities, and replacement style."+ },+ "proxy": {+ "type": "string",+ "enum": [+ "basic",+ "auto"+ ],+ "description": "Proxy mode for parse uploads. `/parse` supports only `basic` and `auto`."+ },+ "origin": {+ "type": "string",+ "description": "Origin identifier for analytics and logging.",+ "default": "api"+ },+ "integration": {+ "type": "string",+ "nullable": true,+ "description": "Optional integration identifier."+ },+ "auditMetadata": {+ "$ref": "#/components/schemas/AuditMetadata"+ },+ "zeroDataRetention": {+ "type": "boolean",+ "default": false,+ "description": "If true, this will enable zero data retention for this parse. To enable this feature, please contact [email protected]"+ }+ }+ },+ "ScrapeOptions": {+ "type": "object",+ "properties": {+ "formats": {+ "$ref": "#/components/schemas/Formats"+ },+ "onlyMainContent": {+ "type": "boolean",+ "description": "Only return the main content of the page excluding headers, navs, footers, etc. This is a deterministic HTML-level filter applied before markdown is generated; no LLM is involved.",+ "default": true+ },+ "onlyCleanContent": {+ "type": "boolean",+ "description": "Beta. Run an additional LLM-based pass over the generated markdown to remove residual boilerplate that `onlyMainContent` can miss (cookie banners, ad blocks, social share widgets, breadcrumbs, newsletter signups, comment sections, related-article lists). Headings, lists, tables, code blocks, image references, and inline links are preserved. Can be combined with `onlyMainContent` (the most common setup) or used on its own. Skipped with a warning when the markdown exceeds the cleaning model's output token limit (the original markdown is preserved). Not supported on zero-data-retention requests.",+ "default": false+ },+ "includeTags": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Tags to include in the output."+ },+ "excludeTags": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Tags to exclude from the output."+ },+ "maxAge": {+ "type": "integer",+ "description": "Returns a cached version of the page if it is younger than this age in milliseconds. If a cached version of the page is older than this value, the page will be scraped. If you do not need extremely fresh data, enabling this can speed up your scrapes by 500%. Defaults to 2 days.",+ "default": 172800000+ },+ "minAge": {+ "type": "integer",+ "description": "When set, the request only checks the cache and never triggers a fresh scrape. The value is in milliseconds and specifies the minimum age the cached data must be. If matching cached data exists, it is returned instantly. If no cached data is found, a 404 with error code SCRAPE_NO_CACHED_DATA is returned. Set to 1 to accept any cached data regardless of age."+ },+ "headers": {+ "type": "object",+ "description": "Headers to send with the request. Can be used to send cookies, user-agent, etc."+ },+ "waitFor": {+ "type": "integer",+ "description": "Specify a delay in milliseconds before fetching the content, allowing the page sufficient time to load. This waiting time is in addition to Firecrawl's smart wait feature.",+ "default": 0+ },+ "mobile": {+ "type": "boolean",+ "description": "Set to true if you want to emulate scraping from a mobile device. Useful for testing responsive pages and taking mobile screenshots.",+ "default": false+ },+ "skipTlsVerification": {+ "type": "boolean",+ "description": "Skip TLS certificate verification when making requests.",+ "default": true+ },+ "timeout": {+ "type": "integer",+ "description": "Timeout in milliseconds for the request. Minimum is 1000 (1 second). Default is 60000 (60 seconds). Maximum is 300000 (300 seconds).",+ "default": 60000,+ "minimum": 1000,+ "maximum": 300000+ },+ "parsers": {+ "type": "array",+ "description": "Controls how files are processed during scraping. When \"pdf\" is included (default), the PDF content is extracted and converted to markdown format, with billing based on the number of pages (1 credit per page). When an empty array is passed, the PDF file is returned in base64 encoding with a flat rate of 1 credit for the entire PDF.",+ "items": {+ "oneOf": [+ {+ "type": "object",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "pdf"+ ]+ },+ "mode": {+ "type": "string",+ "enum": [+ "fast",+ "auto",+ "ocr"+ ],+ "default": "auto",+ "description": "PDF parsing mode. \"fast\": text-based extraction only (embedded text, fastest). \"auto\" (default): attempts fast extraction first, falls back to OCR if needed. \"ocr\": forces OCR parsing on every page."+ },+ "maxPages": {+ "type": "integer",+ "minimum": 1,+ "maximum": 10000,+ "description": "Maximum number of pages to parse from the PDF. Must be a positive integer up to 10000."+ },+ "pages": {+ "type": "boolean",+ "default": false,+ "description": "Include physical per-page markdown alongside the document markdown. Populates the `pages` field on the document as an array of { pageNumber, markdown }. No additional cost."+ },+ "blocks": {+ "type": "boolean",+ "default": false,+ "description": "Include per-page typed layout blocks alongside the document markdown. Populates the `blocks` field on the document: typed blocks (title, section_header, text, table, formula, figure, caption, ...) with normalized bounding boxes, reading order, character-span links into the markdown, and per-block confidence. No additional cost."+ },+ "pageMarkers": {+ "type": "boolean",+ "default": false,+ "description": "Annotate page breaks in the document markdown: pages are joined with `\\n\\n---\\n\\n<!-- page N -->\\n\\n`, where N is the 1-based physical page of the content that follows. Markers appear between pages only (no leading marker for page 1), and numbering may skip pages merged across a page break — use `pages: true` when every physical page is needed. No new response field; no additional cost."+ }+ },+ "required": [+ "type"+ ],+ "additionalProperties": false+ }+ ]+ },+ "default": [+ "pdf"+ ]+ },+ "actions": {+ "type": "array",+ "description": "Actions to perform on the page before grabbing the content",+ "items": {+ "oneOf": [+ {+ "title": "Wait",+ "oneOf": [+ {+ "type": "object",+ "title": "Wait by Duration",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "wait"+ ],+ "description": "Wait for a specified amount of milliseconds"+ },+ "milliseconds": {+ "type": "integer",+ "minimum": 1,+ "description": "Number of milliseconds to wait"+ }+ },+ "required": [+ "type",+ "milliseconds"+ ],+ "additionalProperties": false+ },+ {+ "type": "object",+ "title": "Wait for Element",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "wait"+ ],+ "description": "Wait for a specific element to appear"+ },+ "selector": {+ "type": "string",+ "description": "CSS selector to wait for",+ "example": "#my-element"+ }+ },+ "required": [+ "type",+ "selector"+ ],+ "additionalProperties": false+ }+ ]+ },+ {+ "type": "object",+ "title": "Screenshot",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "screenshot"+ ],+ "description": "Take a screenshot. The links will be in the response's `actions.screenshots` array."+ },+ "fullPage": {+ "type": "boolean",+ "description": "Whether to capture a full-page screenshot (ignores viewport.height) or limit to the current viewport.",+ "default": false+ },+ "quality": {+ "type": "integer",+ "description": "The quality of the screenshot, from 1 to 100. 100 is the highest quality."+ },+ "viewport": {+ "type": "object",+ "properties": {+ "width": {+ "type": "integer",+ "description": "The width of the viewport in pixels"+ },+ "height": {+ "type": "integer",+ "description": "The height of the viewport in pixels"+ }+ },+ "required": [+ "width",+ "height"+ ]+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "Click",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "click"+ ],+ "description": "Click on an element"+ },+ "selector": {+ "type": "string",+ "description": "Query selector to find the element by",+ "example": "#load-more-button"+ },+ "all": {+ "type": "boolean",+ "description": "Clicks all elements matched by the selector, not just the first one. Does not throw an error if no elements match the selector.",+ "default": false+ }+ },+ "required": [+ "type",+ "selector"+ ]+ },+ {+ "type": "object",+ "title": "Write text",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "write"+ ],+ "description": "Write text into an input field, text area, or contenteditable element. Note: You must first focus the element using a 'click' action before writing. The text will be typed character by character to simulate keyboard input."+ },+ "text": {+ "type": "string",+ "description": "Text to type",+ "example": "Hello, world!"+ }+ },+ "required": [+ "type",+ "text"+ ]+ },+ {+ "type": "object",+ "title": "Press a key",+ "description": "Press a key on the page. See https://asawicki.info/nosense/doc/devices/keyboard/key_codes.html for key codes.",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "press"+ ],+ "description": "Press a key on the page"+ },+ "key": {+ "type": "string",+ "description": "Key to press",+ "example": "Enter"+ }+ },+ "required": [+ "type",+ "key"+ ]+ },+ {+ "type": "object",+ "title": "Scroll",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "scroll"+ ],+ "description": "Scroll the page or a specific element"+ },+ "direction": {+ "type": "string",+ "enum": [+ "up",+ "down"+ ],+ "description": "Direction to scroll",+ "default": "down"+ },+ "selector": {+ "type": "string",+ "description": "Query selector for the element to scroll",+ "example": "#my-element"+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "Scrape",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "scrape"+ ],+ "description": "Scrape the current page content, returns the url and the html."+ }+ },+ "required": [+ "type"+ ]+ },+ {+ "type": "object",+ "title": "Execute JavaScript",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "executeJavascript"+ ],+ "description": "Execute JavaScript code on the page"+ },+ "script": {+ "type": "string",+ "description": "JavaScript code to execute",+ "example": "document.querySelector('.button').click();"+ }+ },+ "required": [+ "type",+ "script"+ ]+ },+ {+ "type": "object",+ "title": "Generate PDF",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "pdf"+ ],+ "description": "Generate a PDF of the current page. The PDF will be returned in the `actions.pdfs` array of the response."+ },+ "format": {+ "type": "string",+ "enum": [+ "A0",+ "A1",+ "A2",+ "A3",+ "A4",+ "A5",+ "A6",+ "Letter",+ "Legal",+ "Tabloid",+ "Ledger"+ ],+ "description": "The page size of the resulting PDF",+ "default": "Letter"+ },+ "landscape": {+ "type": "boolean",+ "description": "Whether to generate the PDF in landscape orientation",+ "default": false+ },+ "scale": {+ "type": "number",+ "description": "The scale multiplier of the resulting PDF",+ "default": 1+ }+ },+ "required": [+ "type"+ ]+ }+ ]+ }+ },+ "location": {+ "type": "object",+ "description": "Location settings for the request. When specified, this will use an appropriate proxy if available and emulate the corresponding language and timezone settings. Defaults to 'US' if not specified.",+ "properties": {+ "country": {+ "type": "string",+ "description": "ISO 3166-1 alpha-2 country code (e.g., 'US', 'AU', 'DE', 'JP')",+ "pattern": "^[A-Z]{2}$",+ "default": "US"+ },+ "languages": {+ "type": "array",+ "description": "Preferred languages and locales for the request in order of priority. Defaults to the language of the specified location. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language",+ "items": {+ "type": "string",+ "example": "en-US"+ }+ }+ }+ },+ "removeBase64Images": {+ "type": "boolean",+ "description": "Removes all base 64 images from the markdown output, which may be overwhelmingly long. This does not affect html or rawHtml formats. The image's alt text remains in the output, but the URL is replaced with a placeholder.",+ "default": true+ },+ "blockAds": {+ "type": "boolean",+ "description": "Enables ad-blocking and cookie popup blocking.",+ "default": true+ },+ "proxy": {+ "type": "string",+ "enum": [+ "basic",+ "enhanced",+ "auto"+ ],+ "description": "Specifies the type of proxy to use.\n\n - **basic**: Proxies for scraping sites with none to basic anti-bot solutions. Fast and usually works.\n - **enhanced**: Enhanced proxies for scraping sites with advanced anti-bot solutions. Slower, but more reliable on certain sites. Billed at the same credit cost as basic.\n - **auto**: Firecrawl will automatically retry scraping with enhanced proxies if the basic proxy fails. Enhanced proxies carry no credit surcharge, so either way only the regular cost is billed.",+ "default": "auto"+ },+ "storeInCache": {+ "type": "boolean",+ "description": "If true, the page will be stored in the Firecrawl index and cache. Setting this to false is useful if your scraping activity may have data protection concerns. Using some parameters associated with sensitive scraping (e.g. actions, headers) will force this parameter to be false.",+ "default": true+ },+ "lockdown": {+ "type": "boolean",+ "description": "If true, serves the request from Firecrawl's cache only and never makes an outbound request to the target URL. Designed for compliance-constrained or air-gapped environments where the scrape request itself could leak sensitive information. On cache miss, returns a 404 with error code SCRAPE_LOCKDOWN_CACHE_MISS (the URL is never logged on miss). Lockdown requests are treated as zero data retention. Default maxAge is extended to 2 years so existing cached pages remain eligible. Billed at 5 credits on hit, 1 credit on cache miss.",+ "default": false+ },+ "redactPII": {+ "oneOf": [+ {+ "type": "boolean"+ },+ {+ "$ref": "#/components/schemas/RedactPIIOptions"+ }+ ],+ "default": false,+ "description": "Redact personally identifiable information from returned markdown. Pass `true` to use defaults, or an object to tune mode, entities, and replacement style."+ },+ "profile": {+ "type": "object",+ "description": "Enable persistent browser storage across scrape and interact sessions. Pass a profile when scraping to preserve cookies, localStorage, and session data. Sessions with the same profile name share browser state.",+ "properties": {+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 128,+ "description": "A name for the profile. Scrapes with the same name share browser state (cookies, localStorage, sessions)."+ },+ "saveChanges": {+ "type": "boolean",+ "default": true,+ "description": "When true, browser state is saved back to the profile when the interact session stops. Set to false to load existing data without writing. Only one saving session is allowed at a time."+ }+ },+ "required": [+ "name"+ ]+ },+ "threatProtection": {+ "$ref": "#/components/schemas/ThreatProtectionOverride"+ },+ "auditMetadata": {+ "$ref": "#/components/schemas/AuditMetadata"+ }+ }+ },+ "ScrapeResponse": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ },+ "data": {+ "type": "object",+ "properties": {+ "markdown": {+ "type": "string"+ },+ "pages": {+ "type": "array",+ "nullable": true,+ "description": "Physical per-page markdown for PDFs. Present only when the request set the `pages` PDF parser option.",+ "items": {+ "type": "object",+ "properties": {+ "pageNumber": {+ "type": "integer",+ "description": "1-based physical PDF page number."+ },+ "markdown": {+ "type": "string"+ }+ }+ }+ },+ "blocks": {+ "type": "array",+ "nullable": true,+ "description": "Per-page typed layout blocks for PDFs. Present only when the request set the `blocks` PDF parser option.",+ "items": {+ "type": "object",+ "properties": {+ "pageNumber": {+ "type": "integer",+ "description": "1-based physical PDF page number."+ },+ "width": {+ "type": "number",+ "nullable": true,+ "description": "Page render width in px — the anchor for denormalizing bbox coordinates. Null for pages that never rendered."+ },+ "height": {+ "type": "number",+ "nullable": true,+ "description": "Page render height in px. Null for pages that never rendered."+ },+ "status": {+ "type": "string",+ "description": "Page-level rollup: ok | partial | failed."+ },+ "items": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "Stable within a response: p<page>.b<index in reading order>."+ },+ "type": {+ "type": "string",+ "description": "Block type: title, section_header, text, table, formula, figure, caption, page_number, page_header, page_footer. New types may appear over time."+ },+ "label": {+ "type": "string",+ "nullable": true,+ "description": "Raw layout-model label, passthrough for forward compatibility."+ },+ "bbox": {+ "type": "array",+ "nullable": true,+ "minItems": 4,+ "maxItems": 4,+ "items": {+ "type": "number"+ },+ "description": "[x0, y0, x1, y1] normalized 0-1 relative to the page width/height. Multiply by the page width/height to get pixel coordinates. Null when the page has no known dimensions."+ },+ "content": {+ "type": "string",+ "description": "Markdown fragment this block contributed to the document markdown."+ },+ "markdownSpan": {+ "type": "array",+ "nullable": true,+ "minItems": 2,+ "maxItems": 2,+ "items": {+ "type": "integer"+ },+ "description": "[start, end) character offsets into the document markdown covering this block's fragment. Null when a post-processing transform rewrote the fragment."+ },+ "readingOrder": {+ "type": "integer"+ },+ "source": {+ "type": "string",+ "nullable": true,+ "description": "Pipeline path that produced the block (for example native_text, layout_ocr, tsr, formula_model, full_page)."+ },+ "confidence": {+ "type": "object",+ "properties": {+ "layout": {+ "type": "number",+ "nullable": true,+ "description": "Layout-model detection score (0-1). Null when the page bypassed layout analysis."+ },+ "ocr": {+ "type": "number",+ "nullable": true,+ "description": "Text confidence when the source path provides one; null otherwise."+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "summary": {+ "type": "string",+ "nullable": true,+ "description": "Summary of the page if `summary` is in `formats`"+ },+ "html": {+ "type": "string",+ "nullable": true,+ "description": "Cleaned HTML of the page if `html` is in `formats`. Removes `<script>`, `<style>`, `<noscript>`, `<meta>`, and `<head>` tags; converts relative URLs to absolute; resolves responsive image `srcset` to the largest version. Respects `onlyMainContent`, `includeTags`, and `excludeTags` filters."+ },+ "rawHtml": {+ "type": "string",+ "nullable": true,+ "description": "The exact, unmodified HTML as received from the page if `rawHtml` is in `formats`. No cleaning or filtering is applied."+ },+ "rawBase64": {+ "type": "string",+ "nullable": true,+ "description": "The Base64-encoded original HTTP response body if `rawBase64` is in `formats`. A bare Base64 string, not a data URI. The MIME type is in `metadata.contentType`."+ },+ "screenshot": {+ "type": "string",+ "nullable": true,+ "description": "Screenshot of the page if `screenshot` is in `formats`. Screenshots expire after 24 hours and can no longer be downloaded."+ },+ "audio": {+ "type": "string",+ "nullable": true,+ "description": "Signed URL to the extracted MP3 audio file if `audio` is in `formats`. The signed URL expires after 1 hour."+ },+ "video": {+ "type": "string",+ "nullable": true,+ "description": "Signed URL to the extracted video file if `video` is in `formats`. The signed URL expires after 1 hour."+ },+ "answer": {+ "type": "string",+ "nullable": true,+ "description": "Natural-language answer to the question supplied via the `question` format. Only present if a `question` format object was included in `formats`."+ },+ "highlights": {+ "type": "string",+ "nullable": true,+ "description": "Relevant source text selected by the `highlights` format. Only present if a `highlights` format object was included in `formats`."+ },+ "links": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of links on the page if `links` is in `formats`"+ },+ "actions": {+ "type": "object",+ "nullable": true,+ "description": "Results of the actions specified in the `actions` parameter. Only present if the `actions` parameter was provided in the request",+ "properties": {+ "screenshots": {+ "type": "array",+ "description": "Screenshot URLs, in the same order as the screenshot actions provided.",+ "items": {+ "type": "string",+ "format": "url"+ }+ },+ "scrapes": {+ "type": "array",+ "description": "Scrape contents, in the same order as the scrape actions provided.",+ "items": {+ "type": "object",+ "properties": {+ "url": {+ "type": "string"+ },+ "html": {+ "type": "string"+ }+ }+ }+ },+ "javascriptReturns": {+ "type": "array",+ "description": "JavaScript return values, in the same order as the executeJavascript actions provided.",+ "items": {+ "type": "object",+ "properties": {+ "type": {+ "type": "string"+ },+ "value": {}+ }+ }+ },+ "pdfs": {+ "type": "array",+ "description": "PDFs generated, in the same order as the pdf actions provided.",+ "items": {+ "type": "string"+ }+ }+ }+ },+ "metadata": {+ "type": "object",+ "properties": {+ "title": {+ "oneOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ],+ "description": "Title extracted from the page, can be a string or array of strings"+ },+ "description": {+ "oneOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ],+ "description": "Description extracted from the page, can be a string or array of strings"+ },+ "language": {+ "oneOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ],+ "nullable": true,+ "description": "Language extracted from the page, can be a string or array of strings"+ },+ "sourceURL": {+ "type": "string",+ "format": "uri",+ "description": "The original URL that was requested. May differ from the page's final URL if redirects occurred."+ },+ "url": {+ "type": "string",+ "format": "uri",+ "description": "The final URL of the page after all redirects have been followed."+ },+ "keywords": {+ "oneOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ],+ "description": "Keywords extracted from the page, can be a string or array of strings"+ },+ "ogLocaleAlternate": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Alternative locales for the page"+ },+ "<any other metadata> ": {+ "oneOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ],+ "description": "Other metadata extracted from HTML, can be a string or array of strings"+ },+ "statusCode": {+ "type": "integer",+ "description": "The status code of the page"+ },+ "numPages": {+ "type": "integer",+ "description": "For PDF inputs, the number of pages parsed (capped by the parsers maxPages option)."+ },+ "totalPages": {+ "type": "integer",+ "description": "For PDF inputs, the document's true page count before any maxPages capping. Omitted when it cannot be determined; a totalPages greater than numPages indicates the result was truncated."+ },+ "contentType": {+ "type": "string",+ "description": "The content type (MIME type) of the page, e.g. text/html, application/pdf"+ },+ "error": {+ "type": "string",+ "nullable": true,+ "description": "The error message of the page"+ },+ "concurrencyLimited": {+ "type": "boolean",+ "description": "Whether this scrape was throttled due to team concurrency limits"+ },+ "concurrencyQueueDurationMs": {+ "type": "number",+ "description": "Time in milliseconds the request waited in the concurrency queue. Only present when concurrencyLimited is true."+ }+ }+ },+ "warning": {+ "type": "string",+ "nullable": true,+ "description": "Can be displayed when using LLM Extraction. Warning message will let you know any issues with the extraction."+ },+ "changeTracking": {+ "type": "object",+ "nullable": true,+ "description": "Change tracking information if `changeTracking` is in `formats`. Only present when the `changeTracking` format is requested.",+ "properties": {+ "previousScrapeAt": {+ "type": "string",+ "format": "date-time",+ "nullable": true,+ "description": "The timestamp of the previous scrape that the current page is being compared against. Null if no previous scrape exists."+ },+ "changeStatus": {+ "type": "string",+ "enum": [+ "new",+ "same",+ "changed",+ "removed"+ ],+ "description": "The result of the comparison between the two page versions. 'new' means this page did not exist before, 'same' means content has not changed, 'changed' means content has changed, 'removed' means the page was removed."+ },+ "visibility": {+ "type": "string",+ "enum": [+ "visible",+ "hidden"+ ],+ "description": "The visibility of the current page/URL. 'visible' means the URL was discovered through an organic route (links or sitemap), 'hidden' means the URL was discovered through memory from previous crawls."+ },+ "diff": {+ "type": "string",+ "nullable": true,+ "description": "Git-style diff of changes when using 'git-diff' mode. Only present when the mode is set to 'git-diff'."+ },+ "json": {+ "type": "object",+ "nullable": true,+ "description": "JSON comparison results when using 'json' mode. Only present when the mode is set to 'json'. This will emit a list of all the keys and their values from the `previous` and `current` scrapes based on the type defined in the `schema`. Example [here](/features/change-tracking)"+ }+ }+ },+ "branding": {+ "type": "object",+ "nullable": true,+ "description": "Branding information extracted from the page if `branding` is in `formats`. Includes colors, fonts, typography, spacing, components, and more.",+ "properties": {+ "colorScheme": {+ "type": "string",+ "enum": [+ "light",+ "dark"+ ],+ "description": "The detected color scheme of the page."+ },+ "logo": {+ "type": "string",+ "nullable": true,+ "description": "URL of the primary logo."+ },+ "colors": {+ "type": "object",+ "nullable": true,+ "description": "Brand colors extracted from the page.",+ "properties": {+ "primary": {+ "type": "string",+ "description": "Primary brand color (hex)."+ },+ "secondary": {+ "type": "string",+ "description": "Secondary brand color (hex)."+ },+ "accent": {+ "type": "string",+ "description": "Accent color (hex)."+ },+ "background": {+ "type": "string",+ "description": "Background color (hex)."+ },+ "textPrimary": {+ "type": "string",+ "description": "Primary text color (hex)."+ },+ "textSecondary": {+ "type": "string",+ "description": "Secondary text color (hex)."+ },+ "link": {+ "type": "string",+ "description": "Link color (hex)."+ },+ "success": {+ "type": "string",+ "description": "Success/positive color (hex)."+ },+ "warning": {+ "type": "string",+ "description": "Warning color (hex)."+ },+ "error": {+ "type": "string",+ "description": "Error/danger color (hex)."+ }+ }+ },+ "fonts": {+ "type": "array",+ "nullable": true,+ "description": "Array of font families used on the page.",+ "items": {+ "type": "object",+ "properties": {+ "family": {+ "type": "string",+ "description": "Font family name."+ }+ }+ }+ },+ "typography": {+ "type": "object",+ "nullable": true,+ "description": "Detailed typography information.",+ "properties": {+ "fontFamilies": {+ "type": "object",+ "description": "Font families by role.",+ "properties": {+ "primary": {+ "type": "string",+ "description": "Primary font family."+ },+ "heading": {+ "type": "string",+ "description": "Heading font family."+ },+ "code": {+ "type": "string",+ "description": "Code/monospace font family."+ }+ }+ },+ "fontSizes": {+ "type": "object",+ "description": "Font sizes for different text levels.",+ "properties": {+ "h1": {+ "type": "string"+ },+ "h2": {+ "type": "string"+ },+ "h3": {+ "type": "string"+ },+ "body": {+ "type": "string"+ }+ }+ },+ "fontWeights": {+ "type": "object",+ "description": "Font weight definitions.",+ "properties": {+ "light": {+ "type": "integer"+ },+ "regular": {+ "type": "integer"+ },+ "medium": {+ "type": "integer"+ },+ "bold": {+ "type": "integer"+ }+ }+ },+ "lineHeights": {+ "type": "object",+ "description": "Line height values for different text types.",+ "properties": {+ "heading": {+ "type": "string"+ },+ "body": {+ "type": "string"+ }+ }+ }+ }+ },+ "spacing": {+ "type": "object",+ "nullable": true,+ "description": "Spacing and layout information.",+ "properties": {+ "baseUnit": {+ "type": "integer",+ "description": "Base spacing unit in pixels."+ },+ "borderRadius": {+ "type": "string",+ "description": "Default border radius."+ },+ "padding": {+ "type": "object",+ "description": "Padding values."+ },+ "margins": {+ "type": "object",+ "description": "Margin values."+ }+ }+ },+ "components": {+ "type": "object",+ "nullable": true,+ "description": "UI component styles.",+ "properties": {+ "buttonPrimary": {+ "type": "object",+ "description": "Primary button styles.",+ "properties": {+ "background": {+ "type": "string"+ },+ "textColor": {+ "type": "string"+ },+ "borderRadius": {+ "type": "string"+ }+ }+ },+ "buttonSecondary": {+ "type": "object",+ "description": "Secondary button styles.",+ "properties": {+ "background": {+ "type": "string"+ },+ "textColor": {+ "type": "string"+ },+ "borderColor": {+ "type": "string"+ },+ "borderRadius": {+ "type": "string"+ }+ }+ },+ "input": {+ "type": "object",+ "description": "Input field styles."+ }+ }+ },+ "icons": {+ "type": "object",+ "nullable": true,+ "description": "Icon style information."+ },+ "images": {+ "type": "object",+ "nullable": true,+ "description": "Brand images.",+ "properties": {+ "logo": {+ "type": "string",+ "description": "Logo image URL."+ },+ "favicon": {+ "type": "string",+ "description": "Favicon URL."+ },+ "ogImage": {+ "type": "string",+ "description": "Open Graph image URL."+ }+ }+ },+ "animations": {+ "type": "object",+ "nullable": true,+ "description": "Animation and transition settings."+ },+ "layout": {+ "type": "object",+ "nullable": true,+ "description": "Layout configuration (grid, header/footer heights)."+ },+ "personality": {+ "type": "object",+ "nullable": true,+ "description": "Brand personality traits (tone, energy, target audience)."+ }+ }+ },+ "product": {+ "type": "object",+ "nullable": true,+ "description": "Product information extracted from the page if `product` is in `formats`. Includes title, brand, category, description, and variants. Pricing, availability, and images live on each variant.",+ "properties": {+ "title": {+ "type": "string",+ "description": "The product title."+ },+ "brand": {+ "type": "string",+ "description": "The product brand or manufacturer."+ },+ "category": {+ "type": "string",+ "description": "The product category, optionally as a breadcrumb path (e.g. 'Electronics > Audio > Headphones')."+ },+ "url": {+ "type": "string",+ "description": "The canonical URL of the product page."+ },+ "description": {+ "type": "string",+ "description": "The product description."+ },+ "variants": {+ "type": "array",+ "description": "Product variants (e.g. different colors or sizes).",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "The variant identifier."+ },+ "sku": {+ "type": "string",+ "description": "The variant SKU."+ },+ "title": {+ "type": "string",+ "description": "The variant title."+ },+ "values": {+ "type": "object",+ "description": "The variant option values (e.g. { \"color\": \"Black\" }).",+ "additionalProperties": {+ "type": "string"+ }+ },+ "price": {+ "type": "object",+ "description": "The current price of the variant.",+ "properties": {+ "amount": {+ "type": "number",+ "description": "The numeric price amount."+ },+ "currency": {+ "type": "string",+ "description": "The ISO 4217 currency code (e.g. 'USD')."+ },+ "formatted": {+ "type": "string",+ "description": "The price formatted for display (e.g. '$199.99')."+ }+ },+ "required": [+ "amount"+ ]+ },+ "sale": {+ "type": "object",+ "description": "Sale/discount information for the variant, present when the variant is discounted.",+ "properties": {+ "originalPrice": {+ "type": "object",+ "description": "The original (pre-discount) price of the variant.",+ "properties": {+ "amount": {+ "type": "number",+ "description": "The numeric price amount."+ },+ "currency": {+ "type": "string",+ "description": "The ISO 4217 currency code (e.g. 'USD')."+ },+ "formatted": {+ "type": "string",+ "description": "The price formatted for display (e.g. '$249.99')."+ }+ },+ "required": [+ "amount"+ ]+ }+ },+ "required": [+ "originalPrice"+ ]+ },+ "availability": {+ "type": "object",+ "description": "The availability of the variant. Always present on a variant.",+ "properties": {+ "inStock": {+ "type": "boolean",+ "description": "Whether the variant is in stock."+ },+ "text": {+ "type": "string",+ "description": "Human-readable availability text (e.g. 'In Stock')."+ }+ },+ "required": [+ "inStock"+ ]+ },+ "images": {+ "type": "array",+ "description": "Variant images.",+ "items": {+ "type": "object",+ "properties": {+ "url": {+ "type": "string",+ "description": "Image URL."+ },+ "alt": {+ "type": "string",+ "description": "Alternative text for the image."+ }+ },+ "required": [+ "url"+ ]+ }+ }+ },+ "required": [+ "availability"+ ]+ }+ }+ },+ "required": [+ "title",+ "url",+ "variants"+ ]+ },+ "menu": {+ "type": "object",+ "nullable": true,+ "description": "Menu information extracted from the page if `menu` is in `formats`. Includes the merchant, currency, and a list of sections, where each section carries items with description, images, price, availability, dietary tags, calories, and option groups.",+ "properties": {+ "isMenu": {+ "type": "boolean",+ "description": "Whether the page was identified as a menu."+ },+ "confidence": {+ "type": "number",+ "description": "A confidence score between 0 and 1 for the menu extraction."+ },+ "merchant": {+ "type": "object",+ "description": "The merchant the menu belongs to.",+ "properties": {+ "name": {+ "type": "string",+ "description": "The merchant name."+ },+ "type": {+ "type": "string",+ "description": "The merchant type (e.g. 'restaurant')."+ }+ },+ "required": [+ "name"+ ]+ },+ "currency": {+ "type": "string",+ "description": "The ISO 4217 currency code for the menu (e.g. 'USD'), reported only when the page sources it."+ },+ "sections": {+ "type": "array",+ "description": "Menu sections (e.g. 'Appetizers', 'Entrees').",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "The section identifier."+ },+ "name": {+ "type": "string",+ "description": "The section name."+ },+ "description": {+ "type": "string",+ "nullable": true,+ "description": "The section description."+ },+ "items": {+ "type": "array",+ "description": "The items in the section.",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "The item identifier."+ },+ "name": {+ "type": "string",+ "description": "The item name."+ },+ "description": {+ "type": "string",+ "nullable": true,+ "description": "The item description."+ },+ "images": {+ "type": "array",+ "description": "Item images.",+ "items": {+ "type": "object",+ "properties": {+ "url": {+ "type": "string",+ "description": "Image URL."+ },+ "alt": {+ "type": "string",+ "nullable": true,+ "description": "Alternative text for the image."+ }+ },+ "required": [+ "url"+ ]+ }+ },+ "price": {+ "type": "object",+ "description": "The price of the item.",+ "properties": {+ "amount": {+ "type": "number",+ "description": "The numeric price amount."+ },+ "currency": {+ "type": "string",+ "description": "The ISO 4217 currency code (e.g. 'USD')."+ },+ "formatted": {+ "type": "string",+ "description": "The price formatted for display (e.g. '$7.99')."+ }+ },+ "required": [+ "amount"+ ]+ },+ "availability": {+ "type": "object",+ "description": "The availability of the item.",+ "properties": {+ "inStock": {+ "type": "boolean",+ "description": "Whether the item is available."+ },+ "text": {+ "type": "string",+ "nullable": true,+ "description": "Human-readable availability text."+ }+ },+ "required": [+ "inStock"+ ]+ },+ "dietary": {+ "type": "array",+ "description": "Dietary tags for the item (e.g. ['vegetarian']).",+ "items": {+ "type": "string"+ }+ },+ "calories": {+ "type": "number",+ "nullable": true,+ "description": "The item's calorie count."+ },+ "optionGroups": {+ "type": "array",+ "description": "Option/modifier groups for the item.",+ "items": {+ "type": "object"+ }+ },+ "identifiers": {+ "type": "object",+ "description": "Merchant-specific identifiers for the item.",+ "properties": {+ "merchantItemId": {+ "type": "string",+ "description": "The merchant's own item ID."+ }+ }+ },+ "url": {+ "type": "string",+ "nullable": true,+ "description": "The canonical URL of the item."+ },+ "sourceUrl": {+ "type": "string",+ "nullable": true,+ "description": "The URL the item was extracted from."+ }+ },+ "required": [+ "name"+ ]+ }+ }+ },+ "required": [+ "name",+ "items"+ ]+ }+ },+ "sourceUrl": {+ "type": "string",+ "nullable": true,+ "description": "The URL the menu was extracted from."+ }+ },+ "required": [+ "isMenu",+ "sections"+ ]+ },+ "tools": {+ "type": "array",+ "nullable": true,+ "description": "Tool contracts matched to the scraped page's domain. Present only when `domainTools` is `true` on the request. Requires Alexandria access and no zero data retention (403 otherwise); free.",+ "items": {+ "$ref": "#/components/schemas/DiscoveredTool"+ }+ }+ }+ }+ }+ },+ "AlexandriaCall": {+ "type": "object",+ "description": "A single provider tool to execute from the Alexandria catalogue.",+ "properties": {+ "provider": {+ "type": "string",+ "minLength": 1,+ "maxLength": 200,+ "description": "The catalogued provider to call, e.g. `fred`."+ },+ "capability": {+ "type": "string",+ "minLength": 1,+ "maxLength": 200,+ "description": "The provider-relative capability to invoke, e.g. `series/observations`."+ },+ "options": {+ "type": "object",+ "default": {},+ "description": "Capability-specific options passed through to the provider tool."+ }+ },+ "required": [+ "provider",+ "capability"+ ]+ },+ "AlexandriaResult": {+ "type": "object",+ "description": "The outcome of one executed Alexandria call, returned in the same order as the request.",+ "oneOf": [+ {+ "type": "object",+ "title": "Success",+ "properties": {+ "provider": {+ "type": "string",+ "description": "The provider that was called."+ },+ "capability": {+ "type": "string",+ "description": "The capability that was invoked."+ },+ "creditsCost": {+ "type": "integer",+ "minimum": 0,+ "description": "Credits charged for this call."+ },+ "data": {+ "description": "The provider's response payload."+ },+ "records": {+ "type": "integer",+ "description": "Number of records returned, when applicable."+ },+ "upstreamStatus": {+ "type": "integer",+ "description": "HTTP status code returned by the upstream provider, when applicable."+ }+ },+ "required": [+ "provider",+ "capability",+ "creditsCost",+ "data"+ ]+ },+ {+ "type": "object",+ "title": "Error",+ "properties": {+ "provider": {+ "type": "string",+ "description": "The provider that was called."+ },+ "capability": {+ "type": "string",+ "description": "The capability that was invoked."+ },+ "creditsCost": {+ "type": "integer",+ "default": 0,+ "description": "Always 0 for a failed call."+ },+ "error": {+ "type": "object",+ "properties": {+ "code": {+ "type": "string",+ "description": "Machine-readable error code for this call."+ },+ "message": {+ "type": "string",+ "description": "Human-readable error message for this call."+ },+ "status": {+ "type": "integer",+ "description": "HTTP status code returned by the upstream provider, when applicable."+ }+ },+ "required": [+ "code",+ "message"+ ]+ }+ },+ "required": [+ "error"+ ]+ }+ ]+ },+ "DiscoveredTool": {+ "type": "object",+ "description": "A catalogued provider tool discovered via Alexandria, semantic search, or domain matching.",+ "additionalProperties": true,+ "properties": {+ "id": {+ "type": "string",+ "description": "The tool's identifier, formatted as `provider/capability`."+ },+ "provider": {+ "type": "string",+ "description": "The catalogued provider."+ },+ "capability": {+ "type": "string",+ "description": "The provider-relative capability."+ },+ "name": {+ "type": "string",+ "description": "Human-readable name of the tool."+ },+ "description": {+ "type": "string",+ "description": "Human-readable description of what the tool does."+ },+ "creditsCost": {+ "type": "integer",+ "minimum": 0,+ "description": "Credits charged per execution of this tool."+ },+ "perRecord": {+ "type": "boolean",+ "description": "Whether `creditsCost` is charged per record returned rather than per call."+ },+ "options": {+ "type": "array",+ "description": "The capability's accepted options.",+ "items": {+ "type": "object",+ "additionalProperties": true,+ "properties": {+ "name": {+ "type": "string",+ "description": "The option name."+ },+ "type": {+ "type": "string",+ "description": "The option's data type."+ }+ }+ }+ },+ "response": {+ "type": "object",+ "additionalProperties": true,+ "description": "Description of the shape of a successful response's `data`.",+ "properties": {+ "about": {+ "type": "string",+ "description": "Human-readable description of the response payload."+ },+ "key": {+ "type": "string",+ "description": "The key under which the primary payload is returned, when applicable."+ },+ "fields": {+ "type": "array",+ "description": "The response's documented fields.",+ "items": {+ "type": "object",+ "additionalProperties": true+ }+ }+ }+ },+ "matchedBy": {+ "type": "array",+ "description": "Why this tool was surfaced.",+ "items": {+ "type": "string",+ "enum": [+ "semantic",+ "domain"+ ]+ }+ },+ "matchedUrls": {+ "type": "array",+ "description": "URLs whose domain matched this tool, when matched by domain.",+ "items": {+ "type": "string"+ }+ }+ },+ "required": [+ "id",+ "provider",+ "capability",+ "name",+ "description",+ "creditsCost",+ "perRecord"+ ]+ },+ "AlexandriaScrapeResponse": {+ "type": "object",+ "description": "Response returned when the request executed Alexandria provider tools instead of scraping a URL.",+ "properties": {+ "success": {+ "type": "boolean",+ "example": true+ },+ "scrape_id": {+ "type": "string",+ "description": "Identifier for this request. A completed request replays the same response and `scrape_id` when retried with the same `x-request-id`."+ },+ "data": {+ "type": "object",+ "properties": {+ "alexandria": {+ "type": "array",+ "description": "Results for each requested Alexandria call, in the same order as the request.",+ "items": {+ "$ref": "#/components/schemas/AlexandriaResult"+ }+ },+ "creditsCost": {+ "type": "integer",+ "description": "Sum of `creditsCost` across successful items."+ }+ },+ "required": [+ "alexandria",+ "creditsCost"+ ]+ }+ },+ "required": [+ "success",+ "scrape_id",+ "data"+ ]+ },+ "CrawlStatusResponseObj": {+ "type": "object",+ "properties": {+ "status": {+ "type": "string",+ "description": "The current status of the crawl. Can be `scraping`, `completed`, or `failed`."+ },+ "total": {+ "type": "integer",+ "description": "The total number of pages that were attempted to be crawled."+ },+ "completed": {+ "type": "integer",+ "description": "The number of pages that have been successfully crawled."+ },+ "creditsUsed": {+ "type": "integer",+ "description": "The number of credits used for the crawl."+ },+ "expiresAt": {+ "type": "string",+ "format": "date-time",+ "description": "The date and time when the crawl will expire."+ },+ "createdAt": {+ "type": "string",+ "format": "date-time",+ "description": "The date and time when the crawl was started."+ },+ "completedAt": {+ "type": "string",+ "format": "date-time",+ "description": "The date and time when the crawl finished. Present only when the crawl is in a terminal state (`completed`, `failed`, or `cancelled`)."+ },+ "duration": {+ "type": "number",+ "description": "Crawl duration in seconds. For terminal crawls, this is the elapsed time from `createdAt` to `completedAt`. For in-progress crawls, it is the elapsed time from `createdAt` to now."+ },+ "next": {+ "type": "string",+ "nullable": true,+ "description": "The URL to retrieve the next 10MB of data. Returned if the crawl is not completed or if the response is larger than 10MB."+ },+ "data": {+ "type": "array",+ "description": "The data of the crawl.",+ "items": {+ "type": "object",+ "properties": {+ "markdown": {+ "type": "string"+ },+ "pages": {+ "type": "array",+ "nullable": true,+ "description": "Physical per-page markdown for PDFs. Present only when the request set the `pages` PDF parser option.",+ "items": {+ "type": "object",+ "properties": {+ "pageNumber": {+ "type": "integer",+ "description": "1-based physical PDF page number."+ },+ "markdown": {+ "type": "string"+ }+ }+ }+ },+ "blocks": {+ "type": "array",+ "nullable": true,+ "description": "Per-page typed layout blocks for PDFs. Present only when the request set the `blocks` PDF parser option.",+ "items": {+ "type": "object",+ "properties": {+ "pageNumber": {+ "type": "integer",+ "description": "1-based physical PDF page number."+ },+ "width": {+ "type": "number",+ "nullable": true,+ "description": "Page render width in px — the anchor for denormalizing bbox coordinates. Null for pages that never rendered."+ },+ "height": {+ "type": "number",+ "nullable": true,+ "description": "Page render height in px. Null for pages that never rendered."+ },+ "status": {+ "type": "string",+ "description": "Page-level rollup: ok | partial | failed."+ },+ "items": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "Stable within a response: p<page>.b<index in reading order>."+ },+ "type": {+ "type": "string",+ "description": "Block type: title, section_header, text, table, formula, figure, caption, page_number, page_header, page_footer. New types may appear over time."+ },+ "label": {+ "type": "string",+ "nullable": true,+ "description": "Raw layout-model label, passthrough for forward compatibility."+ },+ "bbox": {+ "type": "array",+ "nullable": true,+ "minItems": 4,+ "maxItems": 4,+ "items": {+ "type": "number"+ },+ "description": "[x0, y0, x1, y1] normalized 0-1 relative to the page width/height. Multiply by the page width/height to get pixel coordinates. Null when the page has no known dimensions."+ },+ "content": {+ "type": "string",+ "description": "Markdown fragment this block contributed to the document markdown."+ },+ "markdownSpan": {+ "type": "array",+ "nullable": true,+ "minItems": 2,+ "maxItems": 2,+ "items": {+ "type": "integer"+ },+ "description": "[start, end) character offsets into the document markdown covering this block's fragment. Null when a post-processing transform rewrote the fragment."+ },+ "readingOrder": {+ "type": "integer"+ },+ "source": {+ "type": "string",+ "nullable": true,+ "description": "Pipeline path that produced the block (for example native_text, layout_ocr, tsr, formula_model, full_page)."+ },+ "confidence": {+ "type": "object",+ "properties": {+ "layout": {+ "type": "number",+ "nullable": true,+ "description": "Layout-model detection score (0-1). Null when the page bypassed layout analysis."+ },+ "ocr": {+ "type": "number",+ "nullable": true,+ "description": "Text confidence when the source path provides one; null otherwise."+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "html": {+ "type": "string",+ "nullable": true,+ "description": "HTML version of the content on page if `includeHtml` is true"+ },+ "rawHtml": {+ "type": "string",+ "nullable": true,+ "description": "Raw HTML content of the page if `includeRawHtml` is true"+ },+ "rawBase64": {+ "type": "string",+ "nullable": true,+ "description": "The Base64-encoded original HTTP response body if `rawBase64` is in `formats`. A bare Base64 string, not a data URI. The MIME type is in `metadata.contentType`."+ },+ "links": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of links on the page if `includeLinks` is true"+ },+ "screenshot": {+ "type": "string",+ "nullable": true,+ "description": "Screenshot of the page if `includeScreenshot` is true"+ },+ "metadata": {+ "type": "object",+ "properties": {+ "title": {+ "oneOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ],+ "description": "Title extracted from the page, can be a string or array of strings"+ },+ "description": {+ "oneOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ],+ "description": "Description extracted from the page, can be a string or array of strings"+ },+ "language": {+ "oneOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ],+ "nullable": true,+ "description": "Language extracted from the page, can be a string or array of strings"+ },+ "sourceURL": {+ "type": "string",+ "format": "uri",+ "description": "The original URL that was requested. May differ from the page's final URL if redirects occurred."+ },+ "url": {+ "type": "string",+ "format": "uri",+ "description": "The final URL of the page after all redirects have been followed."+ },+ "keywords": {+ "oneOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ],+ "description": "Keywords extracted from the page, can be a string or array of strings"+ },+ "ogLocaleAlternate": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Alternative locales for the page"+ },+ "<any other metadata> ": {+ "type": "string"+ },+ "statusCode": {+ "type": "integer",+ "description": "The status code of the page"+ },+ "numPages": {+ "type": "integer",+ "description": "For PDF inputs, the number of pages parsed (capped by the parsers maxPages option)."+ },+ "totalPages": {+ "type": "integer",+ "description": "For PDF inputs, the document's true page count before any maxPages capping. Omitted when it cannot be determined; a totalPages greater than numPages indicates the result was truncated."+ },+ "error": {+ "type": "string",+ "nullable": true,+ "description": "The error message of the page"+ },+ "concurrencyLimited": {+ "type": "boolean",+ "description": "Whether this scrape was throttled due to team concurrency limits"+ },+ "concurrencyQueueDurationMs": {+ "type": "number",+ "description": "Time in milliseconds the request waited in the concurrency queue. Only present when concurrencyLimited is true."+ }+ }+ }+ }+ }+ }+ }+ },+ "CrawlErrorsResponseObj": {+ "type": "object",+ "properties": {+ "errors": {+ "type": "array",+ "description": "Errored scrape jobs and error details",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string"+ },+ "timestamp": {+ "type": "string",+ "nullable": true,+ "description": "ISO timestamp of failure"+ },+ "url": {+ "type": "string",+ "description": "Scraped URL"+ },+ "error": {+ "type": "string",+ "description": "Error message"+ }+ }+ }+ },+ "robotsBlocked": {+ "type": "array",+ "description": "List of URLs that were attempted in scraping but were blocked by robots.txt",+ "items": {+ "type": "string"+ }+ }+ }+ },+ "BatchScrapeStatusResponseObj": {+ "type": "object",+ "properties": {+ "status": {+ "type": "string",+ "description": "The current status of the batch scrape. Can be `scraping`, `completed`, or `failed`."+ },+ "total": {+ "type": "integer",+ "description": "The total number of pages that were attempted to be scraped."+ },+ "completed": {+ "type": "integer",+ "description": "The number of pages that have been successfully scraped."+ },+ "creditsUsed": {+ "type": "integer",+ "description": "The number of credits used for the batch scrape."+ },+ "expiresAt": {+ "type": "string",+ "format": "date-time",+ "description": "The date and time when the batch scrape will expire."+ },+ "createdAt": {+ "type": "string",+ "format": "date-time",+ "description": "The date and time when the batch scrape was started."+ },+ "completedAt": {+ "type": "string",+ "format": "date-time",+ "description": "The date and time when the batch scrape finished. Present only when the batch scrape is in a terminal state (`completed`, `failed`, or `cancelled`)."+ },+ "duration": {+ "type": "number",+ "description": "Batch scrape duration in seconds. For terminal batch scrapes, this is the elapsed time from `createdAt` to `completedAt`. For in-progress batch scrapes, it is the elapsed time from `createdAt` to now."+ },+ "next": {+ "type": "string",+ "nullable": true,+ "description": "The URL to retrieve the next 10MB of data. Returned if the batch scrape is not completed or if the response is larger than 10MB."+ },+ "data": {+ "type": "array",+ "description": "The data of the batch scrape.",+ "items": {+ "type": "object",+ "properties": {+ "markdown": {+ "type": "string"+ },+ "pages": {+ "type": "array",+ "nullable": true,+ "description": "Physical per-page markdown for PDFs. Present only when the request set the `pages` PDF parser option.",+ "items": {+ "type": "object",+ "properties": {+ "pageNumber": {+ "type": "integer",+ "description": "1-based physical PDF page number."+ },+ "markdown": {+ "type": "string"+ }+ }+ }+ },+ "blocks": {+ "type": "array",+ "nullable": true,+ "description": "Per-page typed layout blocks for PDFs. Present only when the request set the `blocks` PDF parser option.",+ "items": {+ "type": "object",+ "properties": {+ "pageNumber": {+ "type": "integer",+ "description": "1-based physical PDF page number."+ },+ "width": {+ "type": "number",+ "nullable": true,+ "description": "Page render width in px — the anchor for denormalizing bbox coordinates. Null for pages that never rendered."+ },+ "height": {+ "type": "number",+ "nullable": true,+ "description": "Page render height in px. Null for pages that never rendered."+ },+ "status": {+ "type": "string",+ "description": "Page-level rollup: ok | partial | failed."+ },+ "items": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "Stable within a response: p<page>.b<index in reading order>."+ },+ "type": {+ "type": "string",+ "description": "Block type: title, section_header, text, table, formula, figure, caption, page_number, page_header, page_footer. New types may appear over time."+ },+ "label": {+ "type": "string",+ "nullable": true,+ "description": "Raw layout-model label, passthrough for forward compatibility."+ },+ "bbox": {+ "type": "array",+ "nullable": true,+ "minItems": 4,+ "maxItems": 4,+ "items": {+ "type": "number"+ },+ "description": "[x0, y0, x1, y1] normalized 0-1 relative to the page width/height. Multiply by the page width/height to get pixel coordinates. Null when the page has no known dimensions."+ },+ "content": {+ "type": "string",+ "description": "Markdown fragment this block contributed to the document markdown."+ },+ "markdownSpan": {+ "type": "array",+ "nullable": true,+ "minItems": 2,+ "maxItems": 2,+ "items": {+ "type": "integer"+ },+ "description": "[start, end) character offsets into the document markdown covering this block's fragment. Null when a post-processing transform rewrote the fragment."+ },+ "readingOrder": {+ "type": "integer"+ },+ "source": {+ "type": "string",+ "nullable": true,+ "description": "Pipeline path that produced the block (for example native_text, layout_ocr, tsr, formula_model, full_page)."+ },+ "confidence": {+ "type": "object",+ "properties": {+ "layout": {+ "type": "number",+ "nullable": true,+ "description": "Layout-model detection score (0-1). Null when the page bypassed layout analysis."+ },+ "ocr": {+ "type": "number",+ "nullable": true,+ "description": "Text confidence when the source path provides one; null otherwise."+ }+ }+ }+ }+ }+ }+ }+ }+ },+ "html": {+ "type": "string",+ "nullable": true,+ "description": "HTML version of the content on page if `includeHtml` is true"+ },+ "rawHtml": {+ "type": "string",+ "nullable": true,+ "description": "Raw HTML content of the page if `includeRawHtml` is true"+ },+ "rawBase64": {+ "type": "string",+ "nullable": true,+ "description": "The Base64-encoded original HTTP response body if `rawBase64` is in `formats`. A bare Base64 string, not a data URI. The MIME type is in `metadata.contentType`."+ },+ "links": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of links on the page if `includeLinks` is true"+ },+ "screenshot": {+ "type": "string",+ "nullable": true,+ "description": "Screenshot of the page if `includeScreenshot` is true"+ },+ "metadata": {+ "type": "object",+ "properties": {+ "title": {+ "oneOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ],+ "description": "Title extracted from the page, can be a string or array of strings"+ },+ "description": {+ "oneOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ],+ "description": "Description extracted from the page, can be a string or array of strings"+ },+ "language": {+ "oneOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ],+ "nullable": true,+ "description": "Language extracted from the page, can be a string or array of strings"+ },+ "sourceURL": {+ "type": "string",+ "format": "uri",+ "description": "The original URL that was requested. May differ from the page's final URL if redirects occurred."+ },+ "url": {+ "type": "string",+ "format": "uri",+ "description": "The final URL of the page after all redirects have been followed."+ },+ "keywords": {+ "oneOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ],+ "description": "Keywords extracted from the page, can be a string or array of strings"+ },+ "ogLocaleAlternate": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Alternative locales for the page"+ },+ "<any other metadata> ": {+ "type": "string"+ },+ "statusCode": {+ "type": "integer",+ "description": "The status code of the page"+ },+ "numPages": {+ "type": "integer",+ "description": "For PDF inputs, the number of pages parsed (capped by the parsers maxPages option)."+ },+ "totalPages": {+ "type": "integer",+ "description": "For PDF inputs, the document's true page count before any maxPages capping. Omitted when it cannot be determined; a totalPages greater than numPages indicates the result was truncated."+ },+ "error": {+ "type": "string",+ "nullable": true,+ "description": "The error message of the page"+ },+ "concurrencyLimited": {+ "type": "boolean",+ "description": "Whether this scrape was throttled due to team concurrency limits"+ },+ "concurrencyQueueDurationMs": {+ "type": "number",+ "description": "Time in milliseconds the request waited in the concurrency queue. Only present when concurrencyLimited is true."+ }+ }+ }+ }+ }+ }+ }+ },+ "CrawlResponse": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ },+ "id": {+ "type": "string"+ },+ "url": {+ "type": "string",+ "format": "uri"+ }+ }+ },+ "BatchScrapeResponseObj": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ },+ "id": {+ "type": "string"+ },+ "url": {+ "type": "string",+ "format": "uri"+ },+ "invalidURLs": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string"+ },+ "description": "If ignoreInvalidURLs is true, this is an array containing the invalid URLs that were specified in the request. If there were no invalid URLs, this will be an empty array. If ignoreInvalidURLs is false, this field will be undefined."+ }+ }+ },+ "MapResponse": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ },+ "links": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "url": {+ "type": "string",+ "format": "uri"+ },+ "title": {+ "type": "string",+ "description": "The title of the page, if available."+ },+ "description": {+ "type": "string",+ "description": "A description of the page, if available."+ }+ },+ "required": [+ "url"+ ]+ }+ }+ }+ },+ "ExtractResponse": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ },+ "id": {+ "type": "string"+ },+ "invalidURLs": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string"+ },+ "description": "If ignoreInvalidURLs is true, this is an array containing the invalid URLs that were specified in the request. If there were no invalid URLs, this will be an empty array. If ignoreInvalidURLs is false, this field will be undefined."+ }+ }+ },+ "ExtractStatusResponse": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ },+ "data": {+ "type": "object"+ },+ "status": {+ "type": "string",+ "enum": [+ "completed",+ "processing",+ "failed",+ "cancelled"+ ],+ "description": "The current status of the extract job"+ },+ "expiresAt": {+ "type": "string",+ "format": "date-time"+ },+ "tokensUsed": {+ "type": "integer",+ "description": "The number of tokens used by the extract job. Only available if the job is completed."+ }+ }+ },+ "SearchFeedbackRequest": {+ "type": "object",+ "description": "For 'good', include valuableSources. For 'partial', include valuableSources or missingContent. For 'bad', include missingContent or querySuggestions.",+ "properties": {+ "rating": {+ "type": "string",+ "enum": [+ "good",+ "partial",+ "bad"+ ]+ },+ "valuableSources": {+ "type": "array",+ "maxItems": 50,+ "items": {+ "type": "object",+ "properties": {+ "url": {+ "type": "string",+ "format": "uri"+ },+ "reason": {+ "type": "string",+ "maxLength": 1000+ }+ },+ "required": [+ "url"+ ]+ }+ },+ "missingContent": {+ "type": "array",+ "maxItems": 20,+ "items": {+ "type": "object",+ "properties": {+ "topic": {+ "type": "string",+ "maxLength": 200,+ "minLength": 1+ },+ "description": {+ "type": "string",+ "maxLength": 2000+ }+ },+ "required": [+ "topic"+ ]+ }+ },+ "querySuggestions": {+ "type": "string",+ "maxLength": 2000+ },+ "origin": {+ "type": "string",+ "default": "api"+ },+ "integration": {+ "type": "string",+ "nullable": true+ }+ },+ "required": [+ "rating"+ ]+ },+ "SupportAskRequest": {+ "type": "object",+ "required": [+ "question"+ ],+ "additionalProperties": true,+ "properties": {+ "question": {+ "type": "string",+ "description": "Question or issue for the support agent to diagnose."+ },+ "rationale": {+ "type": "string",+ "description": "Optional context about what the end user is trying to accomplish."+ }+ }+ },+ "SupportAskResponse": {+ "type": "object",+ "properties": {+ "answer": {+ "type": "string",+ "description": "Diagnosis and recommended fix."+ },+ "confidence": {+ "type": "string",+ "enum": [+ "high",+ "medium",+ "low"+ ]+ },+ "fixParameters": {+ "type": "object",+ "nullable": true,+ "additionalProperties": true,+ "description": "Machine-readable API parameters that may fix the issue."+ },+ "validation": {+ "type": "object",+ "nullable": true,+ "additionalProperties": true,+ "description": "Validation result when the support agent tested or attempted a fix."+ },+ "feedback": {+ "type": "object",+ "nullable": true,+ "additionalProperties": true,+ "description": "Present when the support agent is blocked or needs more information."+ },+ "durationMs": {+ "type": "integer",+ "description": "Total support-agent execution time in milliseconds."+ }+ }+ },+ "SupportDocsSearchRequest": {+ "type": "object",+ "required": [+ "question"+ ],+ "properties": {+ "question": {+ "type": "string",+ "description": "Documentation question to answer."+ }+ }+ },+ "SupportDocsSearchResponse": {+ "type": "object",+ "properties": {+ "requestId": {+ "type": "string"+ },+ "answer": {+ "type": "string",+ "description": "Concise answer grounded in Firecrawl documentation."+ },+ "evidence": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "pathOrUrl": {+ "type": "string"+ },+ "reason": {+ "type": "string"+ }+ }+ }+ },+ "usage": {+ "type": "object",+ "properties": {+ "inputTokens": {+ "type": "integer"+ },+ "outputTokens": {+ "type": "integer"+ },+ "totalTokens": {+ "type": "integer"+ }+ }+ },+ "durationMs": {+ "type": "integer",+ "description": "Total docs-search execution time in milliseconds."+ }+ }+ },+ "SupportProxyErrorResponse": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "description": "Support proxy or upstream error code."+ }+ }+ },+ "RedactPIIEntity": {+ "type": "string",+ "enum": [+ "PERSON",+ "EMAIL",+ "PHONE",+ "LOCATION",+ "FINANCIAL",+ "SECRET"+ ],+ "description": "Public PII entity buckets supported by Firecrawl redaction."+ },+ "RedactPIIOptions": {+ "type": "object",+ "description": "Tuning options for PII redaction.",+ "properties": {+ "mode": {+ "type": "string",+ "enum": [+ "accurate",+ "aggressive",+ "fast"+ ],+ "default": "accurate",+ "description": "Redaction strategy. `accurate` is model-only and optimized for precision, `aggressive` increases recall with additional heuristics, and `fast` uses heuristics without the model call."+ },+ "entities": {+ "type": "array",+ "description": "Restrict redaction to these entity buckets. If omitted, all supported entities are redacted.",+ "items": {+ "$ref": "#/components/schemas/RedactPIIEntity"+ }+ },+ "replaceStyle": {+ "type": "string",+ "enum": [+ "tag",+ "mask",+ "remove"+ ],+ "default": "tag",+ "description": "`tag` replaces spans with placeholders like `<EMAIL>`, `mask` replaces characters with `*`, and `remove` deletes the span text."+ }+ },+ "additionalProperties": false+ },+ "ResearchIdMap": {+ "type": "object",+ "description": "Source identifiers grouped by namespace.",+ "additionalProperties": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "example": {+ "arxiv": [+ "2105.05233"+ ]+ }+ },+ "ResearchPaperSignals": {+ "type": "object",+ "required": [+ "structural",+ "semantic",+ "articleRank",+ "seedOverlap"+ ],+ "properties": {+ "structural": {+ "type": "number",+ "format": "double",+ "description": "Raw structural graph signal."+ },+ "semantic": {+ "type": "number",+ "format": "double",+ "description": "Semantic score from the intent search."+ },+ "articleRank": {+ "type": "number",+ "format": "double",+ "description": "Structural expansion article-rank score."+ },+ "seedOverlap": {+ "type": "integer",+ "minimum": 0,+ "description": "Number of distinct seeds connected to this candidate."+ }+ }+ },+ "ResearchPaperResult": {+ "type": "object",+ "required": [+ "paperId",+ "primaryId",+ "title",+ "abstract",+ "score"+ ],+ "properties": {+ "paperId": {+ "type": "string",+ "description": "Canonical paper id, or web:<url> for SERP-discovered display results."+ },+ "primaryId": {+ "type": "string",+ "description": "Preferred cite/fetch id such as arxiv:<id>, pmid:<id>, pmcid:<id>, or doi:<id>."+ },+ "ids": {+ "$ref": "#/components/schemas/ResearchIdMap"+ },+ "title": {+ "type": "string"+ },+ "abstract": {+ "type": "string"+ },+ "score": {+ "type": "number",+ "format": "double"+ },+ "signals": {+ "$ref": "#/components/schemas/ResearchPaperSignals"+ }+ }+ },+ "ResearchPaperMetadata": {+ "type": "object",+ "required": [+ "paperId",+ "title",+ "abstract"+ ],+ "properties": {+ "paperId": {+ "type": "string",+ "description": "Canonical paper id."+ },+ "ids": {+ "$ref": "#/components/schemas/ResearchIdMap"+ },+ "title": {+ "type": "string"+ },+ "abstract": {+ "type": "string"+ },+ "authors": {+ "type": "string",+ "description": "Comma-joined author names."+ },+ "categories": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Paper categories."+ },+ "createdDate": {+ "type": "string",+ "description": "Original creation date string."+ },+ "updateDate": {+ "type": "string",+ "description": "Last-updated date string."+ }+ }+ },+ "ResearchPassage": {+ "type": "object",+ "required": [+ "text",+ "score"+ ],+ "properties": {+ "text": {+ "type": "string",+ "description": "In-body passage text. May include markdown tables."+ },+ "score": {+ "type": "number",+ "format": "double",+ "description": "Dense similarity score for the passage."+ }+ }+ },+ "ResearchSearchPapersResponse": {+ "type": "object",+ "required": [+ "success",+ "results"+ ],+ "properties": {+ "success": {+ "type": "boolean"+ },+ "results": {+ "type": "array",+ "items": {+ "$ref": "#/components/schemas/ResearchPaperResult"+ }+ }+ }+ },+ "ResearchPaperMetadataResponse": {+ "type": "object",+ "required": [+ "success",+ "paper"+ ],+ "properties": {+ "success": {+ "type": "boolean"+ },+ "paper": {+ "$ref": "#/components/schemas/ResearchPaperMetadata"+ }+ }+ },+ "ResearchReadPaperResponse": {+ "type": "object",+ "required": [+ "success",+ "paper",+ "paperId",+ "query",+ "passages"+ ],+ "properties": {+ "success": {+ "type": "boolean"+ },+ "paper": {+ "$ref": "#/components/schemas/ResearchPaperMetadata"+ },+ "paperId": {+ "type": "string"+ },+ "query": {+ "type": "string"+ },+ "passages": {+ "type": "array",+ "items": {+ "$ref": "#/components/schemas/ResearchPassage"+ }+ }+ }+ },+ "ResearchSimilarPapersResponse": {+ "type": "object",+ "required": [+ "success",+ "results",+ "poolSize",+ "truncated"+ ],+ "properties": {+ "success": {+ "type": "boolean"+ },+ "results": {+ "type": "array",+ "items": {+ "$ref": "#/components/schemas/ResearchPaperResult"+ }+ },+ "poolSize": {+ "type": "integer",+ "minimum": 0+ },+ "truncated": {+ "type": "boolean"+ },+ "note": {+ "type": "string",+ "nullable": true+ }+ }+ },+ "DeveloperSearchResult": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "Stable result id, such as `issue:owner/repo#123`.",+ "example": "issue:firecrawl/firecrawl#1234"+ },+ "type": {+ "type": "string",+ "enum": [+ "doc",+ "issue",+ "pull_request",+ "readme"+ ],+ "description": "Result kind."+ },+ "url": {+ "type": "string",+ "format": "uri"+ },+ "title": {+ "type": "string",+ "description": "Frequently absent on `doc` results, where the source page carries no usable title. Fall back to `url`."+ },+ "passages": {+ "type": "array",+ "description": "Matched passages in markdown, so tables and code blocks survive.",+ "items": {+ "type": "object",+ "properties": {+ "text": {+ "type": "string"+ }+ }+ }+ }+ }+ },+ "DeveloperSearchResponse": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean"+ },+ "results": {+ "type": "array",+ "items": {+ "$ref": "#/components/schemas/DeveloperSearchResult"+ }+ },+ "coverage": {+ "type": "object",+ "description": "Outcome for each result type. Check this when an expected result type is missing: `skipped` means your `types` value did not ask for that type, while `degraded` or `unavailable` means the gap came from the index or from a filter, not from the query. A repository filter is one such cause — see [how the repository filters scope a search](/api-reference/endpoint/developer-search#how-the-repository-filters-scope-a-search).",+ "properties": {+ "doc": {+ "type": "string",+ "enum": [+ "ok",+ "degraded",+ "unavailable",+ "skipped"+ ]+ },+ "issue": {+ "type": "string",+ "enum": [+ "ok",+ "degraded",+ "unavailable",+ "skipped"+ ]+ },+ "pull_request": {+ "type": "string",+ "enum": [+ "ok",+ "degraded",+ "unavailable",+ "skipped"+ ]+ },+ "readme": {+ "type": "string",+ "enum": [+ "ok",+ "degraded",+ "unavailable",+ "skipped"+ ]+ }+ }+ },+ "reranked": {+ "type": "boolean",+ "description": "Whether the ranked list went through the reranking stage."+ },+ "repos": {+ "type": "array",+ "description": "Present only when `repos` was sent. Echoes each slug with whether it is indexed, plus a per-type breakdown under `types`.",+ "items": {+ "type": "object",+ "properties": {+ "repo": {+ "type": "string"+ },+ "indexed": {+ "type": "boolean"+ },+ "types": {+ "type": "object",+ "description": "Which result types are indexed for this repository: `issue`, `pullRequest`, and `readme`.",+ "properties": {+ "issue": {+ "type": "boolean"+ },+ "pullRequest": {+ "type": "boolean"+ },+ "readme": {+ "type": "boolean"+ }+ }+ }+ }+ },+ "example": [+ {+ "repo": "firecrawl/firecrawl",+ "indexed": true,+ "types": {+ "issue": true,+ "pullRequest": true,+ "readme": true+ }+ }+ ]+ },+ "sources": {+ "type": "array",+ "description": "Present only when `sources` was sent. Reports each id exactly as requested along with whether it is indexed. `indexed: true` means the source has a published generation, so documentation evidence from it may appear; `indexed: false` means nothing from that id can match, which distinguishes an id that is not in the index from a query that simply found nothing.",+ "items": {+ "type": "object",+ "properties": {+ "source": {+ "type": "string"+ },+ "indexed": {+ "type": "boolean"+ }+ }+ },+ "example": [+ {+ "source": "some-docs-site",+ "indexed": true+ },+ {+ "source": "unknown-docs-site",+ "indexed": false+ }+ ]+ }+ }+ },+ "EndpointFeedbackRequest": {+ "allOf": [+ {+ "$ref": "#/components/schemas/SearchFeedbackRequest"+ },+ {+ "type": "object",+ "description": "Submit feedback for a v2 job. Include at least one substantive signal such as issues, note, valuableSources, missingContent, querySuggestions, url, or pageNumbers.",+ "properties": {+ "endpoint": {+ "type": "string",+ "enum": [+ "search",+ "scrape",+ "parse",+ "map"+ ]+ },+ "jobId": {+ "type": "string",+ "format": "uuid"+ },+ "issues": {+ "type": "array",+ "maxItems": 20,+ "items": {+ "type": "string",+ "pattern": "^[a-z0-9][a-z0-9_-]*$",+ "maxLength": 80+ }+ },+ "tags": {+ "type": "array",+ "maxItems": 20,+ "items": {+ "type": "string",+ "pattern": "^[a-z0-9][a-z0-9_-]*$",+ "maxLength": 80+ }+ },+ "note": {+ "type": "string",+ "maxLength": 4000+ },+ "url": {+ "type": "string",+ "format": "uri"+ },+ "pageNumbers": {+ "type": "array",+ "maxItems": 100,+ "items": {+ "type": "integer",+ "minimum": 1+ }+ },+ "metadata": {+ "type": "object",+ "additionalProperties": true,+ "description": "Small endpoint-specific metadata object. Must be 8KB or smaller; do not include full endpoint results."+ },+ "missingContent": {+ "type": "array",+ "maxItems": 50,+ "items": {+ "type": "object",+ "properties": {+ "topic": {+ "type": "string",+ "maxLength": 200,+ "minLength": 1+ },+ "description": {+ "type": "string",+ "maxLength": 2000+ }+ },+ "required": [+ "topic"+ ]+ }+ }+ },+ "required": [+ "endpoint",+ "jobId"+ ]+ }+ ]+ },+ "FeedbackResponse": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": true+ },+ "feedbackId": {+ "type": "string",+ "format": "uuid"+ },+ "creditsRefunded": {+ "type": "number"+ },+ "alreadySubmitted": {+ "type": "boolean"+ },+ "dailyCapReached": {+ "type": "boolean"+ },+ "creditsRefundedToday": {+ "type": "number"+ },+ "dailyRefundCap": {+ "type": "number"+ },+ "warning": {+ "type": "string"+ }+ },+ "required": [+ "success",+ "feedbackId",+ "creditsRefunded"+ ]+ },+ "FeedbackErrorResponse": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "example": false+ },+ "error": {+ "type": "string"+ },+ "feedbackErrorCode": {+ "type": "string"+ },+ "details": {+ "type": "array",+ "items": {+ "type": "object"+ }+ }+ },+ "required": [+ "success",+ "error"+ ]+ },+ "ThreatProtectionOverride": {+ "type": "object",+ "title": "Threat Protection Override",+ "description": "Per-request [Threat Protection](https://docs.firecrawl.dev/features/threat-protection) override. Fields you provide replace the corresponding fields of your organization's policy for this request only; omitted fields keep their organization-level values. Requires Threat Protection to be enabled for your team (enterprise feature) — otherwise the request is rejected with a 403. If your organization has disabled request overrides, any request that includes this object is rejected with a 403. If Threat Protection is enforced for your team, `mode` may not be set to `off`.",+ "properties": {+ "mode": {+ "type": "string",+ "enum": [+ "off",+ "normal"+ ],+ "description": "URL scanning mode for this request. `normal` checks URLs against Google Web Risk (+2 credits per URL scanned)."+ },+ "riskScoreThreshold": {+ "type": "integer",+ "minimum": 0,+ "maximum": 100,+ "description": "Normalized risk score (0–100) at or above which a classifier verdict blocks the URL. Lower is stricter.",+ "example": 75+ },+ "blacklist": {+ "type": "array",+ "maxItems": 1000,+ "items": {+ "type": "string"+ },+ "description": "Domains to always block, as plain domains (`example.com`) or wildcard globs (`*.example.com`). No protocol, path, or port."+ },+ "whitelist": {+ "type": "array",+ "maxItems": 1000,+ "items": {+ "type": "string"+ },+ "description": "Domains to always allow, as plain domains or wildcard globs. Wins over every other rule."+ },+ "blockedTlds": {+ "type": "array",+ "maxItems": 1000,+ "items": {+ "type": "string"+ },+ "description": "Top-level domains to block outright, lowercase without the leading dot (e.g. `zip`)."+ },+ "failurePolicy": {+ "type": "string",+ "enum": [+ "open",+ "closed"+ ],+ "description": "What to do when the classifier can't be reached: `closed` blocks the request, `open` allows it."+ }+ }+ }+ }+ },+ "security": [+ {+ "bearerAuth": []+ }+ ]+}diff --git a/apps/elixir-sdk/test/generator_test.exs b/apps/elixir-sdk/test/generator_test.exsindex 5eefdca99..846b2138d 100644--- a/apps/elixir-sdk/test/generator_test.exs+++ b/apps/elixir-sdk/test/generator_test.exs@@ -160,8 +160,22 @@ defmodule Firecrawl.GeneratorTest doendend- describe "get_parse_formats" do- test "is emitted once even when the spec declares GET /parse/formats" do+ describe "regeneration" do+ @lib_path Path.expand("../lib/firecrawl.ex", __DIR__)+ @spec_path Path.expand("../openapi.json", __DIR__)++ defp hand_written, do: @lib_path |> File.read!() |> Firecrawl.Generator.hand_written_region()++ test "lib/firecrawl.ex is exactly what generate.exs produces from openapi.json" do+ spec = @spec_path |> File.read!() |> Jason.decode!()+ lib = File.read!(@lib_path)++ assert Firecrawl.Generator.generate_module(spec, hand_written()) == lib,+ "lib/firecrawl.ex drifted from the generator. Edit generate.exs or the " <>+ "HAND-WRITTEN region, then run: FIRECRAWL_OPENAPI_SPEC=openapi.json mix run generate.exs"+ end++ test "get_parse_formats is emitted once even when the spec declares GET /parse/formats" dospec = %{"paths" => %{"/parse/formats" => %{@@ -170,17 +184,60 @@ defmodule Firecrawl.GeneratorTest do}}- code = Firecrawl.Generator.generate_module(spec)+ code = Firecrawl.Generator.generate_module(spec, hand_written())assert length(Regex.scan(~r/^ def get_parse_formats\(/m, code)) == 1assert length(Regex.scan(~r/^ def get_parse_formats!\(/m, code)) == 1end- test "lib/firecrawl.ex carries the generator's hand-written block verbatim" do- lib = File.read!(Path.expand("../lib/firecrawl.ex", __DIR__))- block = Firecrawl.Generator.parse_formats_code()+ test "a spec operation that clashes with the HAND-WRITTEN region stops generation" do+ spec = %{+ "paths" => %{+ "/agent/{jobId}/trace-v2" => %{+ "get" => %{+ "operationId" => "getAgentTrace",+ "parameters" => [%{"name" => "jobId", "in" => "path"}]+ }+ }+ }+ }++ assert_raise RuntimeError, ~r/clash with the HAND-WRITTEN region: get_agent_trace/, fn ->+ Firecrawl.Generator.generate_module(spec, hand_written())+ end+ end- assert String.contains?(lib, block)+ test "$ref path parameters become interpolations, never literal holes" do+ spec = %{+ "components" => %{"parameters" => %{"ThingId" => %{"name" => "thingId", "in" => "path"}}},+ "paths" => %{+ "/things/{thingId}" => %{+ "get" => %{+ "operationId" => "getThing",+ "parameters" => [%{"$ref" => "#/components/parameters/ThingId"}]+ }+ }+ }+ }++ code = Firecrawl.Generator.generate_module(spec, hand_written())++ assert code =~ ~S|def get_thing(thing_id, opts \\ []) do|+ assert code =~ ~S|url: "/things/#{thing_id}"|+ end++ test "a path parameter the spec never declares stops generation" do+ spec = %{"paths" => %{"/things/{thingId}" => %{"get" => %{"operationId" => "getThing"}}}}++ assert_raise ArgumentError, ~r/unresolved path parameter/, fn ->+ Firecrawl.Generator.generate_module(spec, hand_written())+ end+ end++ test "a lib without a HAND-WRITTEN region is refused" do+ assert_raise RuntimeError, ~r/exactly one HAND-WRITTEN region/, fn ->+ Firecrawl.Generator.hand_written_region("defmodule Firecrawl do\nend\n")+ endendendend