# StackScan API

Technology and company intelligence for any domain: what a website is built
with, and who is behind it. This file is a compact reference for AI agents.
Full field-level detail: https://api.stackscan.com/llms-full.txt
OpenAPI: https://api.stackscan.com/docs/openapi.json    Human docs: https://api.stackscan.com/docs

## Access

Base URL: https://api.stackscan.com
Auth: two headers, both required.
  Authorization: Bearer <token>   from Dashboard -> My Account -> API Tokens
  X-Tenant-Id: <workspace uuid>   shown on the same page
There is no anonymous access and no free tier. Sign up at https://www.stackscan.com/pricing
Manage tokens at https://app.stackscan.com/login

## Credits

Every successful lookup costs 1 Bulk Lookup Credit. A lookup that finds
nothing is NOT charged. Checking your balance is free. Batch endpoints charge
per domain that resolves, not per request and not per row returned.

Every response carries your balance, so you do not need to poll:
  X-Credits-Used        credits this request consumed
  X-Credits-Remaining   wallet balance after this request
  X-Credits-Cost        cost of one successful lookup

## Endpoints

GET    /v1/tech-lookup/credits            Balance and monthly allocation. Free.
GET    /v1/tech-lookup/domains/lookup     Technologies on one domain, paginated (50/page, max 500).
GET    /v1/tech-lookup/technologies/lookup How many sites run a technology, and where.
GET    /v1/tech-lookup/companies/lookup   The company behind one domain.
POST   /v1/tech-lookup/companies/batch    Companies for up to 100 domains in one request.
POST   /v1/tech-lookup/domains/batch      Technologies for up to 100 domains, with optional category filter.

## Conventions that will trip you up

1. A MISS IS A 200, NOT A 404. No data returns HTTP 200 with
   {"success": false, "error": "No data available"}. Check the `success`
   field, not the status code. Misses are not charged.
2. Batch responses never fail as a whole for partial problems. Read
   `results` alongside `not_found`, `invalid` and
   `skipped_insufficient_credits`. The last of those means the wallet ran
   out mid-request: those domains DO have data and are worth retrying.
   The invariant `resolved = served + skipped_insufficient_credits` always
   holds.
3. Paginated results carry `pagination.has_more`. Check it before assuming
   you have a complete list.
4. 402 means out of credits, 429 means too fast (obey `retry_after`).

## MCP

A local MCP server wraps these endpoints as tools for Claude, Cursor and
other MCP clients: npx -y @stackscan/mcp-server
Setup: https://www.stackscan.com/mcp
Source (MIT): https://github.com/stackscan/stackscan-mcp