# BuiltWith API (LLMs - Full Reference)

This is the full reference for AI agents using the BuiltWith API. A compact version is available at `https://api.builtwith.com/llms.txt`.

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

## Authentication
- REST endpoints: pass your API key as the `KEY` query parameter.
- MCP endpoint and Agent Payment API: pass your API key as `Authorization: Bearer YOUR_KEY` (the Payment API also accepts `?KEY=YOUR_KEY`).
- Temporary agent tokens (`bw-` prefixed, from Agent Device-Code Authorization) work anywhere a normal key works.

## Rate Limits
- Maximum 8 concurrent requests and maximum 10 requests per second. Exceeding these limits returns HTTP `429`.
- Contact BuiltWith about dedicated endpoint solutions for rate limit removal.

## Response Headers
Responses include credit and rate limit headers where available:
- `X-API-CREDITS-AVAILABLE` - lookup credits available under your key.
- `X-API-CREDITS-USED` - lookup credits you have used.
- `X-API-CREDITS-REMAINING` - lookup credits remaining.
- `X-RATELIMIT-CURRENT-CONCURRENT` - concurrent requests you are currently making.
- `X-RATELIMIT-CURRENT-PERSECOND` - requests per second you are currently making.
- `X-RATELIMIT-LIMIT-CONCURRENT` - maximum concurrent requests before 429 errors (currently 8).
- `X-RATELIMIT-LIMIT-PERSECOND` - maximum requests per second before 429 errors (currently 10).

## Errors
- Treat any non-200 response as an error; well-formed error bodies cannot be guaranteed for server-level failures.
- Well-formed errors appear in an `Errors` array; the `Lookup` property is `null` (JSON) or omitted (XML) when the error is server related.
- All potential well-formed error codes: `https://api.builtwith.com/errorCodes`

## Special Domains
BuiltWith maintains two domain lists useful when preparing lookups (JSON, XML or TXT):
- Ignore list - domains BuiltWith does not index (blocked, misleading technologies, or user-generated-content subdomains): `https://api.builtwith.com/ignoresv1/api.json`
- BuiltWith Suffix list - based on the Public Suffix List with additional entries where subdomains should be treated as top-level domains: `https://api.builtwith.com/suffixv1/api.json`

## Credit Costs
From WhoAmI `credits.costs` (verify live values via WhoAmI):
- 1 credit per lookup: Domain API, Bulk Domain (per domain), Relationships, Company to URL, Tags, Recommendations, Redirects, Keywords, Product, Trust, Vector Search, Ask (per query). VAT API uses 1 credit only when a domain returns registration data.
- 0 credits: Free API, Trends API, WhoAmI, Usage, MCP API (rate limited to 1 request/sec per API key instead).
- Subscription required: Lists API, Keyword Search API.

## 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.email`, `account.plan`, `account.plan_expiry`.
  - `account.max_batch_size.domain_lookup`: max domains in normal Domain API lookup batches (currently 16).
  - `account.max_batch_size.domain_bulk_submit`: max domains in Bulk Domain API jobs (currently 5000).
  - `rate_limits`: current requests-per-second and concurrency guidance.
  - `credits.purchased`, `credits.used`, `credits.remaining` and `credits.costs`: per-endpoint credit cost hints.
  - `privacy.pii_allowed`, `privacy.default_privacy_mode`, `privacy.flags_supported` (such as `NOPII`).
  - `endpoints.supported_formats` and `endpoints.operations`: machine-readable endpoint inventory with parameters.

Example response shape:
```json
{
  "account": {
    "email": "user@example.com",
    "plan": "pro",
    "plan_expiry": "2026-12-31T00:00:00Z",
    "max_batch_size": {
      "domain_lookup": 16,
      "vat_lookup": 16,
      "domain_bulk_submit": 5000
    }
  },
  "rate_limits": {
    "requests_per_second": 10,
    "concurrency": 8
  },
  "credits": {
    "purchased": 200000,
    "used": 1234,
    "remaining": 198766,
    "costs": {
      "domain_api_lookup": 1,
      "vat_api_lookup": 1,
      "free_api_lookup": 0,
      "lists_api": "requires_subscription"
    }
  },
  "privacy": {
    "pii_allowed": true,
    "default_privacy_mode": "pii",
    "flags_supported": ["NOPII"]
  },
  "endpoints": {
    "base_url": "https://api.builtwith.com",
    "supported_formats": ["json", "xml", "csv", "tsv", "txt"],
    "operations": [
      { "id": "domain.lookup", "method": "GET", "path": "/v23/api.json" }
    ]
  }
}
```

