# BuiltWith API (LLMs)

This file is a compact reference for AI agents using the BuiltWith API.

## Quick Start
- Base URL: `https://api.builtwith.com`
- Most REST endpoints are `GET` requests and require `KEY=YOUR_KEY`.
- Start account-aware agents with:
  - WhoAmI: `https://api.builtwith.com/whoamiv1/api.json?KEY=YOUR_KEY`
  - Usage: `https://api.builtwith.com/usagev2/api.json?KEY=YOUR_KEY`
- Use `KEY=bw-...` temporary tokens from Agent Device-Code Authorization the same way as normal API keys.

## Account and Usage

### WhoAmI
- Endpoint: `GET /whoamiv1/api.json?KEY=YOUR_KEY`
- Credits: no API credits used.
- Purpose: discover account limits, credit costs, privacy flags, max batch sizes, supported formats, and endpoint inventory.
- Important fields:
  - `account.max_batch_size.domain_lookup`: max domains in normal Domain API lookup batches.
  - `account.max_batch_size.domain_bulk_submit`: max domains in Bulk Domain API jobs.
  - `rate_limits`: current requests-per-second and concurrency guidance.
  - `credits.costs`: per-endpoint credit cost hints.
  - `privacy.flags_supported`: supported privacy flags such as `NOPII`.

Example response shape:
```json
{
  "account": {
    "email": "user@example.com",
    "plan": "pro",
    "plan_expiry": "2026-12-31T00:00:00Z",
    "max_batch_size": {
      "domain_lookup": 16,
      "domain_bulk_submit": 5000
    }
  },
  "rate_limits": {
    "requests_per_second": 10,
    "concurrency": 8
  },
  "credits": {
    "purchased": 200000,
    "used": 1234,
    "remaining": 198766
  },
  "privacy": {
    "pii_allowed": true,
    "flags_supported": ["NOPII"]
  }
}
```

### Usage
- Endpoint: `GET /usagev2/api.{json|xml}?KEY=YOUR_KEY`
- Credits: no API credits used.
- Purpose: quick credit balance check.

Example JSON response:
```json
{
  "used": 1234,
  "purchased": 200000,
  "remaining": 198766
}
```

API responses also include credit headers where available:
- `X-API-CREDITS-AVAILABLE`
- `X-API-CREDITS-USED`
- `X-API-CREDITS-REMAINING`

## REST Endpoints
- Domain API: `/v22/api.{json|xml|csv}` - technology and metadata for a domain.
  - Example: `https://api.builtwith.com/v22/api.json?KEY=YOUR_KEY&LOOKUP=example.com`
  - Optional flags include `NOPII`, `NOMETA`, `NOATTR`, `FDRANGE`, `LDRANGE`, `LIVEONLY`, `HIDETEXT`, `HIDEDL`, `IP`, and `TRUST`.
- Change API: `/change1/api.json` - technology additions and removals for one or more domains.
  - Example: `https://api.builtwith.com/change1/api.json?KEY=YOUR_KEY&LOOKUP=example.com&SINCE=last+month`
  - `SINCE` accepts natural language dates such as `last+month`; default is 3 months.
- Lists API: `/lists12/api.{json|xml|txt|csv|tsv}` - sites using a technology.
  - Example: `https://api.builtwith.com/lists12/api.json?KEY=YOUR_KEY&TECH=Shopify`
  - Pagination: use `OFFSET` with the previous response's `NextOffset`; `END` means no more pages.
  - Common optional filters: `COUNTRY=US,CA`, `SINCE=30+days+ago`, `ALL=yes`, `META=yes`, `OTHERTECHS=Google-Analytics,Meta-Pixel`.
  - Numeric filters use `number|operator`, where operator is `EQ`, `LT`, `LTE`, `GT`, or `GTE`; if omitted, `GTE` is used.
  - Spend filter: `SPEND=100|GT` filters monthly technology spend.
  - Attribute filters are combined with AND, so `REVENUE=100000|GT&EMPLOYEES=50|GTE` requires both attributes to match.
  - Attribute filter keys: `REVENUE` (estimated ecommerce sales revenue), `SKU` (product count), `FOLLOWERS`, `EMPLOYEES`, `SITEMAP`, `PAGERANK`, `BWRANK`, `TRANCO`, `MAJESTIC`, `BWS`, `ECAT` (ecommerce category id), `AIM` (AI maturity), `AIO` (AI openness), `AIR` (AI readiness), `AIV` (AI visibility).
  - Example filtered request: `https://api.builtwith.com/lists12/api.json?KEY=YOUR_KEY&TECH=Shopify&REVENUE=100000|GT&SPEND=100|GTE&COUNTRY=US`
