{"openapi":"3.1.0","info":{"title":"exNiche product search","version":"0.6.0","description":"Gap API (products people ask for and can't buy, scored go / maybe / no-go) and keyless catalogue discovery. Listings are recorded observations, not live purchase guarantees. Credits per call: search_products / GET /v1/search: 1; check_demand: 1; report_not_found: 0 (free); list_gaps / GET /v1/gaps (detail=summary): 1 per call; list_gaps / GET /v1/gaps (detail=full): 1 + 10 per scored row; get_gap / GET /v1/gaps/{slug} (detail=summary): 1; get_gap / GET /v1/gaps/{slug} (detail=full): 100; get_dossier / GET /v1/gaps/{slug}/dossier (not yet unlocked): 19,000, unlocks for the account; get_dossier (already unlocked): 0. exNiche data: use with attribution to exniche.com; quoted asks keep their source licence (Stack Exchange: CC BY-SA 4.0, link and author)."},"servers":[{"url":"https://exniche.com"}],"security":[],"paths":{"/v1/gaps":{"get":{"operationId":"listGaps","security":[{},{"workspaceKey":[]}],"summary":"List scored product gaps (go / maybe / no-go)","description":"Credits: detail=summary 1 per call; detail=full 1 + 10 per scored row. Scout/Operator web sessions: no credits.","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":200},"description":"Words that must appear in the label or requirements"},{"name":"category","in":"query","required":false,"schema":{"type":"string"}},{"name":"verdict","in":"query","required":false,"schema":{"type":"string"},"description":"Comma list: go, maybe, no-go"},{"name":"class","in":"query","required":false,"schema":{"type":"string"},"description":"Comma list: absent, exists_hard_to_find, unverified"},{"name":"trend","in":"query","required":false,"schema":{"type":"string"},"description":"Comma list: rising, steady, cooling"},{"name":"source","in":"query","required":false,"schema":{"type":"string"},"description":"Comma list: community_ask, agent_search, store_search, bot_research"},{"name":"min_score","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"since","in":"query","required":false,"schema":{"type":"string"},"description":"ISO date or epoch milliseconds"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["score","newest","asks","rising"],"default":"score"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"next_cursor from the previous page"},{"name":"detail","in":"query","required":false,"schema":{"type":"string","enum":["summary","full"],"default":"summary"},"description":"summary = L0, 1 credit per call; full = L1, 1 + 10 credits per scored row"},{"name":"include","in":"query","required":false,"schema":{"type":"string","enum":["unscored"]},"description":"Also return unscored leads (verdict null, L0 only)"}],"responses":{"200":{"description":"Gaps at the requested level","content":{"application/json":{"schema":{"type":"object","required":["gaps","credits_charged","licence"],"properties":{"gaps":{"type":"array","items":{"$ref":"#/components/schemas/Gap"}},"next_cursor":{"type":["string","null"]},"detail":{"type":"string"},"credits_charged":{"type":"integer"},"licence":{"type":"string"}}}}}},"400":{"description":"Invalid filter or cursor"},"401":{"description":"Invalid supplied workspace key"},"402":{"description":"Credits exhausted. Body has code (MONTHLY_LIMIT or CREDITS_EXHAUSTED), credits_required, upgrade_url and human_message: show both to the user. No automatic charges."}}}},"/v1/gaps/{slug}":{"get":{"operationId":"getGap","security":[{},{"workspaceKey":[]}],"summary":"Get one gap by slug or id","description":"Credits: detail=summary 1; detail=full 100. Unscored leads return summary only.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"detail","in":"query","schema":{"type":"string","enum":["summary","full"],"default":"summary"}}],"responses":{"200":{"description":"One gap","content":{"application/json":{"schema":{"type":"object","properties":{"gap":{"$ref":"#/components/schemas/Gap"},"credits_charged":{"type":"integer"},"licence":{"type":"string"}}}}}},"400":{"description":"Invalid filter or cursor"},"401":{"description":"Invalid supplied workspace key"},"402":{"description":"Credits exhausted. Body has code (MONTHLY_LIMIT or CREDITS_EXHAUSTED), credits_required, upgrade_url and human_message: show both to the user. No automatic charges."},"404":{"description":"Gap not found"}}}},"/v1/gaps/{slug}/dossier":{"get":{"operationId":"getDossier","security":[{"workspaceKey":[]}],"summary":"Get the full dossier for a scored gap","description":"Needs a workspace key or signed-in session. Not yet unlocked: 19,000 credits, then unlocked for the account. Already unlocked: 0 credits. 501 until dossiers launch.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Dossier"},"401":{"description":"Workspace key required"},"402":{"description":"Credits exhausted. Body has code (MONTHLY_LIMIT or CREDITS_EXHAUSTED), credits_required, upgrade_url and human_message: show both to the user. No automatic charges."},"404":{"description":"Gap not found or not scored"},"501":{"description":"Dossiers not available yet; nothing charged"}}}},"/v1/gaps.csv":{"get":{"operationId":"exportGapsCsv","security":[{"workspaceKey":[]}],"summary":"CSV export of the gap ledger (Operator)","description":"Same filters as /v1/gaps; up to 10,000 rows; no credits.","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":200},"description":"Words that must appear in the label or requirements"},{"name":"category","in":"query","required":false,"schema":{"type":"string"}},{"name":"verdict","in":"query","required":false,"schema":{"type":"string"},"description":"Comma list: go, maybe, no-go"},{"name":"class","in":"query","required":false,"schema":{"type":"string"},"description":"Comma list: absent, exists_hard_to_find, unverified"},{"name":"trend","in":"query","required":false,"schema":{"type":"string"},"description":"Comma list: rising, steady, cooling"},{"name":"source","in":"query","required":false,"schema":{"type":"string"},"description":"Comma list: community_ask, agent_search, store_search, bot_research"},{"name":"min_score","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"since","in":"query","required":false,"schema":{"type":"string"},"description":"ISO date or epoch milliseconds"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["score","newest","asks","rising"],"default":"score"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"include","in":"query","required":false,"schema":{"type":"string","enum":["unscored"]},"description":"Also return unscored leads (verdict null, L0 only)"}],"responses":{"200":{"description":"CSV","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"Key or sign-in required"},"403":{"description":"Operator plan required"}}}},"/v1/requests":{"get":{"operationId":"listPublicProductRequests","summary":"Read source-linked purchasing requests; unmet need unverified","description":"Independent seed evidence, never agent traffic. Preserve attribution and license.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"Requests, source metadata, pagination, and explicit unverified unmet-need caveat"}}}},"/v1/search":{"get":{"operationId":"searchProducts","security":[{},{"workspaceKey":[]}],"summary":"Find recorded products with structured shopping constraints","description":"Optional workspace Bearer key: 1,000 free searches per UTC calendar month, then prepaid credits. Otherwise 1,000 searches/month/IP. Use a short category/name for q. No currency conversion. Verify retailer details before buying.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Short product category or name, e.g. keyboards, shoes or coffee. Put constraints in separate fields."}},{"name":"max_price","in":"query","required":false,"schema":{"type":"number","minimum":0,"description":"Maximum recorded price. Supply currency too; no currency conversion."}},{"name":"currency","in":"query","required":false,"schema":{"type":"string","pattern":"^[A-Za-z]{3}$","description":"Three-letter currency code, e.g. AUD."}},{"name":"size","in":"query","required":false,"schema":{"type":"string","description":"Required recorded size, e.g. M."}},{"name":"color","in":"query","required":false,"schema":{"type":"string","description":"Required recorded color, e.g. black."}},{"name":"in_stock","in":"query","required":false,"schema":{"type":"boolean","description":"Filter recorded availability. Availability must be checked at retailer."}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["relevance","price_asc","price_desc"],"default":"relevance"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":10}}],"responses":{"200":{"description":"Catalogue results and limitations","content":{"application/json":{"schema":{"type":"object","required":["found","results"],"properties":{"query":{"type":"string"},"found":{"type":"boolean","description":"Whether this catalogue yielded a suitable match; false is not a claim about the whole market."},"results":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"next_actions":{"type":"array","items":{"type":"string"}},"caveats":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Missing query or invalid filter"},"401":{"description":"Invalid supplied workspace key"},"402":{"description":"Free allowance and prepaid search credits exhausted. Body includes upgrade_url and human_message: show both to the user so they can sign up or add credits. No automatic charges. No x402."},"503":{"description":"Search or usage storage temporarily unavailable; account credits not debited"}}}}},"components":{"securitySchemes":{"workspaceKey":{"type":"http","scheme":"bearer","description":"Optional workspace key for account allowance and search credits"}},"schemas":{"Gap":{"type":"object","required":["id","slug","url","label","level","licence","attribution","source_label"],"description":"L0 fields always; L1 adds score, score_parts, origins, asks, requirements, weekly_asks, products_checked, best_fit.","properties":{"id":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","format":"uri"},"level":{"type":"string","enum":["L0","L1"]},"label":{"type":"string"},"category":{"type":["string","null"]},"status":{"type":"string","enum":["scored","lead"]},"verdict":{"type":["string","null"],"enum":["go","maybe","no-go",null]},"score_band":{"type":["string","null"]},"class":{"type":["string","null"]},"class_label":{"type":["string","null"]},"trend":{"type":["string","null"]},"source_counts":{"type":"object","additionalProperties":{"type":"integer"}},"first_seen":{"type":"number"},"last_seen":{"type":"number"},"ask":{"type":["object","null"]},"locked":{"type":"array","items":{"type":"string"}},"source_label":{"type":"string"},"attribution":{"type":"string"},"licence":{"type":"string"},"score":{"type":["integer","null"]},"score_parts":{"type":["object","null"]},"asks":{"type":"array","items":{"type":"object"}},"requirements":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"Product":{"type":"object","required":["title","url"],"properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri"},"price":{"type":["number","null"],"description":"Recorded price; unknown is null."},"currency":{"type":["string","null"]},"image_url":{"type":["string","null"]},"source":{"type":"string"},"confidence":{"type":"number"},"selected_variant":{"type":["object","null"],"description":"Recorded variant satisfying constraints, when known.","additionalProperties":true},"matching_variants":{"type":"array","description":"Recorded variants satisfying constraints. Verify current details with retailer.","items":{"type":"object","additionalProperties":true}},"availability":{"type":"string","enum":["in_stock","out_of_stock","unknown"]},"observed_at":{"type":["number","null"],"description":"Observation time, milliseconds since Unix epoch."},"freshness":{"type":"string","enum":["within_72h","stale_or_unknown"]},"price_basis":{"type":"string","const":"item_only_excludes_shipping_and_tax"}},"additionalProperties":true}}}}