LIBRARY
TypeScript SDK
- Import createClient and call any of 13 endpoints. Typed responses
- validated with Zod.
+ Call all 13 endpoints with typed, Zod-validated responses.
const data = await client.free("google.com")
@@ -43,8 +41,7 @@
CLI
Command Line
- Query the BuiltWith API from your terminal. Supports all 13 methods
- with flags for every parameter.
+ Call all 13 endpoints from your terminal, with a flag for each parameter.
$ builtwith domain example.com
@@ -52,8 +49,7 @@
MCP
AI Assistant
- Give Claude, Cursor, or any MCP client direct access to
- BuiltWith lookups. Add the config and ask.
+ Run BuiltWith lookups from Claude, Cursor, or any MCP client.
npx -y builtwith-mcp
diff --git a/docs/cli.md b/docs/cli.md
index 136f02c..63fcfa7 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -1,6 +1,6 @@
# Command Line
-Query the BuiltWith API from your terminal. All 13 methods with flags for every parameter.
+Call all 13 BuiltWith API methods from your terminal. Each parameter has a flag.
## Installation
@@ -11,21 +11,21 @@ brew install zcaceres/tap/builtwith
# npm (global)
npm install -g builtwith-api
-# Or run without installing
+# Run without installing
npx --package builtwith-api builtwith free example.com --api-key YOUR_KEY
```
-Standalone binaries are also available on the [GitHub Releases](https://github.com/zcaceres/builtwith-api/releases) page.
+[GitHub Releases](https://github.com/zcaceres/builtwith-api/releases) also provides standalone binaries.
## Output Format
-By default, output is JSON. Use `--table` for a human-readable format:
+Output defaults to JSON. Use `--table` for readable terminal output:
```bash
builtwith free example.com --table
```
-The `--table` flag renders nested data as aligned columns and key-value pairs instead of raw JSON. JSON output is still the default for piping and scripting.
+`--table` renders nested data as columns and key-value pairs. Use the default JSON for pipes and scripts.
## Authentication
diff --git a/docs/guide/index.md b/docs/guide/index.md
index 27047dd..f7d52fb 100644
--- a/docs/guide/index.md
+++ b/docs/guide/index.md
@@ -1,16 +1,16 @@
# Introduction
-**builtwith-api** is a typed wrapper around the [BuiltWith API](https://api.builtwith.com/) that works as a library, CLI, and MCP server.
+**builtwith-api** provides typed access to the [BuiltWith API](https://api.builtwith.com/) through a library, CLI, and MCP server.
## What is BuiltWith?
-BuiltWith tracks the technologies used by websites across the internet — frameworks, analytics, CMS platforms, e-commerce tools, CDNs, and more. Their API gives you programmatic access to this intelligence.
+BuiltWith tracks the frameworks, analytics, CMS platforms, e-commerce tools, CDNs, and other technologies used by websites. Its API makes this data available to code.
## Three ways to use it
### Library
-Import `createClient` and call methods directly. Responses are validated with Zod and fully typed.
+Import `createClient` and call any of the 13 methods. Zod validates each typed response.
```ts
import { createClient } from "builtwith-api";
@@ -21,7 +21,7 @@ const profile = await client.free("example.com");
### CLI
-Query from your terminal. Output is JSON, ready for piping.
+Run lookups from your terminal. JSON output works with pipes and scripts.
```bash
builtwith free example.com
@@ -30,7 +30,7 @@ builtwith domain example.com --onlyLiveTechnologies
### MCP Server
-Connect BuiltWith to AI tools that support the Model Context Protocol.
+Add BuiltWith tools to any MCP client.
```json
{
diff --git a/docs/guide/installation.md b/docs/guide/installation.md
index 3638f34..234e99b 100644
--- a/docs/guide/installation.md
+++ b/docs/guide/installation.md
@@ -28,7 +28,7 @@ brew install zcaceres/tap/builtwith
## CLI (no install)
-Run the CLI directly with `npx`:
+Run the CLI with `npx`:
```bash
npx --package builtwith-api builtwith free example.com --api-key YOUR_KEY
@@ -43,13 +43,13 @@ builtwith free example.com
## MCP Server
-The MCP server is a separate package. Install standalone:
+The MCP server uses the separate `builtwith-mcp` package. Install it globally:
```bash
npm install -g builtwith-mcp
```
-Or use directly with `npx`:
+Or run it with `npx`:
```bash
npx -y builtwith-mcp
@@ -57,7 +57,7 @@ npx -y builtwith-mcp
## Standalone binaries
-Pre-compiled binaries are available on the [GitHub Releases](https://github.com/zcaceres/builtwith-api/releases) page for:
+[GitHub Releases](https://github.com/zcaceres/builtwith-api/releases) provides precompiled binaries for:
- Linux x64 / ARM64
- macOS x64 / ARM64 (Apple Silicon)
@@ -65,7 +65,7 @@ Pre-compiled binaries are available on the [GitHub Releases](https://github.com/
## API Key
-You need a BuiltWith API key. Get one at [api.builtwith.com](https://api.builtwith.com/).
+Get a BuiltWith API key at [api.builtwith.com](https://api.builtwith.com/).
Set it as an environment variable:
@@ -73,4 +73,4 @@ Set it as an environment variable:
export BUILTWITH_API_KEY=your-key-here
```
-Or pass it directly via `--api-key` (CLI/MCP) or as the first argument to `createClient()` (library).
+You can also use `--api-key` with the CLI or MCP server, or pass the key to `createClient()`.
diff --git a/docs/guide/library.md b/docs/guide/library.md
index fe1e9ea..ab39fe0 100644
--- a/docs/guide/library.md
+++ b/docs/guide/library.md
@@ -1,17 +1,17 @@
# Library
-A typed TypeScript wrapper for the BuiltWith API with Zod-validated responses and full ESM support.
+Use the BuiltWith API from TypeScript with typed, Zod-validated responses. The package supports ESM.
## Quick Start
-Create a client with your API key. All methods return typed, Zod-validated responses.
+Create a client with your API key, then call any method.
```ts
import { createClient } from "builtwith-api";
const client = createClient(process.env.BUILTWITH_API_KEY!);
-// Free lookup — basic tech profile
+// Free lookup: basic tech profile
const profile = await client.free("google.com");
// Full domain lookup with options
@@ -24,7 +24,7 @@ const details = await client.domain("example.com", {
### `free(lookup)`
-Basic technology profile for a single domain. Available on free API plans.
+A basic technology profile for one domain. This method works with free API plans.
```ts
const profile = await client.free("stripe.com");
@@ -66,7 +66,7 @@ const filtered = await client.domain("example.com", {
### `domainLive(lookup)`
-Real-time technology scan. Same response shape as `domain()`, but scans the site live.
+Scans a site in real time and returns the same response shape as `domain()`.
```ts
const live = await client.domainLive("example.com");
@@ -93,7 +93,7 @@ const recent = await client.lists("React", {
### `trends(technology, params?)`
-Technology adoption trends and coverage data.
+Returns adoption trends and coverage data for a technology.
```ts
const trends = await client.trends("jQuery");
@@ -102,7 +102,7 @@ const trends = await client.trends("jQuery");
### `relationships(lookup)`
-Find related domains that share identifiers (analytics IDs, ad accounts, etc.).
+Find domains that share identifiers such as analytics IDs or ad accounts.
```ts
const related = await client.relationships("example.com");
@@ -111,7 +111,7 @@ const related = await client.relationships("example.com");
### `keywords(lookup)`
-Get SEO keywords associated with domains.
+Get SEO keywords for a domain.
```ts
const kw = await client.keywords("example.com");
@@ -120,7 +120,7 @@ const kw = await client.keywords("example.com");
### `trust(lookup, params?)`
-Domain trust and verification scoring.
+Get trust and verification scores for a domain.
```ts
const trust = await client.trust("example.com");
@@ -149,7 +149,7 @@ const comOnly = await client.companyToUrl("Google", {
### `tags(lookup)`
-Get tracking and analytics tags found on a domain.
+Get tracking and analytics tags for a domain.
```ts
const tags = await client.tags("example.com");
@@ -165,7 +165,7 @@ const recs = await client.recommendations("example.com");
### `redirects(lookup)`
-Get inbound and outbound redirect chains.
+Get a domain's inbound and outbound redirect chains.
```ts
const redirects = await client.redirects("example.com");
@@ -183,7 +183,7 @@ const products = await client.product("wireless headphones");
## Response Format
-By default, responses are JSON (parsed and validated). You can request other formats:
+Responses default to parsed, validated JSON. To request another format:
```ts
const client = createClient(API_KEY, { responseFormat: "xml" });
@@ -212,14 +212,14 @@ try {
```
::: tip
-BuiltWith sometimes returns errors as HTTP 200 with a JSON `{"Errors":[...]}` body. The client detects this and throws a clear error message instead of a confusing Zod validation failure.
+BuiltWith sometimes returns a JSON `{"Errors":[...]}` body with HTTP 200. The client detects it and throws the API error instead of a Zod validation error.
:::
## Rate Limits
BuiltWith enforces two types of limits:
-**Per-second throttle** — Maximum 1 request per second. Exceeding this returns HTTP 429. Space out concurrent calls or add a delay between requests:
+**Per-second throttle:** One request per second. Extra requests return HTTP 429. Space out calls or add a delay:
```ts
function delay(ms: number) {
@@ -232,8 +232,8 @@ for (const domain of domains) {
}
```
-**Credit-based quota** — Each API plan has a credit allocation. Every call consumes credits from your plan balance. Check your remaining credits via the [BuiltWith dashboard](https://api.builtwith.com/) or in Product API responses (`credits`, `used`, `remaining` fields).
+**Credit quota:** Each call uses credits from your API plan. Check the [BuiltWith dashboard](https://api.builtwith.com/) or the Product API's `credits`, `used`, and `remaining` fields.
::: tip
-The `free` endpoint has a separate, more generous rate limit. Use it for basic lookups when you don't need full domain data.
+The `free` endpoint has its own, higher rate limit. Use it when you don't need full domain data.
:::
diff --git a/docs/mcp.md b/docs/mcp.md
index f6d91b4..ed8fbff 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -1,16 +1,10 @@
# MCP Server
-Expose BuiltWith API lookups as MCP tools for Claude Desktop, Cursor, and any MCP-compatible AI client.
+Add BuiltWith API tools to Claude Desktop, Cursor, or any MCP client.
## How It Works
-The MCP server exposes all 13 BuiltWith API methods as tools. Your AI assistant can call them directly during conversation.
-
-**1. Configure** — Add the server config to your AI client's settings file.
-
-**2. Ask** — "What technologies does stripe.com use?" — your assistant calls the right tool.
-
-**3. Get Results** — Structured data returned inline. No copy-pasting from browser tabs.
+The server turns all 13 BuiltWith API methods into tools your MCP client can call.
## Setup
@@ -70,7 +64,7 @@ Add to your Claude Code settings:
### Other Clients
-Any MCP-compatible client can use the server. The general pattern:
+For other MCP clients, use:
- **Command:** `npx`
- **Args:** `["-y", "builtwith-mcp"]`
@@ -95,11 +89,11 @@ For a local install instead of `npx`:
npm install -g builtwith-mcp
```
-Then use `builtwith-mcp` as the command directly.
+Then set the command to `builtwith-mcp`.
## Available Tools
-All tools are prefixed with `builtwith_` and accept typed input schemas validated by Zod.
+Tool names start with `builtwith_`. Zod validates their inputs.
| Tool | Input | Description |
|------|-------|-------------|
@@ -127,7 +121,7 @@ npx @modelcontextprotocol/inspector -- npx -y builtwith-mcp --api-key YOUR_KEY
## Example prompts
-Once configured, you can ask your AI assistant things like:
+Example prompts:
- "What technologies does stripe.com use?"
- "Find all domains using Shopify"