{ "openapi": "3.1.0", "info": { "title": "TechnologyChecker API", "description": "Discover technology stacks, track market trends, and enrich data with company intelligence.", "version": "1.0.0", "contact": { "name": "TechnologyChecker Support", "email": "support@technologychecker.io", "url": "https://technologychecker.io" } }, "servers": [ { "url": "https://api.technologychecker.io", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Domain technologies", "description": "Look up technologies detected on any domain" }, { "name": "Technology data", "description": "Search, look up, and get details on tracked technologies" }, { "name": "Market intelligence", "description": "Technology stats, trends, and market share" }, { "name": "Company data", "description": "Firmographic and company intelligence" }, { "name": "Live detection", "description": "Real-time technology detection with browser rendering" }, { "name": "Signals", "description": "Intent signals derived from technology state transitions: who adopted, who churned, who switched, and who has a gap in their stack." }, { "name": "Alerts", "description": "Saved signal queries delivered to your webhook. Every signal you can query, you can subscribe to." }, { "name": "Audiences", "description": "Saved groups of domains — uploaded lists or computed recipes — that you can profile, slice and monitor." }, { "name": "Lead lists", "description": "Build and export targeted domain lists combining technology detection with company data." } ], "paths": { "/v1/domain/{domain}": { "get": { "operationId": "getDomainTechnologies", "summary": "Get domain technologies API", "description": "Look up the active and historical technologies detected on any domain. Returns the full technology stack including category information.", "tags": [ "Domain technologies" ], "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "The domain to look up (e.g., `shopify.com`)", "schema": { "type": "string", "example": "shopify.com" } } ], "responses": { "200": { "description": "Technology stack for the domain", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "domain": { "type": "string", "example": "shopify.com" }, "active_technologies": { "type": "array", "items": { "$ref": "#/components/schemas/DomainTechnology" } }, "historical_technologies": { "type": "array", "items": { "$ref": "#/components/schemas/DomainTechnology" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/domain/{domain}/history": { "get": { "operationId": "getDomainTechHistory", "summary": "Get domain tech history API", "description": "Get the full technology history for a domain, including removed technologies with status and dates. Useful for tracking technology adoption and removal over time.", "tags": [ "Domain technologies" ], "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "The domain to look up (e.g., `stripe.com`)", "schema": { "type": "string", "example": "stripe.com" } } ], "responses": { "200": { "description": "Technology history for the domain", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "domain": { "type": "string", "example": "stripe.com" }, "technologies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 2 }, "name": { "type": "string", "example": "Cloudflare" }, "category": { "type": "string", "example": "CDN" }, "status": { "type": "string", "enum": [ "active", "removed" ], "example": "active" }, "first_seen": { "type": "string", "example": "2020-05-08 00:00:00" }, "last_seen": { "type": "string", "example": "2026-01-08 00:00:00" } } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/technology/{id}/info": { "get": { "operationId": "getTechnologyInfo", "summary": "Get technology info (extended) API", "description": "Get extended details for a technology including description, website, icon, and group information.", "tags": [ "Technology data" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Technology ID", "schema": { "type": "integer", "example": 268 } } ], "responses": { "200": { "description": "Extended technology details", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/TechnologyExtended" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/technology/name/{name}": { "get": { "operationId": "lookupTechnologyByName", "summary": "Lookup technology by name API", "description": "Quick lookup of a technology by its exact name (case-insensitive).", "tags": [ "Technology data" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Technology name (URL-encoded)", "schema": { "type": "string", "example": "React" } } ], "responses": { "200": { "description": "Technology lookup result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "exists": { "type": "boolean", "example": true }, "technology": { "$ref": "#/components/schemas/TechnologyBasic" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/technology/name/{name}/domains": { "get": { "operationId": "findDomainsByTechnology", "summary": "Find domains by technology API", "description": "Get the top domains using a specific technology, identified by name. Results are sorted by most recently detected.", "tags": [ "Domain technologies" ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Technology name (URL-encoded, e.g., `React`, `Shopify`, `Google%20Analytics`)", "schema": { "type": "string", "example": "Shopify" } }, { "name": "limit", "in": "query", "description": "Number of domains to return (max 1000)", "schema": { "type": "integer", "default": 100, "maximum": 1000 } } ], "responses": { "200": { "description": "Domains using the technology", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "technology": { "$ref": "#/components/schemas/TechnologyBasic" }, "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string", "example": "gymshark.com" }, "first_detected": { "type": "string", "example": "2018-03-08 00:00:00" }, "last_detected": { "type": "string", "example": "2026-01-08 00:00:00" } } } }, "count": { "type": "integer", "example": 3 } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/technology/{id}/stats": { "get": { "operationId": "getTechnologyStats", "summary": "Technology stats API", "description": "Get quick statistics for a technology including active and total domain counts.", "tags": [ "Market intelligence" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Technology ID", "schema": { "type": "integer", "example": 268 } } ], "responses": { "200": { "description": "Technology statistics", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 268 }, "name": { "type": "string", "example": "React" }, "category": { "type": "string", "example": "JavaScript Frameworks" }, "active_domains": { "type": "integer", "example": 4742704 }, "total_domains": { "type": "integer", "example": 4750194 } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/technology/{id}/history": { "get": { "operationId": "getTechnologyTrends", "summary": "Technology usage trends API", "description": "Get monthly domain counts for a technology over time — up to 20 years of historical data for trend analysis.", "tags": [ "Market intelligence" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Technology ID", "schema": { "type": "integer", "example": 268 } }, { "name": "years", "in": "query", "description": "Number of years of history to return (1–20)", "schema": { "type": "integer", "default": 12, "minimum": 1, "maximum": 20 } } ], "responses": { "200": { "description": "Monthly usage data", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "technology": { "$ref": "#/components/schemas/TechnologyBasic" }, "history": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "example": "2025-12" }, "active_domains": { "type": "integer", "example": 1039 }, "total_domains": { "type": "integer", "example": 1039 } } } }, "data_points": { "type": "integer", "example": 300 }, "years_requested": { "type": "integer", "example": 2 } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/category/{id}/market-share": { "get": { "operationId": "getCategoryMarketShare", "summary": "Technology market share API", "description": "Get market share data for all technologies within a specific category. Technologies are ranked by domain count with percentage share.", "tags": [ "Market intelligence" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Category ID", "schema": { "type": "integer", "example": 203 } }, { "name": "limit", "in": "query", "description": "Number of technologies to return (max 100)", "schema": { "type": "integer", "default": 50, "maximum": 100 } } ], "responses": { "200": { "description": "Market share data", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "category": { "$ref": "#/components/schemas/Category" }, "technologies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 86 }, "name": { "type": "string", "example": "DoubleClick.Net" }, "domain_count": { "type": "integer", "example": 5750120 }, "market_share": { "type": "number", "format": "float", "example": 29.67 } } } }, "total_technologies": { "type": "integer", "example": 5 }, "total_domains": { "type": "integer", "example": 19382458 } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/technology/{id}/companies": { "get": { "operationId": "getCompaniesByTechnology", "summary": "Get companies by technology API", "description": "Get companies using a specific technology with optional company filters (country, industry, employees, etc.).", "tags": [ "Company data" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Technology ID", "schema": { "type": "integer", "example": 268 } }, { "name": "country", "in": "query", "description": "Filter by country (case-insensitive)", "schema": { "type": "string" } }, { "name": "city", "in": "query", "description": "Filter by city (case-insensitive)", "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "Filter by state (case-insensitive)", "schema": { "type": "string" } }, { "name": "industry", "in": "query", "description": "Filter by industry (case-insensitive)", "schema": { "type": "string" } }, { "name": "industry_code", "in": "query", "description": "LinkedIn industry code (1–201)", "schema": { "type": "integer", "minimum": 1, "maximum": 201 } }, { "name": "employees", "in": "query", "description": "Employee range", "schema": { "type": "string", "enum": [ "1-1", "1-10", "2-10", "11-50", "51-200", "201-500", "501-1000", "1001-5000", "5001-10000", "10001+" ] } }, { "name": "company_type", "in": "query", "description": "Company type", "schema": { "type": "string", "enum": [ "Privately Held", "Self-Owned", "Partnership", "Self-Employed", "Public Company", "Nonprofit", "Educational", "Government Agency" ] } }, { "name": "founded_min", "in": "query", "description": "Minimum founding year (1800–2025)", "schema": { "type": "integer", "minimum": 1800, "maximum": 2025 } }, { "name": "founded_max", "in": "query", "description": "Maximum founding year (1800–2025)", "schema": { "type": "integer", "minimum": 1800, "maximum": 2025 } }, { "name": "limit", "in": "query", "description": "Results per page (max 100)", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Pagination offset", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Companies using the technology", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "technology": { "$ref": "#/components/schemas/TechnologyBasic" }, "companies": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } }, "total": { "type": "integer", "example": 133 }, "limit": { "type": "integer", "example": 50 }, "offset": { "type": "integer", "example": 0 } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/company/{domain}": { "get": { "operationId": "getCompanyByDomain", "summary": "Company data by domain API", "description": "Get detailed company information for a specific domain from the LinkedIn company database (25.4M records).", "tags": [ "Company data" ], "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "The domain to look up (e.g., `stripe.com`)", "schema": { "type": "string", "example": "stripe.com" } } ], "responses": { "200": { "description": "Company details", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/CompanyFull" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/companies": { "get": { "operationId": "searchCompanies", "summary": "Search companies API", "description": "Search and filter companies with comprehensive criteria. Results are sorted by associated LinkedIn members (descending).", "tags": [ "Company data" ], "parameters": [ { "name": "country", "in": "query", "description": "Filter by country (case-insensitive)", "schema": { "type": "string" } }, { "name": "city", "in": "query", "description": "Filter by city (case-insensitive)", "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "Filter by state (case-insensitive)", "schema": { "type": "string" } }, { "name": "industry", "in": "query", "description": "Filter by industry (case-insensitive)", "schema": { "type": "string" } }, { "name": "industry_code", "in": "query", "description": "LinkedIn industry code (1–201)", "schema": { "type": "integer", "minimum": 1, "maximum": 201 } }, { "name": "employees", "in": "query", "description": "Employee range", "schema": { "type": "string", "enum": [ "1-1", "1-10", "2-10", "11-50", "51-200", "201-500", "501-1000", "1001-5000", "5001-10000", "10001+" ] } }, { "name": "company_type", "in": "query", "description": "Company type", "schema": { "type": "string", "enum": [ "Privately Held", "Self-Owned", "Partnership", "Self-Employed", "Public Company", "Nonprofit", "Educational", "Government Agency" ] } }, { "name": "founded_min", "in": "query", "description": "Minimum founding year (1800–2025)", "schema": { "type": "integer", "minimum": 1800, "maximum": 2025 } }, { "name": "founded_max", "in": "query", "description": "Maximum founding year (1800–2025)", "schema": { "type": "integer", "minimum": 1800, "maximum": 2025 } }, { "name": "search", "in": "query", "description": "Text search in company name and description (min 2 characters)", "schema": { "type": "string", "minLength": 2 } }, { "name": "limit", "in": "query", "description": "Results per page (max 100)", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Pagination offset", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Paginated company list", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "companies": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } }, "total": { "type": "integer", "example": 592403 }, "limit": { "type": "integer", "example": 50 }, "offset": { "type": "integer", "example": 0 } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/companies/batch": { "post": { "operationId": "batchCompanyLookup", "summary": "Batch company lookup API", "description": "Look up company data for multiple domains in a single request. Returns full details including description and specialties.", "tags": [ "Company data" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domains" ], "properties": { "domains": { "type": "array", "description": "Array of domains to look up (max 100)", "maxItems": 100, "items": { "type": "string" }, "example": [ "stripe.com", "shopify.com" ] } } } } } }, "responses": { "200": { "description": "Batch company results", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "companies": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyFull" } }, "found": { "type": "integer", "example": 2 }, "not_found": { "type": "array", "items": { "type": "string" }, "example": [] } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/technology-lookup-live": { "post": { "operationId": "technologyLookupLive", "summary": "Technology lookup (live) API", "description": "Detect technologies on a website in real-time using multiple detection modes.\n\n**Costs 5 credits per request.**", "tags": [ "Live detection" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "The URL to analyze", "example": "https://stripe.com" }, "options": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "browser", "fetch" ], "default": "browser", "description": "Detection mode: `browser` (Puppeteer headless Chrome, JS execution, 5–22s, maximum accuracy) or `fetch` (HTTP only, 1–3s, best for static sites)" }, "interact": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "basic", "full" ] } ], "default": false, "description": "Simulate user behavior (browser mode only). `false` — no interaction, just load and scan. `true` or `\"basic\"` — scroll the page to trigger lazy-loaded content. `\"full\"` — scroll + accept cookie consent banners + fire DOM events. Adds ~5–10s per request." } } } } } } } }, "responses": { "200": { "description": "Live detection results", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "url": { "type": "string", "description": "The final URL after any redirects", "example": "https://stripe.com/de" }, "originalUrl": { "type": "string", "description": "The URL that was originally requested", "example": "https://stripe.com" }, "mode": { "type": "string", "description": "The detection mode that was used", "example": "browser" }, "technologies": { "type": "array", "items": { "$ref": "#/components/schemas/LiveTechnology" } }, "stats": { "$ref": "#/components/schemas/DetectionStats" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "get": { "operationId": "technologyLookupLiveGet", "summary": "Technology lookup (live) API", "description": "Detect technologies on a website in real-time using multiple detection modes. This is a convenience GET alternative to the POST endpoint.\n\n**Costs 5 credits per request.**", "tags": [ "Live detection" ], "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The URL to analyze", "example": "https://example.com" }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "browser", "fetch" ], "default": "browser" }, "description": "Detection mode: `browser` (Puppeteer headless Chrome, JS execution, 5–22s, maximum accuracy) or `fetch` (HTTP only, 1–3s, best for static sites)" }, { "name": "interact", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "false", "basic", "full" ], "default": "false" }, "description": "Simulate user behavior (browser mode only). `false` — no interaction. `basic` — scroll the page. `full` — scroll + accept cookie consent banners + fire DOM events." } ], "responses": { "200": { "description": "Live detection results", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "url": { "type": "string", "description": "The final URL after any redirects", "example": "https://example.com/" }, "originalUrl": { "type": "string", "description": "The URL that was originally requested", "example": "https://example.com" }, "mode": { "type": "string", "description": "The detection mode that was used", "example": "browser" }, "technologies": { "type": "array", "items": { "$ref": "#/components/schemas/LiveTechnology" } }, "stats": { "$ref": "#/components/schemas/DetectionStats" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/signals": { "get": { "operationId": "listSignalTypes", "summary": "List signal types API", "description": "List the signal types available to query, along with the shared firmographic filter vocabulary. Free — this endpoint is metadata only and consumes no credits.", "tags": [ "Signals" ], "responses": { "200": { "description": "Available signal types and the shared filter vocabulary", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "signals": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "adoption" }, "verb": { "type": "string", "example": "adopted" }, "description": { "type": "string" } } } }, "firmographics": { "type": "object", "properties": { "filters": { "type": "array", "items": { "type": "string" } }, "web_filters": { "type": "array", "items": { "type": "string" } }, "enrich_only": { "type": "string", "example": "company=true" }, "saved_segment": { "type": "string" }, "applies_to": { "type": "array", "items": { "type": "string" } } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/signals/{type}": { "get": { "operationId": "getSignalsByType", "summary": "Adoption and churn signals API", "description": "Domains where an adoption or churn happened inside a look-back window, scoped by a technology or a whole category. Returns the matching rows plus `total_sites`, the corpus-wide count of distinct sites with the event (not capped by `limit`).\n\nCosts 1 credit. Endpoints under `/v1/signals` carry a tighter per-key rate limit than the rest of the API.", "tags": [ "Signals" ], "parameters": [ { "name": "type", "in": "path", "required": true, "description": "The signal type. `churn` = a technology the domain had is now gone. `adoption` = a technology the domain newly started using.", "schema": { "type": "string", "enum": [ "churn", "adoption" ], "example": "adoption" } }, { "name": "technology_id", "in": "query", "required": false, "description": "Scope by BuiltWith technology id. Provide exactly one of `technology_id`, `technology` or `category_id`.", "schema": { "type": "integer" }, "example": 2184 }, { "name": "technology", "in": "query", "required": false, "description": "Scope by exact technology name. The technology must be detectable.", "schema": { "type": "string" }, "example": "Shopify" }, { "name": "category_id", "in": "query", "required": false, "description": "Scope by category — fans out to every detectable technology whose *primary* category is this one. Each result row names the specific technology.", "schema": { "type": "integer" }, "example": 202 }, { "name": "window", "in": "query", "required": false, "description": "Look-back window in days. Accepts `30` or `30d`. Clamped to 1–365.", "schema": { "type": "string", "default": "30" }, "example": "30" }, { "name": "limit", "in": "query", "required": false, "description": "Rows returned. Clamped to 1–1000.", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 1000 } }, { "name": "min_confidence", "in": "query", "required": false, "description": "Minimum `detection_rate` for a row to be returned.", "schema": { "type": "number", "format": "float", "default": 0.5, "minimum": 0, "maximum": 1 } }, { "name": "include_first_seen", "in": "query", "required": false, "description": "Adoption only. `true` disables the first-seen gate and counts first-time-crawled domains as adopters — a newly-discovered-domains feed, not genuine adoption.", "schema": { "type": "boolean", "default": false } }, { "$ref": "#/components/parameters/FirmoCountry" }, { "$ref": "#/components/parameters/FirmoCity" }, { "$ref": "#/components/parameters/FirmoState" }, { "$ref": "#/components/parameters/FirmoIndustry" }, { "$ref": "#/components/parameters/FirmoIndustryCode" }, { "$ref": "#/components/parameters/FirmoEmployees" }, { "$ref": "#/components/parameters/FirmoCompanyType" }, { "$ref": "#/components/parameters/FirmoFoundedMin" }, { "$ref": "#/components/parameters/FirmoFoundedMax" }, { "$ref": "#/components/parameters/FirmoCompany" }, { "$ref": "#/components/parameters/WebHasEmail" }, { "$ref": "#/components/parameters/WebHasPhone" }, { "$ref": "#/components/parameters/WebSocial" }, { "$ref": "#/components/parameters/WebLanguage" }, { "$ref": "#/components/parameters/WebCountry" }, { "$ref": "#/components/parameters/SegmentId" } ], "responses": { "200": { "description": "Matching domains and the corpus-wide site count", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "signal": { "type": "object", "properties": { "type": { "type": "string", "example": "adoption" }, "verb": { "type": "string", "example": "adopted" } } }, "scope": { "type": "string", "enum": [ "technology", "category" ], "example": "category" }, "technology": { "type": "object", "nullable": true, "description": "Set for technology scope, `null` for category scope." }, "category": { "type": "object", "nullable": true, "description": "Set for category scope, `null` for technology scope.", "properties": { "id": { "type": "integer", "example": 202 }, "name": { "type": "string", "example": "Email Marketing" }, "technology_count": { "type": "integer", "example": 37 } } }, "window_days": { "type": "integer", "example": 30 }, "min_confidence": { "type": "number", "format": "float", "example": 0.5 }, "excludes_first_seen": { "type": "boolean", "description": "Adoption only — first-crawl domains were excluded.", "example": true }, "total_sites": { "type": "integer", "nullable": true, "description": "Distinct sites with this event across the whole corpus, not capped by `limit`. `null` when the count query was too slow (very large categories).", "example": 2479434 }, "domains": { "type": "array", "items": { "$ref": "#/components/schemas/SignalEvent" } }, "firmographics": { "$ref": "#/components/schemas/FirmographicsEcho" }, "count": { "type": "integer", "description": "Rows returned, capped at `limit`. Use `total_sites` for the corpus total.", "example": 1 } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/signals/{type}/export": { "get": { "operationId": "exportSignals", "summary": "Export signals to CSV API", "description": "Download an adoption or churn query as a CSV file. Takes the same scope, window and filters as the JSON endpoint — forward the identical query parameters.\n\n**Billing is 1 credit per exported row, charged after completion.** `X-Credits-Cost` and `X-Export-Rows` report the exact figures. If the match is larger than your balance the export is capped to your remaining credits and the response carries `X-Export-Capped: credits`. Because the underlying scan runs regardless of `LIMIT`, every export that runs debits at least 1 credit.\n\nEvery export carries the same fixed 27 columns regardless of which filters produced it: 10 signal columns, 9 LinkedIn company columns and 8 website columns from the crawl.", "tags": [ "Signals" ], "parameters": [ { "name": "type", "in": "path", "required": true, "description": "The signal type to export. Switch and whitespace have different row shapes and are not exportable.", "schema": { "type": "string", "enum": [ "churn", "adoption" ], "example": "adoption" } }, { "name": "technology_id", "in": "query", "required": false, "description": "Scope by BuiltWith technology id. Provide exactly one of `technology_id`, `technology` or `category_id`.", "schema": { "type": "integer" }, "example": 2184 }, { "name": "technology", "in": "query", "required": false, "description": "Scope by exact technology name. The technology must be detectable.", "schema": { "type": "string" }, "example": "Shopify" }, { "name": "category_id", "in": "query", "required": false, "description": "Scope by category — fans out to every detectable technology whose *primary* category is this one.", "schema": { "type": "integer" }, "example": 202 }, { "name": "window", "in": "query", "required": false, "description": "Look-back window in days. Clamped to 1–365.", "schema": { "type": "string", "default": "30" } }, { "name": "limit", "in": "query", "required": false, "description": "Bounds both the delivered rows and the bill. Clamped to 10,000. Omit for a full export up to that cap.", "schema": { "type": "integer", "maximum": 10000 }, "example": 1000 }, { "name": "min_confidence", "in": "query", "required": false, "description": "Minimum `detection_rate` for a row to be exported.", "schema": { "type": "number", "format": "float", "default": 0.5 } }, { "name": "include_first_seen", "in": "query", "required": false, "description": "Adoption only. Disables the first-seen gate.", "schema": { "type": "boolean", "default": false } }, { "$ref": "#/components/parameters/FirmoCountry" }, { "$ref": "#/components/parameters/FirmoCity" }, { "$ref": "#/components/parameters/FirmoState" }, { "$ref": "#/components/parameters/FirmoIndustry" }, { "$ref": "#/components/parameters/FirmoIndustryCode" }, { "$ref": "#/components/parameters/FirmoEmployees" }, { "$ref": "#/components/parameters/FirmoCompanyType" }, { "$ref": "#/components/parameters/FirmoFoundedMin" }, { "$ref": "#/components/parameters/FirmoFoundedMax" }, { "$ref": "#/components/parameters/FirmoCompany" }, { "$ref": "#/components/parameters/WebHasEmail" }, { "$ref": "#/components/parameters/WebHasPhone" }, { "$ref": "#/components/parameters/WebSocial" }, { "$ref": "#/components/parameters/WebLanguage" }, { "$ref": "#/components/parameters/WebCountry" }, { "$ref": "#/components/parameters/SegmentId" } ], "responses": { "200": { "description": "CSV file with a fixed 27-column header", "headers": { "X-Credits-Cost": { "description": "Credits charged for this export (one per exported row).", "schema": { "type": "integer" } }, "X-Export-Rows": { "description": "Number of rows in the file.", "schema": { "type": "integer" } }, "X-Export-Capped": { "description": "Present as `credits` when the export was truncated to your remaining balance.", "schema": { "type": "string" } }, "Content-Disposition": { "description": "`attachment` with a generated filename.", "schema": { "type": "string" } } }, "content": { "text/csv": { "schema": { "type": "string", "format": "binary" }, "example": "domain,subdomain,technology_id,technology_name,event_at,last_detected,detection_rate,detection_count,confidence_score,confidence_label,company_name,company_industry,company_employees,company_country,company_city,company_state,company_founded,company_type,linkedin_url,emails,phones,social_linkedin,social_x,social_facebook,social_instagram,social_youtube,web_language\nexample.com,WWW.EXAMPLE.COM,2184,Shopify,2026-05-31 14:10:33,2026-04-18 07:39:59,0.86,6,79,high,Example Inc.,Retail,51-200,united states,austin,texas,2015,Privately Held,linkedin.com/company/example,hi@example.com,+1 555 0100,https://www.linkedin.com/company/example,,,,,en" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/signals/switch": { "get": { "operationId": "getCompetitiveSwitches", "summary": "Competitive switch API", "description": "Domains that dropped one technology and adopted a competing technology in the same category inside the window. The sharpest in-market signal: who left your competitor for you, and who is leaving you.\n\nCompetitors are defined by shared *primary* category, so there is no cross-category switch. Alongside the rows, `flow` returns the corpus-wide destination distribution — the \"247 left X, 69 went to Y\" chart.\n\nCosts 1 credit.", "tags": [ "Signals" ], "parameters": [ { "name": "technology_id", "in": "query", "required": false, "description": "Scope by BuiltWith technology id. Provide exactly one of `technology_id`, `technology` or `category_id`.", "schema": { "type": "integer" }, "example": 2184 }, { "name": "technology", "in": "query", "required": false, "description": "Scope by exact technology name. The technology must be detectable.", "schema": { "type": "string" }, "example": "Shopify" }, { "name": "category_id", "in": "query", "required": false, "description": "Scope by category — fans out to every detectable technology whose *primary* category is this one.", "schema": { "type": "integer" }, "example": 202 }, { "name": "direction", "in": "query", "required": false, "description": "Technology scope only. `from` returns who left the anchor and where they went; `to` returns who came to the anchor and from where. Ignored for category scope.", "schema": { "type": "string", "enum": [ "from", "to" ], "default": "from" } }, { "name": "window", "in": "query", "required": false, "description": "Look-back window in days. Both the churn and the adoption must fall inside it. Clamped to 1–365.", "schema": { "type": "string", "default": "30" }, "example": "90" }, { "name": "min_confidence", "in": "query", "required": false, "description": "Minimum `detection_rate` on the churn side.", "schema": { "type": "number", "format": "float", "default": 0.5 } }, { "name": "limit", "in": "query", "required": false, "description": "Rows returned. Clamped to 1–1000.", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 1000 } }, { "$ref": "#/components/parameters/FirmoCountry" }, { "$ref": "#/components/parameters/FirmoCity" }, { "$ref": "#/components/parameters/FirmoState" }, { "$ref": "#/components/parameters/FirmoIndustry" }, { "$ref": "#/components/parameters/FirmoIndustryCode" }, { "$ref": "#/components/parameters/FirmoEmployees" }, { "$ref": "#/components/parameters/FirmoCompanyType" }, { "$ref": "#/components/parameters/FirmoFoundedMin" }, { "$ref": "#/components/parameters/FirmoFoundedMax" }, { "$ref": "#/components/parameters/FirmoCompany" }, { "$ref": "#/components/parameters/WebHasEmail" }, { "$ref": "#/components/parameters/WebHasPhone" }, { "$ref": "#/components/parameters/WebSocial" }, { "$ref": "#/components/parameters/WebLanguage" }, { "$ref": "#/components/parameters/WebCountry" }, { "$ref": "#/components/parameters/SegmentId" } ], "responses": { "200": { "description": "Switch events and the destination distribution", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "signal": { "type": "object", "properties": { "type": { "type": "string", "example": "switch" }, "verb": { "type": "string", "example": "switched" } } }, "scope": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "technology", "category" ] }, "direction": { "type": "string", "nullable": true, "enum": [ "from", "to", null ] } } }, "technology": { "type": "object", "nullable": true }, "category": { "type": "object", "nullable": true }, "window_days": { "type": "integer", "example": 30 }, "min_confidence": { "type": "number", "format": "float", "example": 0.5 }, "flow": { "type": "array", "nullable": true, "description": "Distinct sites per destination technology, corpus-wide and not capped by `limit`. Best-effort — `null` if the query timed out.", "items": { "type": "object", "properties": { "to_id": { "type": "integer", "example": 402 }, "to_name": { "type": "string", "example": "WooCommerce" }, "sites": { "type": "integer", "example": 69 } } } }, "switches": { "type": "array", "items": { "$ref": "#/components/schemas/SwitchEvent" } }, "firmographics": { "$ref": "#/components/schemas/FirmographicsEcho" }, "count": { "type": "integer", "example": 1 } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/signals/whitespace": { "get": { "operationId": "getCategoryWhitespace", "summary": "Category whitespace API", "description": "Greenfield prospecting: domains that **have** a qualifying anchor technology but run **no tool at all** in a target category. The structural inverse of adoption — not who just bought, but who visibly has not yet.\n\nThis is a current-state signal rather than a transition, so there is no `window` parameter. It is also the cheapest signal to run, and supports offset pagination because matches routinely run into the millions.\n\nCosts 1 credit.", "tags": [ "Signals" ], "parameters": [ { "name": "technology_id", "in": "query", "required": false, "description": "Scope by BuiltWith technology id. Provide exactly one of `technology_id`, `technology` or `category_id`.", "schema": { "type": "integer" }, "example": 2184 }, { "name": "technology", "in": "query", "required": false, "description": "Scope by exact technology name. The technology must be detectable.", "schema": { "type": "string" }, "example": "Shopify" }, { "name": "category_id", "in": "query", "required": false, "description": "Scope by category — fans out to every detectable technology whose *primary* category is this one.", "schema": { "type": "integer" }, "example": 202 }, { "name": "missing_category_id", "in": "query", "required": false, "description": "**Required.** The category the domain must run no tool in. Must differ from the anchor category.", "schema": { "type": "integer" }, "example": 202 }, { "name": "min_confidence", "in": "query", "required": false, "description": "Minimum `detection_rate` gating the *anchor* presence. The gap side counts any active detection, which is deliberately conservative.", "schema": { "type": "number", "format": "float", "default": 0.5 } }, { "name": "limit", "in": "query", "required": false, "description": "Rows returned. Clamped to 1–1000.", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset, clamped to 0–1,000,000. Results are ordered alphabetically by domain, so paging is stable within one corpus generation.", "schema": { "type": "integer", "default": 0 } }, { "$ref": "#/components/parameters/FirmoCountry" }, { "$ref": "#/components/parameters/FirmoCity" }, { "$ref": "#/components/parameters/FirmoState" }, { "$ref": "#/components/parameters/FirmoIndustry" }, { "$ref": "#/components/parameters/FirmoIndustryCode" }, { "$ref": "#/components/parameters/FirmoEmployees" }, { "$ref": "#/components/parameters/FirmoCompanyType" }, { "$ref": "#/components/parameters/FirmoFoundedMin" }, { "$ref": "#/components/parameters/FirmoFoundedMax" }, { "$ref": "#/components/parameters/FirmoCompany" }, { "$ref": "#/components/parameters/WebHasEmail" }, { "$ref": "#/components/parameters/WebHasPhone" }, { "$ref": "#/components/parameters/WebSocial" }, { "$ref": "#/components/parameters/WebLanguage" }, { "$ref": "#/components/parameters/WebCountry" }, { "$ref": "#/components/parameters/SegmentId" } ], "responses": { "200": { "description": "Domains with the anchor and no tool in the target category", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "signal": { "type": "object", "properties": { "type": { "type": "string", "example": "whitespace" }, "verb": { "type": "string", "example": "lacks" } } }, "anchor": { "type": "object", "description": "What the domains have.", "properties": { "kind": { "type": "string", "enum": [ "technology", "category" ] }, "technology": { "type": "object", "nullable": true }, "category": { "type": "object", "nullable": true } } }, "missing_category": { "type": "object", "description": "What the domains lack.", "properties": { "id": { "type": "integer", "example": 202 }, "name": { "type": "string", "example": "Email Marketing" }, "technology_count": { "type": "integer", "example": 37 } } }, "min_confidence": { "type": "number", "format": "float", "example": 0.5 }, "total_sites": { "type": "integer", "nullable": true, "description": "Corpus-wide count of whitespace domains, not capped by `limit`.", "example": 911747 }, "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string", "example": "0-5.fr" }, "company": { "$ref": "#/components/schemas/CompanyCard" } } } }, "firmographics": { "$ref": "#/components/schemas/FirmographicsEcho" }, "limit": { "type": "integer", "example": 100 }, "offset": { "type": "integer", "example": 0 }, "count": { "type": "integer", "example": 1 } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/signals/churn/validate": { "post": { "operationId": "validateChurn", "summary": "Validate churn signals API", "description": "Actively re-detect churn candidates right now and return a reasoned verdict per item. The statistical accuracy layers grade a churn from history; this endpoint settles it by loading the site again with a browser and consent-banner clicks, so it sees more than the bulk crawl did.\n\n**Billing is per domain, charged after completion:** roughly 2 credits for a fetch-mode check and 5 for a browser-mode check. An `inconclusive` result is never charged. Verdicts are cached for 48 hours per `(domain, technology_id)` pair — a repeat call returns the stored verdict with `cached: true`, with no re-crawl and no charge.", "tags": [ "Signals" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "description": "The churn candidates to re-check. Maximum 10 items in `auto` or `browser` mode, 100 in `fetch` mode.", "items": { "type": "object", "required": [ "domain", "technology_id" ], "properties": { "domain": { "type": "string", "example": "sandovalcountynm.gov" }, "technology_id": { "type": "integer", "example": 300 } } } }, "mode": { "type": "string", "enum": [ "auto", "fetch", "browser" ], "default": "auto", "description": "`auto` routes high-reliability technologies to a fast fetch and everything else straight to a browser, escalating weak fetch results once. `fetch` parallelises at roughly 1–3 seconds per item. `browser` takes 30–60 seconds per item." }, "interact": { "type": "boolean", "default": true, "description": "Click consent banners so consent-gated tags fire." } } }, "example": { "items": [ { "domain": "sandovalcountynm.gov", "technology_id": 300 } ], "mode": "auto", "interact": true } } } }, "responses": { "200": { "description": "A verdict per submitted item", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string", "example": "sandovalcountynm.gov" }, "technology_id": { "type": "integer", "example": 300 }, "verdict": { "type": "string", "enum": [ "confirmed", "false_positive", "masked", "inconclusive" ], "description": "`confirmed` — absent on a healthy re-detection, a genuine removal. `false_positive` — still detected live, so the churn was a prior crawl miss. `masked` — a header-detected origin web server is now behind a CDN or proxy, which is a detection change rather than a removal. `inconclusive` — unreachable, blocked or too little signal; never cached and never charged.", "example": "confirmed" }, "still_detected": { "type": "boolean", "example": false }, "newly_detected": { "type": "array", "items": { "type": "string" }, "example": [ "Cloudflare" ] }, "mode_used": { "type": "string", "enum": [ "fetch", "browser" ], "example": "browser" }, "cached": { "type": "boolean", "description": "The verdict came from the 48-hour cache; nothing was re-crawled or charged.", "example": false }, "credits_charged": { "type": "integer", "example": 5 }, "reason": { "type": "string" } } } }, "credits_charged": { "type": "integer", "description": "Total charged for this request.", "example": 5 } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/domain/{domain}/changes": { "get": { "operationId": "getDomainChanges", "summary": "Get domain tech changes API", "description": "What a single domain recently **added** and **dropped**, with the same accuracy stack as the Signals API — the same confidence score, the same first-seen gate and the same churn guards. This is the domain-scoped sibling of the adoption and churn signals, which are technology- or category-scoped.\n\nUse it to power an account watch view: `GET /v1/domain/{domain}` tells you what a domain runs today, and this tells you what changed.\n\nCosts 1 credit.", "tags": [ "Domain technologies" ], "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "The domain to inspect (for example `shopify.com`).", "schema": { "type": "string", "example": "shopify.com" } }, { "name": "window", "in": "query", "required": false, "description": "Look-back window in days, 1–365. The response's summary buckets cover `min(window, bucket)`.", "schema": { "type": "integer", "default": 90, "minimum": 1, "maximum": 365 } }, { "name": "include_first_seen", "in": "query", "required": false, "description": "`true` disables the first-seen gate on adoptions, turning the feed into newly-observed technologies rather than genuine adoptions. Echoed back as `excludes_first_seen`.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Adoption and churn events for this domain", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "domain": { "type": "string", "example": "shopify.com" }, "window_days": { "type": "integer", "example": 90 }, "excludes_first_seen": { "type": "boolean", "example": true }, "summary": { "type": "object", "description": "Counts bucketed by window. The 90-day bucket includes the 30-day one.", "properties": { "30d": { "type": "object", "properties": { "added": { "type": "integer", "example": 3 }, "dropped": { "type": "integer", "example": 1 } } }, "90d": { "type": "object", "properties": { "added": { "type": "integer", "example": 7 }, "dropped": { "type": "integer", "example": 2 } } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "adoption", "churn" ], "example": "adoption" }, "technology_id": { "type": "integer", "example": 2184 }, "technology_name": { "type": "string", "example": "Shopify" }, "category": { "type": "string", "nullable": true, "example": "Ecommerce Platforms" }, "subdomain": { "type": "string", "example": "WWW.SHOPIFY.COM" }, "detection_url": { "type": "string", "example": "https://www.shopify.com" }, "event_at": { "type": "string", "example": "2026-05-31 14:10:33" }, "detection_count": { "type": "integer", "example": 6 }, "detection_rate": { "type": "number", "format": "float", "example": 0.86 }, "churn_reliability": { "type": "string", "nullable": true }, "confidence": { "$ref": "#/components/schemas/SignalConfidence" } } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/alerts": { "get": { "operationId": "listAlerts", "summary": "List alerts API", "description": "List every alert owned by the calling API key, with its status, last fire time, consecutive failure count and your plan's alert limit. Free — alert management never consumes credits.", "tags": [ "Alerts" ], "responses": { "200": { "description": "Your alerts and the plan limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "alerts": { "type": "array", "items": { "$ref": "#/components/schemas/Alert" } }, "count": { "type": "integer", "example": 3 }, "limit": { "type": "integer", "description": "Maximum alerts on your plan.", "example": 5 } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createAlert", "summary": "Create alert API", "description": "Save a signal query plus a webhook URL. From then on an hourly sweep delivers only the **new** events since the last successful delivery, signed with HMAC-SHA256.\n\nProvide exactly one scope: `technology_id`, `technology`, `category_id`, `domains` or `segment_id`. Scope is immutable after creation because the watermark's meaning is bound to it — delete and recreate to change it.\n\nThe response includes the `webhook_secret` (prefixed `whsec_`). **Store it now** — it signs every delivery and is only returned here and on the detail endpoint.\n\nCreation runs a hot-scope guard: a scope producing more events per hour than the 100-events-per-delivery cap can never drain its backlog, so it is rejected with `HOT_SCOPE` and guidance to narrow. Free — alerts are a plan entitlement, not a metered call.", "tags": [ "Alerts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "signal_types", "webhook_url" ], "properties": { "name": { "type": "string", "example": "Who leaves Shopify (US, 51-200)" }, "signal_types": { "type": "array", "items": { "type": "string", "enum": [ "churn", "adoption", "switch" ] }, "description": "`[\"churn\",\"adoption\"]` means any stack change, which is the natural account watch. `switch` cannot be combined with the others because its event shape differs.", "example": [ "switch" ] }, "technology_id": { "type": "integer", "description": "Technology scope. Must be a detectable technology.", "example": 2184 }, "technology": { "type": "string", "description": "Technology scope by exact name." }, "category_id": { "type": "integer", "description": "Category scope. Re-resolved fresh at every sweep, so technologies added to the category are covered automatically." }, "domains": { "type": "array", "items": { "type": "string" }, "description": "Domains scope — the account watchlist. 1 to 1,000 domains (100 on Free). Normalized to lowercase and deduped; invalid entries are rejected with the offending values.", "example": [ "acme.com", "example.com" ] }, "segment_id": { "type": "string", "description": "Audience scope. List audiences only; membership resolves live at each sweep." }, "direction": { "type": "string", "enum": [ "from", "to" ], "default": "from", "description": "Switch alerts on a technology scope only. `from` is who left the anchor; `to` is who came to it." }, "missing_category_id": { "type": "integer", "description": "Turns an adoption alert into a whitespace-entrant alert. Requires `signal_types` of exactly `[\"adoption\"]`, a technology or category scope, and a category different from the anchor." }, "min_scans": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Whitespace precision gate. Defaults to 2 when `missing_category_id` is set." }, "filters": { "$ref": "#/components/schemas/AlertFilters" }, "webhook_url": { "type": "string", "format": "uri", "description": "HTTPS only. Private, internal and metadata hosts are rejected, and redirects are never followed.", "example": "https://example.com/hooks/tc" }, "delivery_frequency": { "type": "string", "enum": [ "hourly", "daily" ], "default": "daily", "description": "`daily` batches a day's events into one digest delivery. `hourly` is a per-sweep drip. Independent of `crawl_cadence`." }, "crawl_cadence": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "default": "monthly", "description": "Domains scope on a paid plan only. Buys re-scans of the watched domains so the underlying data refreshes as fast as the subscription. Forced to `monthly` on other scopes." }, "backfill_days": { "type": "integer", "minimum": 0, "maximum": 30, "default": 7, "description": "How far back the first sweep reaches. `0` means future events only." } }, "example": { "name": "Who leaves Shopify (US, 51-200)", "signal_types": [ "switch" ], "technology_id": 2184, "direction": "from", "filters": { "min_confidence": 0.5, "country": "united states", "employees": "51-200" }, "webhook_url": "https://example.com/hooks/tc", "backfill_days": 7 } } } } }, "responses": { "201": { "description": "Alert created. `webhook_secret` is returned here — store it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "alert": { "allOf": [ { "$ref": "#/components/schemas/Alert" }, { "type": "object", "properties": { "webhook_secret": { "type": "string", "example": "whsec_3f9a2b7c1d4e5f60" } } } ] } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/alerts/{id}": { "get": { "operationId": "getAlert", "summary": "Get alert API", "description": "Full detail for one alert, **including `webhook_secret`** — your consumer needs it to verify signatures. Another key's alert id returns 404. Free.", "tags": [ "Alerts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The alert id.", "schema": { "type": "string", "example": "alrt_9f2c4a1e" } } ], "responses": { "200": { "description": "Alert detail including the webhook secret", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "alert": { "allOf": [ { "$ref": "#/components/schemas/Alert" }, { "type": "object", "properties": { "webhook_secret": { "type": "string", "example": "whsec_3f9a2b7c1d4e5f60" } } } ] } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "updateAlert", "summary": "Update alert API", "description": "Edit an alert's name, status, webhook URL, filters, crawl cadence or delivery frequency.\n\n**Scope is immutable** — delete and recreate to change what the alert watches. Setting `status` back to `active` on a disabled alert re-enables it with a clean slate; the resumed sweep reaches back at most 7 days and the next payload carries a `gap` note saying so. Free.", "tags": [ "Alerts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The alert id.", "schema": { "type": "string", "example": "alrt_9f2c4a1e" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "webhook_url": { "type": "string", "format": "uri" }, "filters": { "$ref": "#/components/schemas/AlertFilters" }, "crawl_cadence": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] }, "delivery_frequency": { "type": "string", "enum": [ "hourly", "daily" ] } }, "example": { "status": "paused" } } } } }, "responses": { "200": { "description": "The updated alert", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "alert": { "$ref": "#/components/schemas/Alert" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "deleteAlert", "summary": "Delete alert API", "description": "Delete an alert. Its delivery history is removed with it. Free.", "tags": [ "Alerts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The alert id.", "schema": { "type": "string", "example": "alrt_9f2c4a1e" } } ], "responses": { "200": { "description": "Alert deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/alerts/{id}/test": { "post": { "operationId": "testAlert", "summary": "Test alert delivery API", "description": "Fire a synthetic payload through the **real** delivery path — same headers, same HMAC signing, same timeout. The payload carries `\"test\": true`.\n\nUse it to exercise your signature verification end to end before relying on live deliveries. Rate-limited to roughly 10 per hour per key. Free.", "tags": [ "Alerts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The alert id.", "schema": { "type": "string", "example": "alrt_9f2c4a1e" } } ], "responses": { "200": { "description": "The test fire result, including how your endpoint responded", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "delivered": { "type": "boolean", "example": true }, "delivery_id": { "type": "string", "example": "dlv_7a1c3e9f" }, "response_status": { "type": "integer", "example": 200 }, "duration_ms": { "type": "integer", "example": 214 }, "error": { "type": "string", "nullable": true } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/alerts/{id}/deliveries": { "get": { "operationId": "listAlertDeliveries", "summary": "Alert delivery log API", "description": "The delivery history for one alert — what was sent, when, and whether your endpoint accepted it. This is the activity feed behind the dashboard and the answer to \"what did you send me?\".\n\nDeliveries older than 30 days are pruned, always keeping the newest 20 per alert. Free.", "tags": [ "Alerts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The alert id.", "schema": { "type": "string", "example": "alrt_9f2c4a1e" } }, { "name": "limit", "in": "query", "required": false, "description": "Deliveries returned. Maximum 100.", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset.", "schema": { "type": "integer", "default": 0 } }, { "name": "include_events", "in": "query", "required": false, "description": "Embed the delivered event rows in each record. Opt-in because the payload can reach roughly 30KB per delivery.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Delivery records, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "dlv_7a1c3e9f" }, "fired_at": { "type": "string", "example": "2026-06-10 17:39:39" }, "event_count": { "type": "integer", "example": 3 }, "truncated": { "type": "boolean", "description": "More events existed than the 100-per-delivery cap; the remainder arrives on the next sweep.", "example": false }, "is_test": { "type": "boolean", "example": false }, "response_status": { "type": "integer", "nullable": true, "example": 200 }, "success": { "type": "boolean", "example": true }, "duration_ms": { "type": "integer", "example": 214 }, "error": { "type": "string", "nullable": true }, "events": { "type": "array", "description": "Only present when `include_events=true`.", "items": { "$ref": "#/components/schemas/SignalEvent" } } } } }, "count": { "type": "integer", "example": 20 }, "limit": { "type": "integer", "example": 20 }, "offset": { "type": "integer", "example": 0 } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/segments": { "get": { "operationId": "listAudiences", "summary": "List audiences API", "description": "List every audience saved by the calling API key, newest first, along with your plan's audience count limit and computed-member cap. Free.", "tags": [ "Audiences" ], "responses": { "200": { "description": "Your audiences and plan limits", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "segments": { "type": "array", "items": { "$ref": "#/components/schemas/Audience" } }, "count": { "type": "integer", "example": 3 }, "limit": { "type": "integer", "description": "Maximum saved audiences on your plan.", "example": 10 }, "member_limit": { "type": "integer", "description": "Maximum members a computed audience may build to on your plan.", "example": 10000 } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createAudience", "summary": "Create audience API", "description": "Create an audience in one of two ways.\n\n**Upload a list** — pass `type: \"list\"` and a `domains` array. Domains are lowercased, stripped of scheme, path and a leading `www.`, then deduped before the plan cap is checked, so pasting a raw export with duplicates does not eat your cap. Uploads are **free**.\n\n**Compute a recipe** — pass a `definition` with a `kind` of `firmo`, `technology` or `signal`. The recipe is materialized into a membership snapshot at create time and **costs 1 credit**, charged after the build completes. A build that exceeds your plan's member cap is rejected rather than sampled, so an audience is always complete.\n\nMembership is a point-in-time snapshot, not a live query. Re-send the definition with `PATCH` to refresh it.", "tags": [ "Audiences" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Uploaded list", "required": [ "name", "type", "domains" ], "properties": { "name": { "type": "string", "maxLength": 120, "example": "YC W25 portfolio" }, "type": { "type": "string", "enum": [ "list" ] }, "domains": { "type": "array", "items": { "type": "string" }, "description": "1 to your plan's cap: 100 on Free, 2,500 on Pro, 10,000 on Scale, 100,000 on Enterprise.", "example": [ "acme.com", "example.com" ] } } }, { "type": "object", "title": "Computed recipe", "required": [ "name", "definition" ], "properties": { "name": { "type": "string", "maxLength": 120, "example": "US ecommerce, 51-200" }, "definition": { "$ref": "#/components/schemas/AudienceDefinition" } } } ], "example": { "name": "US ecommerce, 51-200", "definition": { "kind": "technology", "technologies": { "and": [ 2184 ] }, "country": "united states", "employees": "51-200" } } } } } }, "responses": { "201": { "description": "Audience created, with corpus coverage", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "segment": { "$ref": "#/components/schemas/Audience" }, "coverage": { "type": "object", "description": "How many members we hold detection data for. Computed audiences are in-corpus by construction.", "properties": { "in_corpus": { "type": "integer", "nullable": true, "example": 5114 }, "total": { "type": "integer", "example": 5914 } } }, "rejected_domains": { "type": "object", "description": "Present when uploaded entries failed normalization.", "properties": { "count": { "type": "integer", "example": 2 }, "sample": { "type": "array", "items": { "type": "string" } } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/QueryTimeout" } } } }, "/v1/segments/{id}": { "get": { "operationId": "getAudience", "summary": "Get audience API", "description": "Detail for one audience, including its definition, member count, build status and crawl cadence. Another key's audience id returns 404. Free.", "tags": [ "Audiences" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The audience id.", "schema": { "type": "string", "example": "seg_8f3a2c1b" } } ], "responses": { "200": { "description": "Audience detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "segment": { "$ref": "#/components/schemas/Audience" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "updateAudience", "summary": "Update audience API", "description": "Rename an audience, replace its membership, or set its crawl cadence.\n\n**Renaming alone is free** and never touches membership. Sending `definition` rebuilds the audience and **costs 1 credit** — presence of the field triggers the rebuild with no diffing, which is deliberately the only way to refresh a snapshot. Sending `domains` replaces an uploaded list's membership, also free.\n\nMembership replacement is a generation flip: the new set is written in full and the pointer moves only after a verified complete insert, so a reader mid-update always sees the complete old membership rather than a partial new one.\n\n`type` and `kind` are immutable. Signal audiences cannot be edited — save a new one from Signals instead.", "tags": [ "Audiences" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The audience id.", "schema": { "type": "string", "example": "seg_8f3a2c1b" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 }, "domains": { "type": "array", "items": { "type": "string" }, "description": "List audiences only. Full replacement, not a delta." }, "definition": { "$ref": "#/components/schemas/AudienceDefinition" }, "crawl_cadence": { "type": "string", "enum": [ "none", "weekly", "daily" ], "description": "Re-scan cadence for this audience's members. Weekly and daily require a paid plan and are metered at 1 credit per dispatched domain." } }, "example": { "name": "US ecommerce, 51-200 (refreshed)", "crawl_cadence": "weekly" } } } } }, "responses": { "200": { "description": "The updated audience", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "segment": { "$ref": "#/components/schemas/Audience" }, "coverage": { "type": "object", "properties": { "in_corpus": { "type": "integer", "nullable": true }, "total": { "type": "integer" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/QueryTimeout" } } }, "delete": { "operationId": "deleteAudience", "summary": "Delete audience API", "description": "Delete an audience and its membership. There is no credit refund for a computed audience. Free.", "tags": [ "Audiences" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The audience id.", "schema": { "type": "string", "example": "seg_8f3a2c1b" } } ], "responses": { "200": { "description": "Audience deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/segments/{id}/domains": { "get": { "operationId": "listAudienceMembers", "summary": "List audience members API", "description": "A page of the audience's member domains in the current generation, ordered alphabetically, plus the total and the build timestamp. Works for every audience kind. Free.", "tags": [ "Audiences" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The audience id.", "schema": { "type": "string", "example": "seg_8f3a2c1b" } }, { "name": "limit", "in": "query", "required": false, "description": "Domains per page. Clamped to 1–100.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "A page of member domains", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "segment": { "type": "object", "properties": { "id": { "type": "string", "example": "seg_8f3a2c1b" }, "name": { "type": "string", "example": "YC W25 portfolio" }, "type": { "type": "string", "example": "list" }, "kind": { "type": "string", "example": "upload" }, "status": { "type": "string", "example": "ready" }, "membership_at": { "type": "string", "nullable": true } } }, "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string", "example": "acme.com" } } } }, "total": { "type": "integer", "example": 5914 }, "limit": { "type": "integer", "example": 50 }, "offset": { "type": "integer", "example": 0 } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/QueryTimeout" } } } }, "/v1/segments/{id}/technologies": { "get": { "operationId": "getAudienceTechnologies", "summary": "Audience technology report API", "description": "What does this group of companies actually run? Per-technology active domain counts across the audience's membership, with penetration as a share of the members we hold data for.\n\nThe response includes a `freshness` block — median last-scan age and the share of members scanned within 7 and 30 days. Under a rolling crawl, \"how current is this data\" is a distribution rather than a yes or no, and this is the honest answer.\n\nAdd inline firmographic parameters to slice the group before the rollup, so coverage, penetration and freshness all describe the slice (for example your portfolio list intersected with US companies) rather than the whole list.\n\nCosts 1 credit.", "tags": [ "Audiences" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The audience id.", "schema": { "type": "string", "example": "seg_8f3a2c1b" } }, { "$ref": "#/components/parameters/FirmoCountry" }, { "$ref": "#/components/parameters/FirmoCity" }, { "$ref": "#/components/parameters/FirmoState" }, { "$ref": "#/components/parameters/FirmoIndustry" }, { "$ref": "#/components/parameters/FirmoIndustryCode" }, { "$ref": "#/components/parameters/FirmoEmployees" }, { "$ref": "#/components/parameters/FirmoCompanyType" }, { "$ref": "#/components/parameters/FirmoFoundedMin" }, { "$ref": "#/components/parameters/FirmoFoundedMax" }, { "$ref": "#/components/parameters/WebHasEmail" }, { "$ref": "#/components/parameters/WebHasPhone" }, { "$ref": "#/components/parameters/WebSocial" }, { "$ref": "#/components/parameters/WebLanguage" }, { "$ref": "#/components/parameters/WebCountry" } ], "responses": { "200": { "description": "Per-technology counts, penetration and data freshness", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "segment": { "type": "object", "properties": { "id": { "type": "string", "example": "seg_8f3a2c1b" }, "name": { "type": "string", "example": "YC W25 portfolio" }, "type": { "type": "string", "example": "list" }, "kind": { "type": "string", "example": "upload" }, "domain_count": { "type": "integer", "example": 5914 } } }, "coverage": { "type": "object", "properties": { "in_corpus": { "type": "integer", "description": "Members we hold detection data for. This is the denominator for penetration and freshness.", "example": 5114 }, "total": { "type": "integer", "example": 5914 }, "note": { "type": "string" } } }, "firmographics": { "$ref": "#/components/schemas/FirmographicsEcho" }, "freshness": { "type": "object", "properties": { "median_age_days": { "type": "integer", "nullable": true, "example": 12 }, "scanned_7d_pct": { "type": "number", "format": "float", "nullable": true, "example": 31.4 }, "scanned_30d_pct": { "type": "number", "format": "float", "nullable": true, "example": 88.2 } } }, "technologies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 2 }, "name": { "type": "string", "example": "Cloudflare" }, "category": { "type": "string", "nullable": true, "example": "CDN" }, "domains": { "type": "integer", "example": 1785 }, "penetration": { "type": "number", "format": "float", "nullable": true, "description": "Share of in-corpus members running this technology.", "example": 0.663 } } } }, "count": { "type": "integer", "example": 250 }, "generated_at": { "type": "string", "example": "2026-07-29T10:20:11.000Z" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/QueryTimeout" } } } }, "/v1/segments/{id}/breakdown": { "get": { "operationId": "getAudienceBreakdown", "summary": "Audience composition breakdown API", "description": "Who is in this group — its composition along one dimension. Firmographic dimensions group members by normalized values, so display shares the same vocabulary the filters take. `by=category` instead rolls the group's stack up per category using server-side distinct-domain counts, which is the correct way to do it: summing the technology report's per-technology numbers double-counts domains running more than one tool in a category.\n\nComposable with the same inline firmographic parameters as the technology report, so you can ask for the industry breakdown of the US slice.\n\nCosts 1 credit.", "tags": [ "Audiences" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The audience id.", "schema": { "type": "string", "example": "seg_8f3a2c1b" } }, { "name": "by", "in": "query", "required": true, "description": "The dimension to group by.", "schema": { "type": "string", "enum": [ "country", "industry", "employees", "company_type", "language", "web_country", "category" ], "example": "country" } }, { "$ref": "#/components/parameters/FirmoCountry" }, { "$ref": "#/components/parameters/FirmoCity" }, { "$ref": "#/components/parameters/FirmoState" }, { "$ref": "#/components/parameters/FirmoIndustry" }, { "$ref": "#/components/parameters/FirmoIndustryCode" }, { "$ref": "#/components/parameters/FirmoEmployees" }, { "$ref": "#/components/parameters/FirmoCompanyType" }, { "$ref": "#/components/parameters/FirmoFoundedMin" }, { "$ref": "#/components/parameters/FirmoFoundedMax" }, { "$ref": "#/components/parameters/WebHasEmail" }, { "$ref": "#/components/parameters/WebHasPhone" }, { "$ref": "#/components/parameters/WebSocial" }, { "$ref": "#/components/parameters/WebLanguage" }, { "$ref": "#/components/parameters/WebCountry" } ], "responses": { "200": { "description": "Member counts and shares per dimension value, top 50", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "segment": { "type": "object" }, "by": { "type": "string", "example": "country" }, "total": { "type": "integer", "example": 5914 }, "matched": { "type": "integer", "description": "Members with data on this dimension. This is the share denominator.", "example": 4459 }, "coverage_note": { "type": "string" }, "firmographics": { "$ref": "#/components/schemas/FirmographicsEcho" }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "example": "united states" }, "members": { "type": "integer", "example": 3091 }, "share_of_matched": { "type": "number", "format": "float", "nullable": true, "example": 0.693 } } } }, "count": { "type": "integer", "example": 50 }, "generated_at": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/QueryTimeout" } } } }, "/v1/segments/stats": { "get": { "operationId": "getSegmentTechnologyStats", "summary": "Segment technology stats API", "description": "How much of one technology's live footprint belongs to a slice of companies. Returns three self-consistent counts from a single pass, so `segment_domains ≤ matched_domains ≤ live_active_domains` always holds:\n\n- `live_active_domains` — domains currently running the technology\n- `matched_domains` — of those, the ones with a matched company record\n- `segment_domains` — of those, the ones passing your predicates\n\nRequires a technology scope and **at least one** firmographic predicate, or a saved `segment_id`. Without a predicate this would just re-derive global stats expensively, so it is rejected.\n\nResults are cached for 24 hours. **Cache hits still cost 1 credit** — a cache tuning must never become a silent price change.", "tags": [ "Audiences" ], "parameters": [ { "name": "technology_id", "in": "query", "required": false, "description": "The technology to measure. Provide this or `technology`.", "schema": { "type": "integer" }, "example": 2184 }, { "name": "technology", "in": "query", "required": false, "description": "The technology to measure, by exact name.", "schema": { "type": "string" }, "example": "Shopify" }, { "$ref": "#/components/parameters/FirmoCountry" }, { "$ref": "#/components/parameters/FirmoCity" }, { "$ref": "#/components/parameters/FirmoState" }, { "$ref": "#/components/parameters/FirmoIndustry" }, { "$ref": "#/components/parameters/FirmoIndustryCode" }, { "$ref": "#/components/parameters/FirmoEmployees" }, { "$ref": "#/components/parameters/FirmoCompanyType" }, { "$ref": "#/components/parameters/FirmoFoundedMin" }, { "$ref": "#/components/parameters/FirmoFoundedMax" }, { "$ref": "#/components/parameters/WebHasEmail" }, { "$ref": "#/components/parameters/WebHasPhone" }, { "$ref": "#/components/parameters/WebSocial" }, { "$ref": "#/components/parameters/WebLanguage" }, { "$ref": "#/components/parameters/WebCountry" }, { "$ref": "#/components/parameters/SegmentId" } ], "responses": { "200": { "description": "Three self-consistent counts plus the share of matched companies", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "technology": { "type": "object", "properties": { "id": { "type": "integer", "example": 2184 }, "name": { "type": "string", "example": "Shopify" }, "category": { "type": "string", "nullable": true, "example": "Ecommerce Platforms" } } }, "segment": { "type": "object", "properties": { "applied": { "type": "object", "additionalProperties": true, "example": { "country": "united states", "employees": "51-200" } }, "coverage_note": { "type": "string" } } }, "stats": { "type": "object", "properties": { "live_active_domains": { "type": "integer", "example": 2314529 }, "matched_domains": { "type": "integer", "example": 578632 }, "segment_domains": { "type": "integer", "example": 32311 }, "segment_share_of_matched": { "type": "number", "format": "float", "nullable": true, "example": 0.0559 } } }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean", "example": false }, "age_seconds": { "type": "integer", "example": 0 } } }, "generated_at": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/QueryTimeout" } } } }, "/v1/segments/{id}/crawl": { "post": { "operationId": "refreshAudienceCrawl", "summary": "Refresh audience crawl API", "description": "Dispatch a one-off re-crawl of the audience's members so their technology data refreshes now instead of waiting for the rolling corpus crawl.\n\nMembers scanned within the last 7 days are skipped as already fresh and are **not charged**. Everything else is dispatched at **1 credit per domain**. Members beyond the nightly fleet budget are deferred to a later night and are also not charged.\n\nPaid plans only. An audience dispatched within the last 24 hours returns `REFRESH_PENDING` — those crawls are still landing.", "tags": [ "Audiences" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The audience id.", "schema": { "type": "string", "example": "seg_8f3a2c1b" } } ], "responses": { "200": { "description": "Dispatch summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "resolved": { "type": "integer", "description": "Members considered.", "example": 5914 }, "dispatched": { "type": "integer", "description": "Domains sent to the crawler and charged.", "example": 812 }, "skipped_fresh": { "type": "integer", "description": "Scanned within 7 days, not charged.", "example": 5102 }, "deferred": { "type": "integer", "description": "Beyond tonight's fleet budget, not charged.", "example": 0 }, "credits_charged": { "type": "integer", "example": 812 }, "request_ids": { "type": "array", "items": { "type": "string" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/QueryTimeout" } } } }, "/v1/segments/{id}/crawls": { "get": { "operationId": "getAudienceCrawlHistory", "summary": "Audience crawl history API", "description": "The last 30 crawl dispatches for this audience — scheduled and one-off — plus lifetime totals for domains dispatched and credits charged. Free.", "tags": [ "Audiences" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The audience id.", "schema": { "type": "string", "example": "seg_8f3a2c1b" } } ], "responses": { "200": { "description": "Dispatch history and totals", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "segment": { "type": "object", "properties": { "id": { "type": "string", "example": "seg_8f3a2c1b" }, "name": { "type": "string", "example": "YC W25 portfolio" } } }, "crawl_cadence": { "type": "string", "example": "weekly" }, "last_dispatched_at": { "type": "string", "nullable": true }, "totals": { "type": "object", "properties": { "crawls": { "type": "integer", "example": 6 }, "domains_dispatched": { "type": "integer", "example": 4212 }, "credits_charged": { "type": "integer", "example": 4212 } } }, "crawls": { "type": "array", "items": { "type": "object", "properties": { "dispatched_at": { "type": "string", "example": "2026-08-20 03:00:12" }, "source": { "type": "string", "enum": [ "cadence", "on-demand" ], "example": "cadence" }, "domains_dispatched": { "type": "integer", "example": 812 }, "domains_skipped_fresh": { "type": "integer", "example": 5102 }, "domains_deferred": { "type": "integer", "example": 0 }, "credits_charged": { "type": "integer", "example": 812 }, "request_ids": { "type": "array", "items": { "type": "string" } } } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/leads/technologies/search": { "get": { "operationId": "searchLeadTechnologies", "summary": "Search technologies for lead lists API", "description": "Search technologies by name and get their live domain counts, so you can size a filter before you build a list. Free.", "tags": [ "Lead lists" ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query, minimum 2 characters.", "schema": { "type": "string", "minLength": 2, "example": "cloudflare" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum results. Capped at 50.", "schema": { "type": "integer", "default": 20, "maximum": 50 } } ], "responses": { "200": { "description": "Matching technologies with domain counts", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "technologies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 2 }, "name": { "type": "string", "example": "Cloudflare" }, "category": { "type": "string", "example": "CDN" }, "icon_url": { "type": "string" }, "domain_count": { "type": "integer", "example": 4954630 } } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/leads/tech-map": { "get": { "operationId": "getTechnologyMap", "summary": "Technology ID map API", "description": "The full technology id to name and category mapping, for resolving the `technology_ids` arrays that list previews return. Cached for 24 hours — fetch it once and keep it. Free.", "tags": [ "Lead lists" ], "responses": { "200": { "description": "The complete technology map", "headers": { "Cache-Control": { "description": "`public, max-age=86400`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "technologies": { "type": "object", "additionalProperties": { "type": "object", "properties": { "name": { "type": "string" }, "category": { "type": "string" } } }, "example": { "2": { "name": "Cloudflare", "category": "CDN" } } }, "count": { "type": "integer", "example": 28402 }, "last_updated": { "type": "string", "example": "2026-01-15T00:00:00Z" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/leads/preview-count": { "post": { "operationId": "previewLeadListCount", "summary": "Preview lead list count API", "description": "Estimate how many domains a filter set will match, and what building it would cost, before you commit. Free — use it as the live counter on a filter builder.\n\nThe estimate is a fast approximation and results are cached for 5 minutes per filter set. Billing always happens on the actual row count, never on this number.", "tags": [ "Lead lists" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadListFilters" }, "example": { "technologies": { "ids": [ 2, 7 ], "logic": "or" }, "keywords": { "include": [ "shop" ], "exclude": [ "health" ] }, "website_type": "company_only", "countries": [ "United States", "Germany" ], "industries": [ "Software Development" ], "employees": [ "51-200", "201-500" ] } } } }, "responses": { "200": { "description": "Estimated match count and credit cost", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "estimated_count": { "type": "integer", "example": 518300 }, "credit_cost": { "type": "integer", "description": "One credit per row delivered.", "example": 518300 }, "filters_applied": { "type": "object", "additionalProperties": { "type": "integer" }, "example": { "technologies": 2, "countries": 2, "industries": 1, "employees": 2 } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/leads/create": { "post": { "operationId": "createLeadList", "summary": "Create lead list API", "description": "Build a lead list from a filter set. The request returns immediately with `status: \"processing\"` and a background job assembles the rows — poll the list detail endpoint until it is `ready`.\n\n**Billing is 1 credit per delivered row, charged after the job completes.** Nothing is charged upfront and a failed job charges nothing, so there is no refund path to worry about. At create time we only check that your balance covers `list_size`, the maximum the job could deliver; if your balance is lower the list is capped to it.\n\nLists expire after 60 days. Concurrency is capped per plan: 1 on Free, 3 on Pro, 5 on Scale, 10 on Enterprise.", "tags": [ "Lead lists" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/LeadListFilters" }, { "type": "object", "required": [ "name", "list_size" ], "properties": { "name": { "type": "string", "example": "US SaaS Companies using Cloudflare" }, "list_size": { "type": "integer", "minimum": 1000, "maximum": 100000, "description": "Maximum rows to deliver, and therefore the maximum charge.", "example": 10000 }, "segment_id": { "type": "string", "description": "Export a saved audience as a lead list instead of specifying technology filters.", "example": "seg_8f3a2c1b" }, "selected_columns": { "type": "array", "items": { "type": "string" }, "example": [ "domain", "company_name", "linkedin_url" ] } } } ], "example": { "name": "US SaaS Companies using Cloudflare", "technologies": { "ids": [ 2 ], "logic": "or" }, "countries": [ "United States" ], "industries": [ "Software Development" ], "employees": [ "51-200", "201-500" ], "has_email": true, "list_size": 10000 } } } } }, "responses": { "200": { "description": "The list was accepted and is being built", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "list_id": { "type": "string", "format": "uuid", "example": "f6ab2d94-c34f-47b7-9d1a-228e71488cd2" }, "status": { "type": "string", "example": "processing" }, "estimated_count": { "type": "integer", "example": 10000 }, "credits_charged": { "type": "integer", "description": "Charged after completion, on the actual row count.", "example": 10000 }, "created_at": { "type": "string", "example": "2026-01-15T19:19:21.179Z" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/leads/lists": { "get": { "operationId": "listLeadLists", "summary": "List lead lists API", "description": "Every lead list owned by the calling API key, with status and a filter summary. Free.", "tags": [ "Lead lists" ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string", "enum": [ "processing", "ready", "failed", "expired" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page. Capped at 100.", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset.", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Your lead lists", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "lists": { "type": "array", "items": { "$ref": "#/components/schemas/LeadList" } }, "total": { "type": "integer", "example": 1 }, "limit": { "type": "integer", "example": 20 }, "offset": { "type": "integer", "example": 0 } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/leads/lists/{id}": { "get": { "operationId": "getLeadList", "summary": "Get lead list API", "description": "Detail for one lead list including its full filter set, row counts, credits charged and the `can_preview` / `can_download` flags. Poll this after `POST /v1/leads/create` until `status` is `ready`. Free.", "tags": [ "Lead lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The lead list id.", "schema": { "type": "string", "format": "uuid", "example": "f6ab2d94-c34f-47b7-9d1a-228e71488cd2" } } ], "responses": { "200": { "description": "Lead list detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/LeadList" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "deleteLeadList", "summary": "Delete lead list API", "description": "Delete a lead list and its results. Lists in any status can be deleted. There is no credit refund for a list you already paid for. Free.", "tags": [ "Lead lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The lead list id.", "schema": { "type": "string", "format": "uuid", "example": "f6ab2d94-c34f-47b7-9d1a-228e71488cd2" } } ], "responses": { "200": { "description": "List deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true }, "list_id": { "type": "string", "format": "uuid" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/leads/lists/{id}/preview": { "get": { "operationId": "previewLeadList", "summary": "Preview lead list API", "description": "Page through a finished list's rows with sorting and search. The preview returns **everything the list holds** — all 14 stored company columns plus the crawl-sourced `web` block — so what you see here is exactly what the export ships. Free.", "tags": [ "Lead lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The lead list id.", "schema": { "type": "string", "format": "uuid", "example": "f6ab2d94-c34f-47b7-9d1a-228e71488cd2" } }, { "name": "limit", "in": "query", "required": false, "description": "Rows per page. Capped at 100.", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset.", "schema": { "type": "integer", "default": 0 } }, { "name": "sort_by", "in": "query", "required": false, "description": "Column to sort by.", "schema": { "type": "string", "enum": [ "domain", "company_name", "country", "industry", "employees" ] } }, { "name": "sort_order", "in": "query", "required": false, "description": "Sort direction.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } }, { "name": "search", "in": "query", "required": false, "description": "Filter rows by domain or company name.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of list rows", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/LeadListRow" } }, "total": { "type": "integer", "example": 1000 }, "limit": { "type": "integer", "example": 50 }, "offset": { "type": "integer", "example": 0 } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/leads/lists/{id}/export": { "get": { "operationId": "exportLeadList", "summary": "Export lead list API", "description": "Download a finished list as CSV or newline-delimited JSON, with technology names resolved from ids. The response streams straight from the database and supports lists up to 100,000 rows.\n\nEvery export carries the contact columns — `emails`, `phones` and five social profile URLs reconstructed from handles found during the crawl. Free: you already paid per row when the list was built.", "tags": [ "Lead lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The lead list id.", "schema": { "type": "string", "format": "uuid", "example": "f6ab2d94-c34f-47b7-9d1a-228e71488cd2" } }, { "name": "format", "in": "query", "required": true, "description": "Output format.", "schema": { "type": "string", "enum": [ "csv", "json" ], "example": "csv" } } ], "responses": { "200": { "description": "The list as a downloadable file", "headers": { "Content-Disposition": { "description": "`attachment` with a generated filename.", "schema": { "type": "string" } } }, "content": { "text/csv": { "schema": { "type": "string", "format": "binary" }, "example": "\"domain\",\"detection_url\",\"technologies\",\"company_name\",\"emails\",\"phones\",\"social_linkedin\"\n\"example.com\",\"EXAMPLE.COM\",\"Cloudflare\",\"Example Corp\",\"hi@example.com\",\"+1 555 0100\",\"https://www.linkedin.com/company/example\"" }, "application/json": { "schema": { "type": "string", "format": "binary" }, "example": "{\"domain\":\"example.com\",\"technologies\":\"Cloudflare\",\"company_name\":\"Example Corp\"}\n{\"domain\":\"acme.com\",\"technologies\":\"Cloudflare, WordPress\",\"company_name\":\"Acme\"}" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key in format `tapi_live_[32-char]` (live) or `tapi_test_[32-char]` (test)" } }, "schemas": { "DomainTechnology": { "type": "object", "properties": { "id": { "type": "integer", "example": 2 }, "name": { "type": "string", "example": "Cloudflare" }, "category": { "type": "string", "example": "CDN" }, "first_seen": { "type": "string", "example": "2020-05-08 00:00:00" }, "last_seen": { "type": "string", "example": "2026-01-08 00:00:00" }, "subdomain": { "type": "string", "nullable": true, "example": "SHOPIFY.COM" } } }, "TechnologyBasic": { "type": "object", "properties": { "id": { "type": "integer", "example": 268 }, "name": { "type": "string", "example": "React" }, "category": { "type": "string", "example": "JavaScript Frameworks" } } }, "TechnologyExtended": { "type": "object", "properties": { "id": { "type": "integer", "example": 268 }, "name": { "type": "string", "example": "React" }, "description": { "type": "string", "example": "React is an open-source JavaScript library for building user interfaces or UI components." }, "website": { "type": "string", "example": "https://reactjs.org" }, "icon": { "type": "string", "example": "https://logo.technologychecker.io/technology-logos/React.svg" }, "primary_category_id": { "type": "integer", "example": 601 }, "primary_group_id": { "type": "integer", "example": 6 }, "category_name": { "type": "string", "example": "JavaScript Frameworks" }, "group_name": { "type": "string", "example": "Development" } } }, "LiveTechnology": { "type": "object", "properties": { "id": { "type": "integer", "example": 1115 }, "slug": { "type": "string", "example": "amazon-s3" }, "name": { "type": "string", "example": "Amazon S3" }, "description": { "type": "string", "example": "Amazon S3 or Amazon Simple Storage Service is a service offered by Amazon Web Services (AWS) that provides object storage through a web service interface." }, "confidence": { "type": "integer", "example": 100 }, "version": { "type": "string", "nullable": true, "example": null }, "icon": { "type": "string", "description": "Technology icon filename", "example": "AmazonS3.svg" }, "website": { "type": "string", "description": "Technology official website", "example": "https://aws.amazon.com/s3/" }, "cpe": { "type": "string", "nullable": true }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 705 }, "slug": { "type": "string", "example": "cdn" }, "name": { "type": "string", "example": "CDN" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 7 }, "name": { "type": "string", "example": "Infrastructure" }, "slug": { "type": "string", "example": "infrastructure-hosting" } } } } } } } } }, "DetectionStats": { "type": "object", "properties": { "htmlLength": { "type": "integer", "example": 594693 }, "scriptsCount": { "type": "integer", "example": 0 }, "scriptSrcCount": { "type": "integer", "example": 63 }, "cookiesCount": { "type": "integer", "example": 0 }, "headersCount": { "type": "integer", "example": 19 }, "metaCount": { "type": "integer", "example": 18 }, "dnsRecordTypes": { "type": "integer", "example": 4 }, "dnsTxtCount": { "type": "integer", "example": 31 }, "jsGlobalsFound": { "type": "integer", "example": 0 }, "domMatchesFound": { "type": "integer", "example": 0 }, "xhrHostsFound": { "type": "integer", "example": 0 }, "textLength": { "type": "integer", "example": 0 }, "cssLength": { "type": "integer", "example": 0 } } }, "Company": { "type": "object", "properties": { "domain": { "type": "string", "example": "stripe.com" }, "subdomain": { "type": "string", "nullable": true }, "company_name": { "type": "string", "example": "Stripe, Inc." }, "linkedin_url": { "type": "string", "example": "linkedin.com/company/stripe" }, "industry": { "type": "string", "example": "Technology, Information and Internet" }, "industry_code": { "type": "integer", "example": 6 }, "country": { "type": "string", "example": "united states" }, "city": { "type": "string", "example": "south san francisco" }, "state": { "type": "string", "example": "california" }, "founded": { "type": "integer", "example": 2010 }, "employees": { "type": "string", "example": "1001-5000" }, "company_type": { "type": "string", "example": "Privately Held" }, "associated_members": { "type": "integer", "example": 12741 } } }, "CompanyFull": { "allOf": [ { "$ref": "#/components/schemas/Company" }, { "type": "object", "properties": { "description": { "type": "string", "example": "Stripe builds programmable financial services. Millions of companies—from the world's largest enterprises to the most ambitious startups—use Stripe to accept payments, grow their revenue, and accelerate new business opportunities." }, "specialties": { "type": "string", "nullable": true, "example": null } } } ] }, "Category": { "type": "object", "properties": { "id": { "type": "integer", "example": 203 }, "name": { "type": "string", "example": "Advertising Networks" }, "slug": { "type": "string", "example": "advertising-networks" }, "priority": { "type": "integer", "example": 1 }, "tech_count": { "type": "integer", "example": 2318 } } }, "ApiError": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "UNAUTHORIZED" }, "message": { "type": "string", "example": "Missing or invalid API key" } } } } }, "SignalConfidence": { "type": "object", "description": "Per-event trust score combining detection method reliability, persistence (how many distinct scans saw the technology) and consistency (detection rate). A single-scan detection caps at `medium`; a churn with `detection_count` below 2 caps at `low`.", "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 100, "example": 79 }, "label": { "type": "string", "enum": [ "high", "medium", "low" ], "example": "high" }, "guard": { "type": "string", "nullable": true, "description": "Present when a churn guard capped this score in place, e.g. `scan_flap`.", "example": "scan_flap" } } }, "CompanyCard": { "type": "object", "nullable": true, "description": "LinkedIn company card attached when firmographic enrichment is on. `null` when the domain has no LinkedIn match (roughly 23–30% of technology domains match).", "properties": { "name": { "type": "string", "example": "Ghostcircusapparel" }, "industry": { "type": "string", "example": "Retail Apparel and Fashion" }, "industry_code": { "type": "integer", "example": 18 }, "employees": { "type": "string", "example": "51-200" }, "country": { "type": "string", "example": "united states" }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "founded": { "type": "integer", "nullable": true, "example": 2015 }, "company_type": { "type": "string", "example": "Privately Held" } } }, "FirmographicsEcho": { "type": "object", "description": "Echo of the firmographic predicates that took effect on this request.", "properties": { "applied": { "type": "object", "additionalProperties": true, "example": { "country": "united states", "employees": "51-200" } }, "filtered": { "type": "boolean", "description": "`true` when results were narrowed to matched companies; `false` for enrich-only (`company=true`).", "example": true }, "note": { "type": "string", "example": "Results are limited to domains with a matched LinkedIn company that passes these filters (~23–30% of tech-domains have a company match)." } } }, "SignalEvent": { "type": "object", "description": "One adoption or churn event: a domain and the technology transition observed on it.", "properties": { "domain": { "type": "string", "example": "example.com" }, "subdomain": { "type": "string", "example": "WWW.EXAMPLE.COM" }, "detection_url": { "type": "string", "description": "The URL the crawler loaded for this row. An event on `docs.example.com` is not an event on the apex — show this host, not just `domain`.", "example": "https://www.example.com" }, "technology_id": { "type": "integer", "example": 900783 }, "technology_name": { "type": "string", "example": "Google Workspace" }, "event_at": { "type": "string", "description": "When the transition was observed (scan time).", "example": "2026-05-31 14:10:33" }, "last_detected": { "type": "string", "nullable": true, "example": "2026-04-18 07:39:59" }, "detection_rate": { "type": "number", "format": "float", "description": "`detection_count / scan_count` for this host.", "example": 0.86 }, "detection_count": { "type": "integer", "description": "How many distinct scans actually saw this technology.", "example": 6 }, "churn_reliability": { "type": "string", "nullable": true, "enum": [ "high", "medium", "low", null ], "description": "Reliability class of the detection method. Present on churn rows." }, "confidence": { "$ref": "#/components/schemas/SignalConfidence" }, "company": { "$ref": "#/components/schemas/CompanyCard" } } }, "SwitchEvent": { "type": "object", "description": "One competitive switch: a domain dropped technology A and adopted a competing technology B in the same category.", "properties": { "domain": { "type": "string", "example": "indigo.ca" }, "subdomain": { "type": "string", "example": "" }, "detection_url": { "type": "string", "example": "https://indigo.ca" }, "from": { "type": "object", "properties": { "id": { "type": "integer", "example": 12 }, "name": { "type": "string", "example": "Salesforce Commerce Cloud" } } }, "to": { "type": "object", "properties": { "id": { "type": "integer", "example": 2184 }, "name": { "type": "string", "example": "Shopify" } } }, "category": { "type": "string", "example": "Ecommerce Platforms" }, "churned_at": { "type": "string", "example": "2026-05-20 14:02:11" }, "adopted_at": { "type": "string", "example": "2026-05-20 14:02:11" }, "gap_days": { "type": "integer", "description": "Absolute days between the churn and the adoption. A genuine in-place swap shows a tiny gap (0–1 days).", "example": 0 }, "detection_rate": { "type": "number", "format": "float", "example": 0.5 }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "Graded from `gap_days` and the churn side's detection rate.", "example": "medium" }, "company": { "$ref": "#/components/schemas/CompanyCard" } } }, "AlertFilters": { "type": "object", "description": "Row-level filters applied to every sweep. Firmographic keys use the same vocabulary as the Signals API.", "properties": { "min_confidence": { "type": "number", "format": "float", "default": 0.5, "description": "Detection-rate floor.", "example": 0.5 }, "churn_reliability": { "type": "array", "items": { "type": "string", "enum": [ "high", "medium", "low" ] }, "description": "Churn alerts only. Defaults to `[\"high\",\"medium\"]` — low-reliability technologies flap and produce false-churn spam. Unclassified technologies count as medium.", "example": [ "high", "medium" ] }, "min_confidence_label": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "Per-event confidence floor, off by default. Unlike `churn_reliability` this gates the combined score and applies to adoption too, so it is how a watchlist suppresses single-scan noise. Note that a churn with fewer than 2 detections is floored to `low`, so any value above `low` drops single-scan churns.", "example": "medium" }, "country": { "type": "string", "example": "united states" }, "city": { "type": "string" }, "state": { "type": "string" }, "industry": { "type": "string" }, "industry_code": { "type": "integer" }, "employees": { "type": "string", "example": "51-200" }, "company_type": { "type": "string" }, "founded_min": { "type": "integer" }, "founded_max": { "type": "integer" }, "company": { "type": "boolean", "description": "Attach company cards without filtering." }, "has_email": { "type": "boolean" }, "has_phone": { "type": "boolean" }, "social": { "type": "string" }, "language": { "type": "string" }, "web_country": { "type": "string" } } }, "Alert": { "type": "object", "properties": { "id": { "type": "string", "example": "alrt_9f2c4a1e" }, "name": { "type": "string", "example": "Who leaves Shopify (US, 51-200)" }, "signal_types": { "type": "array", "items": { "type": "string", "enum": [ "churn", "adoption", "switch" ] }, "example": [ "switch" ] }, "scope": { "type": "object", "description": "The saved scope. Immutable after creation.", "properties": { "kind": { "type": "string", "enum": [ "technology", "category", "domains", "segment" ], "example": "technology" }, "technology_id": { "type": "integer", "nullable": true, "example": 2184 }, "technology_name": { "type": "string", "nullable": true, "example": "Shopify" }, "category_id": { "type": "integer", "nullable": true }, "domains": { "type": "array", "nullable": true, "items": { "type": "string" } }, "segment_id": { "type": "string", "nullable": true } } }, "direction": { "type": "string", "nullable": true, "enum": [ "from", "to", null ] }, "missing_category_id": { "type": "integer", "nullable": true, "description": "Set turns an adoption alert into a whitespace-entrant alert." }, "filters": { "$ref": "#/components/schemas/AlertFilters" }, "webhook_url": { "type": "string", "format": "uri", "example": "https://example.com/hooks/tc" }, "status": { "type": "string", "enum": [ "active", "paused", "disabled" ], "example": "active" }, "delivery_frequency": { "type": "string", "enum": [ "hourly", "daily" ], "default": "daily", "example": "daily" }, "crawl_cadence": { "type": "string", "nullable": true, "enum": [ "daily", "weekly", "monthly", null ], "example": "monthly" }, "last_fired_at": { "type": "string", "nullable": true, "example": "2026-06-10 17:39:39" }, "consecutive_failures": { "type": "integer", "example": 0 }, "created_at": { "type": "string", "example": "2026-06-10T16:39:39.000Z" }, "updated_at": { "type": "string", "example": "2026-06-10T16:39:39.000Z" } } }, "Audience": { "type": "object", "properties": { "id": { "type": "string", "example": "seg_8f3a2c1b" }, "name": { "type": "string", "example": "YC W25 portfolio" }, "type": { "type": "string", "enum": [ "filter", "list" ], "description": "`list` for an uploaded set of domains, `filter` for a computed recipe. Immutable.", "example": "list" }, "kind": { "type": "string", "enum": [ "upload", "firmo", "technology", "signal" ], "description": "How membership was produced. `upload` is a pasted list; the rest are computed recipes.", "example": "upload" }, "definition": { "type": "object", "nullable": true, "description": "The recipe that produced membership. `null`-ish for uploads." }, "domain_count": { "type": "integer", "description": "Members in the current generation.", "example": 5914 }, "status": { "type": "string", "enum": [ "uploading", "ready", "failed" ], "example": "ready" }, "membership_at": { "type": "string", "nullable": true, "description": "When membership was last built. Computed audiences are point-in-time snapshots — re-send the definition to refresh.", "example": "2026-07-29T10:14:02.000Z" }, "matched_total": { "type": "integer", "nullable": true }, "crawl_cadence": { "type": "string", "enum": [ "none", "weekly", "daily" ], "default": "none", "example": "none" }, "last_dispatched_at": { "type": "string", "nullable": true }, "created_at": { "type": "string", "example": "2026-07-29T10:12:00.000Z" }, "updated_at": { "type": "string", "example": "2026-07-29T10:14:02.000Z" } } }, "AudienceDefinition": { "type": "object", "description": "A computed audience recipe. `kind` selects which shape applies; firmographic keys may be combined with any kind to narrow it further.", "properties": { "kind": { "type": "string", "enum": [ "firmo", "technology", "signal" ], "default": "firmo", "description": "`firmo` builds from company attributes alone. `technology` builds from a technology expression. `signal` builds from a saved adoption or churn query." }, "technologies": { "type": "object", "description": "Required for `kind: technology`. Combine technology ids at domain grain.", "properties": { "or": { "type": "array", "items": { "type": "integer" }, "description": "Domains running any of these." }, "and": { "type": "array", "items": { "type": "integer" }, "description": "Domains running all of these." }, "and_not": { "type": "array", "items": { "type": "integer" }, "description": "Domains running none of these." } }, "example": { "and": [ 2184 ], "and_not": [ 402 ] } }, "signal": { "type": "object", "description": "Required for `kind: signal`. Only adoption and churn queries can be saved as audiences.", "properties": { "type": { "type": "string", "enum": [ "adoption", "churn" ] }, "technology_id": { "type": "integer", "description": "Exactly one of `technology_id` or `category_id`." }, "category_id": { "type": "integer" }, "window": { "type": "integer", "default": 30, "minimum": 1, "maximum": 365 }, "min_confidence": { "type": "number", "format": "float", "default": 0.5 }, "include_first_seen": { "type": "boolean", "default": false } }, "example": { "type": "adoption", "technology_id": 2184, "window": 90 } }, "country": { "type": "string", "example": "united states" }, "city": { "type": "string" }, "state": { "type": "string" }, "industry": { "type": "string" }, "industry_code": { "type": "integer" }, "employees": { "type": "string", "example": "51-200" }, "company_type": { "type": "string" }, "founded_min": { "type": "integer" }, "founded_max": { "type": "integer" }, "has_email": { "type": "boolean" }, "has_phone": { "type": "boolean" }, "social": { "type": "string" }, "language": { "type": "string" }, "web_country": { "type": "string" } } }, "LeadListFilters": { "type": "object", "description": "The filter set that defines a lead list. Technology filters and company filters combine with AND.", "properties": { "technologies": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "example": [ 2, 7 ] }, "logic": { "type": "string", "enum": [ "or", "and", "and_not" ], "default": "or", "description": "`or` matches domains running any listed technology. `and` requires all of them. `and_not` requires the first and excludes the rest." } } }, "keywords": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" }, "example": [ "shop" ] }, "exclude": { "type": "array", "items": { "type": "string" }, "example": [ "health" ] } } }, "website_type": { "type": "string", "example": "company_only" }, "countries": { "type": "array", "items": { "type": "string" }, "example": [ "United States", "Germany" ] }, "industries": { "type": "array", "items": { "type": "string" }, "example": [ "Software Development" ] }, "employees": { "type": "array", "items": { "type": "string" }, "example": [ "51-200", "201-500" ] }, "has_email": { "type": "boolean", "description": "Only domains where the crawler found an email address." }, "has_phone": { "type": "boolean", "description": "Only domains where the crawler found a phone number." }, "languages": { "type": "array", "items": { "type": "string" }, "example": [ "en" ] }, "web_countries": { "type": "array", "items": { "type": "string" }, "description": "ISO-2 codes or English names. Unresolvable values are rejected at create time.", "example": [ "USA" ] } } }, "LeadListRow": { "type": "object", "properties": { "domain": { "type": "string", "example": "example.com" }, "detection_url": { "type": "string", "example": "EXAMPLE.COM" }, "technology_ids": { "type": "array", "items": { "type": "integer" }, "example": [ 2 ] }, "company_name": { "type": "string", "example": "Example Corp" }, "linkedin_url": { "type": "string", "example": "linkedin.com/company/example" }, "industry": { "type": "string", "example": "Software Development" }, "industry_code": { "type": "integer", "description": "`0` means unknown.", "example": 4 }, "country": { "type": "string", "example": "United States" }, "city": { "type": "string", "example": "Austin" }, "state": { "type": "string", "example": "Texas" }, "founded": { "type": "integer", "description": "`0` means unknown.", "example": 2015 }, "employees": { "type": "string", "example": "51-200" }, "company_type": { "type": "string", "example": "Privately Held" }, "associated_members": { "type": "integer", "description": "`0` means unknown.", "example": 42 }, "web": { "type": "object", "nullable": true, "description": "Crawl-sourced contact data, matching what the export ships. `null` when the domain has no crawled row.", "properties": { "emails": { "type": "array", "items": { "type": "string" }, "example": [ "hi@example.com" ] }, "phones": { "type": "array", "items": { "type": "string" }, "example": [ "+1 555 0100" ] }, "socials": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Only the platforms that domain publishes, as full profile URLs.", "example": { "linkedin": "https://www.linkedin.com/company/example" } }, "language": { "type": "string", "example": "en" } } } } }, "LeadList": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "f6ab2d94-c34f-47b7-9d1a-228e71488cd2" }, "name": { "type": "string", "example": "US SaaS Companies" }, "status": { "type": "string", "enum": [ "processing", "ready", "failed", "expired" ], "example": "ready" }, "estimated_count": { "type": "integer", "example": 1000 }, "actual_count": { "type": "integer", "example": 1000 }, "credits_charged": { "type": "integer", "example": 1000 }, "created_at": { "type": "string", "example": "2026-01-15 19:19:19" }, "completed_at": { "type": "string", "nullable": true, "example": "2026-01-15 19:19:49" }, "expires_at": { "type": "string", "description": "Results are deleted 60 days after creation.", "example": "2026-03-16T19:19:19.875Z" }, "filters": { "$ref": "#/components/schemas/LeadListFilters" }, "can_preview": { "type": "boolean", "example": true }, "can_download": { "type": "boolean", "example": true } } } }, "responses": { "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "RateLimited": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "PaymentRequired": { "description": "Not enough credits, or the plan does not include this feature", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "success": false, "error": { "code": "INSUFFICIENT_CREDITS", "message": "Insufficient credits for this request.", "details": { "required": 1, "available": 0 } } } } } }, "BadRequest": { "description": "Invalid or missing parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Provide exactly one scope: technology_id, technology or category_id." } } } } }, "Forbidden": { "description": "The plan does not allow this action, or a plan limit was reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "success": false, "error": { "code": "PLAN_LIMIT", "message": "Your plan allows up to 2 saved audiences. Delete one to create another." } } } } }, "QueryTimeout": { "description": "The query exceeded the 30-second server-side limit. Narrow the query and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "success": false, "error": { "code": "SEGMENT_QUERY_TIMEOUT", "message": "The segment query exceeded the 30s server-side limit.", "details": { "suggestion": "Narrow the segment — add an employees band, industry, or city — and try again." } } } } } } }, "parameters": { "FirmoCountry": { "name": "country", "in": "query", "required": false, "description": "Filter to companies in this country (case-insensitive).", "schema": { "type": "string" }, "example": "united states" }, "FirmoCity": { "name": "city", "in": "query", "required": false, "description": "Filter to companies in this city (case-insensitive).", "schema": { "type": "string" } }, "FirmoState": { "name": "state", "in": "query", "required": false, "description": "Filter to companies in this state or region (case-insensitive).", "schema": { "type": "string" } }, "FirmoIndustry": { "name": "industry", "in": "query", "required": false, "description": "Filter to companies in this industry (case-insensitive).", "schema": { "type": "string" }, "example": "retail" }, "FirmoIndustryCode": { "name": "industry_code", "in": "query", "required": false, "description": "Filter by exact LinkedIn industry code.", "schema": { "type": "integer" } }, "FirmoEmployees": { "name": "employees", "in": "query", "required": false, "description": "Filter by exact LinkedIn employee band. Unknown bands are rejected with `INVALID_EMPLOYEE_BAND` and the allowed list.", "schema": { "type": "string" }, "example": "51-200" }, "FirmoCompanyType": { "name": "company_type", "in": "query", "required": false, "description": "Filter by exact company type.", "schema": { "type": "string" }, "example": "Privately Held" }, "FirmoFoundedMin": { "name": "founded_min", "in": "query", "required": false, "description": "Only companies founded in or after this year.", "schema": { "type": "integer", "minimum": 1800, "maximum": 2025 } }, "FirmoFoundedMax": { "name": "founded_max", "in": "query", "required": false, "description": "Only companies founded in or before this year.", "schema": { "type": "integer", "minimum": 1800, "maximum": 2025 } }, "FirmoCompany": { "name": "company", "in": "query", "required": false, "description": "Set to `true` to attach the company card without filtering results (enrich-only mode).", "schema": { "type": "boolean" }, "example": true }, "WebHasEmail": { "name": "has_email", "in": "query", "required": false, "description": "Filter to domains where the crawler found (or did not find) an email address. `false` is a real filter, not a no-op.", "schema": { "type": "boolean" } }, "WebHasPhone": { "name": "has_phone", "in": "query", "required": false, "description": "Filter to domains where the crawler found (or did not find) a phone number.", "schema": { "type": "boolean" } }, "WebSocial": { "name": "social", "in": "query", "required": false, "description": "Filter to domains publishing a profile on this platform.", "schema": { "type": "string", "enum": [ "linkedin", "x", "facebook", "instagram", "youtube", "github", "tiktok", "discord", "reddit", "crunchbase", "slack" ] }, "example": "instagram" }, "WebLanguage": { "name": "language", "in": "query", "required": false, "description": "Filter by the site's primary language.", "schema": { "type": "string" }, "example": "de" }, "WebCountry": { "name": "web_country", "in": "query", "required": false, "description": "Filter by the country the site declares in its schema.org markup. Accepts ISO-2, English name or common variants.", "schema": { "type": "string" }, "example": "USA" }, "SegmentId": { "name": "segment_id", "in": "query", "required": false, "description": "Apply a saved audience instead of inline filters. Filter audiences replay their firmographic predicates; list audiences restrict rows to their member domains. Mutually exclusive with inline firmographic parameters.", "schema": { "type": "string" }, "example": "seg_8f3a2c1b" } } } }