### 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
}
```

## MCP API (v2)
- Endpoint: `GET /mcp2/api.{json|xml|csv|txt}` - search and browse the BuiltWith MCP registry (other remote MCP servers BuiltWith has discovered across the web - not an MCP protocol endpoint itself). See `https://builtwith.com/mcp-registry`.
- Example: `https://api.builtwith.com/mcp2/api.json?KEY=YOUR_KEY&SEARCH=payments`
- Example: `https://api.builtwith.com/mcp2/api.json?KEY=YOUR_KEY&CATEGORY=developer-tools&OFFSET=100`
- Credit cost: free - no API credits used.
- Rate limit: 1 request per second per API key (stricter than the general API rate limit, since this endpoint is free).
- Categories: `GET /mcp2/categories.{json|xml|csv}` lists every valid `CATEGORY` slug with its friendly `Label` and current `Count`. This endpoint is public and uses no API credits.
- Documentation: `https://api.builtwith.com/mcp-api`
- Note: Exposed as a tool via the BuiltWith MCP server (`https://api.builtwith.com/mcp`, see the MCP Server section)

### Parameters
- `KEY` (required) - your API key.
- `SEARCH` (optional) - matches against the MCP server's domain, description, endpoint URLs, tool (method) names/descriptions, and overview instructions. At least one of `SEARCH` or `CATEGORY` is required.
- `CATEGORY` (optional) - a category slug from the categories endpoint above. At least one of `SEARCH` or `CATEGORY` is required.
- `OFFSET` (optional, default `0`) - pagination offset; page size is fixed at 100 results.

### Response
The response is a list of records with:
- `Domain` - the MCP server's root domain.
- `Category` - the friendly category label.
- `Description` - a short description of the MCP server.
- `Endpoints` - array of the actual remote MCP endpoint(s) the domain exposes, each with `Endpoint` (URL), `AuthRequired` (bool), `Tools` (the methods that endpoint supports, each with `Name` and `Description`), and the complete `Overview` discovery object when available. `Overview` includes fields reported by the remote server such as `instructions`, `protocolVersion`, `serverInfo`, and `capabilities`.

Results are sorted alphabetically by domain, up to 100 per page. Pagination metadata is returned as response headers rather than in the body: `X-TOTAL-COUNT`, `X-OFFSET`, `X-PAGE-SIZE`, `X-HAS-MORE`.

Example JSON:
```json
[
  {
    "Domain": "example.com",
    "Category": "Developer Tools",
    "Description": "Example MCP server description",
    "Endpoints": [
      {
        "Endpoint": "https://example.com/mcp",
        "AuthRequired": true,
        "Tools": [
          { "Name": "search_orders", "Description": "Search orders by customer or status" }
        ],
        "Overview": {
          "instructions": "Use this server to search and manage orders.",
          "protocolVersion": "2025-06-18",
          "serverInfo": { "name": "example-orders", "version": "1.0.0" },
          "capabilities": { "tools": { "listChanged": false } }
        }
      }
    ]
  }
]
```

Example CSV (`Endpoints` is flattened to `url [tool1, tool2]`; `Overview` contains the endpoint URL and JSON overview):
```csv
Domain,Category,Description,Endpoints,Overview
example.com,Developer Tools,Example MCP server description,"https://example.com/mcp [search_orders, get_order]","https://example.com/mcp: {""instructions"":""Use this server to search and manage orders.""}"
```

## VAT API (v1)
- Endpoint: `GET /vat1/api.{json|xml|csv}` - VAT, GSTIN, CNPJ and other available company registration numbers for websites.
- Example: `https://api.builtwith.com/vat1/api.json?KEY=YOUR_KEY&LOOKUP=example.com`
- Credit cost: 1 API credit for each domain that returns one or more registration records. Domains with no results use no credit.
- Registration types: `GET /vat1/types.{json|xml|csv}` lists every possible `Type` value with its friendly `Name` and `Description`. This endpoint is public and uses no API credits.
- Documentation: `https://api.builtwith.com/vat-api`

### Parameters
- `KEY` (required) - your API key.
- `LOOKUP` (required) - 1 to 16 comma-separated root domains.

### Response
The response is a flat list of records with:
- `Domain` - the requested root domain.
- `Type` - registration type, such as `VAT`, `GSTIN`, `CNPJ`, `ABN`, `EIN`, or another available company registration type.
- `Number` - the company registration number.

A domain can return multiple records. Domains with no known registration data return no records and use no API credit.

Example JSON:
```json
[
  { "Domain": "builtwith.com", "Type": "GSTIN", "Number": "2332323" }
]
```

Example CSV:
```csv
Domain,Type,Number
builtwith.com,GSTIN,2332323
```

