> ## Documentation Index > Fetch the complete documentation index at: https://docs.nimbleway.com/llms.txt > Use this file to discover all available pages before exploring further. # Onboard your Agent > Web data APIs for AI: search, extract, crawl, and research the live web Nimble gives your application and your AI agents live web data through a single API. Search the web, extract any page, crawl whole sites, or hand off entire research tasks. Every product returns structured, LLM-ready output. Fastest path: paste this into your coding agent and it installs Nimble itself. ```text theme={"system"} Read and follow https://docs.nimbleway.com/agents.md ``` ## Install in your coding agent Prefer to do it yourself? No API key needed where the client supports OAuth. Works in Claude, Cursor, Codex, and Cortex Code. Installs the Nimble skills and configures the MCP server. ```bash theme={"system"} claude plugin marketplace add Nimbleway/agent-skills && \ claude plugin install nimble@nimble-plugin-marketplace ``` Run `/mcp` and confirm `nimble` appears in your connected servers. One click, from the Anthropic and Partners directory inside Claude.

Approve the scopes in your browser. There is no API key to paste or manage. One click, then confirm the install in Cursor.

Then replace `NIMBLE_API_KEY` in **Settings → MCP Servers → nimble-mcp-server** with your [Nimble API key](https://online.nimbleway.com/settings/api-keys). The deeplink ships a placeholder, not a key. Teaches the agent which Nimble product fits a given job. ```bash theme={"system"} npx skills add Nimbleway/agent-skills -a cursor ``` Open Settings, then MCP, and confirm `nimble-mcp-server` is listed. Open **Plugins**, click **Add → Add a marketplace**, and enter this source: ```text theme={"system"} https://github.com/Nimbleway/agent-skills.git ``` Nimble is not in OpenAI's public plugin directory, so this is the early-access route. Click **Install**, then approve the scopes in your browser. This installs the Nimble skills and the hosted MCP connection together. There is no API key to paste or manage. Bundled skills register on a new session. Start a new task, type `@nimble`, and select **Nimble**. Full walkthrough with screenshots: [Plugin Installation](/integrations/agent-skills/plugin-installation). Codex stores MCP configuration in `~/.codex/config.toml`, or a project-scoped `.codex/config.toml`. Add: ```toml theme={"system"} [mcp_servers.nimble-mcp-server] url = "https://mcp.nimbleway.com/mcp" bearer_token_env_var = "NIMBLE_API_KEY" ``` Codex reads `NIMBLE_API_KEY` from your environment at runtime, so the key is never written to the config file. Installs the Nimble skills into Codex's skill discovery paths (`~/.agents/skills/`). ```bash theme={"system"} npx skills add Nimbleway/agent-skills -a codex ``` Run `/mcp` inside the Codex TUI to confirm the server, and `/skills` to confirm the skills. Restart Codex if they do not appear. Adds the Nimble MCP server to Snowflake's terminal agent. ```bash theme={"system"} cortex mcp add nimble https://mcp.nimbleway.com/mcp --transport http ``` No `Authorization` header is needed. The Nimble MCP server advertises OAuth and Cortex Code runs the flow on first connection, storing tokens in your OS keychain. Run `cortex mcp list` to confirm, then `cortex mcp start`. Once it is installed, ask for what you want: ```text theme={"system"} Compare prices for the Sony WH-1000XM5 across Amazon, Walmart, and Best Buy using Nimble. Show price, availability, and rating from each. ``` No coding agent? The [Quickstart](/nimble-sdk/getting-started/quickstart) has working code in Python, TypeScript, Go, cURL, and the CLI. Need MCP, a warehouse app, or another path? See [all install options](/integrations/overview). ## Build with Nimble Pick a product, copy the setup prompt, and paste it into your coding agent. Each prompt tells the agent when to use that product, when to reach for a different one, and the gotchas per language. Brief it like an analyst and it plans its own searches, reads the sources, and writes the answer. Every claim comes back with a citation and a confidence grade. [View docs →](/nimble-sdk/web-search-agents/overview) ````markdown theme={"system"} # Nimble Web Search Agent: setup prompt You are integrating **Nimble Web Search Agent** into this project. ## When to use it Use a Web Search Agent when the task is a research question rather than a lookup. It plans its own searches, reads sources, and returns a written answer with a citation and a confidence grade per claim. It takes minutes, not seconds. For a single fast lookup, use Search. ## Setup ```bash pip install nimble_python # Python npm install @nimble-way/nimble-js # TypeScript export NIMBLE_API_KEY="your-api-key" ``` ## Example (Python) ```python import os, time from nimble_python import Nimble nimble = Nimble(api_key=os.environ["NIMBLE_API_KEY"]) run = nimble.agents.run( input="Compare the pricing of Datadog, Grafana Cloud, and New Relic.", ) agent_id = run.web_search_agent_id while run.is_active: time.sleep(10) run = nimble.agents.runs.get(run.id, agent_id=agent_id) result = nimble.agents.runs.result(run.id, agent_id=agent_id) print(result.output.content) print(result.output.trust.confidence) ``` ## Notes - Runs are asynchronous. Poll while `run.is_active` is true, then fetch the result. - Keep `web_search_agent_id` from the first response. Later calls require it. - `output.trust` grades every claim and links its sources. Surface it rather than discarding it. - Effort level trades depth against time and cost. ## Language notes - TypeScript import is a default export: `import Nimble from "@nimble-way/nimble-js"`. - The TypeScript client keeps the API's underscore field names. Write `max_results`, not `maxResults`. Follow-up calls take the id positionally and the rest as an object: `nimble.agents.runs.get(run.id, { agent_id: agentId })`. - Do not block on a single call. There is no synchronous variant. ## Links - Docs: https://docs.nimbleway.com/nimble-sdk/web-search-agents/overview - REST: POST https://sdk.nimbleway.com/v2/agents/runs - CLI: `nimble agents run --input "..."` ## Other Nimble products | Product | Returns | Reach for it when | |---------|---------|-------------------| | **Web Search Agent** | Research question to a cited answer plus a trust report | The task needs multi-step research, not a single lookup | | **Search** | Query to ranked results with titles, URLs, descriptions | You need current facts, or candidate URLs to feed into Extract | | **Extract Template** | Template name and params to structured fields | The site has a maintained template, so no selectors are needed | | **Extract** | URL to clean markdown, HTML, or parsed fields | You have a specific page and want its content | | **Map** | Domain to every URL, no page content | Planning which pages to fetch before extracting | | **Crawl** | Domain to content from many pages, async | You want a whole section of a site in one request | | **Extract Jobs** | Template plus schedule plus destination to delivered files | The same extraction has to run repeatedly, on a schedule | ```` Real-time results from across the web, ranked and structured for a model to consume. Choose how deep to go, from metadata only through to full page content. [View docs →](/nimble-sdk/web-tools/search) ````markdown theme={"system"} # Nimble Search: setup prompt You are integrating **Nimble Search** into this project. ## When to use it Use Search when you need current web results for a query. It returns ranked results with titles, URLs, and descriptions. If you need a written answer with citations rather than a result list, use a Web Search Agent. If you already know the page you want, use Extract. ## Setup ```bash pip install nimble_python # Python npm install @nimble-way/nimble-js # TypeScript export NIMBLE_API_KEY="your-api-key" ``` ## Example (Python) ```python import os from nimble_python import Nimble nimble = Nimble(api_key=os.environ["NIMBLE_API_KEY"]) result = nimble.search( query="best CRM tools for startups 2026", max_results=5, search_depth="standard", # lite | standard ) for item in result.results: print(item.title, item.url) ``` ## Notes - `search_depth` controls cost and latency. `standard` is the default and returns rich content. `lite` returns title, URL, and description only. - Full page extraction is a separate flag, `full_content=True`, not a depth. It works alongside either `search_depth` value. - `focus` narrows the result type, for example a shopping or news focus. - Read `total_results`. Do not assume a fixed count. ## Language notes - TypeScript import is a default export: `import Nimble from "@nimble-way/nimble-js"`. - The TypeScript client keeps the API's underscore field names. Write `max_results`, not `maxResults`. `max_results` and `search_depth` keep their underscores. - Go takes optional scalars through `param.NewOpt(...)` and enums as typed constants such as `nimble.SearchParamsSearchDepthLite`. ## Links - Docs: https://docs.nimbleway.com/nimble-sdk/web-tools/search - REST: POST https://sdk.nimbleway.com/v2/search - CLI: `nimble search --query "..." --max-results 5` ## Other Nimble products | Product | Returns | Reach for it when | |---------|---------|-------------------| | **Web Search Agent** | Research question to a cited answer plus a trust report | The task needs multi-step research, not a single lookup | | **Search** | Query to ranked results with titles, URLs, descriptions | You need current facts, or candidate URLs to feed into Extract | | **Extract Template** | Template name and params to structured fields | The site has a maintained template, so no selectors are needed | | **Extract** | URL to clean markdown, HTML, or parsed fields | You have a specific page and want its content | | **Map** | Domain to every URL, no page content | Planning which pages to fetch before extracting | | **Crawl** | Domain to content from many pages, async | You want a whole section of a site in one request | | **Extract Jobs** | Template plus schedule plus destination to delivered files | The same extraction has to run repeatedly, on a schedule | ```` Maintained extractors for popular sites such as Amazon and Google Maps. Pass a template and its parameters and get clean structured fields, with no selectors to write. [View docs →](/nimble-sdk/web-tools/extract/template) ````markdown theme={"system"} # Nimble Extract Template: setup prompt You are integrating **Nimble Extract Template** into this project. ## When to use it Use an Extract Template for sites that already have a maintained template, such as Amazon product pages or Google Maps. Pass a template name and its parameters and get structured fields back. Nimble maintains the template, so it keeps working when the site changes its markup. For an arbitrary URL with no template, use Extract. ## Setup ```bash pip install nimble_python # Python npm install @nimble-way/nimble-js # TypeScript export NIMBLE_API_KEY="your-api-key" ``` ## Example (Python) ```python import os from nimble_python import Nimble nimble = Nimble(api_key=os.environ["NIMBLE_API_KEY"]) result = nimble.extract.templates.run( template="amazon_pdp", params={"asin": "B0DKB1GWML"}, ) print(result.data.parsing) ``` ## Notes - List what exists with `nimble.extract.templates.list()` before assuming a template is available. - Each template declares its own required params. Read the template first. - A template can be generated for a site that lacks one. ## Language notes - TypeScript import is a default export: `import Nimble from "@nimble-way/nimble-js"`. - The TypeScript client keeps the API's underscore field names. Write `max_results`, not `maxResults`. - `params` is a free-form object. Its keys come from the template, not the SDK, so they are not type-checked. ## Links - Docs: https://docs.nimbleway.com/nimble-sdk/web-tools/extract/template - REST: POST https://sdk.nimbleway.com/v2/extract/templates/run - CLI: `nimble extract:templates run --template amazon_pdp` ## Other Nimble products | Product | Returns | Reach for it when | |---------|---------|-------------------| | **Web Search Agent** | Research question to a cited answer plus a trust report | The task needs multi-step research, not a single lookup | | **Search** | Query to ranked results with titles, URLs, descriptions | You need current facts, or candidate URLs to feed into Extract | | **Extract Template** | Template name and params to structured fields | The site has a maintained template, so no selectors are needed | | **Extract** | URL to clean markdown, HTML, or parsed fields | You have a specific page and want its content | | **Map** | Domain to every URL, no page content | Planning which pages to fetch before extracting | | **Crawl** | Domain to content from many pages, async | You want a whole section of a site in one request | | **Extract Jobs** | Template plus schedule plus destination to delivered files | The same extraction has to run repeatedly, on a schedule | ```` Any URL to clean, LLM-ready content, with JavaScript rendering handled for you. Return markdown, raw HTML, parsed fields, or a screenshot. [View docs →](/nimble-sdk/web-tools/extract/quickstart) ````markdown theme={"system"} # Nimble Extract: setup prompt You are integrating **Nimble Extract** into this project. ## When to use it Use Extract when you have a specific URL and want its content. It handles JavaScript rendering and returns whichever formats you ask for. For a popular site with a known layout, prefer an Extract Template: it returns structured fields without selectors. ## Setup ```bash pip install nimble_python # Python npm install @nimble-way/nimble-js # TypeScript export NIMBLE_API_KEY="your-api-key" ``` ## Example (Python) ```python import os from nimble_python import Nimble nimble = Nimble(api_key=os.environ["NIMBLE_API_KEY"]) result = nimble.extract.run( url="https://www.nimbleway.com", formats=["markdown"], # html | markdown | parsing | screenshots ) print(result.data.markdown) ``` ## Notes - Pass `formats=["markdown"]` for LLM input. Add `"html"` only if you need raw markup. - Heavy pages can exceed a sync request. Use the async variant and poll the task. - Geo-targeting, stealth mode, and browser actions are per-request options. ## Language notes - TypeScript import is a default export: `import Nimble from "@nimble-way/nimble-js"`. - The TypeScript client keeps the API's underscore field names. Write `max_results`, not `maxResults`. - The response nests content under `data`, so read `result.data.markdown`, not `result.markdown`. ## Links - Docs: https://docs.nimbleway.com/nimble-sdk/web-tools/extract/quickstart - REST: POST https://sdk.nimbleway.com/v2/extract - CLI: `nimble extract run --url "..." --format markdown` ## Other Nimble products | Product | Returns | Reach for it when | |---------|---------|-------------------| | **Web Search Agent** | Research question to a cited answer plus a trust report | The task needs multi-step research, not a single lookup | | **Search** | Query to ranked results with titles, URLs, descriptions | You need current facts, or candidate URLs to feed into Extract | | **Extract Template** | Template name and params to structured fields | The site has a maintained template, so no selectors are needed | | **Extract** | URL to clean markdown, HTML, or parsed fields | You have a specific page and want its content | | **Map** | Domain to every URL, no page content | Planning which pages to fetch before extracting | | **Crawl** | Domain to content from many pages, async | You want a whole section of a site in one request | | **Extract Jobs** | Template plus schedule plus destination to delivered files | The same extraction has to run repeatedly, on a schedule | ```` Every URL on a domain, gathered from links and sitemaps without fetching page content. Use it to pick your targets before you extract. [View docs →](/nimble-sdk/web-tools/map) ````markdown theme={"system"} # Nimble Map: setup prompt You are integrating **Nimble Map** into this project. ## When to use it Use Map to plan work before extracting. It returns the URLs on a domain by following links and reading sitemaps, without fetching page content. Pick targets from it, then pass those URLs to Extract. To get content from every page in one call instead, use Crawl. ## Setup ```bash pip install nimble_python # Python npm install @nimble-way/nimble-js # TypeScript export NIMBLE_API_KEY="your-api-key" ``` ## Example (Python) ```python import os from nimble_python import Nimble nimble = Nimble(api_key=os.environ["NIMBLE_API_KEY"]) result = nimble.map( url="https://www.nimbleway.com", sitemap="include", ) for link in result.links: print(link.url) ``` ## Notes - Map returns links and metadata, not page content, so it costs far less to run than Crawl. - `sitemap="include"` merges sitemap entries with discovered links. - Large sites return a lot of URLs. Filter before extracting. ## Language notes - TypeScript import is a default export: `import Nimble from "@nimble-way/nimble-js"`. - The TypeScript client keeps the API's underscore field names. Write `max_results`, not `maxResults`. - Results are under `links`, each with `url`, `title`, and `description`. ## Links - Docs: https://docs.nimbleway.com/nimble-sdk/web-tools/map - REST: POST https://sdk.nimbleway.com/v2/map - CLI: `nimble map --url "..." --sitemap include` ## Other Nimble products | Product | Returns | Reach for it when | |---------|---------|-------------------| | **Web Search Agent** | Research question to a cited answer plus a trust report | The task needs multi-step research, not a single lookup | | **Search** | Query to ranked results with titles, URLs, descriptions | You need current facts, or candidate URLs to feed into Extract | | **Extract Template** | Template name and params to structured fields | The site has a maintained template, so no selectors are needed | | **Extract** | URL to clean markdown, HTML, or parsed fields | You have a specific page and want its content | | **Map** | Domain to every URL, no page content | Planning which pages to fetch before extracting | | **Crawl** | Domain to content from many pages, async | You want a whole section of a site in one request | | **Extract Jobs** | Template plus schedule plus destination to delivered files | The same extraction has to run repeatedly, on a schedule | ```` Bind an extractor to a schedule and a destination, and the data keeps arriving. Runs on cron and delivers files to S3 or your warehouse. [View docs →](/nimble-sdk/agentic/jobs) ````markdown theme={"system"} # Nimble Extract Jobs: setup prompt You are integrating **Nimble Extract Jobs** into this project. ## When to use it Use an Extract Job when the same extraction has to run repeatedly. A job binds a template to a set of inputs, a schedule, and a destination, then delivers files there on every run. For a one-off extraction, call Extract or an Extract Template directly instead. ## Setup ```bash pip install nimble_python # Python npm install @nimble-way/nimble-js # TypeScript export NIMBLE_API_KEY="your-api-key" ``` ## Example (Python) ```python import os, time from nimble_python import Nimble nimble = Nimble(api_key=os.environ["NIMBLE_API_KEY"]) job = nimble.jobs.create( name="daily_amazon_top_skus", extract_template_name="amazon_pdp", schedule={"cron": "0 7 * * *", "enabled": True}, inputs={"type": "inline", "data": [{"asin": "B08N5WRWNW"}]}, destination={ "type": "s3", "path": "s3://my-bucket/amazon-skus/", "format": "parquet", }, ) run = nimble.jobs.runs.create(job.id) artifacts = nimble.jobs.runs.artifacts.list(run.id) ``` ## Notes - A job needs four things: a template, inputs, a schedule, and a destination. - `schedule.cron` is standard cron. Set `enabled: false` to create it paused. - Trigger a run immediately with `jobs.runs.create` rather than waiting for the cron. - Output arrives as artifacts. List them, then request a download URL. - Destinations include S3 and Databricks; the connection is configured separately. ## Language notes - TypeScript import is a default export: `import Nimble from "@nimble-way/nimble-js"`. - The TypeScript client keeps the API's underscore field names. Write `max_results`, not `maxResults`. One exception to watch: the artifact download helper is `downloadURL` in TypeScript and `download_url` in Python. - `inputs` and `destination` are free-form objects whose shape depends on the type you pass, so they are not fully type-checked. ## Links - Docs: https://docs.nimbleway.com/nimble-sdk/agentic/jobs - REST: POST https://sdk.nimbleway.com/v2/jobs - CLI: `nimble jobs create --name ... --extract-template-name ...` ## Other Nimble products | Product | Returns | Reach for it when | |---------|---------|-------------------| | **Web Search Agent** | Research question to a cited answer plus a trust report | The task needs multi-step research, not a single lookup | | **Search** | Query to ranked results with titles, URLs, descriptions | You need current facts, or candidate URLs to feed into Extract | | **Extract Template** | Template name and params to structured fields | The site has a maintained template, so no selectors are needed | | **Extract** | URL to clean markdown, HTML, or parsed fields | You have a specific page and want its content | | **Map** | Domain to every URL, no page content | Planning which pages to fetch before extracting | | **Crawl** | Domain to content from many pages, async | You want a whole section of a site in one request | | **Extract Jobs** | Template plus schedule plus destination to delivered files | The same extraction has to run repeatedly, on a schedule | ```` ## Next steps Your first API call in under a minute Plugin, MCP, SDK, or warehouse: which path fits and how each authenticates Hand off a research question, get a cited answer back Configure and run agents in the browser, no code This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.