{"openapi":"3.1.0","info":{"title":"StoreTechScan Ecommerce & Website Tech Stack API","version":"1.2.0","summary":"Pay-as-you-go alternative to Store Leads, Wappalyzer & BuiltWith: website tech stack + passive DNS + auditable evidence, live Shopify/WooCommerce/DTC product price & availability probe, ICP classification, and public role contacts.","description":"StoreTechScan inspects domains across 4 stages plus general web/SaaS tech stacks, passive DNS (MX/TXT/CNAME/NS), and auditable evidence[] via `/api/v1/inspect` (`profile=ecommerce | tech_stack | full`), and probes live Shopify, WooCommerce, BigCommerce, and Schema.org DTC product URLs via `/api/v1/product` for real-time price, variants, and explicit public `available` status. Unreachable, rate-limited, or WAF-blocked targets return `billable: false` ($0). Commercial SaaS embedding, Clay/n8n/Make workflows, and AI agent integration are explicitly permitted with no mandatory attribution backlink.","contact":{"name":"StoreTechScan Support","email":"storetechscan-support@ydev.work","url":"https://storetechscan.com"}},"servers":[{"url":"https://storetechscan.com","description":"Production / Configured StoreTechScan Endpoint"}],"security":[{"BearerAuth":[]},{"ApiKeyHeader":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"StoreTechScan API Key (zsk_live_...)","description":"Pass your StoreTechScan API key in the Authorization header: `Authorization: Bearer zsk_live_...`"},"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Alternative header for Clay / n8n / Zapier integrations: `X-API-Key: zsk_live_...`"}},"schemas":{"DomainInspectionResult":{"type":"object","description":"Single-domain 4-stage inspection row. On ununlocked `/api/jobs/{id}` batches, rows beyond `free_preview_limit` return `locked: true` with redacted domain/platform/tech/contact placeholders until unlocked.","properties":{"row_number":{"type":"integer","example":1},"locked":{"type":"boolean","example":false,"description":"True when a batch row exceeds `free_preview_limit` and has not yet been unlocked with credits."},"domain":{"type":"string","example":"gymshark.com"},"final_url":{"type":["string","null"],"example":"https://www.gymshark.com/"},"status":{"type":"string","example":"OK"},"error_code":{"type":["string","null"],"example":null},"http_status":{"type":["integer","null"],"example":200},"billable":{"type":"boolean","example":true},"enrichment_deferred":{"type":"boolean","example":false},"primary_platform":{"type":["string","null"],"example":"Shopify Plus"},"platforms":{"type":"array","items":{"type":"string"}},"marketing_plugins":{"type":"array","items":{"type":"string"}},"support_plugins":{"type":"array","items":{"type":"string"}},"subscription_reviews_plugins":{"type":"array","items":{"type":"string"}},"pixels":{"type":"array","items":{"type":"string"}},"tech_stack":{"type":"array","items":{"type":"string"}},"tech_count":{"type":"integer","example":8},"is_shopify":{"type":"boolean","example":true},"is_shopify_plus":{"type":"boolean","example":true},"is_live_shopify":{"type":"boolean","example":true},"shopify_probe_status":{"type":["string","null"],"example":"LIVE","description":"LIVE_SAMPLE_50 or LIVE_SAMPLE_10 indicates a smaller complete sample after the decoded size cap; failures remain unknown."},"shopify_products_count_sample":{"type":["integer","null"],"example":250,"description":"Observed product sample count, up to 250. 0 means a confirmed empty public catalog; null means unavailable, blocked or invalid."},"shopify_price_min":{"type":["number","null"],"example":18},"shopify_price_median":{"type":["number","null"],"example":44},"shopify_price_max":{"type":["number","null"],"example":140},"shopify_currency":{"type":["string","null"],"example":"USD"},"shopify_latest_updated_at":{"type":["string","null"],"format":"date-time"},"icp_vertical":{"type":["string","null"],"example":"DTC Apparel & Athleisure"},"business_model":{"type":["string","null"],"enum":["B2C / DTC","B2B","SaaS","Agency / Service","Other",null]},"icp_one_liner":{"type":["string","null"]},"icp_source":{"type":["string","null"],"example":"calibrated_ai","description":"Stage 3 classification source (`calibrated_ai` calibrated AI decision model on paid tiers when configured, or `local_rules` deterministic classifier)."},"icp_confidence":{"type":["number","null"],"minimum":0,"maximum":1,"example":0.91,"description":"Calibrated decision model confidence (0.00–1.00); null when classified via deterministic `local_rules`."},"icp_fit_score":{"type":["number","null"],"minimum":1,"maximum":5,"example":4.5,"description":"Prospect fit on a 1.0–5.0 scale when a classification is available. Anonymous rows can have a local rules score. Check icp_source for the actual scoring method; failed inspections can return null."},"is_real_merchant":{"type":["boolean","null"],"example":true,"description":"True when the domain is an active commercial merchant, brand, or SaaS product rather than a parked/placeholder page or agency portfolio."},"has_b2b_wholesale":{"type":["boolean","null"],"example":false,"description":"True when wholesale, bulk ordering, trade accounts, stockists, or B2B sales programs are detected."},"primary_email":{"type":["string","null"],"example":"support@gymshark.com"},"generic_emails":{"type":"array","items":{"type":"string"}},"instagram_url":{"type":["string","null"]},"tiktok_url":{"type":["string","null"]},"linkedin_url":{"type":["string","null"]},"youtube_url":{"type":["string","null"]},"x_url":{"type":["string","null"]},"profile":{"type":"string","enum":["ecommerce","tech_stack","full"],"description":"Present when profile=tech_stack or profile=full."},"tech_categories":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Detected technologies grouped by category (platform, frontend, cdn_hosting, payment, auth_infra, analytics_obs, marketing, support, subscription_reviews, ai_widget, email_infra, security, productivity)."},"dns_signals":{"type":["object","null"],"description":"Passive DNS summary (MX, SPF includes, DMARC presence, www CNAME, NS) collected in parallel when profile=tech_stack or profile=full.","properties":{"mx_hosts":{"type":"array","items":{"type":"string"}},"spf_includes":{"type":"array","items":{"type":"string"}},"has_dmarc":{"type":"boolean"},"www_cname":{"type":"array","items":{"type":"string"}},"ns_hosts":{"type":"array","items":{"type":"string"}}}},"evidence":{"type":"array","description":"Auditable detection evidence items when profile=tech_stack, profile=full, or include_evidence=true.","items":{"type":"object","properties":{"tech":{"type":"string"},"category":{"type":"string"},"source":{"type":"string","enum":["dns_mx","dns_txt","dns_cname","dns_ns","http_header","cookie","script_src","link_href","meta","html_marker","implied"]},"signal":{"type":"string"}}}}}},"ProductInspectionResult":{"type":"object","description":"Live single-product URL probe result for Shopify, WooCommerce, BigCommerce, and Schema.org DTC pages.","properties":{"url":{"type":"string","format":"uri"},"final_url":{"type":["string","null"]},"domain":{"type":["string","null"]},"status":{"type":"string","example":"OK"},"error_code":{"type":["string","null"],"example":null},"http_status":{"type":["integer","null"],"example":200},"billable":{"type":"boolean","example":true,"description":"False ($0 charged) on WAF_BLOCKED, RATE_LIMITED, HTTP_404, TIMEOUT, DNS_ERROR, NOT_PRODUCT_PAGE, or SSRF_BLOCKED."},"observed_at":{"type":"string","format":"date-time"},"platform":{"type":["string","null"],"example":"Shopify"},"extraction_source":{"type":["string","null"],"enum":["shopify_product_js","shopify_product_json","woocommerce_store_api","json_ld","opengraph",null]},"title":{"type":["string","null"]},"brand":{"type":["string","null"]},"sku":{"type":["string","null"]},"currency":{"type":["string","null"],"example":"USD"},"price":{"type":["number","null"],"example":98},"price_min":{"type":["number","null"]},"price_max":{"type":["number","null"]},"compare_at_price":{"type":["number","null"]},"available":{"type":["boolean","null"],"description":"Explicit public availability boolean observed from storefront; never fabricates stock quantity."},"variants_count":{"type":"integer"},"variants":{"type":"array","items":{"type":"object","properties":{"variant_id":{"type":["string","null"]},"sku":{"type":["string","null"]},"title":{"type":["string","null"]},"price":{"type":["number","null"]},"compare_at_price":{"type":["number","null"]},"available":{"type":["boolean","null"]}}}}}},"ApiInspectRequest":{"type":"object","properties":{"domain":{"type":"string","description":"Single domain or URL to inspect (use either `domain` or `domains`).","example":"allbirds.com"},"domains":{"type":"array","maxItems":100,"items":{"type":"string"},"description":"Up to 100 domains per synchronous API call.","example":["allbirds.com","gymshark.com"]},"profile":{"type":"string","enum":["ecommerce","tech_stack","full"],"default":"ecommerce","description":"`ecommerce` (default 4-stage ecommerce enrichment), `tech_stack` (fast general Web/SaaS 200+ fingerprints + parallel passive DNS + evidence[]), or `full` (all 4 ecommerce stages + general tech stack + DNS + evidence[])."},"include_evidence":{"type":"boolean","default":false,"description":"Include auditable `evidence[]` entries even on the default `ecommerce` profile."}}},"ApiInspectResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"total_requested":{"type":"integer"},"input_summary":{"type":"object","description":"Normalization accounting: original candidates, accepted unique domains, duplicates and invalid inputs.","properties":{"total_candidates":{"type":"integer"},"valid_unique_domains":{"type":"integer"},"duplicates_removed":{"type":"integer"},"invalid_skipped":{"type":"integer"}}},"billable_domains":{"type":"integer"},"failed_unbilled_domains":{"type":"integer"},"credits_charged":{"type":"integer"},"credits_refunded":{"type":"integer"},"credits_balance":{"type":["integer","null"]},"mode":{"type":"string","enum":["anonymous_free_preview"]},"job_id":{"type":"string"},"free_quota_remaining":{"type":"integer","minimum":0,"description":"Remaining domains in the one-time anonymous trial."},"free_quota_remaining_today":{"type":"integer","minimum":0,"deprecated":true,"description":"Compatibility alias for free_quota_remaining. Both fields report the same one-time balance."},"upgrade":{"$ref":"#/components/schemas/ApiUpgrade"},"results":{"type":"array","items":{"$ref":"#/components/schemas/DomainInspectionResult"}}}},"ApiUpgrade":{"type":"object","required":["pricing_url","how"],"properties":{"pricing_url":{"type":"string","format":"uri","example":"https://storetechscan.com/pricing"},"how":{"type":"string","description":"Purchase availability and instructions for passing Authorization: Bearer with the purchased API key on the same endpoint."},"packs":{"type":"array","items":{"type":"object","required":["name","price_usd","credits"],"properties":{"name":{"type":"string"},"price_usd":{"type":"number"},"credits":{"type":"integer"}}}}}},"ApiInspectPaymentRequired":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"error_code":{"type":"string","enum":["FREE_PREVIEW_EXHAUSTED","FREE_PREVIEW_BATCH_TOO_LARGE"]},"free_preview":{"type":"object","required":["limit","remaining","period"],"properties":{"limit":{"type":"integer","example":25},"remaining":{"type":"integer","description":"Remaining one-time trial allowance when available, otherwise 0."},"period":{"type":"string","enum":["one_time"]}}},"upgrade":{"$ref":"#/components/schemas/ApiUpgrade"},"credits_balance":{"type":"integer","description":"Present for authenticated requests with insufficient credits."},"required_max_credits":{"type":"integer"}}}}},"paths":{"/api/v1/inspect":{"post":{"operationId":"inspectDomainsV1","summary":"Inspect 1 to 100 domains synchronously (Clay / n8n / Make / Agent ready)","description":"Without an Authorization header, use the anonymous one-time 25-domain free trial (shared with MCP). Anonymous requests use local rules without external AI calls. Supply a Bearer API key for paid inspection of up to 100 domains per call (first purchase includes +25 bonus credits).","security":[{"BearerAuth":[]},{"ApiKeyHeader":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiInspectRequest"},"examples":{"anonymousPreview":{"summary":"Three domains, no Authorization header","value":{"domains":["fromourplace.com","hydromateusa.com","snugsofa.com"]}}}}}},"responses":{"200":{"description":"Inspection results with transparent failure-refund billing summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiInspectResponse"},"examples":{"anonymousPreview":{"summary":"Anonymous free preview: two live Shopify stores and one unreachable, unbilled domain","value":{"ok":true,"mode":"anonymous_free_preview","total_requested":3,"input_summary":{"total_candidates":3,"valid_unique_domains":3,"duplicates_removed":0,"invalid_skipped":0},"billable_domains":2,"failed_unbilled_domains":1,"credits_charged":0,"credits_refunded":0,"credits_balance":null,"free_quota_remaining":22,"free_quota_remaining_today":22,"results":[{"domain":"fromourplace.com","final_url":"https://fromourplace.com/","status":"OK","http_status":200,"billable":true,"duration_ms":1421,"primary_platform":"Shopify","platforms":["Shopify"],"marketing_plugins":["Klaviyo","Attentive"],"support_plugins":["Gorgias"],"subscription_reviews_plugins":["Yotpo"],"pixels":["Google Tag Manager"],"tech_stack":["Shopify","Klaviyo","Attentive","Gorgias","Yotpo","Google Tag Manager"],"tech_count":6,"is_shopify":true,"is_shopify_plus":false,"is_live_shopify":true,"shopify_probe_status":"LIVE","shopify_products_count_sample":138,"shopify_price_min":10.99,"shopify_price_median":95,"shopify_price_max":849,"shopify_currency":"USD","icp_vertical":"DTC Home & Living","business_model":"B2C / DTC","icp_one_liner":"Cookware brand with a live Shopify catalog and email marketing.","icp_source":"local_rules","icp_confidence":null,"icp_fit_score":5,"is_real_merchant":true,"has_b2b_wholesale":false,"generic_emails":["hello@fromourplace.com"],"primary_email":"hello@fromourplace.com","instagram_url":"https://www.instagram.com/ourplace","tiktok_url":null,"linkedin_url":null,"youtube_url":null,"x_url":null},{"domain":"hydromateusa.com","final_url":"https://hydromateusa.com/","status":"OK","http_status":200,"billable":true,"duration_ms":739,"primary_platform":"Shopify","platforms":["Shopify"],"marketing_plugins":[],"support_plugins":["Gorgias"],"subscription_reviews_plugins":["Recharge"],"pixels":["Microsoft Clarity"],"tech_stack":["Shopify","Gorgias","Recharge","Microsoft Clarity"],"tech_count":4,"is_shopify":true,"is_shopify_plus":false,"is_live_shopify":true,"shopify_probe_status":"LIVE","shopify_products_count_sample":19,"shopify_price_min":25.95,"shopify_price_median":35.95,"shopify_price_max":97.07,"shopify_currency":"USD","icp_vertical":"DTC Health & Wellness","business_model":"B2C / DTC","icp_one_liner":"Electrolyte powder brand selling subscriptions through a public Shopify catalog.","icp_source":"local_rules","icp_confidence":null,"icp_fit_score":4.6,"is_real_merchant":true,"has_b2b_wholesale":false,"generic_emails":[],"primary_email":null,"instagram_url":null,"tiktok_url":null,"linkedin_url":null,"youtube_url":null,"x_url":null},{"domain":"snugsofa.com","final_url":"https://snugsofa.com/","status":"HTTP_4XX","http_status":404,"billable":false,"error_message":"Homepage returned HTTP 404","duration_ms":180,"primary_platform":null,"platforms":[],"marketing_plugins":[],"support_plugins":[],"subscription_reviews_plugins":[],"pixels":[],"tech_stack":[],"tech_count":0,"is_shopify":false,"is_shopify_plus":false,"is_live_shopify":false,"shopify_probe_status":null,"shopify_products_count_sample":null,"shopify_price_min":null,"shopify_price_median":null,"shopify_price_max":null,"shopify_currency":null,"icp_vertical":null,"business_model":null,"icp_one_liner":null,"icp_source":null,"icp_confidence":null,"icp_fit_score":null,"is_real_merchant":null,"has_b2b_wholesale":null,"generic_emails":[],"primary_email":null,"instagram_url":null,"tiktok_url":null,"linkedin_url":null,"youtube_url":null,"x_url":null}],"upgrade":{"pricing_url":"https://storetechscan.com/pricing","how":"Pass Authorization: Bearer zsk_live_YOUR_KEY on the same endpoint for non-expiring credits, up to 100 domains per call and calibrated AI ICP scoring (icp_fit_score 1.0-5.0)."}}}}}}},"400":{"description":"No valid domains, malformed input, or more than 100 unique domains. No credits reserved."},"401":{"description":"Invalid supplied API key. Remove the Authorization header to use the anonymous free preview."},"402":{"description":"Anonymous preview batch too large or quota exhausted (error_code, remaining one-time allowance and upgrade instructions), or insufficient paid credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiInspectPaymentRequired"}}}},"429":{"description":"Temporary concurrency, hourly job, or rolling domain limit reached. When the one-time trial still has rows, RATE_LIMITED reports the remaining allowance. Retry-After is supplied for concurrency and rolling rate limits.","headers":{"Retry-After":{"description":"Seconds to wait before trying again.","schema":{"type":"integer","example":2}}}}}},"get":{"operationId":"inspectSingleDomainQueryV1","summary":"Inspect a single domain via query parameter (ideal for Clay HTTP API column)","description":"Accepts domain or domains query input. Without an Authorization header, use the anonymous one-time 25-domain free trial (shared with MCP). Anonymous requests use local rules without external AI calls. Supply a Bearer API key for paid inspection of up to 100 domains per call.","security":[{"BearerAuth":[]},{"ApiKeyHeader":[]},{}],"parameters":[{"name":"domain","in":"query","schema":{"type":"string"},"example":"allbirds.com"},{"name":"domains","in":"query","schema":{"type":"string"},"description":"Multiple domains separated by commas or newlines. Provide either domain or domains."},{"name":"profile","in":"query","schema":{"type":"string","enum":["ecommerce","tech_stack","full"],"default":"ecommerce"},"description":"Inspection depth: ecommerce (default), tech_stack (general Web/SaaS + passive DNS + evidence[]), or full."},{"name":"include_evidence","in":"query","schema":{"type":"boolean","default":false},"description":"Set true to return auditable detection evidence[] items."}],"responses":{"200":{"description":"Inspection result for the requested domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiInspectResponse"}}}},"400":{"description":"No valid domains, malformed input, or more than 100 unique domains. No credits reserved."},"401":{"description":"Invalid supplied API key. Remove the Authorization header to use the anonymous free preview."},"402":{"description":"Anonymous preview batch too large or quota exhausted (error_code, remaining one-time allowance and upgrade instructions), or insufficient paid credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiInspectPaymentRequired"}}}},"429":{"description":"Temporary concurrency, hourly job, or rolling domain limit reached. When the one-time trial still has rows, RATE_LIMITED reports the remaining allowance. Retry-After is supplied for concurrency and rolling rate limits.","headers":{"Retry-After":{"description":"Seconds to wait before trying again.","schema":{"type":"integer","example":2}}}}}}},"/api/v1/product":{"post":{"operationId":"inspectProductUrlsV1","summary":"Probe 1 to 50 public ecommerce product URLs for live price, variants, and explicit available status","description":"Supports public Shopify (.js/.json + HTML currency), WooCommerce (Store API + JSON-LD), BigCommerce, and Schema.org DTC product pages. Unreachable, rate-limited, or WAF-blocked URLs return `billable: false` ($0). Shares the one-time 25-unit anonymous trial when called without an Authorization header.","security":[{"BearerAuth":[]},{"ApiKeyHeader":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","example":"https://www.allbirds.com/products/mens-wool-runners"},"urls":{"type":"array","maxItems":50,"items":{"type":"string","format":"uri"}}}}}}},"responses":{"200":{"description":"Live product probe results with zero-charge billing summary for failed/WAF URLs.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"total_requested":{"type":"integer"},"billable_products":{"type":"integer"},"failed_unbilled_products":{"type":"integer"},"credits_charged":{"type":"integer"},"credits_refunded":{"type":"integer"},"credits_balance":{"type":["integer","null"]},"results":{"type":"array","items":{"$ref":"#/components/schemas/ProductInspectionResult"}}}}}}},"400":{"description":"No valid product URLs or more than 50 unique URLs."},"401":{"description":"Invalid Bearer API key."},"402":{"description":"Anonymous trial exhausted or insufficient credits."},"429":{"description":"Concurrency or rolling rate limit reached; Retry-After included."}}},"get":{"operationId":"inspectSingleProductQueryV1","summary":"Probe a single ecommerce product URL via query parameter","security":[{"BearerAuth":[]},{"ApiKeyHeader":[]},{}],"parameters":[{"name":"url","in":"query","schema":{"type":"string","format":"uri"},"example":"https://www.allbirds.com/products/mens-wool-runners"},{"name":"urls","in":"query","schema":{"type":"string"},"description":"Comma-separated product URLs."}],"responses":{"200":{"description":"Live product probe result."},"400":{"description":"Invalid or missing URL."},"402":{"description":"Trial exhausted or insufficient credits."},"429":{"description":"Rate or concurrency limit reached."}}}},"/api/v1/credits":{"get":{"operationId":"getCreditBalanceV1","summary":"Check remaining pay-as-you-go credits and recent ledger transactions","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Current account balance and credit ledger history."}}}},"/api/jobs":{"post":{"operationId":"createBatchJob","summary":"Submit up to 500 domains anonymously (25 free trial rows total) or up to 10,000 domains with a funded API Key (1 credit/domain)","security":[{"BearerAuth":[]},{"ApiKeyHeader":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"string","description":"Newline/comma-separated domains or full CSV text."},"domains":{"type":"array","items":{"type":"string"},"description":"Optional array of domains."}}}}}},"responses":{"202":{"description":"Batch job created and running asynchronously."},"402":{"description":"Anonymous batches over 500 domains require a funded API key."},"429":{"description":"Per-IP hourly anonymous job, rolling domain cap, or daily service capacity limit exceeded, or one-time trial allowance exhausted.","headers":{"Retry-After":{"description":"Seconds to wait before trying again when a rolling rate or capacity limit is exceeded.","schema":{"type":"integer","example":3600}}}}}}},"/api/jobs/{id}":{"get":{"operationId":"getBatchJob","summary":"Poll batch job progress, counts, and filtered/preview-redacted results (filters apply only to unlocked rows on ununlocked jobs)","security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"platform","in":"query","schema":{"type":"string"}},{"name":"shopify","in":"query","description":"Shorthand alias (`1` or `true`) for `platform=Shopify`.","schema":{"type":"string","enum":["true","false","1","0"]}},{"name":"plugin","in":"query","schema":{"type":"string"}},{"name":"business_model","in":"query","schema":{"type":"string"}},{"name":"live_shopify","in":"query","schema":{"type":"string","enum":["true","false","1","0"]}},{"name":"has_email","in":"query","schema":{"type":"string","enum":["true","false","1","0"]}},{"name":"real_merchant","in":"query","description":"Filter to active commercial merchants/brands/SaaS (`is_real_merchant === true`).","schema":{"type":"string","enum":["true","false","1","0"]}},{"name":"b2b_wholesale","in":"query","description":"Filter to domains with wholesale, stockist, trade, or B2B signals (`has_b2b_wholesale === true`).","schema":{"type":"string","enum":["true","false","1","0"]}},{"name":"min_fit_score","in":"query","description":"Minimum Stage-3 outreach fit score (`1.0` to `5.0`).","schema":{"type":"number","minimum":1,"maximum":5}},{"name":"price_min","in":"query","schema":{"type":"number"}},{"name":"price_max","in":"query","schema":{"type":"number"}},{"name":"currency","in":"query","description":"Observed currency code, such as USD or EUR. Prices are not converted.","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Defaults to 250; at most 500 rows and 512 KiB of result rows per page. Use next_offset for the next page; null means complete.","schema":{"type":"integer","minimum":1,"maximum":500}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Batch job status, enrichment_status, total_filtered_count, exportable_count (unlocked matches across all pages), and paginated results. Job rows include billing_state: trial, locked, charged, reserved or unbilled. billable describes eligibility; billing_state describes this job’s settlement."},"404":{"description":"Job not found."}}}},"/api/jobs/{id}/unlock":{"post":{"operationId":"unlockBatchJob","summary":"Spend credits for reachable locked rows and trigger Stage 2-4 enrichment (async 202 when >25 deferred domains or ?async=true)","security":[{"BearerAuth":[]},{"ApiKeyHeader":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"async","in":"query","schema":{"type":"string","enum":["true","false"]}},{"name":"sync","in":"query","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"Job unlocked. If synchronous enrichment fails, enrichment_status=pending_retry; repeat unlock without another charge.","content":{"application/json":{"schema":{"type":"object","properties":{"enrichment_status":{"type":"string","enum":["none","pending","pending_retry","running","done"]},"credits_charged":{"type":"integer","description":"Credits charged; 0 on already_unlocked retries."},"retry_hint":{"type":"string","description":"Returned with pending_retry to explain how to resume enrichment without paying again."}}}}}},"202":{"description":"Job unlocked; background Stage 2-4 enrichment running (poll /api/jobs/{id} until enrichment_status=done)."},"401":{"description":"Valid API Key required."},"402":{"description":"Insufficient credits."},"409":{"description":"Job still running."}}}},"/api/jobs/{id}/export.csv":{"post":{"operationId":"exportSelectedJobDomains","summary":"Export exact selected domains from previously inspected, unlocked results","security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domains"],"properties":{"domains":{"type":"array","minItems":1,"maxItems":10000,"items":{"type":"string","maxLength":253}}}}}}},"responses":{"200":{"description":"Selected results in batch order, using the standard 39-column CSV. Exporting an existing result costs zero credits.","content":{"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Empty or invalid selection."},"404":{"description":"Batch is missing or expired."},"409":{"description":"A selected domain is unavailable within the unlocked export scope, or the batch changed during export. No partial selection is returned."}}},"get":{"operationId":"exportJobCsv","summary":"Download Clay/Instantly/Smartlead/Apollo-compatible CSV (free preview sample, partial while enriching, or full unlocked)","security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"mode","in":"query","schema":{"type":"string","enum":["auto","sample"]}},{"name":"platform","in":"query","schema":{"type":"string"}},{"name":"shopify","in":"query","schema":{"type":"string","enum":["true","false","1","0"]}},{"name":"plugin","in":"query","schema":{"type":"string"}},{"name":"business_model","in":"query","schema":{"type":"string"}},{"name":"live_shopify","in":"query","schema":{"type":"string"}},{"name":"has_email","in":"query","schema":{"type":"string"}},{"name":"real_merchant","in":"query","schema":{"type":"string","enum":["true","false","1","0"]}},{"name":"b2b_wholesale","in":"query","schema":{"type":"string","enum":["true","false","1","0"]}},{"name":"min_fit_score","in":"query","schema":{"type":"number","minimum":1,"maximum":5}},{"name":"price_min","in":"query","schema":{"type":"number"}},{"name":"price_max","in":"query","schema":{"type":"number"}},{"name":"currency","in":"query","description":"Observed currency code. Use the same filters as the result view.","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Flattened CSV export (X-StoreTechScan-Enrichment-Status header indicates running/done).","content":{"text/csv":{"schema":{"type":"string"}}}}}}},"/api/billing/packages":{"get":{"operationId":"listCreditPackages","summary":"List pay-as-you-go credit packages, active billing provider (Waffo MoR), and failure billing policy","security":[],"responses":{"200":{"description":"Available credit packs."}}}},"/api/billing/checkout":{"post":{"operationId":"createBillingCheckout","summary":"Create a Waffo Merchant-of-Record (or Stripe fallback) checkout session and return a claim_token","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["package_id"],"properties":{"package_id":{"type":"string","enum":["starter","growth","agency"]},"email":{"type":"string","format":"email"},"job_id":{"type":"string"},"source":{"type":"string","enum":["web","agent"],"default":"web","description":"Agent mode returns claim_token only to the caller; the browser success redirect uses checkout=agent-success without claim_token. Keep the token with the agent to poll for the purchased API key."}}}}}},"responses":{"200":{"description":"Checkout session created."}}}},"/api/billing/claim":{"post":{"operationId":"claimCheckoutSessionPost","summary":"Exchange session_id + claim_token in a JSON body for the fulfilled API key and credit balance (15-min same-IP retry grace window)","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["session_id","claim_token"],"properties":{"session_id":{"type":"string"},"claim_token":{"type":"string"}}}}}},"responses":{"200":{"description":"Payment settled and API key returned. Cache-Control: no-store."},"202":{"description":"Payment pending webhook confirmation."},"400":{"description":"session_id and claim_token are required."},"403":{"description":"Invalid claim_token."},"404":{"description":"Checkout session not found."},"410":{"description":"Claim token expired or claimed from another IP."}}},"get":{"operationId":"claimCheckoutSession","deprecated":true,"summary":"Exchange session_id + claim_token for the fulfilled API key and credit balance (15-min same-IP retry grace window)","security":[],"parameters":[{"name":"session_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"claim_token","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Payment settled and API key returned."},"202":{"description":"Payment pending webhook confirmation."},"403":{"description":"Invalid claim_token."},"404":{"description":"Checkout session not found."},"410":{"description":"Claim token expired or claimed from another IP."}}}},"/api/billing/waffo-webhook":{"post":{"operationId":"waffoWebhookHandler","summary":"Verify Waffo Pancake X-Waffo-Signature (RSA-SHA256) or Acquiring X-SIGNATURE and fulfill/refund credits idempotently","security":[],"responses":{"200":{"description":"Waffo order.completed or refund.succeeded processed idempotently."},"400":{"description":"Invalid signature, replay timeout, or test event in prod mode."}}}},"/api/billing/webhook":{"post":{"operationId":"billingWebhookHandler","summary":"Unified Waffo MoR / Stripe webhook handler (auto-dispatches by signature header)","security":[],"responses":{"200":{"description":"Webhook processed idempotently."},"400":{"description":"Invalid webhook signature or malformed payload."},"503":{"description":"Webhook verification key/secret not configured."}}}},"/api/v1/telemetry/summary":{"get":{"operationId":"getTelemetrySummary","summary":"Admin-only funnel telemetry summary (requires ZSTACK_ADMIN_KEY Bearer token)","security":[{"BearerAuth":[]}],"parameters":[{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":365}}],"responses":{"200":{"description":"Aggregated non-PII funnel conversion event counts."},"403":{"description":"Invalid or missing ZSTACK_ADMIN_KEY."}}}}}}