## Domain API (v23)
- Endpoint: `GET /v23/api.{json|xml|csv}` - technology and metadata for a domain.
- Example: `https://api.builtwith.com/v23/api.json?KEY=YOUR_KEY&LOOKUP=example.com`
- Credits: 1 per domain looked up.
- `v23` adds `Result.SpendHistory` (historic monthly spend as `{D, S}` pairs), per-result `SalesRevenue`, and per-technology `Id`; the previous `/v22/` endpoints remain available.

### Parameters
- `KEY` (required) - your API key.
- `LOOKUP` (required) - root domain to look up. Multi-lookup: up to 16 domains as CSV, for example `cnn.com,about.com,builtwith.com`.
- `HIDETEXT` (`yes`) - hide technology description, link, tag and category fields.
- `HIDEDL` (`yes`) - hide technology description and link fields (keep tag and categories).
- `LIVEONLY` (`yes`) - only return technologies considered live.
- `TRUST` (`yes`) - include Trust data, same as an additional Trust API call; uses an additional API credit.
- `NOMETA` (`yes`) - no meta data (address, names etc.) returned; improves performance.
- `NOPII` (`yes`) - remove people names/emails. EU and California PII is automatically removed regardless.
- `NOATTR` (`yes`) - no attributes data returned; improves performance.
- `IP` (`yes`) - include IP address information when available.
- `FDRANGE` (`YYYY-MM-DD|YYYY-MM-DD`) - filter technologies by first detected date range.
- `LDRANGE` (`YYYY-MM-DD|YYYY-MM-DD`) - filter technologies by last detected date range.

### Index lookups (no LOOKUP needed)
- `GET /v23/api.json?KEY=YOUR_KEY&CATEGORIES=yes` - full technology category index (tags with sub-categories).
- `GET /v23/api.json?KEY=YOUR_KEY&VERTICALS=1` - list of valid `Vertical` values.

### Response object
Format: `Results[ Lookup, Result -> Paths[ Path -> Technologies[Technology] ], Meta, Attributes ], Errors[]`

Result-level fields:
- `Lookup` - the domain that was looked up.
- `IsDB` - `True`/`False`/`Misleading`: whether the lookup used the database or visited the site; `Misleading` means a user-generated-content site profile.
- `Result.Spend` - average monthly USD tech spend based on detected technologies.
- `Result.SalesRevenue` - estimated monthly USD sales revenue for eCommerce sites (0 for non-eCommerce). v23+.
- `Result.SpendHistory` - array of `{D, S}` (epoch-millisecond date, USD spend) across domain coverage; max 60 periods between first/last indexed. v23+.
- `Meta` - meta data object (below).
- `Attributes` - attributes object (below).
- `FirstIndexed` / `LastIndexed` - earliest/most recent index points for the entire domain.

Path fields:
- `Domain` - the root domain.
- `Url` - `dd` means path data built from multiple sub-pages (domain-only lookups).
- `SubDomain` - subdomain of the profile (e.g. `blog` + `disney.com` = blog.disney.com).
- `FirstIndexed` / `LastIndexed` - earliest/most recent index points for this path.

Technology fields:
- `Name` - name of the technology found.
- `Id` - BuiltWith technology integer identifier (v23 and later).
- `Parent` - parent technology name (for versions etc.).
- `Description` - description of the technology.
- `Link` - link to the technology website.
- `IsPremium` - is this a paid technology: `yes`, `no`, or `maybe`.
- `Tag` - base category (see the `CATEGORIES=yes` index).
- `Categories` - array of sub-categories for the tag.
- `FirstDetected` / `LastDetected` - dates the technology was first/last detected.

Meta fields:
- `ARank` - Page Rank, 1 to 100,000,000.
- `QRank` - Tranco traffic rank, 1 to 1,000,000.
- `Majestic` - Majestic rank, 1 to 1,000,000.
- `Umbrella` - Umbrella global router traffic rank, 1 to 1,000,000.
- `CompanyName`, `City`, `Postcode`, `State`, `Country` (ISO 3166-1 alpha-2), `Vertical` (see `VERTICALS=1` index).
- `Telephones[]`, `Emails[]`, `Social[]` - contact details and social presence.
- `Names[]` - people: `Name`, `Level` (job title), `Email`. Removed when `NOPII=yes`.