- Ask API: `/ask1/api.{json|xml|txt|csv|tsv}` - natural language website list lookups.
  - Example sample request: `https://api.builtwith.com/ask1/api.json?KEY=YOUR_KEY&QUERY=Magento%20websites%20in%20Spain`
  - `QUERY` accepts normal URL-encoded spaces or dash-separated words, for example `Magento-websites-in-Spain`.
  - Each lookup uses 1 API credit and normal requests always return a sample.
  - Use `COMMIT=true` to create and run a full Ask report, returning up to 1000 results ordered by sequence.
  - Pagination: use `NEXTOFFSET` with the previous response's `NextOffset`; `END` means no more pages.
  - Optional: `META=yes` includes metadata. Results use Lists API result attributes, but Ask does not return `LOS`.
- Relationships API: `/rv4/api.{json|xml|csv|tsv}` - relationships between sites.
  - Example: `https://api.builtwith.com/rv4/api.json?KEY=YOUR_KEY&LOOKUP=example.com`
- Free API: `/free1/api.{json|xml}` - summary counts and update ranges for technology groups.
  - Example: `https://api.builtwith.com/free1/api.json?KEY=YOUR_KEY&LOOKUP=example.com`
- Company to URL API: `/ctu3/api.{json|xml}` - discover domains from company names.
  - Example: `https://api.builtwith.com/ctu3/api.json?KEY=YOUR_KEY&COMPANY=Example`
- Tags API: `/tag1/api.{json|xml}` - domains related to IPs and site attributes.
  - Example: `https://api.builtwith.com/tag1/api.json?KEY=YOUR_KEY&LOOKUP=IP-1.2.3.4`
- Recommendations API: `/rec1/api.{json|xml}` - related technology recommendations for a domain.
  - Example: `https://api.builtwith.com/rec1/api.json?KEY=YOUR_KEY&LOOKUP=example.com`
- Redirects API: `/redirect1/api.{json|xml}` - redirect history.
  - Example: `https://api.builtwith.com/redirect1/api.json?KEY=YOUR_KEY&LOOKUP=example.com`
- Keywords API: `/kw2/api.{json|xml}` - keywords for a domain.
  - Example: `https://api.builtwith.com/kw2/api.json?KEY=YOUR_KEY&LOOKUP=example.com`
- Keyword Search API: `/kws1/api.{json|csv}` - websites containing a keyword.
  - Example: `https://api.builtwith.com/kws1/api.json?KEY=YOUR_KEY&KEYWORD=perfume`
  - Optional: `LIMIT` (16-1000, default 100), `OFFSET` from the previous page's `NextOffset`.
- Trends API: `/trends/v6/api.{json|xml}` - technology trend metadata.
  - Example: `https://api.builtwith.com/trends/v6/api.json?KEY=YOUR_KEY&TECH=Shopify`
- Product API: `/productv1/api.json` - websites selling products.
  - Example: `https://api.builtwith.com/productv1/api.json?KEY=YOUR_KEY&QUERY=Adidas%20Yeezy`
- Trust API: `/trustv1/api.{json|xml}` - trust and fraud signals.
  - Example: `https://api.builtwith.com/trustv1/api.json?KEY=YOUR_KEY&LOOKUP=example.com`
- Vector Search API: `/vector/v1/api.{json|xml|csv}` - semantic search across technologies and categories.
  - Example: `https://api.builtwith.com/vector/v1/api.json?KEY=YOUR_KEY&QUERY=react+framework`
  - Optional: `LIMIT` (default 10, max 100). Uses 1 API credit per search.

## Bulk Domain API
Use this for high-volume Domain API lookups.

### Submit
- Endpoint: `POST /v22/domain/bulk?KEY=YOUR_KEY`
- Content-Type: `application/json`
- Max lookups: use WhoAmI `account.max_batch_size.domain_bulk_submit` (currently 5000 in the API response).

Request body:
```json
{
  "lookups": ["example.com", "builtwith.com"],
  "options": {
    "noMeta": false,
    "noPii": true,
    "hideText": false,
    "hideDL": false,
    "liveOnly": false
  }
}
```

Small batches may return the normal Domain API result synchronously. Larger batches return `202`:
```json
{
  "job_id": "00000000-0000-0000-0000-000000000000",
  "status": "queued",
  "count": 250,
  "sync_max": 32
}
```

### Poll Status
- Endpoint: `GET /v22/domain/bulk/{job_id}?KEY=YOUR_KEY`

Example response:
```json
{
  "job_id": "00000000-0000-0000-0000-000000000000",
  "status": "completed",
  "created_utc": "2026-02-03T12:00:00Z",
  "completed_utc": "2026-02-03T12:01:15Z",
  "result_url": "/v22/domain/bulk/00000000-0000-0000-0000-000000000000/result",
  "count": 250
}
```

