{"openapi":"3.1.0","info":{"title":"StoreTechScan Domain Intelligence API","version":"1.0.0","summary":"Pay-as-you-go bulk tech stack, Shopify live inventory/pricing, ICP classification, and public generic contact enrichment.","description":"StoreTechScan inspects domains across 4 stages: (1) deterministic tech stack & e-commerce plugin fingerprinting, (2) Shopify /products.json live inventory & median pricing probe, (3) homepage ICP vertical & business model classification, and (4) public generic role email & official social profile extraction. Unreachable domains (DNS errors, >8s timeouts, TLS failures, WAF challenges, and 5xx) are never billed.","contact":{"name":"StoreTechScan Support","email":"storetechscan-support@ydev.work","url":"https://storetechscan.ytriple.dev"}},"servers":[{"url":"https://storetechscan.ytriple.dev","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":"Outreach prospect maturity & commercial readiness score on a 1.0–5.0 scale."},"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"]}}},"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"]}}},"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"},"results":{"type":"array","items":{"$ref":"#/components/schemas/DomainInspectionResult"}}}}}},"paths":{"/api/v1/inspect":{"post":{"operationId":"inspectDomainsV1","summary":"Inspect 1 to 100 domains synchronously (Clay / n8n / Make / Agent ready)","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiInspectRequest"}}}},"responses":{"200":{"description":"Inspection results with transparent failure-refund billing summary.","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":"Missing or invalid Bearer API Key."},"402":{"description":"Insufficient credit balance."},"429":{"description":"Concurrent inspection capacity reached before reservation. Default: 4 requests per running server.","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)","security":[{"BearerAuth":[]}],"parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string"},"example":"allbirds.com"}],"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":"Missing or invalid Bearer API Key."},"402":{"description":"Insufficient credit balance."},"429":{"description":"Concurrent inspection capacity reached before reservation. Default: 4 requests per running server.","headers":{"Retry-After":{"description":"Seconds to wait before trying again.","schema":{"type":"integer","example":2}}}}}}},"/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 rows/24h per IP) or up to 10,000 domains with a funded API Key","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 rate limit exceeded."}}}},"/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, and paginated results."},"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":{"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"}}}}}},"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."}}}}}}