Attributes fields:
- `MJRank`, `MJTLDRank` - Majestic rank and top-level-domain rank.
- `RefSN`, `RefIP` - referring subnet and IP counts.
- `Sitemap` - sitemap link count.
- `GTMTags`, `QubitTags`, `TealiumTags`, `AdobeTags` - tag manager tag counts.
- `CDimensions`, `CGoals`, `CMetrics` - custom analytics dimension/goal/metric counts.
- `Followers` - brand social followers, grouped (1000 = 1000+ but under 2000).
- `ProductCount` - SKU product count.
- `Employees` - employee count estimate.
- `PageRank`, `BWRank`, `Tranco`, `BWS` - rank attribute values.
- `Revenue` - revenue attribute value.
- `EcommerceCategory` - eCommerce category id.
- `AIMaturity`, `AIOpenness`, `AIReadiness`, `AIVisibility` - AI scores.
- `TTFB` - time to first byte.
- `SourceBytes` - source byte count.

Sample response (fields abridged; full sample at `https://api.builtwith.com/samples/domain_api_v22.json`; v23 uses the same shape plus `SpendHistory`, `SalesRevenue`, and technology `Id`):
```json
{
  "Results": [
    {
      "Lookup": "example.com",
      "Result": {
        "Paths": [
          {
            "Technologies": [
              {
                "Name": "nginx",
                "Id": 1515864597,
                "Tag": "Web Server",
                "Categories": ["Web Server"],
                "FirstDetected": 1700000000000,
                "LastDetected": 1760000000000,
                "IsPremium": "No"
              }
            ]
          }
        ],
        "Spend": 11390,
        "SalesRevenue": 0,
        "SpendHistory": [{ "D": 1140042000000, "S": 100 }]
      },
      "Meta": {
        "CompanyName": "Example Inc",
        "Country": "US"
      }
    }
  ],
  "Errors": []
}
```

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

### Submit
- Endpoint: `POST /v23/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 /v23/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": "/v23/domain/bulk/00000000-0000-0000-0000-000000000000/result",
  "count": 250
}
```

### Retrieve Results
- Endpoint: `GET /v23/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.

## Change API
- Endpoint: `GET /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`
- `LOOKUP` accepts one or more comma-separated domains.
- `SINCE` accepts natural language dates such as `last+month`; default is 3 months.

Sample response (`https://api.builtwith.com/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"
          }
        ]
      }
    }
  ]
}
```

## Lists API
- Endpoint: `GET /lists12/api.{json|xml|txt|csv|tsv}` - sites using a technology.
- Example: `https://api.builtwith.com/lists12/api.json?KEY=YOUR_KEY&TECH=Shopify`
- Requires a subscription (see WhoAmI `credits.costs.lists_api`).

### Parameters
- `KEY` (required) - your API key.
- `TECH` (required) - technology name; replace spaces with dashes, for example `AB-Tasty`. Validate names for free with the Trends API (`/trends/v6/`) before spending credits.
- `OTHERTECHS` - comma-separated technology names; results must use `TECH` and all technologies in `OTHERTECHS`. Maximum 16, for example `Google-Analytics,Meta-Pixel`.
- `META` (`yes`) - include meta data (names, titles, social links, addresses, emails, telephone numbers, traffic ranks etc.).
- `COUNTRY` - filter by TLD extension and/or country address; ISO 3166-1 alpha-2 (except UK); comma for multiple, for example `AU,NZ`.
- `OFFSET` - next page anchor; use the exact `NextOffset` value from the previous response. `END` means no more results.
- `SINCE` - live sites using the technology since a time; accepts dates and natural language such as `30 Days Ago` or `Last January`.
- `ALL` (`yes`) - all sites including historical; cannot be used with `SINCE`.
- Numeric filters use `number|operator`, where operator is `EQ`, `LT`, `LTE`, `GT`, or `GTE`; if omitted, `GTE` is used. Multiple attribute filters are combined with AND.
- `SPEND` - monthly technology spend, for example `100|GT`.
- `REVENUE` - estimated sales revenue for eCommerce sites.
- `SKU` - unique product count found on the eCommerce portion of the site.
- `FOLLOWERS` - social follower count.
- `EMPLOYEES` - employee count.
- `SITEMAP` - sitemap URL count.
- `PAGERANK` - Page Rank Top 100m traffic rank.
- `BWRANK` - BuiltWith rank.
- `TRANCO` - Tranco Top 1m traffic rank.
- `MAJESTIC` - Majestic Top 1m link rank.
- `BWS` - BuiltWith site ranking attribute.
- `ECAT` - eCommerce category id, for example `12|EQ`.
- `AIM`, `AIO`, `AIR`, `AIV` - AI maturity, openness, readiness, and visibility scores.
- Example filtered request: `https://api.builtwith.com/lists12/api.json?KEY=YOUR_KEY&TECH=Shopify&REVENUE=100000|GT&SPEND=100|GTE&COUNTRY=US`

### Response
Top level: `NextOffset` (pass as `OFFSET` for the next page; `END` when finished), `Results[]`, and potentially `Errors[]`.

