> ## 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.

# Quickstart

> Get a key, install a client, and call every Nimble product

Every Nimble product in Python, TypeScript, Go, cURL, and the CLI. Copy, paste, and run.

<Tip>
  Prefer not to write code? Install the [Nimble plugin](/integrations/agent-skills/plugin-installation) and describe what you need in plain language. [Onboard your Agent](/nimble-sdk/getting-started/overview) has the one-command setup for every coding agent.
</Tip>

<Steps>
  <Step title="Get your API key" titleSize="h3">
    [Sign up](https://online.nimbleway.com/signup) and copy your key from [Settings → API Keys](https://online.nimbleway.com/settings/api-keys). Then set it as an environment variable:

    <CodeGroup>
      ```bash macOS / Linux theme={"system"}
      export NIMBLE_API_KEY="your-api-key"
      ```

      ```bash Windows (PowerShell) theme={"system"}
      $env:NIMBLE_API_KEY="your-api-key"
      ```
    </CodeGroup>

    Every SDK and the CLI read `NIMBLE_API_KEY` automatically.
  </Step>

  <Step title="Install a client" titleSize="h3">
    Requires Python 3.9+, Node.js 20 LTS+, or Go 1.22+.

    <CodeGroup>
      ```bash Python theme={"system"}
      pip install nimble_python
      ```

      ```bash TypeScript theme={"system"}
      npm install @nimble-way/nimble-js
      ```

      ```bash Go theme={"system"}
      go get github.com/Nimbleway/nimble-go@latest
      ```

      ```bash CLI theme={"system"}
      npm install -g @nimble-way/nimble-cli
      ```
    </CodeGroup>

    Full client docs: [Python](/nimble-sdk/sdks/python), [Node](/nimble-sdk/sdks/node), [Go](/nimble-sdk/sdks/go), and [CLI](/nimble-sdk/sdks/cli). Python also offers an aiohttp extra: `pip install "nimble_python[aiohttp]"`.

    Calling the API over plain HTTP? Skip this step and see the [API Reference](/api-reference/introduction).
  </Step>
</Steps>

Every example below reads the key from `NIMBLE_API_KEY`. The first Search example is a complete program; the rest are abbreviated and assume you have already created a client the same way.

## Search

Real-time web search with structured results:

<CodeGroup>
  ```python Python theme={"system"}
  import os
  from nimble_python import Nimble

  nimble = Nimble(api_key=os.environ["NIMBLE_API_KEY"])

  result = nimble.search(
      query="latest developments in AI agents",
      max_results=5
  )

  for r in result.results:
      print(f"- {r.title}: {r.url}")
  ```

  ```typescript TypeScript theme={"system"}
  import Nimble from "@nimble-way/nimble-js";

  const nimble = new Nimble({ apiKey: process.env.NIMBLE_API_KEY });

  const result = await nimble.search({
    query: "latest developments in AI agents",
    max_results: 5,
  });

  result.results.forEach((r) => {
    console.log(`- ${r.title}: ${r.url}`);
  });
  ```

  ```go Go theme={"system"}
  package main

  import (
      "context"
      "fmt"
      "os"

      nimble "github.com/Nimbleway/nimble-go"
      "github.com/Nimbleway/nimble-go/option"
      "github.com/Nimbleway/nimble-go/packages/param"
  )

  func main() {
      client := nimble.NewClient(option.WithAPIKey(os.Getenv("NIMBLE_API_KEY")))

      result, err := client.Search(context.Background(), nimble.SearchParams{
          Query:      "latest developments in AI agents",
          MaxResults: param.NewOpt(int64(5)),
      })
      if err != nil {
          panic(err)
      }
      for _, r := range result.Results {
          fmt.Printf("- %s: %s\n", r.Title, r.URL)
      }
  }
  ```

  ```bash CLI theme={"system"}
  nimble search \
    --query "latest developments in AI agents" \
    --max-results 5
  ```

  ```bash cURL theme={"system"}
  curl -X POST 'https://sdk.nimbleway.com/v2/search' \
  --header "Authorization: Bearer $NIMBLE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "query": "latest developments in AI agents",
      "max_results": 5
  }'
  ```
</CodeGroup>

## Extract

Get clean HTML and structured data from any URL:

<CodeGroup>
  ```python Python theme={"system"}
  import os
  from nimble_python import Nimble

  nimble = Nimble(api_key=os.environ["NIMBLE_API_KEY"])

  result = nimble.extract.run(
      url="https://www.example.com",
      render=True,
      formats=["html", "markdown"]
  )

  print(result.data.html)
  ```

  ```typescript TypeScript theme={"system"}
  import Nimble from "@nimble-way/nimble-js";

  const nimble = new Nimble({ apiKey: process.env.NIMBLE_API_KEY });

  const result = await nimble.extract.run({
    url: "https://www.example.com",
    render: true,
    formats: ["html", "markdown"],
  });

  console.log(result.data?.html);
  ```

  ```go Go theme={"system"}
  result, err := client.Extract.Run(ctx, nimble.ExtractRunParams{
      URL:     "https://www.example.com",
      Render:  nimble.ExtractRunParamsRenderUnion{OfBool: param.NewOpt(true)},
      Formats: []string{"html", "markdown"},
  })
  if err != nil {
      panic(err)
  }
  fmt.Println(result.Data.HTML)
  ```

  ```bash CLI theme={"system"}
  nimble extract run \
    --url "https://www.example.com" \
    --render true \
    --format html --format markdown
  ```

  ```bash cURL theme={"system"}
  curl -X POST 'https://sdk.nimbleway.com/v2/extract' \
  --header "Authorization: Bearer $NIMBLE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "url": "https://www.example.com",
      "render": true,
      "formats": ["html", "markdown"]
  }'
  ```
</CodeGroup>

## Extract Template

Run pre-built extraction templates for popular sites, or [create one for any website](https://online.nimbleway.com/workflow-builder):

<CodeGroup>
  ```python Python theme={"system"}
  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": "B08N5WRWNW"
      }
  )

  parsed = result.data.parsing
  print(f"Product: {parsed['product_title']}")
  print(f"Price: ${parsed['web_price']}")
  ```

  ```typescript TypeScript theme={"system"}
  import Nimble from "@nimble-way/nimble-js";

  const nimble = new Nimble({ apiKey: process.env.NIMBLE_API_KEY });

  const result = await nimble.extract.templates.run({
    template: "amazon_pdp",
    params: {
      asin: "B08N5WRWNW",
    },
  });

  const parsed = result.data?.parsing as Record<string, any>;
  console.log(`Product: ${parsed.product_title}`);
  console.log(`Price: $${parsed.web_price}`);
  ```

  ```go Go theme={"system"}
  result, err := client.Extract.Templates.Run(ctx, nimble.ExtractTemplateRunParams{
      Template: "amazon_pdp",
      Params: map[string]any{
          "asin": "B08N5WRWNW",
      },
  })
  if err != nil {
      panic(err)
  }
  fmt.Println(result.Data.Parsing)
  ```

  ```bash CLI theme={"system"}
  nimble extract:templates run \
    --template amazon_pdp \
    --params '{asin: B08N5WRWNW}'
  ```

  ```bash cURL theme={"system"}
  curl -X POST 'https://sdk.nimbleway.com/v2/extract/templates/run' \
  --header "Authorization: Bearer $NIMBLE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "template": "amazon_pdp",
      "params": {
          "asin": "B08N5WRWNW"
      }
  }'
  ```
</CodeGroup>

## Map

Fast URL discovery and site structure mapping:

<CodeGroup>
  ```python Python theme={"system"}
  import os
  from nimble_python import Nimble

  nimble = Nimble(api_key=os.environ["NIMBLE_API_KEY"])

  result = nimble.map(
      url="https://www.example.com",
      sitemap="include"
  )

  for link in result.links:
      print(f"{link.title}: {link.url}")
  ```

  ```typescript TypeScript theme={"system"}
  import Nimble from "@nimble-way/nimble-js";

  const nimble = new Nimble({ apiKey: process.env.NIMBLE_API_KEY });

  const result = await nimble.map({
    url: "https://www.example.com",
    sitemap: "include",
  });

  result.links.forEach((link) => {
    console.log(`${link.title}: ${link.url}`);
  });
  ```

  ```go Go theme={"system"}
  result, err := client.Map(ctx, nimble.MapParams{
      URL:     "https://www.example.com",
      Sitemap: nimble.MapParamsSitemapInclude,
  })
  if err != nil {
      panic(err)
  }
  for _, link := range result.Links {
      fmt.Printf("%s: %s\n", link.Title, link.URL)
  }
  ```

  ```bash CLI theme={"system"}
  nimble map \
    --url "https://www.example.com" \
    --sitemap include
  ```

  ```bash cURL theme={"system"}
  curl -X POST 'https://sdk.nimbleway.com/v2/map' \
  --header "Authorization: Bearer $NIMBLE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "url": "https://www.example.com",
      "sitemap": "include"
  }'
  ```
</CodeGroup>

## Crawl

Extract content from entire websites:

<CodeGroup>
  ```python Python theme={"system"}
  import os
  from nimble_python import Nimble

  nimble = Nimble(api_key=os.environ["NIMBLE_API_KEY"])

  result = nimble.crawl.run(
      url="https://docs.example.com",
      limit=10
  )

  print(f"Crawl started: {result.crawl_id}")
  print(f"Status: {result.status}")
  ```

  ```typescript TypeScript theme={"system"}
  import Nimble from "@nimble-way/nimble-js";

  const nimble = new Nimble({ apiKey: process.env.NIMBLE_API_KEY });

  const result = await nimble.crawl.run({
    url: "https://docs.example.com",
    limit: 10,
  });

  console.log(`Crawl started: ${result.crawl_id}`);
  console.log(`Status: ${result.status}`);
  ```

  ```go Go theme={"system"}
  result, err := client.Crawl.Run(ctx, nimble.CrawlRunParams{
      URL:   "https://docs.example.com",
      Limit: param.NewOpt(int64(10)),
  })
  if err != nil {
      panic(err)
  }
  fmt.Println("Crawl started:", result.CrawlID)
  fmt.Println("Status:", result.Status)
  ```

  ```bash CLI theme={"system"}
  nimble crawl run \
    --url "https://docs.example.com" \
    --limit 10
  ```

  ```bash cURL theme={"system"}
  curl -X POST 'https://sdk.nimbleway.com/v2/crawl' \
  --header "Authorization: Bearer $NIMBLE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "url": "https://docs.example.com",
      "limit": 10
  }'
  ```
</CodeGroup>

## Web Search Agent

Ask a research question, get a cited answer. See the full flow in the [Web Search Agent quickstart](/nimble-sdk/web-search-agents/quickstart):

<CodeGroup>
  ```python Python theme={"system"}
  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)
  ```

  ```typescript TypeScript theme={"system"}
  import Nimble from "@nimble-way/nimble-js";

  const nimble = new Nimble({ apiKey: process.env.NIMBLE_API_KEY });

  let run = await nimble.agents.run({
    input: "Compare the pricing of Datadog, Grafana Cloud, and New Relic.",
  });
  const agentId = run.web_search_agent_id;

  while (run.is_active) {
    await new Promise((r) => setTimeout(r, 10000));
    run = await nimble.agents.runs.get(run.id, { agent_id: agentId });
  }

  const result = await nimble.agents.runs.result(run.id, { agent_id: agentId });
  if ("output" in result) {
    console.log(result.output.content);
  }
  ```

  ```go Go theme={"system"}
  run, err := client.Agents.Run(ctx, nimble.AgentRunParams{
      Input: "Compare the pricing of Datadog, Grafana Cloud, and New Relic.",
  })
  if err != nil {
      panic(err)
  }

  for run.IsActive {
      time.Sleep(10 * time.Second)
      polled, err := client.Agents.Runs.Get(ctx, run.ID, nimble.AgentRunGetParams{
          AgentID: run.WebSearchAgentID,
      })
      if err != nil {
          panic(err)
      }
      run.IsActive = polled.IsActive
  }

  result, err := client.Agents.Runs.Result(ctx, run.ID, nimble.AgentRunResultParams{
      AgentID: run.WebSearchAgentID,
  })
  if err != nil {
      panic(err)
  }
  fmt.Println(result.Output.Content.OfString)
  ```

  ```bash CLI theme={"system"}
  RUN=$(nimble agents run \
    --input "Compare the pricing of Datadog, Grafana Cloud, and New Relic.")
  RUN_ID=$(echo "$RUN" | jq -r .id)
  AGENT_ID=$(echo "$RUN" | jq -r .web_search_agent_id)

  # repeat while "is_active" is true
  nimble agents:runs get --agent-id "$AGENT_ID" --run-id "$RUN_ID"

  # then fetch the result
  nimble agents:runs result --agent-id "$AGENT_ID" --run-id "$RUN_ID"
  ```

  ```bash cURL theme={"system"}
  curl -X POST 'https://sdk.nimbleway.com/v2/agents/runs' \
  --header "Authorization: Bearer $NIMBLE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "input": "Compare the pricing of Datadog, Grafana Cloud, and New Relic."
  }'
  # => { "id": "task_run_...", "web_search_agent_id": "wsa_...", "status": "queued" }

  # repeat while "is_active" is true
  curl "https://sdk.nimbleway.com/v2/agents/$AGENT_ID/runs/$RUN_ID" \
    --header "Authorization: Bearer $NIMBLE_API_KEY"

  # then fetch the result
  curl "https://sdk.nimbleway.com/v2/agents/$AGENT_ID/runs/$RUN_ID/result" \
    --header "Authorization: Bearer $NIMBLE_API_KEY"
  ```
</CodeGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Choose your integration" icon="compass" href="/integrations/overview">
    Plugin, MCP, SDK, or warehouse: which path fits and how each authenticates
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Full REST documentation for every endpoint
  </Card>

  <Card title="Web Search Agent" icon="bullseye-pointer" href="/nimble-sdk/web-search-agents/overview">
    Efforts, trust reports, and use cases
  </Card>

  <Card title="Rate limits" icon="gauge-high" href="/nimble-sdk/admin/rate-limits">
    Concurrency and throughput per plan
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.