{"openapi":"3.1.0","info":{"title":"NicheIQs API","description":"Data-driven winnability scores for market niches. Powered by Reddit signals, Google Trends, and Claude AI synthesis. Built for indie founders and autonomous agents evaluating markets to enter.","version":"1.0.0"},"paths":{"/auth/request-link":{"post":{"summary":"Request Magic Link","description":"Send a magic sign-in link. Always returns 200 (no user enumeration).","operationId":"request_magic_link_auth_request_link_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MagicLinkRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/verify":{"get":{"summary":"Verify Magic Link","description":"Validate magic link token, set session cookie, redirect to landing.","operationId":"verify_magic_link_auth_verify_get","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string","title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/me":{"get":{"summary":"Auth Me","description":"Return session info for signed-in users.","operationId":"auth_me_auth_me_get","parameters":[{"name":"ne_session","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ne Session"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/logout":{"post":{"summary":"Logout","operationId":"logout_auth_logout_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/auth/preferences":{"patch":{"summary":"Update Preferences","operationId":"update_preferences_auth_preferences_patch","parameters":[{"name":"ne_session","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ne Session"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreferencesRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/unsubscribe":{"get":{"summary":"Unsubscribe","description":"One-click unsubscribe from digest via signed token in email footer.","operationId":"unsubscribe_auth_unsubscribe_get","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string","title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/billing/setup":{"get":{"summary":"Billing Setup","description":"Redirect signed-in users to Stripe Checkout to activate PAYG billing.\nIf not signed in, bounce to landing with a flag to open the auth modal.","operationId":"billing_setup_billing_setup_get","parameters":[{"name":"ne_session","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ne Session"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/billing/keys":{"get":{"summary":"Billing Keys","description":"Return the signed-in user's active API keys with current-month usage.","operationId":"billing_keys_billing_keys_get","parameters":[{"name":"ne_session","in":"cookie","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ne Session"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/health":{"get":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/trending":{"get":{"summary":"Trending","description":"Public endpoint — returns the most-queried niches with their scores.\nUsed by the landing page to show real community activity.","operationId":"trending_trending_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/old":{"get":{"summary":"Root","operationId":"root_old_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/analyze":{"post":{"summary":"Submit Analysis","operationId":"submit_analysis_analyze_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyzeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyzeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/analyze/batch":{"post":{"summary":"Batch Analyze","description":"Submit up to 10 niches at once. Returns a list of job_ids to poll, or fires callback_url when all complete.","operationId":"batch_analyze_analyze_batch_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchAnalyzeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/analyze/sync":{"post":{"summary":"Analyze Sync","description":"Synchronous analysis endpoint for ChatGPT GPT Actions and other callers\nthat can't handle async polling. Submits the job, polls internally, and\nreturns the full report in one response. Times out after 90 seconds.","operationId":"analyze_sync_analyze_sync_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyzeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/results/{job_id}":{"get":{"summary":"Get Result","operationId":"get_result_results__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResultResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/webhook/stripe":{"post":{"summary":"Stripe Webhook","description":"Auto-provisions API keys on successful payment.\nWire this URL in your Stripe dashboard → Webhooks.\nEvents: checkout.session.completed, customer.subscription.deleted","operationId":"stripe_webhook_webhook_stripe_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"AnalyzeRequest":{"properties":{"niche":{"type":"string","maxLength":300,"minLength":3,"title":"Niche","example":"AI invoice software for freelancers"},"client":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Client","description":"Agent/client identifier (e.g. 'claude-agent', 'autogpt')"},"callback_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Callback Url","description":"Webhook URL — POSTed with the full report when analysis completes"}},"type":"object","required":["niche"],"title":"AnalyzeRequest"},"AnalyzeResponse":{"properties":{"job_id":{"type":"string","title":"Job Id"},"status":{"type":"string","title":"Status"},"poll_url":{"type":"string","title":"Poll Url"}},"type":"object","required":["job_id","status","poll_url"],"title":"AnalyzeResponse"},"BatchAnalyzeRequest":{"properties":{"niches":{"items":{"type":"string"},"type":"array","maxItems":10,"minItems":1,"title":"Niches","description":"1–10 niches to analyze in parallel"},"callback_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Callback Url","description":"Webhook URL — POSTed once with all results when every job completes"},"client":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Client"}},"type":"object","required":["niches"],"title":"BatchAnalyzeRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"MagicLinkRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email"}},"type":"object","required":["email"],"title":"MagicLinkRequest"},"PreferencesRequest":{"properties":{"subscribed_digest":{"type":"boolean","title":"Subscribed Digest"}},"type":"object","required":["subscribed_digest"],"title":"PreferencesRequest"},"ResultResponse":{"properties":{"job_id":{"type":"string","title":"Job Id"},"status":{"type":"string","title":"Status"},"report":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Report"}},"type":"object","required":["job_id","status"],"title":"ResultResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}