Result fields:
- `D` - a website that matches the query.
- `LOS` - array of locations on the site where the technology was detected recently.
- `FD` / `LD` - epoch seconds the technology was first/last detected.
- `S` - monthly technology spend average in USD.
- `SKU` - unique product count on the eCommerce portion of the site.
- `R` - estimated sales revenue for eCommerce sites.
- `F` - social followers.
- `E` - employee count.
- `A` - Page Rank Top 100m traffic rank.
- `Q` - Tranco Top 1m traffic rank.
- `M` - Majestic Top 1m link rank.
- `U` - Umbrella Top 1m traffic rank.
- `META` - meta object, supplied when `META=yes`: `CompanyName`, `City`, `Postcode`, `State`, `Country`, `Vertical`, `Telephones[]`, `Emails[]`, `Social[]`, `Titles[]`.

Sample response (`https://api.builtwith.com/samples/list_api_v12.json`):
```json
{
  "NextOffset": "opaque-next-offset",
  "Results": [
    {
      "D": "example-shop.com",
      "FI": 1725494400,
      "LI": 1767657600,
      "Country": "US"
    }
  ]
}
```

## Ask API
- Endpoint: `GET /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`.

Sample response:
```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
    }
  ]
}
```

## Other REST Endpoints

### Relationships API
- Endpoint: `GET /rv4/api.{json|xml|csv|tsv}` - relationships between sites (shared analytics identifiers, hosting, ownership signals).
- Example: `https://api.builtwith.com/rv4/api.json?KEY=YOUR_KEY&LOOKUP=example.com`
- Credits: 1 per lookup.