### Retrieve Results
- Endpoint: `GET /v22/domain/bulk/{job_id}/result?KEY=YOUR_KEY`
- Response: Domain API JSON result.
- Important: results are deleted after first successful access, so store the response if you need to reuse it.

## Live Feed API (WebSocket)
- Requires an active plan.
- Trial/preview users receive redacted domain names.
- Supports automatic reconnection.
- Connect to all new detections: `wss://sync.builtwith.com/wss/new?KEY=YOUR_KEY`
- Connect and auto-subscribe to a technology: `wss://sync.builtwith.com/wss/channel/Shopify?KEY=YOUR_KEY`

Commands:
```json
{"action":"subscribe","channel":"Shopify"}
{"action":"subscribe","channel":"new"}
{"action":"subscribe","channel":"new-historical"}
{"action":"subscribe","channel":"premium"}
{"action":"unsubscribe","channel":"Shopify"}
{"action":"list_subscriptions"}
```

## Agent Device-Code Authorization
Allows an AI agent to obtain a temporary `bw-` prefixed API token without asking the user to paste an API key.

1. Start:
   - `POST https://api.builtwith.com/agent-auth/start`
   - No body and no API key required.

Response:
```json
{
  "device_code": "11c3dd0e3a014816a5c62a04b0f00097",
  "verification_uri": "https://api.builtwith.com/device-auth?code=11c3dd0e3a014816a5c62a04b0f00097",
  "expires_in": 900,
  "interval": 5
}
```

2. Send the user to `verification_uri` in a browser where they can log in to BuiltWith and approve access.
3. Poll:
   - `POST https://api.builtwith.com/agent-auth/token`
   - Body: `{"device_code":"<device_code>"}`
   - Poll no faster than `interval` seconds.

Token responses:
```json
{"error":"authorization_pending"}
{"access_token":"bw-...","token_type":"bearer","expires_in":86400}
{"error":"access_denied"}
{"error":"expired_token"}
```

Denied and expired responses use HTTP 400. Always parse the response body even on 4xx.

Use approved tokens as `KEY=bw-...` on REST endpoints:
```text
https://api.builtwith.com/v22/api.json?KEY=bw-11c3dd0e3a014816a5c62a04b0f00097&LOOKUP=example.com
```

## Agent Payment API
- Base URL: `https://payments.builtwith.com`
- Auth: `Authorization: Bearer YOUR_KEY` or `?KEY=YOUR_KEY`
- Setup: `https://payments.builtwith.com/agent-payment-api-config`

Endpoints:
- `GET /v1/billing/api-discovery?KEY=YOUR_KEY` - returns `credits_total`, `credits_used`, `credits_available`.
- `GET /v1/billing/api-configuration?KEY=YOUR_KEY` - returns spending limits and monthly purchase status.
- `POST /v1/billing/api-purchase` - body `{"credits":2000}`; minimum 2000 credits.

## MCP Server
- Discovery manifest: `https://builtwith.com/.well-known/mcp.json`
- Hosted MCP endpoint: `https://api.builtwith.com/mcp`
- Transport: streamable HTTP.
- Auth: `Authorization: Bearer YOUR_BUILTWITH_API_KEY`
- Docs/source: `https://github.com/builtwith/builtwith-mcp`
- Note: `https://api.builtwith.com/.well-known/mcp.json` redirects to the BuiltWith `.well-known` host.

Example MCP client config:
```json
{
  "mcpServers": {
    "builtwith": {
      "url": "https://api.builtwith.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_BUILTWITH_API_KEY"
      }
    }
  }
}
```

## CLI
- GitHub: `https://github.com/builtwith/builtwith-official-cli`
- Install: `npm install -g builtwith-official-cli`
- Example: `bw domain lookup example.com --key YOUR_KEY`
- Supports JSON, table, CSV, dry-run mode, and MCP stdio server (`bw mcp`).

## Common Agent Workflows
- Account-aware startup: call WhoAmI -> call Usage -> choose endpoints based on remaining credits, per-endpoint costs, privacy flags, and max batch sizes.
- Research a company: Company to URL API (`ctu3`) -> choose likely domain -> Domain API (`v22`) -> Relationships API (`rv4`) -> optional Trust API (`trustv1`) and Redirects API (`redirect1`).
- Research a domain stack: Free API (`free1`) for quick counts -> Domain API (`v22`) for full stack -> Change API (`change1`) for recent technology changes.
- Find prospects by technology or natural language audience: Vector Search API (`vector/v1`) or known tech name -> Lists API (`lists12`), or Ask API (`ask1`) for natural language criteria -> enrich selected domains with Domain API (`v22`).
- Product or ecommerce research: Product API (`productv1`) -> enrich shops with Domain API (`v22`) -> check Trust API (`trustv1`).
- Relationship investigation: Domain API (`v22`) to identify technologies and metadata -> Relationships API (`rv4`) for linked sites -> Tags API (`tag1`) for IP or attribute expansion.
- High-volume enrichment: WhoAmI to confirm `domain_bulk_submit` size -> Bulk Domain submit -> poll status -> retrieve one-time result.

