Skip to main content
Install the Nimble JavaScript/TypeScript library to interact with the Nimble API from Node.js, Deno, Bun, Cloudflare Workers, and modern browsers. All methods are async and return typed responses.

​
Installation

npm install @nimble-way/sdk
Requires Node.js 20 LTS+ (also supports Deno v1.28+, Bun 1.0+, and Cloudflare Workers). Never hardcode your API key — use environment variables.

​
Setup

Initialize the client with your API key:
TypeScript
import Nimble from "@nimble-way/nimble-js";

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

​
Quick Start

Extract content from a URL in one call:
TypeScript
import Nimble from "@nimble-way/nimble-js";

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

const result = await nimble.extract({
  url: "https://www.example.com",
  render: true,
});

console.log(result.task_id);

​
TypeScript Types

The SDK ships full TypeScript definitions for all request parameters and responses, with IDE autocompletion:
TypeScript
import Nimble from "@nimble-way/nimble-js";

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

const params: Nimble.ExtractParams = {
  url: "https://www.example.com",
  render: true,
};

const result: Nimble.ExtractResponse = await nimble.extract(params);
console.log(result.task_id);

​
Core Methods

​
Extract

Get clean HTML, markdown, or structured data from any URL. Supports JavaScript rendering, stealth mode, browser actions, and more.
TypeScript
const result = await nimble.extract({
  url: "https://www.example.com",
  render: true,
});

console.log(result.task_id);
See the Extract docs for the full parameter list — geo-targeting, output formats, parsing schemas, and more.
Perform real-time web searches and get structured results:
TypeScript
const result = await nimble.search({
  query: "best web scraping tools",
  country: "US",
});

console.log(result);

​
Map

Discover all URLs within a domain or sitemap:
TypeScript
const result = await nimble.map({
  URL: "https://www.example.com",
  sitemap: "only",
});

console.log(result);

​
Crawl

Recursively crawl and extract an entire website at scale:
TypeScript
const result = await nimble.crawl.run({
  url: "https://www.example.com",
  limit: 100,
});

console.log(result);

​
Agents

Run pre-built agents for structured data from popular platforms:
TypeScript
const result = await nimble.agent.run({
  agent: "amazon_pdp",
  params: {
    asin: "B08N5WRWNW",
  },
});

console.log(result);
Browse the full agent catalog in the Agent Gallery.

​
Error Handling

The SDK throws typed APIError subclasses for failed requests:
TypeScript
import Nimble, { APIError } from "nimble-js";

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

try {
  const result = await nimble.extract({ url: "https://www.example.com" });
} catch (error) {
  if (error instanceof APIError) {
    console.log(`Status: ${error.status}`);
    console.log(`Message: ${error.message}`);
  }
  throw error;
}
Error ClassHTTP StatusWhen it occurs
BadRequestError400Invalid request parameters
AuthenticationError401Invalid or missing API key
PermissionDeniedError403Insufficient account permissions
NotFoundError404Resource not found
RateLimitError429Request rate exceeded
InternalServerError500+Server-side error

​
Configuration

​
Timeouts & Retries

The SDK retries automatically on connection errors and server failures. Defaults: 2 retries, 3-minute timeout.
TypeScript
// Configure globally
const nimble = new Nimble({
  apiKey: process.env.NIMBLE_API_KEY,
  maxRetries: 3,
  timeout: 60 * 1000, // 60 seconds in ms
});

// Override per-request
const result = await nimble.extract(
  { url: "https://www.example.com" },
  { maxRetries: 0 },
);

​
Logging

Control log verbosity via environment variable: 
export NIMBLE_LOG=debug
Or configure programmatically using any compatible logger (pino, winston, consola, etc.):
TypeScript
import Nimble from "@nimble-way/nimble-js";
import pino from "pino";

const nimble = new Nimble({
  apiKey: process.env.NIMBLE_API_KEY,
  logger: pino(),
  logLevel: "debug",
});

​
Advanced

​
Raw Response Access

Access HTTP headers and status alongside the parsed response:
TypeScript
// Get just the raw Response object
const raw = await nimble
  .extract({ url: "https://www.example.com" })
  .asResponse();
console.log(raw.headers.get("x-request-id"));

// Get both parsed result and raw response
const { data, response } = await nimble
  .extract({ url: "https://www.example.com" })
  .withResponse();

console.log(response.headers.get("x-request-id"));
console.log(data.task_id);

​
Custom Fetch / Proxy

Provide a custom fetch implementation or configure proxies for Node.js, Bun, and Deno:
TypeScript
import Nimble from "@nimble-way/nimble-js";

const nimble = new Nimble({
  apiKey: process.env.NIMBLE_API_KEY,
  fetchOptions: {
    proxy: "http://proxy.example.com:8080",
  },
});

​
MCP Server

The SDK includes a built-in MCP Server for AI assistant integrations, enabling API exploration and request testing directly from tools like Claude.

​
Next Steps

API Reference

Full REST API documentation for all endpoints

Extract

Rendering, formats, stealth mode, and more

Search

Real-time web search with structured results

Agents

Pre-built extraction agents for popular platforms