Sample response (`https://api.builtwith.com/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
}
```

### Free API
- Endpoint: `GET /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`
- Credits: free.

### Company to URL API
- Endpoint: `GET /ctu3/api.{json|xml}` - discover domains from company names.
- Example: `https://api.builtwith.com/ctu3/api.json?KEY=YOUR_KEY&COMPANY=Example`
- Credits: 1 per lookup.

Sample response (`https://api.builtwith.com/samples/ctu_api_v3.json`):
```json
[
  {
    "Domain": "example.com",
    "CompanyName": "Example",
    "Spend": 1024,
    "Country": "US",
    "Socials": ["linkedin.com/company/example"]
  }
]
```

### Tags API
- Endpoint: `GET /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`
- Credits: 1 per lookup.

### Recommendations API
- Endpoint: `GET /rec1/api.{json|xml}` - related technology recommendations for a domain.
- Example: `https://api.builtwith.com/rec1/api.json?KEY=YOUR_KEY&LOOKUP=example.com`
- Credits: 1 per lookup.

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

### Redirects API
- Endpoint: `GET /redirect1/api.{json|xml}` - live and historical redirect history.
- Example: `https://api.builtwith.com/redirect1/api.json?KEY=YOUR_KEY&LOOKUP=example.com`
- Credits: 1 per lookup.

Sample response (`https://api.builtwith.com/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": []
}
```

### Keywords API
- Endpoint: `GET /kw2/api.{json|xml}` - keywords for a domain.
- Example: `https://api.builtwith.com/kw2/api.json?KEY=YOUR_KEY&LOOKUP=example.com`
- Credits: 1 per lookup.

### Keyword Search API
- Endpoint: `GET /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`.
- Requires a subscription (see WhoAmI `credits.costs.keyword_search_api`).

Sample response (`https://api.builtwith.com/samples/keyword_search_api_v1.json`):
```json
{
  "Keyword": "perfume",
  "Domains": ["example-store.com"],
  "NextOffset": "example-store.com"
}
```

### Trends API
- Endpoint: `GET /trends/v6/api.{json|xml}` - technology trend metadata.
- Example: `https://api.builtwith.com/trends/v6/api.json?KEY=YOUR_KEY&TECH=Shopify`
- Credits: free.
- Use it to validate a technology name before spending credits on Lists API or Live Feed calls: a valid `TECH` returns a `Tech` object, an unknown name returns `Errors` with code `-8`. Use `Tech.name` as the canonical name in other endpoints.
- If validation fails, discover the correct name with the Vector Search API (`/vector/v1/`) or browse `https://trends.builtwith.com`.

Sample response for a valid `TECH`:
```json
{
  "Tech": {
    "name": "Shopify",
    "tag": "shop",
    "categories": ["Ecommerce"],
    "description": "Hosted shopping cart solution.",
    "is_premium": "false",
    "icon": "https://x.cdnpi.pe/serve/.../shopify.com",
    "link": "https://kb.builtwith.com/...",
    "trends_link": "//trends.builtwith.com/shop/Shopify",
    "coverage": {
      "ten_k": 500,
      "hundred_k": 5000,
      "milly": 50000,
      "live": 1000000,
      "expired": 2000000
    }
  }
}
```
`coverage` counts sites in the top 10k/100k/1m, plus total live and expired detections.

Sample response for an unknown `TECH`:
```json
{
  "Errors": [
    {
      "Message": "Not a valid technology to lookup sorry - find the exact name with the Vector Search API https://api.builtwith.com/vector/v1/api.json?KEY=YOUR_KEY&QUERY=... or browse trends.builtwith.com",
      "Code": -8
    }
  ]
}
```

### Product API
- Endpoint: `GET /productv1/api.json` - websites selling products.
- Example: `https://api.builtwith.com/productv1/api.json?KEY=YOUR_KEY&QUERY=Adidas%20Yeezy`
- Credits: 1 per lookup.
- Pagination: response includes `is_more` and a `next_page` URL (`PAGE` and `LIMIT` parameters).

Sample response (`https://api.builtwith.com/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
- Endpoint: `GET /trustv2/api.{json|xml}` - trust and fraud signals, returned as a self-describing assessment (`TrustLevel`, `Summary`, `Reasons`) plus content-safety flags (gambling, adult, scam, placeholder content) and a business profile.
- Example: `https://api.builtwith.com/trustv2/api.json?KEY=YOUR_KEY&LOOKUP=example.com`
- Optional: `LIVE` (`yes`) - also runs a live crawl and returns `LiveVerification`; uses an additional API credit.
- Credits: 1 per lookup. Also available inline on the Domain API with `TRUST=yes` (additional credit).

Sample response (`https://api.builtwith.com/samples/trust_api_v2.json`):
```json
{
  "Domain": "example.com",
  "Assessment": {
    "TrustLevel": "Trusted",
    "Summary": "Established technology history and meaningful ad/tool spend indicate an ongoing, real business.",
    "Reasons": [
      "Site has been indexed with technology detections for over 1 year.",
      "Estimated monthly technology spend of $11,284 USD.",
      "No gambling, adult, scam, or placeholder content detected."
    ]
  },
  "ContentSafety": {
    "Gambling": false,
    "AdultContent": false,
    "SuspectedScam": false,
    "PlaceholderContent": false
  },
  "BusinessProfile": {
    "IsIndexed": true,
    "DomainAgeDays": 6772,
    "LastCrawledDaysAgo": 0,
    "PremiumTechnologyCount": 21,
    "HasActiveTechnologyStack": true,
    "IsParkedDomain": false,
    "IsEcommerceSite": false,
    "HasPaymentProcessing": true,
    "HasAffiliateLinks": false,
    "IsEstablishedBusiness": true,
    "EstimatedMonthlySpendUSD": 11284
  },
  "LiveVerification": null
}
```
`TrustLevel` is always one of: `Unverified`, `RestrictedContent`, `HighRisk`, `Caution`, `VerificationRecommended`, `Neutral`, `Trusted`. `LiveVerification` is only populated when the request includes `&LIVE=yes`.

### Vector Search API
- Endpoint: `GET /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).
- Credits: 1 per search.

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

## 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/v23/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 (`max_per_purchase`, `max_monthly`, `monthly_purchased`, `monthly_remaining`, `cost_per_2000_credits_usd`).
- `POST /v1/billing/api-purchase` - body `{"credits":2000}`; minimum 2000 credits. Uses the account's saved Stripe payment method and configured spending limits.

### mppx Agent Payment API Aliases
- Base URL: `https://api.builtwith.com/mppx`
- Purpose: API-domain aliases for the same Agent Payment API operations above.
- Availability: requires manual enablement.
- Auth: same as Agent Payment API, `Authorization: Bearer YOUR_KEY` or `?KEY=YOUR_KEY`.
- Behavior: uses the existing Agent Payment API, saved Stripe payment method, configured spending limits, and error responses. These aliases do not use a separate third-party payment host.
- Discovery: `GET https://api.builtwith.com/mppx/openapi.json`

Endpoints:
- `GET /mppx/api-discovery?KEY=YOUR_KEY` - alias for `/v1/billing/api-discovery`.
- `GET /mppx/api-configuration?KEY=YOUR_KEY` - alias for `/v1/billing/api-configuration`.
- `POST /mppx/api-purchase` - alias for `/v1/billing/api-purchase`; body `{"credits":2000}`.
- Short aliases are also accepted: `/mppx/balance`, `/mppx/configuration`, and `/mppx/purchase`.

## MCP Server
- Discovery manifest: `https://builtwith.com/.well-known/mcp.json`
- Hosted MCP endpoint: `https://api.builtwith.com/mcp`
- Transport: streamable HTTP (stateless; the endpoint only accepts `POST`).
- Standard tools: authenticate with `Authorization: Bearer YOUR_BUILTWITH_API_KEY`.
- x402 tools: buy a batch of non-expiring API credits with Base USDC, then use the returned reusable `creditKey`; callers do not need their own BuiltWith API key.
- x402 discovery: `https://api.builtwith.com/.well-known/x402`
- x402 protocol/network: version 2 on Base mainnet (`eip155:8453`), using native USDC (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`).
- Payment recipient: `0x1937E2d648b8f07A03429AE35f28C4942A756C94`.
- Facilitator: `https://facilitator.payai.network`.
- Credit flow: call `x402-pricing` with an optional `credits` quantity, then call `x402-credit-purchase` with at least 2000 credits and the payer wallet. Sign a returned payment requirement and retry with the payment payload in MCP request metadata at `_meta["x402/payment"]`. Store the returned `creditKey` and supply it to credit-based lookup tools.
- Top-ups: pass an existing `creditKey` to `x402-credit-purchase`; the payer wallet must match the wallet that created the key.
- Credits do not expire. A 2,000-credit batch costs $99 and a 10,000-credit batch costs $259. Failed BuiltWith API calls release their reserved credits.
- 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"
      }
    }
  }
}
```

### Tools
Inputs are listed as `name (type, required?)`. Tools map to the REST endpoints above and return JSON.

Domain tools (Domain API `v23`):
- `domain-lookup` - live web technologies for a root domain, with UI widget output. Inputs: `domain` (string, required), `liveOnly` (boolean, optional; defaults to true - set false to include historical technologies).
- `domain-api` - technology and metadata lookup with UI widget output. Inputs: `lookup` (string, required).
- `domain-api-json` - raw Domain API JSON. Inputs: `lookup` (string, required).

Per-domain lookups:
- `change-api` - technology additions/removals. Inputs: `lookup` (string, required; one or more comma-separated domains), `since` (string, optional; natural language such as "last month", defaults to 3 months).
- `relationships-api` - related websites. Inputs: `lookup` (string, required).
- `free-api` - category/group counts; free. Inputs: `lookup` (string, required).
- `company-to-url` - domains from a company name. Inputs: `company` (string, required).
- `tags-api` - related domains from IP or attributes. Inputs: `lookup` (string, required).
- `recommendations-api` - technology recommendations. Inputs: `lookup` (string, required).
- `redirects-api` - live and historical redirects. Inputs: `lookup` (string, required).

Keyword, trend, product, trust, and semantic search:
- `keywords-api` - keywords for a domain. Inputs: `lookup` (string, required).
- `keywords-search-api` - websites containing a keyword, paginated. Inputs: `keyword` (string, required), `limit` (integer, optional; 16-1000, default 100), `offset` (string, optional; `NextOffset` from the previous response).
- `trends-api` - technology trend data; free. Inputs: `tech` (string, required).
- `product-api` - eCommerce product search. Inputs: `query` (string, required).
- `trust-api` - trust scoring for a domain. Inputs: `lookup` (string, required).
- `vector-api` - semantic search over technologies and categories with similarity scores. Inputs: `query` (string, required), `limit` (integer, optional; 1-100, default 10).

Natural language website lists (Ask API):
- `ask-api` - natural language website list queries with UI widget output. Inputs: `query` (string, required), `commit` (boolean, optional; run a full report with up to 1000 results), `nextOffset` (string, optional), `meta` (boolean, optional).
- `ask-api-json` - raw Ask API JSON. Inputs: same as `ask-api`.

Account (no API credits):
- `whoami-api` - account limits, credit costs, privacy flags, max batch sizes, endpoint inventory. No inputs. Call this first to make account-aware decisions.
- `usage-api` - current credit balance (used, purchased, remaining). No inputs.

Agent Payment API:
- `payment-balance` - returns `credits_total`, `credits_used`, `credits_available`. No inputs.
- `payment-config` - returns `max_per_purchase`, `max_monthly`, `monthly_purchased`, `monthly_remaining`, `cost_per_2000_credits_usd`. No inputs.
- `payment-purchase` - purchase credits with the saved payment method. Inputs: `credits` (integer, required; minimum 2000).

x402 (Base USDC; no caller BuiltWith API key):
- `x402-pricing` - public configuration, prepaid batch-credit tiers, List pass tiers, and an optional batch quote. Optional input: `credits` (integer, minimum 2000).
- `x402-credit-purchase` - buy or top up non-expiring credits with one x402 payment. Inputs: `credits` (integer, minimum 2000), `payer`, and optional existing `creditKey`. A new key is returned in plaintext only when created and must be stored securely.
- `x402-credit-balance` - purchased, used, pending, and available credits. Input: `creditKey`; no payment or credit required.
- `x402-domain-lookup`, `x402-domain-api`, `x402-domain-api-json`, `x402-change-api`, `x402-relationships-api`, `x402-company-to-url`, `x402-tags-api`, `x402-recommendations-api`, `x402-redirects-api`, `x402-keywords-api`, `x402-trust-api`, `x402-vat-api`, `x402-vector-api` - prepaid lookup tools. Each requires `creditKey`; other inputs mirror its standard tool. Multi-domain tools deduct one credit per unique requested domain.
- `x402-ask-api` - prepaid Ask lookup. Inputs: `query`, `payer`, `creditKey`, optional `commit`, `nextOffset`, `meta`, and `passToken`. Committed reports and pagination require a valid List pass.
- `x402-list-pass-purchase` - buy a 30-day List pass. Inputs: `tier` (`basic` or `pro`) and `payer`.
- `x402-list-api`, `x402-keywords-search-api` - List tools used with a purchased pass. Inputs include `payer` and `passToken`.
- Only `x402-credit-purchase` and `x402-list-pass-purchase` return x402 v2 payment requirements. Prepaid lookups use the stored key without another facilitator transaction.

### Prompts
- `analyze-tech-stack` (`domain`) - analyze the technology stack of a domain.
- `find-related-websites` (`domain`) - find websites related to a domain.
- `get-technology-recommendations` (`domain`) - technology recommendations for a domain.
- `research-company` (`company`) - research a company's web presence by name.
- `check-domain-trust` (`domain`) - check the trust score of a domain.
- `discover-technologies-by-concept` (`concept`) - search technologies matching a concept, then explore adoption trends.

### Resources
UI widget resources used by `domain-lookup`, `domain-api`, and `ask-api` in MCP clients that support embedded apps:
- `ui://widget/domain-technologies.html` - interactive table for domain technology results.
- `ui://widget/ask-sites.html` - interactive table for Ask API website list results.