## Compact Response Shapes
Full sample payloads are available under `https://api.builtwith.com/samples/*.json`. Use these shapes for field orientation.

### Domain API (`/samples/domain_api_v22.json`)
```json
{
  "Results": [
    {
      "Lookup": "example.com",
      "Result": {
        "Paths": [
          {
            "Technologies": [
              {
                "Name": "nginx",
                "Tag": "Web Server",
                "Categories": ["Web Server"],
                "FirstDetected": 1700000000000,
                "LastDetected": 1760000000000,
                "IsPremium": "No"
              }
            ]
          }
        ],
        "Spend": 11390
      },
      "Meta": {
        "CompanyName": "Example Inc",
        "Country": "US"
      }
    }
  ],
  "Errors": []
}
```

### Change API (`/samples/change_v1.json`)
```json
{
  "Results": [
    {
      "Lookup": "example.com",
      "Changes": {
        "summary": "example.com added Shopify.",
        "events": [
          {
            "type": "technology_added",
            "technology": "Shopify",
            "tag": "shop",
            "first_seen_utc": "2026-02-24T00:00:00Z",
            "importance": "medium"
          }
        ]
      }
    }
  ]
}
```

### Company to URL API (`/samples/ctu_api_v3.json`)
```json
[
  {
    "Domain": "example.com",
    "CompanyName": "Example",
    "Spend": 1024,
    "Country": "US",
    "Socials": ["linkedin.com/company/example"]
  }
]
```

### Relationships API (`/samples/relationship_api_v4.json`)
```json
{
  "Relationships": [
    {
      "Domain": "example.com",
      "Identifiers": [
        {
          "Value": "GTM-ABC123",
          "Type": "GTM",
          "Matches": [
            {
              "Domain": "related-example.com",
              "Overlap": true
            }
          ]
        }
      ]
    }
  ],
  "more_results": true,
  "next_skip": 500
}
```

### Lists API (`/samples/list_api_v12.json`)
```json
{
  "NextOffset": "opaque-next-offset",
  "Results": [
    {
      "D": "example-shop.com",
      "FI": 1725494400,
      "LI": 1767657600,
      "Country": "US"
    }
  ]
}
```

### Ask API
```json
{
  "Explanation": "Matched websites using Magento with a Spain location signal.",
  "NextOffset": "opaque-next-offset-or-END",
  "Results": [
    {
      "D": "example-shop.es",
      "FI": 1725494400,
      "LI": 1767657600,
      "Country": "ES",
      "Q": 565,
      "S": 323
    }
  ]
}
```

### Keyword Search API (`/samples/keyword_search_api_v1.json`)
```json
{
  "Keyword": "perfume",
  "Domains": ["example-store.com"],
  "NextOffset": "example-store.com"
}
```

### Recommendations API (`/samples/recommendations_api_v1.json`)
```json
[
  {
    "Domain": "example.com",
    "Recommendations": [
      {
        "name": "Zendesk",
        "tag": "mx",
        "categories": [],
        "stars": 4,
        "match": 0.126
      }
    ]
  }
]
```

### Redirects API (`/samples/redirect_apiv_v1.json`)
```json
{
  "Lookup": "example.com",
  "Inbound": [
    {
      "Domain": "old-example.com",
      "FirstDetected": "2019-09-03T00:00:00Z",
      "LastDetected": "2021-12-01T00:00:00Z"
    }
  ],
  "Outbound": []
}
```

### Product API (`/samples/product_api_v1.json`)
```json
{
  "query": "Adidas Yeezy",
  "is_more": true,
  "next_page": "/productv1/api.json?KEY=[your-key]&QUERY=Adidas Yeezy&PAGE=1&LIMIT=50",
  "shops": [
    {
      "Domain": "example-shop.com",
      "Products": [
        {
          "Title": "Adidas Yeezy",
          "Url": "adidas-yeezy",
          "Price": 129.95
        }
      ]
    }
  ]
}
```

### Trust API (`/samples/trust_api_v1.json`)
```json
{
  "Domain": "example.com",
  "DBRecord": {
    "PremiumTechs": 21,
    "LiveTechs": true,
    "PaymentOptions": true,
    "Ecommerce": false,
    "Parked": false,
    "Spend": 11284
  },
  "Status": 0
}
```

### Vector Search API
```json
{
  "Query": "react framework",
  "Results": [
    {
      "Type": "tech",
      "Name": "React",
      "Tag": "javascript",
      "Score": 0.9812,
      "Categories": ["JavaScript Library", "Framework"]
    }
  ],
  "Errors": []
}
```