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:
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:
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:
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
Get clean HTML, markdown, or structured data from any URL. Supports JavaScript rendering, stealth mode, browser actions, and more.
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. Search
Perform real-time web searches and get structured results:
const result = await nimble.search({
query: "best web scraping tools",
country: "US",
});
console.log(result);
Map
Discover all URLs within a domain or sitemap:
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:
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:
const result = await nimble.agent.run({
agent: "amazon_pdp",
params: {
asin: "B08N5WRWNW",
},
});
console.log(result);
Error Handling
The SDK throws typed APIError subclasses for failed requests:
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 Class | HTTP Status | When it occurs |
|---|
BadRequestError | 400 | Invalid request parameters |
AuthenticationError | 401 | Invalid or missing API key |
PermissionDeniedError | 403 | Insufficient account permissions |
NotFoundError | 404 | Resource not found |
RateLimitError | 429 | Request rate exceeded |
InternalServerError | 500+ | Server-side error |
Configuration
Timeouts & Retries
The SDK retries automatically on connection errors and server failures. Defaults: 2 retries, 3-minute timeout.
// 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:
Or configure programmatically using any compatible logger (pino, winston, consola, etc.):
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:
// 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:
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