## 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 (`v23`) -> Relationships API (`rv4`) -> optional Trust API (`trustv2`) and Redirects API (`redirect1`).
- Research a domain stack: Free API (`free1`) for quick counts -> Domain API (`v23`) 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 -> validate the name for free with Trends API (`trends/v6`) -> Lists API (`lists12`), or Ask API (`ask1`) for natural language criteria -> enrich selected domains with Domain API (`v23`).
- Product or ecommerce research: Product API (`productv1`) -> enrich shops with Domain API (`v23`) -> check Trust API (`trustv2`).
- Relationship investigation: Domain API (`v23`) 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.



## Enterprise API Integration Information


Authentication:
- BuiltWith APIs use API-key authentication over HTTPS.
- Query-string authentication: KEY=YOUR_API_KEY
- Header authentication: Authorization: API YOUR_API_KEY
- API keys must not be exposed in client-side applications or public repositories.

API versions:
- API versions are included in endpoint paths, such as /v23/.
- Existing versioned endpoints are retained where practical when incompatible changes are introduced.
- Material changes affecting active enterprise integrations are communicated directly.
- Public changelog: [URL OR "A public changelog is not currently maintained."]

Testing:
- BuiltWith does not provide a separate public sandbox or UAT environment - use a secondary email account for testing.
- Testing is performed against production endpoints using an API key.
- Customers should begin with low-volume requests against known test domains.
- Test credits may be provided for approved enterprise integration projects - contact us
- BuiltWith responses contain real production data; no synthetic mock dataset is currently provided.

Rate limits and throughput:
- Maximum 8 concurrent requests - with maximum of 10 requests per second - please ensure you remain below this or you will get 429 errors.
- Rate-limit documentation: https://api.builtwith.com/domain-api#rate
- High-throughput or dedicated endpoints are available by arrangement.
- Customers expecting sustained or burst traffic should provide anticipated requests per second and daily volume before launch.

Errors:
- Error-code documentation: https://api.builtwith.com/errorCodes
- Support requests should include the endpoint, parameters with the API key removed, UTC request time, HTTP status and response body.

Support:
- Primary support channel: support@builtwith.com
- Technical documentation: https://api.builtwith.com/
- Knowledge Base: https://kb.builtwith.com/
- Telephone support:
  Australia: +61 2 7242 2020
  United States: +1 347 514 7140

Escalation:
- Production-blocking incidents should be marked URGENT and sent to support@builtwith.com.
- Include the affected endpoint, business impact, first observed time, request identifier if available, HTTP status and response excerpt.
- Formal response-time commitments apply only where included in the customer agreement.