{"openapi":"3.1.0","info":{"title":"SONAR API","description":"KYB company lookup and due-diligence API. The public API is under /v1: send the key as X-API-Key or Authorization: Bearer sk-sonar-...; guide and changelog at https://getsonar.report/developers. The /api routes serve the SONAR web app.","version":"1.0.0"},"paths":{"/api/profiles/products":{"get":{"tags":["profiles"],"summary":"List Available Products","description":"Product types this user may pick (product selector).\n\nT1.2: non-admins get the public products only; admins also get the\nfrozen ones, marked ``visibility: \"admin_only\"``. Same rule as\n``GET /api/products``.","operationId":"list_available_products_api_profiles_products_get","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/profiles/industries":{"get":{"tags":["profiles"],"summary":"List Industries","description":"Return industry configuration for the frontend (selector + module toggles).","operationId":"list_industries_api_profiles_industries_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/profiles":{"get":{"tags":["profiles"],"summary":"List Profiles","description":"List all profiles for the authenticated user.","operationId":"list_profiles_api_profiles_get","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["profiles"],"summary":"Create Profile","description":"Create a new profile.","operationId":"create_profile_api_profiles_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/profiles/{profile_id}":{"get":{"tags":["profiles"],"summary":"Get Profile","description":"Get a single profile with its competitors.","operationId":"get_profile_api_profiles__profile_id__get","parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","title":"Profile Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["profiles"],"summary":"Update Profile","description":"Update a profile.","operationId":"update_profile_api_profiles__profile_id__put","parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","title":"Profile Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["profiles"],"summary":"Delete Profile","description":"Delete a profile and all associated data.","operationId":"delete_profile_api_profiles__profile_id__delete","parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","title":"Profile Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/profiles/detect_industry":{"post":{"tags":["profiles"],"summary":"Detect Industry","description":"Classify a company's industry from its website using Claude Haiku.\n\nThe LLM is constrained to picking a key from INDUSTRY_MODULES — it\ncannot hallucinate a new industry. Any failure (missing API key,\nnetwork error, parse error, key not in the allowlist) returns the\n`custom_software` fallback with confidence 0 so the caller's flow\nis never blocked.\n\nCompetitive-intelligence onboarding only: the same product gate as the\nother CI entry points (403 while CI is frozen, admins excepted), so a\nfree signup cannot spend SONAR's Anthropic key here.","operationId":"detect_industry_api_profiles_detect_industry_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetectIndustryRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetectIndustryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/products":{"get":{"tags":["products"],"summary":"Get Products","description":"Return the product registry as this user sees it.\n\n``as_customer=true``: as a non-admin sees it (admin onboarding preview).","operationId":"get_products_api_products_get","parameters":[{"name":"as_customer","in":"query","required":false,"schema":{"type":"boolean","description":"The registry a non-admin gets.","default":false,"title":"As Customer"},"description":"The registry a non-admin gets."},{"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/ProductsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/profiles/{profile_id}/competitors":{"get":{"tags":["competitors"],"summary":"List Competitors","description":"List all competitors for a profile.","operationId":"list_competitors_api_profiles__profile_id__competitors_get","parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","title":"Profile Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["competitors"],"summary":"Add Competitor","description":"Add a competitor to a profile (max 20 for regular users, unlimited for admins).","operationId":"add_competitor_api_profiles__profile_id__competitors_post","parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","title":"Profile Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompetitorCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/competitors/{competitor_id}":{"put":{"tags":["competitors"],"summary":"Update Competitor","description":"Update a competitor.","operationId":"update_competitor_api_competitors__competitor_id__put","parameters":[{"name":"competitor_id","in":"path","required":true,"schema":{"type":"string","title":"Competitor Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompetitorUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["competitors"],"summary":"Delete Competitor","description":"Delete a competitor.","operationId":"delete_competitor_api_competitors__competitor_id__delete","parameters":[{"name":"competitor_id","in":"path","required":true,"schema":{"type":"string","title":"Competitor Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/competitors/import-preview":{"post":{"tags":["competitors"],"summary":"Import From Excel Preview","description":"Parse an Excel/CSV file WITHOUT writing to the DB.\n\nUsed by the New-Screening form so a user can upload a competitor list\nbefore the screening profile exists. Returns parsed rows the frontend\npushes into its staged-accounts state; the actual DB write happens\nwhen the user clicks \"Create Screening\".\n\nNo profile_id required, no _verify_profile_ownership call. Pure\nfile-parsing endpoint, just authenticated.","operationId":"import_from_excel_preview_api_competitors_import_preview_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_import_from_excel_preview_api_competitors_import_preview_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/profiles/{profile_id}/competitors/import":{"post":{"tags":["competitors"],"summary":"Import From Excel","description":"Import competitors from an Excel file. Replaces existing competitors.","operationId":"import_from_excel_api_profiles__profile_id__competitors_import_post","parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","title":"Profile Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_import_from_excel_api_profiles__profile_id__competitors_import_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/competitors/discover-preview":{"post":{"tags":["competitors"],"summary":"Discover Competitors Preview","description":"AI-suggest 5 competitors/accounts WITHOUT a saved profile.\n\nUsed by the New-Screening form (and the embedded onboarding wizard)\nbefore the profile exists. Pure LLM-call, just authenticated;\nno DB writes, no profile_id required.","operationId":"discover_competitors_preview_api_competitors_discover_preview_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscoverPreviewRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/profiles/{profile_id}/competitors/discover":{"post":{"tags":["competitors"],"summary":"Discover Competitors","description":"Use AI to suggest 5 direct competitors based on the company profile.\n\nBody is optional; when present, `exclude_names` is merged into the\nDB-persisted competitor list so \"Refresh suggestions\" in the\nonboarding wizard can preserve the user's already-ticked picks\nwhile regenerating the rest.","operationId":"discover_competitors_api_profiles__profile_id__competitors_discover_post","parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","title":"Profile Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/DiscoverRequest"},{"type":"null"}],"title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/reports/profiles/{profile_id}/generate":{"post":{"tags":["reports"],"summary":"Generate Report","description":"Trigger a new report generation. Returns immediately with report_id.\n\n503 + Retry-After when the report queue is unavailable.","operationId":"generate_report_api_reports_profiles__profile_id__generate_post","parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","title":"Profile Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateRequest","default":{}}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/reports/{report_id}/status":{"get":{"tags":["reports"],"summary":"Get Report Status","description":"Poll report generation status. Phase K3 surfaces step + pct\nwhile status == running so the frontend can show real-time progress.","operationId":"get_report_status_api_reports__report_id__status_get","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","title":"Report Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/reports":{"get":{"tags":["reports"],"summary":"List Reports","description":"List reports for the authenticated user, optionally filtered by profile.\n\nCancelled reports are excluded — once a user cancels a screening they\ndon't want it cluttering the Reports list / Dashboard widget. The row\nstays in the DB (admin views still surface it) but is hidden from the\nend-user surfaces.","operationId":"list_reports_api_reports_get","parameters":[{"name":"profile_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Profile Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/reports/{report_id}":{"get":{"tags":["reports"],"summary":"Get Report","description":"Get full report data (JSON content + metadata).","operationId":"get_report_api_reports__report_id__get","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","title":"Report Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["reports"],"summary":"Delete Report","description":"Delete a report (only if completed or failed).","operationId":"delete_report_api_reports__report_id__delete","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","title":"Report Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/reports/usage/me":{"get":{"tags":["reports"],"summary":"Get My Usage","description":"Get current user's credit usage statistics.","operationId":"get_my_usage_api_reports_usage_me_get","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/reports/{report_id}/cancel":{"post":{"tags":["reports"],"summary":"Cancel Report","description":"Cancel a pending OR running report and refund its quota.\n\nPhase Y — previously this endpoint only accepted ``status=pending``,\nso users couldn't cancel an in-flight 3-min screening. Now it\naccepts both pending and running, marks the report as\n``status='cancelled'`` (distinct from 'failed' so it doesn't\npollute the failure-rate metrics), and refunds:\n\n  - SaaS subscription quota — calls refund_subscription_report\n    SQL helper which decrements reports_used_this_period.\n    Only when the report used the quota (``billing_mode``\n    'subscription', or NULL on rows from before pricing v2).\n  - Free report: the free counter excludes cancelled reports.\n  - Pay as you go / overage balance charge: refunded by the\n    ``reports_refund_charge`` DB trigger on the 'cancelled' write.\n\nBest-effort job stop (services.jobs.cancel) — if the report row carries a\ntask_id, signal the worker to terminate. The task itself checks\nreport.status before persisting any output, so even if the\nrevoke doesn't reach a worker mid-flight, the cancelled-row\nwrite here will block the late commit.","operationId":"cancel_report_api_reports__report_id__cancel_post","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","title":"Report Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/reports/{report_id}/pdf":{"get":{"tags":["reports"],"summary":"Download Report Pdf","description":"Get a signed URL for downloading the report PDF.","operationId":"download_report_pdf_api_reports__report_id__pdf_get","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","title":"Report Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/reports/{report_id}/pdf/brand-preview":{"get":{"tags":["reports"],"summary":"Preview Branded Pdf","description":"The owner's brand kit on this KYB report, as PDF bytes for the in-app\npreview. Not entitled to white-label: every page carries a \"PREVIEW\"\nmark (the clean branded PDF is GET /{report_id}/pdf on the Agency plan).\nNever stored, never served on a share link. Owner only.","operationId":"preview_branded_pdf_api_reports__report_id__pdf_brand_preview_get","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","title":"Report Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/reports/{report_id}/share":{"post":{"tags":["reports"],"summary":"Share Report","description":"Create or return a shareable link token for a report.\n\nThe token is 32 bytes (~256-bit) URL-safe random and expires after\n``expires_in_days`` (default 90, max 365). Re-issuing for a report\nthat already has an active token returns the existing token unchanged\n— the caller can DELETE the token to rotate.","operationId":"share_report_api_reports__report_id__share_post","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","title":"Report Id"}},{"name":"expires_in_days","in":"query","required":false,"schema":{"type":"integer","default":90,"title":"Expires In Days"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["reports"],"summary":"Unshare Report","description":"Revoke sharing for a report by clearing the share token.","operationId":"unshare_report_api_reports__report_id__share_delete","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","title":"Report Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/reports/cron/run-scheduled":{"post":{"tags":["reports"],"summary":"Run Scheduled Reports","description":"Triggered by Render Cron Job. Finds due schedules and generates reports.\n\nProtected by X-Cron-Secret header matching CRON_SECRET env var with\nconstant-time comparison + optional source-IP allow-list (Phase N5).","operationId":"run_scheduled_reports_api_reports_cron_run_scheduled_post","parameters":[{"name":"X-Cron-Secret","in":"header","required":true,"schema":{"type":"string","title":"X-Cron-Secret"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/user/settings":{"get":{"tags":["user"],"summary":"Get User Settings","operationId":"get_user_settings_api_user_settings_get","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["user"],"summary":"Update User Settings","operationId":"update_user_settings_api_user_settings_put","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserSettingsUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/user/contact":{"post":{"tags":["user"],"summary":"Send Contact Message","operationId":"send_contact_message_api_user_contact_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactMessage"}}}},"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/schedules/{profile_id}":{"get":{"tags":["schedules"],"summary":"Get Schedule","description":"Get the schedule for a profile.","operationId":"get_schedule_api_schedules__profile_id__get","parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","title":"Profile Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["schedules"],"summary":"Upsert Schedule","description":"Create or update a schedule for a profile.","operationId":"upsert_schedule_api_schedules__profile_id__put","parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","title":"Profile Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["schedules"],"summary":"Disable Schedule","description":"Disable (not delete) the schedule for a profile.","operationId":"disable_schedule_api_schedules__profile_id__delete","parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","title":"Profile Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/webhooks/user-signup":{"post":{"tags":["webhooks"],"summary":"User Signup","description":"Called by Supabase Auth Hook when a new user confirms their account.\n\nSupabase → Authentication → Hooks → \"Send email\" or custom hook.\nSet the Authorization header value to match SIGNUP_WEBHOOK_SECRET env var.","operationId":"user_signup_api_webhooks_user_signup_post","parameters":[{"name":"x-webhook-secret","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Webhook-Secret"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/screenings/run":{"post":{"tags":["screenings"],"summary":"Run Screening","description":"Run a new KYB screening for a single company. Returns immediately.\n\n503 + Retry-After when the report queue is unavailable.","operationId":"run_screening_api_screenings_run_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreeningRunRequest"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/screenings":{"get":{"tags":["screenings"],"summary":"List Screenings","description":"List all screenings for a KYB workspace.","operationId":"list_screenings_api_screenings_get","parameters":[{"name":"profile_id","in":"query","required":true,"schema":{"type":"string","title":"Profile Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/screenings/{screening_id}":{"get":{"tags":["screenings"],"summary":"Get Screening","description":"Get a single screening detail.","operationId":"get_screening_api_screenings__screening_id__get","parameters":[{"name":"screening_id","in":"path","required":true,"schema":{"type":"string","title":"Screening Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/screenings/{screening_id}/rescreen":{"post":{"tags":["screenings"],"summary":"Rescreen","description":"Re-run a screening for the same company. Creates a new report.","operationId":"rescreen_api_screenings__screening_id__rescreen_post","parameters":[{"name":"screening_id","in":"path","required":true,"schema":{"type":"string","title":"Screening Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/company-search":{"post":{"tags":["company-search"],"summary":"Company Search Route","operationId":"company_search_route_api_company_search_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanySearchRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanySearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/shared/{share_token}":{"get":{"tags":["shared"],"summary":"Get Shared Report","description":"Public endpoint — fetch a shared report by its share token. No auth required.","operationId":"get_shared_report_api_shared__share_token__get","parameters":[{"name":"share_token","in":"path","required":true,"schema":{"type":"string","title":"Share Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/shared/{share_token}/pdf":{"get":{"tags":["shared"],"summary":"Get Shared Report Pdf","description":"Public endpoint — get a signed PDF download URL for a shared report. No auth required.","operationId":"get_shared_report_pdf_api_shared__share_token__pdf_get","parameters":[{"name":"share_token","in":"path","required":true,"schema":{"type":"string","title":"Share Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/account":{"get":{"tags":["account"],"summary":"Get Account","description":"Current balance + lifetime totals + pricing reference for the UI.","operationId":"get_account_api_account_get","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Account Api Account Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/account/signup-ip":{"post":{"tags":["account"],"summary":"Record Signup Ip","description":"Record the IP address this new account signed up from (the frontend\ncalls it once after sign-up). The IP is the one our edge proxy saw,\nnever a value from the client. Accounts older than 24 hours and admins\nare not recorded; a second call changes nothing. Always 204: a failure\nhere never affects sign-up (``services.signup_ip_gate``).","operationId":"record_signup_ip_api_account_signup_ip_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/account/business-email/check":{"post":{"tags":["account"],"summary":"Check Business Email","description":"Can this address unlock the free report of an account gated by the\nsame-IP rule? A business domain (not free webmail, not disposable), not\nthe current address, not already used by another account to unlock.\nThe frontend then asks Supabase Auth to change the account email, which\nsends a confirmation link; the gate lifts once the change is confirmed.\n409 ``not_gated`` for any other account. Rate limited per IP (inbound\nlimiter bucket ``/api/account/business-email/``).","operationId":"check_business_email_api_account_business_email_check_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessEmailCheck"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessEmailCheckResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/account/transactions":{"get":{"tags":["account"],"summary":"Get Transactions","description":"Paginated transaction history for the current user.\n\nReturns up to 200 rows per page (clamped server-side). Most-recent first.","operationId":"get_transactions_api_account_transactions_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Transactions Api Account Transactions Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/account/topup-intent":{"post":{"tags":["account"],"summary":"Create Topup Intent","description":"Create a Stripe Checkout session (mode=payment) for a one-shot\nbalance top-up. Returns a ``checkout_url`` the frontend can redirect\nto; on success Stripe sends ``checkout.session.completed`` (with\nmode=payment) and ``payment_intent.succeeded`` to the existing\n``/api/billing/webhook``, which credits the account balance.\n\nBody:\n    pack:         \"pack_5\" | \"pack_20\" (optional) — a credit pack: the\n                  pack's price is charged and the webhook adds its\n                  bonus credit (``core.pricing.CREDIT_PACKS``). Wins\n                  over amount_cents.\n    amount_cents: int (required without pack) — clamped to\n                  [MIN_DEPOSIT_CENTS, MAX_DEPOSIT_CENTS]\n    notes:        str (optional, max 2000 chars) — passed through\n                  to Stripe metadata for support traceability\n\nIdempotency: each call creates a fresh Checkout session; multiple\nabandoned sessions are harmless (no charge until the user completes\npayment in Stripe). The webhook path is idempotent on event_id.","operationId":"create_topup_intent_api_account_topup_intent_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create Topup Intent Api Account Topup Intent Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/me":{"delete":{"tags":["me"],"summary":"Delete My Account","description":"Permanently delete the caller's account, reports, PDFs and screenings.","operationId":"delete_my_account_api_me_delete","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteAccountRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/billing/plan":{"get":{"tags":["billing"],"summary":"Get Plan","description":"Return the current subscription state for the Settings Plan card.\n\nAlways 200; absence of a subscription is conveyed via\n``plan: \"free\"``. Frontend renders an upgrade CTA in that case.","operationId":"get_plan_api_billing_plan_get","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Plan Api Billing Plan Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/billing/report-cost":{"get":{"tags":["billing"],"summary":"Get Report Cost","description":"What the user's next web report costs, without taking anything:\n``mode`` (admin | free | subscription | overage | payg | past_due),\n``price_cents`` from the balance, ``balance_cents``, ``can_run``, the\nplan quota and the free report count. The screening form shows it\nbefore submit.","operationId":"get_report_cost_api_billing_report_cost_get","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Report Cost Api Billing Report Cost Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/billing/checkout":{"post":{"tags":["billing"],"summary":"Create Checkout Session","description":"Create a Stripe Checkout session for a subscription upgrade.\n\nBody:\n    plan:    \"team\" | \"agency\"   (pricing v2; Pulse / Pro are not sold)\n    billing: \"monthly\" | \"yearly\"\n\nReturns:\n    {\"checkout_url\": \"https://checkout.stripe.com/c/...\"}","operationId":"create_checkout_session_api_billing_checkout_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create Checkout Session Api Billing Checkout Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/billing/portal":{"post":{"tags":["billing"],"summary":"Create Portal Session","description":"Return a Stripe Customer Portal URL for the current user.\n\nThe portal lets users update card, change plan, or cancel — Stripe\ndrives the whole flow.","operationId":"create_portal_session_api_billing_portal_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create Portal Session Api Billing Portal Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/billing/webhook":{"post":{"tags":["billing"],"summary":"Stripe Webhook","description":"Stripe webhook receiver — Phase V hardened.\n\nDecision tree:\n  1. Signature missing/invalid → 400 (Stripe won't retry; correct).\n  2. Idempotency hit → 200 (already processed).\n  3. Handler success → record event_id, return 200.\n  4. Transient infra failure (Supabase / network) →\n     alert + 500 so Stripe retries with exponential backoff.\n  5. Poison failure (unknown price, missing user mapping, schema\n     drift) → alert + 200 so Stripe gives up; admin must intervene.\n\nThe previous version returned 200 on every exception, which meant\ntoday's Stripe period-fields hotfix would have permanently lost\n`customer.subscription.created` events from real customers.\n\nEvents handled:\n  - checkout.session.completed\n  - customer.subscription.{created, updated, deleted}\n  - invoice.payment_failed   (Phase V3 — recurring charge dunning)","operationId":"stripe_webhook_api_billing_webhook_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/brand":{"get":{"tags":["brand"],"summary":"Get Brand","operationId":"get_brand_api_brand_get","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["brand"],"summary":"Update Brand","operationId":"update_brand_api_brand_put","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/brand/logo":{"put":{"tags":["brand"],"summary":"Upload Logo","operationId":"upload_logo_api_brand_logo_put","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandLogoUpload"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["brand"],"summary":"Delete Logo","operationId":"delete_logo_api_brand_logo_delete","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/feedback/me":{"get":{"tags":["feedback"],"summary":"Get My Feedback","operationId":"get_my_feedback_api_feedback_me_get","parameters":[{"name":"report_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Report Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/feedback":{"post":{"tags":["feedback"],"summary":"Submit Feedback","operationId":"submit_feedback_api_feedback_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackSubmit"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/feedback/events":{"post":{"tags":["feedback"],"summary":"Feedback Event","operationId":"feedback_event_api_feedback_events_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackEvent"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/client-errors":{"post":{"tags":["observability"],"summary":"Report Client Error","operationId":"report_client_error_api_client_errors_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientErrorReport"}}},"required":true},"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/landing":{"post":{"tags":["observability"],"summary":"Record Landing","operationId":"record_landing_api_landing_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LandingBeacon"}}},"required":true},"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/signup-source":{"post":{"tags":["observability"],"summary":"Record Signup Source","operationId":"record_signup_source_api_signup_source_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupSource"}}}},"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/funnel/signup":{"post":{"tags":["observability"],"summary":"Record Funnel Signup","description":"Tool-to-report funnel: a new account reached the pre-filled\nnew-screening form (``signup_completed_with_prefill``). Counted once per\naccount, only within an hour of its creation, as a count per CTA ref\n(``services.tool_funnel``); always 204.","operationId":"record_funnel_signup_api_funnel_signup_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FunnelSignup"}}}},"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/public/tools/vat-check":{"post":{"tags":["public-tools"],"summary":"Vat Check","operationId":"vat_check_api_public_tools_vat_check_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VatCheckRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VatCheckResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/public/tools/uk-company-lookup":{"post":{"tags":["public-tools"],"summary":"Uk Company Lookup","operationId":"uk_company_lookup_api_public_tools_uk_company_lookup_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UkCompanyLookupRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UkCompanyLookupResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/public/tools/company-lookup":{"post":{"tags":["public-tools"],"summary":"Company Lookup","operationId":"company_lookup_api_public_tools_company_lookup_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCompanyLookupRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCompanyLookupResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/public/funnel-event":{"post":{"tags":["public-tools"],"summary":"Funnel Event","description":"Count one arrival on /login from a \"Run a full KYB check\" CTA.","operationId":"funnel_event_api_public_funnel_event_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FunnelEvent"}}},"required":true},"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/check/{jurisdiction}/{slug}":{"get":{"tags":["pseo-public"],"summary":"Get Pseo Page","description":"Phase P7 — serve a published pSEO page from Supabase Storage.\n\nStatus semantics:\n  200 — page found, in the sitemap (not thin, a registry\n        jurisdiction) and both snapshot verdicts clear\n  410 — page exists but was deindexed (GDPR forget request approved\n        or admin manual deindex), is thin, is a no-registry ('xx')\n        page, or has a non-clear sanctions / PEP verdict: a neutral\n        HTML body, noindex\n  404 — page never existed (no row in pseo_pages)\n  301 — an alias jurisdiction page whose company has a gb page\n        (/check/uk/x → /check/gb/<same company>, query kept); a live\n        uk row with no gb page yet is served as before","operationId":"get_pseo_page_check__jurisdiction___slug__get","parameters":[{"name":"jurisdiction","in":"path","required":true,"schema":{"type":"string","title":"Jurisdiction"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/check/{jurisdiction}":{"get":{"tags":["pseo-public"],"summary":"Get Pseo Country Index","description":"Phase P7 — paginated country index page (50 per page).\n\nThese index pages are themselves SEO assets — long-tail queries\nlike \"uk kyb companies\" land here.","operationId":"get_pseo_country_index_check__jurisdiction__get","parameters":[{"name":"jurisdiction","in":"path","required":true,"schema":{"type":"string","title":"Jurisdiction"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":1,"title":"Page"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/check":{"get":{"tags":["pseo-public"],"summary":"Get Pseo Root Index","description":"Cross-jurisdiction root index. Lists each jurisdiction with its\npage count + a link to the country index.","operationId":"get_pseo_root_index_check_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/sitemap.xml":{"get":{"tags":["pseo-public"],"summary":"Get Sitemap Index","description":"Phase P4 — sitemap index, lists all per-country sitemaps.\n\nNote: in production, the static frontend file at\n`frontend/public/sitemap.xml` shadows this route (Render serves\nstatic files before applying rewrite rules). For pSEO discovery,\nuse `/sitemap-pseo.xml` instead — referenced from robots.txt.","operationId":"get_sitemap_index_sitemap_xml_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/sitemap-pseo.xml":{"get":{"tags":["pseo-public"],"summary":"Get Pseo Sitemap Index","description":"Phase P4 — pSEO sitemap-index. Lives at a separate path from\nthe static `/sitemap.xml` (which is the frontend marketing\nsitemap) so both can coexist. Referenced from robots.txt.","operationId":"get_pseo_sitemap_index_sitemap_pseo_xml_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/sitemap-{jurisdiction}.xml":{"get":{"tags":["pseo-public"],"summary":"Get Per Country Sitemap","description":"Phase P4 — per-country sitemap. URLs for that jurisdiction.","operationId":"get_per_country_sitemap_sitemap__jurisdiction__xml_get","parameters":[{"name":"jurisdiction","in":"path","required":true,"schema":{"type":"string","title":"Jurisdiction"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/robots.txt":{"get":{"tags":["pseo-public"],"summary":"Get Robots","description":"Phase P4 — robots.txt: allow /check, block /admin + /api except\n/api/pseo/forget (needs to be reachable for GDPR submissions).","operationId":"get_robots_robots_txt_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/api/pseo/forget/mode":{"get":{"tags":["pseo-public"],"summary":"Get Forget Mode","description":"How a submission is verified, so the form can say what happens\nbefore the user submits: ``verification`` is ``manual`` (a person\nreviews it, no email is sent) or ``email`` (confirmation link).","operationId":"get_forget_mode_api_pseo_forget_mode_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Get Forget Mode Api Pseo Forget Mode Get"}}}}}}},"/api/pseo/forget":{"post":{"tags":["pseo-public"],"summary":"Submit Forget Request","description":"Public GDPR Article 17 submission endpoint.\n\nManual mode (no email provider, the launch default):\n  1. Validate the page URL maps to an existing pseo_pages row\n  2. Insert pseo_forget_requests with status='pending'; no email\n  3. Admin alert \"needs manual review\"; a person approves (deindex)\n     or rejects (with a reason) in /admin/pseo/forget\n\nEmail mode (RESEND_API_KEY set, Phase AB6):\n  1. Insert with status='unverified' + confirmation_token (DB default)\n  2. Email the link GET /api/pseo/forget/confirm?token=<uuid>\n  3. User clicks → page auto-deindexed → sitemap regen queued\n\nResponse is intentionally generic — don't leak whether the\npage exists or not (defense against enumeration). It carries\n``verification`` (\"manual\" | \"email\") and ``review_days``.","operationId":"submit_forget_request_api_pseo_forget_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForgetRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Submit Forget Request Api Pseo Forget Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/pseo/forget/confirm":{"get":{"tags":["pseo-public"],"summary":"Confirm Forget Request","description":"Phase AB6 — user clicks the confirmation link from the email.\n\nOn valid token:\n  - Mark forget_request status='confirmed', confirmed_at=NOW()\n  - Set pseo_pages.deindexed_at = NOW() (page returns 410 from now)\n  - Mark forget_request status='auto_approved', auto_approved_at=NOW()\n  - Queue sitemap regen (best-effort)\n  - Return a plain HTML success page\n\nIdempotent — clicking the link twice doesn't error.\n\nToken expiry: 7 days from submitted_at. Older tokens still\nauto-confirm but log a warning so admin can review.","operationId":"confirm_forget_request_api_pseo_forget_confirm_get","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string","minLength":10,"maxLength":64,"title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/agents/{agent_type}/findings":{"post":{"tags":["agents"],"summary":"Create Findings","description":"Run OSINT collectors for an agent type and return structured findings.\n\nThe collection runs on the queue worker, never in the web process (R8).\nWaits up to ``wait`` seconds (default and max 120): 200 with the findings\nwhen they are ready, else 202 with ``job_id`` + ``poll_url`` (also in\n``Location``) and ``Retry-After``; poll ``GET /v1/agents/findings/{job_id}``.\nDoes NOT call Claude. 503 + Retry-After (QUEUE_UNAVAILABLE) when the\nqueue is down, before any charge.","operationId":"create_findings_v1_agents__agent_type__findings_post","parameters":[{"name":"agent_type","in":"path","required":true,"schema":{"type":"string","title":"Agent Type"}},{"name":"wait","in":"query","required":false,"schema":{"type":"integer","maximum":120,"minimum":0,"description":"Seconds to wait for the result before answering 202 + poll URL.","default":120,"title":"Wait"},"description":"Seconds to wait for the result before answering 202 + poll URL."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindingsRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindingsResponse"}}}},"400":{"description":"Invalid input the schema cannot catch (code INVALID_INPUT with a reason). Not charged. A refused website is 400 INVALID_INPUT with reason INVALID_URL (url_error, host, field); a full queue is 429 QUEUE_FULL with retry_after_seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing, unknown or revoked API key (code UNAUTHORIZED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Balance too low for this call (code INSUFFICIENT_BALANCE, with price_cents and topup_url).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"A test key (sk-sonar-test-) on an endpoint without a sandbox (code SANDBOX_KEY).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Unknown id, or a frozen agent (code NOT_FOUND / AGENT_UNAVAILABLE).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request body or parameters fail validation (code INVALID_INPUT, with fields).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit reached (code RATE_LIMITED); wait for Retry-After. A refused website is 400 INVALID_INPUT with reason INVALID_URL (url_error, host, field); a full queue is 429 QUEUE_FULL with retry_after_seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The register or queue did not answer (code REGISTRY_UNAVAILABLE and others); never 'not found'. Retry after Retry-After unless reason is NOT_CONNECTED. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindingsPendingResponse"}}},"description":"Accepted"}},"security":[{"ApiKeyHeader":[]},{"BearerKey":[]}]}},"/v1/agents/findings/{job_id}":{"get":{"tags":["agents"],"summary":"Get Findings","description":"Poll a /findings job: 200 with the findings (same body as the POST),\n202 while it runs (``Retry-After``), 500 PROCESSING_FAILED when it failed\n(a paid call was refunded), 404 for an unknown id or another key's job.","operationId":"get_findings_v1_agents_findings__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindingsResponse"}}}},"400":{"description":"Invalid input the schema cannot catch (code INVALID_INPUT with a reason). Not charged. A refused website is 400 INVALID_INPUT with reason INVALID_URL (url_error, host, field); a full queue is 429 QUEUE_FULL with retry_after_seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing, unknown or revoked API key (code UNAUTHORIZED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Balance too low for this call (code INSUFFICIENT_BALANCE, with price_cents and topup_url).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"A test key (sk-sonar-test-) on an endpoint without a sandbox (code SANDBOX_KEY).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Unknown id, or a frozen agent (code NOT_FOUND / AGENT_UNAVAILABLE).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request body or parameters fail validation (code INVALID_INPUT, with fields).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit reached (code RATE_LIMITED); wait for Retry-After. A refused website is 400 INVALID_INPUT with reason INVALID_URL (url_error, host, field); a full queue is 429 QUEUE_FULL with retry_after_seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The register or queue did not answer (code REGISTRY_UNAVAILABLE and others); never 'not found'. Retry after Retry-After unless reason is NOT_CONNECTED. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindingsPendingResponse"}}},"description":"Accepted"}},"security":[{"ApiKeyHeader":[]},{"BearerKey":[]}]}},"/v1/agents/{agent_type}/run":{"post":{"tags":["agents"],"summary":"Create Run","description":"Submit an async report run with full Claude analysis.\n\nReturns immediately with a run_id. Poll GET /v1/agents/{type}/run/{id} for results.\n503 + Retry-After (QUEUE_UNAVAILABLE) when the report queue is unavailable.","operationId":"create_run_v1_agents__agent_type__run_post","parameters":[{"name":"agent_type","in":"path","required":true,"schema":{"type":"string","title":"Agent Type"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunRequest"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunSubmitResponse"}}}},"400":{"description":"Invalid input the schema cannot catch (code INVALID_INPUT with a reason). Not charged. A refused website is 400 INVALID_INPUT with reason INVALID_URL (url_error, host, field); a full queue is 429 QUEUE_FULL with retry_after_seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing, unknown or revoked API key (code UNAUTHORIZED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Balance too low for this call (code INSUFFICIENT_BALANCE, with price_cents and topup_url).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"A test key (sk-sonar-test-) on an endpoint without a sandbox (code SANDBOX_KEY).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Unknown id, or a frozen agent (code NOT_FOUND / AGENT_UNAVAILABLE).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request body or parameters fail validation (code INVALID_INPUT, with fields).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit reached (code RATE_LIMITED); wait for Retry-After. A refused website is 400 INVALID_INPUT with reason INVALID_URL (url_error, host, field); a full queue is 429 QUEUE_FULL with retry_after_seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The register or queue did not answer (code REGISTRY_UNAVAILABLE and others); never 'not found'. Retry after Retry-After unless reason is NOT_CONNECTED. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"ApiKeyHeader":[]},{"BearerKey":[]}]}},"/v1/agents/{agent_type}/run/{run_id}":{"get":{"tags":["agents"],"summary":"Get Run","description":"Poll for async run status and results.\n\nPhase AD3 follow-up (2026-05-09) — Bug 2 from MCP integration test:\nClaude Desktop's MCP client hit \"HTTP failed\" 5 times in a row on\nthis endpoint while polling for run 77f18d75. Without retry/backoff\non transient Supabase errors, every blip turned into a 500 → agent\ncallers (which poll in tight loops) interpreted it as fatal and gave\nup. Now:\n\n  1. Retry the Supabase select up to 2 times with short backoff\n     (~100ms, 300ms). Absorbs most transient blips invisibly.\n  2. On persistent failure, return HTTP 503 with Retry-After: 3 —\n     a recoverable signal to retry, NOT a 500 (which signals\n     fatal-give-up to most clients).","operationId":"get_run_v1_agents__agent_type__run__run_id__get","parameters":[{"name":"agent_type","in":"path","required":true,"schema":{"type":"string","title":"Agent Type"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","title":"Run Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunStatusResponse"}}}},"400":{"description":"Invalid input the schema cannot catch (code INVALID_INPUT with a reason). Not charged. A refused website is 400 INVALID_INPUT with reason INVALID_URL (url_error, host, field); a full queue is 429 QUEUE_FULL with retry_after_seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing, unknown or revoked API key (code UNAUTHORIZED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Balance too low for this call (code INSUFFICIENT_BALANCE, with price_cents and topup_url).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"A test key (sk-sonar-test-) on an endpoint without a sandbox (code SANDBOX_KEY).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Unknown id, or a frozen agent (code NOT_FOUND / AGENT_UNAVAILABLE).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request body or parameters fail validation (code INVALID_INPUT, with fields).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit reached (code RATE_LIMITED); wait for Retry-After. A refused website is 400 INVALID_INPUT with reason INVALID_URL (url_error, host, field); a full queue is 429 QUEUE_FULL with retry_after_seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The register or queue did not answer (code REGISTRY_UNAVAILABLE and others); never 'not found'. Retry after Retry-After unless reason is NOT_CONNECTED. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"ApiKeyHeader":[]},{"BearerKey":[]}]}},"/v1/agents/{agent_type}/run/{run_id}/share":{"post":{"tags":["agents"],"summary":"Share Run","description":"Create a public share link for a completed KYB run of this API key.\n\nAnyone with ``share_url`` can open the report, no key needed; it shows\nwhat the report page shows, never costs, tokens or source names. Calling\nagain while the link is live returns the same token and expiry (an\nexpired link is replaced). Free: no charge, no usage row. 404 NOT_FOUND\nfor an unknown run or another key's run, 409 RUN_NOT_COMPLETED while the\nrun is pending / running / failed, 400 SHARE_NOT_SUPPORTED for a non-KYB\nagent, 400 NO_REPORT for a /findings job id. Links stop working when the\nkey that made them is revoked.","operationId":"share_run_v1_agents__agent_type__run__run_id__share_post","parameters":[{"name":"agent_type","in":"path","required":true,"schema":{"type":"string","title":"Agent Type"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","title":"Run Id"}},{"name":"expires_in_days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"description":"Days until the link expires (default 90, max 365).","default":90,"title":"Expires In Days"},"description":"Days until the link expires (default 90, max 365)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunShareResponse"}}}},"400":{"description":"Invalid input the schema cannot catch (code INVALID_INPUT with a reason). Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing, unknown or revoked API key (code UNAUTHORIZED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"A test key (sk-sonar-test-) on an endpoint without a sandbox (code SANDBOX_KEY).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Unknown id, or a frozen agent (code NOT_FOUND / AGENT_UNAVAILABLE).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The run is not completed (code RUN_NOT_COMPLETED): poll a pending / running run until it completes; a failed run cannot be shared.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request body or parameters fail validation (code INVALID_INPUT, with fields).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The register or queue did not answer (code REGISTRY_UNAVAILABLE and others); never 'not found'. Retry after Retry-After unless reason is NOT_CONNECTED. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"ApiKeyHeader":[]},{"BearerKey":[]}]},"delete":{"tags":["agents"],"summary":"Unshare Run","description":"Revoke the run's share link: the URL answers 404 from now on. 204 also\nwhen the run had no link. 404 NOT_FOUND for an unknown or another key's\nrun.","operationId":"unshare_run_v1_agents__agent_type__run__run_id__share_delete","parameters":[{"name":"agent_type","in":"path","required":true,"schema":{"type":"string","title":"Agent Type"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","title":"Run Id"}}],"responses":{"204":{"description":"Successful Response"},"400":{"description":"Invalid input the schema cannot catch (code INVALID_INPUT with a reason). Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing, unknown or revoked API key (code UNAUTHORIZED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"A test key (sk-sonar-test-) on an endpoint without a sandbox (code SANDBOX_KEY).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Unknown id, or a frozen agent (code NOT_FOUND / AGENT_UNAVAILABLE).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The run is not completed (code RUN_NOT_COMPLETED): poll a pending / running run until it completes; a failed run cannot be shared.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request body or parameters fail validation (code INVALID_INPUT, with fields).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The register or queue did not answer (code REGISTRY_UNAVAILABLE and others); never 'not found'. Retry after Retry-After unless reason is NOT_CONNECTED. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"ApiKeyHeader":[]},{"BearerKey":[]}]}},"/v1/companies/lookup":{"post":{"tags":["companies"],"summary":"Lookup Company","description":"Registered companies named ``company_name`` (or numbered\n``registration_number``) in ``country``.\n\nCase, punctuation, accents and the spelling of the legal form are set\naside; any other difference is another company, so a name that only\nresembles a registered one returns ``found: false``. A\n``registration_number`` is matched exactly and decides alone. 400\nINVALID_INPUT for a number not in the country's format, a country\nwithout a register search, a name without a number in PL / BE / BR\n(``reason`` NAME_SEARCH_NOT_SUPPORTED) or a US lookup without a\nsupported state (``reason`` STATE_NOT_SUPPORTED), 503 REGISTRY_UNAVAILABLE (not charged) when\nthe register did not answer. A test key (``sk-sonar-test-``) answers\nfixed scenarios and is never charged.","operationId":"lookup_company_v1_companies_lookup_post","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Same key + same request = the same answer, charged once (kept 24 h)","title":"Idempotency-Key"},"description":"Same key + same request = the same answer, charged once (kept 24 h)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyLookupRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyLookupResponse"}}}},"400":{"description":"Invalid input the schema cannot catch (code INVALID_INPUT with a reason). Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing, unknown or revoked API key (code UNAUTHORIZED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Unknown id, or a frozen agent (code NOT_FOUND / AGENT_UNAVAILABLE).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request body or parameters fail validation (code INVALID_INPUT, with fields).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit reached (code RATE_LIMITED); wait for Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The register or queue did not answer (code REGISTRY_UNAVAILABLE and others); never 'not found'. Retry after Retry-After unless reason is NOT_CONNECTED. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Balance too low for this call (code INSUFFICIENT_BALANCE, with price_cents and topup_url).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"ApiKeyHeader":[]},{"BearerKey":[]}]}},"/v1/companies/lookup/{request_id}":{"get":{"tags":["companies"],"summary":"Get Lookup","description":"The answer a lookup gave, by its ``request_id``: the same body, for an\naudit trail. Any key of the same account can read it. 404 NOT_FOUND\notherwise. Free.","operationId":"get_lookup_v1_companies_lookup__request_id__get","parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","title":"Request Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyLookupResponse"}}}},"400":{"description":"Invalid input the schema cannot catch (code INVALID_INPUT with a reason). Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing, unknown or revoked API key (code UNAUTHORIZED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Unknown id, or a frozen agent (code NOT_FOUND / AGENT_UNAVAILABLE).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request body or parameters fail validation (code INVALID_INPUT, with fields).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit reached (code RATE_LIMITED); wait for Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The register or queue did not answer (code REGISTRY_UNAVAILABLE and others); never 'not found'. Retry after Retry-After unless reason is NOT_CONNECTED. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"ApiKeyHeader":[]},{"BearerKey":[]}]},"delete":{"tags":["companies"],"summary":"Delete Lookup","description":"Delete the stored answer of one lookup (K4, deletion on request) and\nblank the name / number on its usage row. ``GET`` on the same\n``request_id`` is 404 afterwards. Any key of the same account can delete\nit. 404 NOT_FOUND for an unknown id or one of another account. Free.","operationId":"delete_lookup_v1_companies_lookup__request_id__delete","parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","title":"Request Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupDeletionResponse"}}}},"400":{"description":"Invalid input the schema cannot catch (code INVALID_INPUT with a reason). Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing, unknown or revoked API key (code UNAUTHORIZED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Unknown id, or a frozen agent (code NOT_FOUND / AGENT_UNAVAILABLE).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request body or parameters fail validation (code INVALID_INPUT, with fields).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit reached (code RATE_LIMITED); wait for Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The register or queue did not answer (code REGISTRY_UNAVAILABLE and others); never 'not found'. Retry after Retry-After unless reason is NOT_CONNECTED. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"ApiKeyHeader":[]},{"BearerKey":[]}]}},"/v1/companies/lookups":{"delete":{"tags":["companies"],"summary":"Delete Lookups","description":"Delete every stored lookup answer of the account (all its keys) and\nblank the company name / number on its lookup and officers usage rows\n(K4). Without this, stored answers are deleted 24 months after the\nlookup. Idempotent. Free.","operationId":"delete_lookups_v1_companies_lookups_delete","parameters":[],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupDeletionResponse"}}}},"400":{"description":"Invalid input the schema cannot catch (code INVALID_INPUT with a reason). Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing, unknown or revoked API key (code UNAUTHORIZED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Unknown id, or a frozen agent (code NOT_FOUND / AGENT_UNAVAILABLE).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request body or parameters fail validation (code INVALID_INPUT, with fields).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit reached (code RATE_LIMITED); wait for Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The register or queue did not answer (code REGISTRY_UNAVAILABLE and others); never 'not found'. Retry after Retry-After unless reason is NOT_CONNECTED. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"ApiKeyHeader":[]},{"BearerKey":[]}]}},"/v1/companies/{country}/{registration_number}/officers":{"get":{"tags":["companies"],"summary":"Company Officers","description":"The officers of the company numbered ``registration_number`` in\n``country`` (GB, CZ, SK, NO, FR), read live from its register: name,\nrole, person or company, ``appointed_on`` / ``resigned_on`` where the\nregister publishes them (``null`` + ``field_reasons`` where not). No\nbirth date, nationality or address is returned.\n\nPriced like a lookup (a free lookup first, then the lookup price), only\nwhen the register holds the company; NOT_FOUND is free. 400\nINVALID_INPUT for a country whose register publishes no officers\n(``reason`` OFFICERS_NOT_SUPPORTED: FI, CH, US) or a number not in the\ncountry's format, 503 REGISTRY_UNAVAILABLE (not charged) when the\nregister did not answer.","operationId":"company_officers_v1_companies__country___registration_number__officers_get","parameters":[{"name":"country","in":"path","required":true,"schema":{"type":"string","title":"Country"}},{"name":"registration_number","in":"path","required":true,"schema":{"type":"string","title":"Registration Number"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfficersResponse"}}}},"400":{"description":"Invalid input the schema cannot catch (code INVALID_INPUT with a reason). Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing, unknown or revoked API key (code UNAUTHORIZED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Unknown id, or a frozen agent (code NOT_FOUND / AGENT_UNAVAILABLE).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request body or parameters fail validation (code INVALID_INPUT, with fields).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit reached (code RATE_LIMITED); wait for Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The register or queue did not answer (code REGISTRY_UNAVAILABLE and others); never 'not found'. Retry after Retry-After unless reason is NOT_CONNECTED. Not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Balance too low for this call (code INSUFFICIENT_BALANCE, with price_cents and topup_url).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"ApiKeyHeader":[]},{"BearerKey":[]}]}},"/v1/auth/keys":{"post":{"tags":["auth"],"summary":"Create Key","description":"Create a new API key for the signed-in user.\n\nAuthenticated with the web app session (``Authorization: Bearer <Supabase\naccess token>``), not with an API key. The raw key is returned ONCE in\nthe response; it cannot be retrieved again. At most 5 active keys.\n``mode: \"test\"`` makes an ``sk-sonar-test-`` sandbox key.","operationId":"create_key_v1_auth_keys_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateKeyRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["auth"],"summary":"List Keys","description":"List all API keys of the signed-in user (web app session, not an API key).","operationId":"list_keys_v1_auth_keys_get","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyResponse"},"title":"Response List Keys V1 Auth Keys Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/auth/keys/{key_id}":{"delete":{"tags":["auth"],"summary":"Revoke Key","description":"Revoke (deactivate) an API key (web app session, not an API key).","operationId":"revoke_key_v1_auth_keys__key_id__delete","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/coverage":{"get":{"tags":["meta"],"summary":"Get Coverage","description":"Countries, fields, live / index and refresh age, generated from the\nregistry catalog.","operationId":"get_coverage_v1_coverage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Get Coverage V1 Coverage Get"}}}}}}},"/v1/limits":{"get":{"tags":["meta"],"summary":"Get Limits","description":"The rate limits the API enforces.","operationId":"get_limits_v1_limits_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Get Limits V1 Limits Get"}}}}}}},"/v1/usage":{"get":{"tags":["usage"],"summary":"Get Usage","description":"Get usage statistics + free-trial + pre-paid balance for the calling key.\n\nA new account's first call is free (any endpoint type). After that,\n/v1/agents/* deducts ``€0.50`` per /findings call and ``€6.00`` per\n/run call from ``balance_cents``. A company lookup that finds its\ncompany spends one of ``free_lookups_remaining`` (100 per account) first.","operationId":"get_usage_v1_usage_get","parameters":[],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"401":{"description":"Missing, unknown or revoked API key (code UNAUTHORIZED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request body or parameters fail validation (code INVALID_INPUT, with fields).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit reached (code RATE_LIMITED); wait for Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"ApiKeyHeader":[]},{"BearerKey":[]}]}},"/v1/usage/export":{"get":{"tags":["usage"],"summary":"Export Usage","description":"Every API call of this account (all its keys) with what it was\ncharged, for reconciliation. Usage rows are kept 90 days; at most\n10,000 rows per export (narrow ``since`` / ``until`` for more).","operationId":"export_usage_v1_usage_export_get","parameters":[{"name":"format","in":"query","required":false,"schema":{"enum":["csv","json"],"type":"string","description":"csv or json","default":"json","title":"Format"},"description":"csv or json"},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO date, default: the 1st of this month","title":"Since"},"description":"ISO date, default: the 1st of this month"},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO date, exclusive, default: now","title":"Until"},"description":"ISO date, exclusive, default: now"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing, unknown or revoked API key (code UNAUTHORIZED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Request body or parameters fail validation (code INVALID_INPUT, with fields).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit reached (code RATE_LIMITED); wait for Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"ApiKeyHeader":[]},{"BearerKey":[]}]}},"/health":{"get":{"summary":"Health","description":"Liveness probe — the process is alive and accepting HTTP.\n\nNever fails unless the Python process is dead. Render's healthcheck\nis pointed here: a Supabase blip must NOT cause Render to re-route\ntraffic or restart the container. Readiness is a separate concern —\nsee /health/deps.","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health/deps":{"get":{"summary":"Health Deps","description":"Readiness probe — can we actually serve end-to-end?\n\nPings Supabase with a cheap 1-row select. Returns 503 if Supabase is\nunreachable so dashboards and monitoring can distinguish \"pod up,\nSupabase down\" from \"pod down\". Added 2026-04-13 (Wave 3).\n\n``commit`` is the deployed SHA (``RENDER_GIT_COMMIT``), which\n``ops/post_deploy_smoke.sh`` compares with the merge SHA (T1.12).","operationId":"health_deps_health_deps_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health/queue":{"get":{"summary":"Health Queue","description":"Job queue probe (T1.7): 200 with the number of active (queued +\nrunning) jobs when the queue database answers, 503 when it doesn't.","operationId":"health_queue_health_queue_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"ApiError":{"properties":{"detail":{"$ref":"#/components/schemas/ApiErrorDetail"}},"type":"object","required":["detail"],"title":"ApiError","description":"Every /v1 error: ``{\"detail\": {\"error\": {\"code\", \"message\", ...}}}``."},"ApiErrorBody":{"properties":{"code":{"type":"string","title":"Code","description":"Stable machine code: INVALID_INPUT, UNAUTHORIZED, INSUFFICIENT_BALANCE, SANDBOX_KEY, NOT_FOUND, AGENT_UNAVAILABLE, IDEMPOTENCY_KEY_REUSED, RUN_NOT_COMPLETED, SHARE_NOT_SUPPORTED, NO_REPORT, RATE_LIMITED, REGISTRY_UNAVAILABLE, ... (an open list)"},"message":{"type":"string","title":"Message","description":"Human-readable explanation; may change, do not parse"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Finer cause under a code, e.g. NAME_SEARCH_NOT_SUPPORTED, STATE_NOT_SUPPORTED, OFFICERS_NOT_SUPPORTED, NOT_CONNECTED, UNREACHABLE (an open list)"},"fields":{"anyOf":[{"items":{"additionalProperties":{"type":"string"},"type":"object"},"type":"array"},{"type":"null"}],"title":"Fields","description":"422 only: [{field, message}] for each invalid request field"}},"additionalProperties":true,"type":"object","required":["code","message"],"title":"ApiErrorBody","description":"One error. Fields beyond ``code`` and ``message`` depend on the code\n(``price_cents`` / ``topup_url`` on 402, ``supported_states`` on a US\n400, ``retry_after_seconds`` on some 429s); clients ignore the ones\nthey do not know."},"ApiErrorDetail":{"properties":{"error":{"$ref":"#/components/schemas/ApiErrorBody"}},"type":"object","required":["error"],"title":"ApiErrorDetail"},"ApiKeyResponse":{"properties":{"id":{"type":"string","title":"Id"},"key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key"},"key_prefix":{"type":"string","title":"Key Prefix"},"name":{"type":"string","title":"Name"},"plan":{"type":"string","title":"Plan"},"rate_limit_rpm":{"type":"integer","title":"Rate Limit Rpm"},"monthly_quota":{"type":"integer","title":"Monthly Quota"},"is_active":{"type":"boolean","title":"Is Active"},"created_at":{"type":"string","title":"Created At"},"last_used_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Used At"},"mode":{"type":"string","enum":["live","test"],"title":"Mode","default":"live"},"created_from":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created From"}},"type":"object","required":["id","key_prefix","name","plan","rate_limit_rpm","monthly_quota","is_active","created_at"],"title":"ApiKeyResponse"},"Body_import_from_excel_api_profiles__profile_id__competitors_import_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_import_from_excel_api_profiles__profile_id__competitors_import_post"},"Body_import_from_excel_preview_api_competitors_import_preview_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_import_from_excel_preview_api_competitors_import_preview_post"},"BrandLogoUpload":{"properties":{"data_base64":{"type":"string","maxLength":1398120,"title":"Data Base64"}},"type":"object","required":["data_base64"],"title":"BrandLogoUpload"},"BrandUpdate":{"properties":{"display_name":{"anyOf":[{"type":"string","maxLength":400},{"type":"null"}],"title":"Display Name"},"primary_color":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Primary Color"},"footer_line":{"anyOf":[{"type":"string","maxLength":600},{"type":"null"}],"title":"Footer Line"},"contact_email":{"anyOf":[{"type":"string","maxLength":600},{"type":"null"}],"title":"Contact Email"},"website":{"anyOf":[{"type":"string","maxLength":600},{"type":"null"}],"title":"Website"}},"type":"object","title":"BrandUpdate","description":"Fields left out are unchanged; an empty string clears a field."},"BusinessEmailCheck":{"properties":{"email":{"type":"string","maxLength":254,"title":"Email"}},"type":"object","required":["email"],"title":"BusinessEmailCheck"},"BusinessEmailCheckResult":{"properties":{"ok":{"type":"boolean","title":"Ok"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Why it can't be used: invalid | free_webmail | disposable | same_as_current | already_used"}},"type":"object","required":["ok"],"title":"BusinessEmailCheckResult"},"ClientErrorReport":{"properties":{"message":{"type":"string","maxLength":2000,"minLength":1,"title":"Message"},"stack":{"type":"string","maxLength":8000,"title":"Stack","default":""},"url":{"type":"string","maxLength":2000,"title":"Url","description":"Page URL; only the path is kept","default":""},"component":{"type":"string","maxLength":200,"title":"Component","description":"React component stack head","default":""},"release":{"type":"string","maxLength":64,"title":"Release","description":"Frontend build id, if known","default":""}},"type":"object","required":["message"],"title":"ClientErrorReport"},"CompanyInfo":{"properties":{"name":{"type":"string","title":"Name"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"}},"type":"object","required":["name"],"title":"CompanyInfo"},"CompanyLookupQuery":{"properties":{"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name"},"registration_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Registration Number"},"country":{"type":"string","title":"Country"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"}},"type":"object","required":["country"],"title":"CompanyLookupQuery"},"CompanyLookupRequest":{"properties":{"company_name":{"anyOf":[{"type":"string","maxLength":200,"minLength":2},{"type":"null"}],"title":"Company Name","description":"The legal name. Optional when registration_number is given"},"registration_number":{"anyOf":[{"type":"string","maxLength":40,"minLength":1},{"type":"null"}],"title":"Registration Number","description":"The register's number (GB company number, FR SIREN, CZ / SK IČO, NO orgnr, FI Y-tunnus, CH UID, EE registry code, LV registration number, CY registration number (HE / AE), SG UEN, IE CRO company number, PL KRS number, BE enterprise number, BR CNPJ, US state file number). Matched exactly; it decides alone when given. Required for PL, BE and BR, whose registers have no name search"},"country":{"type":"string","maxLength":2,"minLength":2,"title":"Country","description":"ISO 3166-1 alpha-2 (GB, FR, CZ, SK, NO, FI, CH, EE, LV, CY, SG, IE, US; PL, BE, BR by number only)"},"state":{"anyOf":[{"type":"string","maxLength":2,"minLength":2},{"type":"null"}],"title":"State","description":"US only, required there: the 2-letter state whose register is searched (NY, CO, OR, CT, TX, PA, FL, IA, DC)"},"include":{"items":{"type":"string","enum":["officers","filings"]},"type":"array","title":"Include","description":"Also return the FOUND company's officers (GB, CZ, SK, NO, FR) and / or latest filings (GB, FR), at no extra cost; null with a field_reasons entry where the register does not publish them or did not answer"}},"type":"object","required":["country"],"title":"CompanyLookupRequest"},"CompanyLookupResponse":{"properties":{"query":{"$ref":"#/components/schemas/CompanyLookupQuery"},"status":{"type":"string","enum":["FOUND","NOT_FOUND","AMBIGUOUS"],"title":"Status","description":"AMBIGUOUS: more than one active company holds the name; see matches"},"found":{"type":"boolean","title":"Found"},"matches":{"items":{"$ref":"#/components/schemas/CompanyMatchOut"},"type":"array","title":"Matches"},"cached":{"type":"boolean","title":"Cached","description":"Answered from the 24 h cache of hits","default":false},"truncated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Truncated","description":"FR name searches: true when the register holds more companies of this name than the 25 it returns at once, so matches may be incomplete; send registration_number. null where the register's answer does not say"},"last_updated":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Updated","description":"When the register was read"},"coverage_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Coverage Note","description":"US: the register searched and what it holds, so a NOT_FOUND reads for what it is (NY, OR, PA: active entities only; TX: the Comptroller's active franchise taxpayers, not the formation register). SG: what SONAR's copy of ACRA's data holds (deregistered companies with a UEN from before 2010 are not in it), so a NOT_FOUND means only that the company is not in that copy. null elsewhere"},"suggestions":{"anyOf":[{"items":{"$ref":"#/components/schemas/CompanySuggestionOut"},"type":"array"},{"type":"null"}],"title":"Suggestions","description":"CY, EE, LV, SG, IE (SONAR's copies): when a company_name has no exact match (NOT_FOUND), up to 10 ACTIVE companies or branches whose registered name starts with it, exact name first, then names in alphabetical order of the first 200 per prefix; [] when none does. Candidates only: status stays NOT_FOUND, found false, and the call is not charged; look one up by registration_number to verify it. A dissolved company is never suggested: it needs its exact registered name or number. null when no partial search ran (other countries, a number lookup, a hit, a name shorter than 3 characters)"},"suggestions_prefix":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Suggestions Prefix","description":"The start of a name the suggestions were searched for (upper case, legal form removed: \"Lanitis Farm Ltd\" → \"LANITIS FARM\"); null when no partial search ran"},"checked_at":{"type":"string","title":"Checked At"},"price_cents":{"type":"integer","title":"Price Cents","description":"What this call cost: 0 when nothing was found or a free lookup paid for it"},"free_lookups_remaining":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Free Lookups Remaining","description":"Free lookups left on the account (null for a sandbox key)"},"sandbox":{"type":"boolean","title":"Sandbox","description":"Answered by a test key: a fixed scenario","default":false},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id","description":"GET /v1/companies/lookup/{request_id} returns this answer again"}},"type":"object","required":["query","status","found","matches","checked_at","price_cents"],"title":"CompanyLookupResponse"},"CompanyMatchOut":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"The registered name; null (field_reasons redacted) only when restricted"},"registration_number":{"type":"string","title":"Registration Number"},"status":{"type":"string","title":"Status","description":"active / inactive / unknown, the same for every country"},"register_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Register Status","description":"The register's own status wording"},"legal_form":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Legal Form"},"incorporated_on":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Incorporated On"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address"},"register_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Register Url"},"previous_names":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Previous Names","description":"Former registered names, latest first; [] = none on the register"},"entity_kind":{"anyOf":[{"type":"string","enum":["company","branch","other"]},{"type":"null"}],"title":"Entity Kind"},"jurisdiction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Jurisdiction","description":"US: the state of formation when it is not the state searched"},"vat_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vat Id","description":"The VAT number: CZ DIČ while the VAT register is active (ARES), NO <orgnr>MVA when in the VAT register (Brreg), FI <Y-tunnus digits> when VAT-liable (PRH), FR derived from the SIREN for a company or branch, BE BE<number> while the CBE records VAT liability. null with a reason otherwise (GB, SK, CH, PL, BR, US: not_supported)"},"registered_agent":{"anyOf":[{"$ref":"#/components/schemas/RegisteredAgentOut"},{"type":"null"}],"description":"US (NY, CO, OR, FL): the registered agent for service of process"},"officers":{"anyOf":[{"items":{"$ref":"#/components/schemas/OfficerOut"},"type":"array"},{"type":"null"}],"title":"Officers","description":"With include officers, FOUND only (GB, CZ, SK, NO, FR): as GET .../officers; free with the lookup"},"filings":{"anyOf":[{"items":{"$ref":"#/components/schemas/FilingOut"},"type":"array"},{"type":"null"}],"title":"Filings","description":"With include filings, FOUND only (GB: Companies House filing history; FR: BODACC announcements): the latest 10, newest first; free with the lookup"},"good_standing":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Good Standing","description":"From the register's own markers. false: closed, or the register marks a default (GB: accounts or confirmation statement overdue, strike-off pending; US-CO: Delinquent / Noncompliant; US-TX: right to transact forfeited or pending termination), insolvency (CZ insolvency register; NO bankruptcy or liquidation; FI bankruptcy, liquidation or restructuring). true: active with none of those markers (GB API, NO, CZ, FI, US-CO, US-TX). null (not_supported) where the register publishes no such markers"},"confidence":{"type":"number","title":"Confidence","description":"1.0: exact name or exact number","default":1.0},"matched_on":{"items":{"type":"string","enum":["name","registration_number"]},"type":"array","title":"Matched On"},"field_reasons":{"additionalProperties":{"type":"string","enum":["not_in_registry","not_supported","redacted","register_unavailable"]},"type":"object","title":"Field Reasons","description":"Why each null field is null"},"restricted":{"type":"boolean","title":"Restricted","description":"FR: the business opted out of publication in Sirene (statut_diffusion P). Only the number, status, register_status, good_standing and register_url are given; every other field (and officers / filings) is null with field_reasons redacted. Returned for a registration_number lookup only, never for a name","default":false}},"type":"object","required":["name","registration_number","status","matched_on"],"title":"CompanyMatchOut"},"CompanySearchRequest":{"properties":{"country":{"type":"string","maxLength":2,"minLength":2,"title":"Country","description":"ISO-2 country code"},"q":{"type":"string","maxLength":200,"title":"Q","description":"The start of a company name, as typed"}},"type":"object","required":["country","q"],"title":"CompanySearchRequest"},"CompanySearchResponse":{"properties":{"country":{"type":"string","title":"Country"},"searchable":{"type":"boolean","title":"Searchable","description":"False: this country has no name search"},"results":{"items":{"$ref":"#/components/schemas/CompanySearchResult"},"type":"array","title":"Results"},"partial":{"type":"boolean","title":"Partial","description":"True: the register did not answer in time; results may be missing"},"cached":{"type":"boolean","title":"Cached"}},"type":"object","required":["country","searchable","results","partial","cached"],"title":"CompanySearchResponse"},"CompanySearchResult":{"properties":{"name":{"type":"string","title":"Name"},"registration_number":{"type":"string","title":"Registration Number"},"status":{"type":"string","enum":["active","inactive","unknown"],"title":"Status"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address","description":"Registered address, when the register gives it"},"vat_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vat Id","description":"VAT number, only where the register gives it"}},"type":"object","required":["name","registration_number","status"],"title":"CompanySearchResult"},"CompanySuggestionOut":{"properties":{"name":{"type":"string","title":"Name"},"registration_number":{"type":"string","title":"Registration Number"},"status":{"type":"string","enum":["active","inactive","unknown"],"title":"Status"},"register_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Register Status"},"legal_form":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Legal Form"},"incorporated_on":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Incorporated On"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address"},"entity_kind":{"anyOf":[{"type":"string","enum":["company","branch","other"]},{"type":"null"}],"title":"Entity Kind"},"register_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Register Url"},"match_kind":{"type":"string","const":"prefix","title":"Match Kind","description":"prefix: the registered name starts with the name asked for","default":"prefix"}},"type":"object","required":["name","registration_number","status"],"title":"CompanySuggestionOut","description":"A company whose name starts with the one asked for: a candidate to\nlook up by number, never a match."},"CompetitorCreate":{"properties":{"company_name":{"type":"string","title":"Company Name"},"website":{"type":"string","title":"Website"},"tier":{"type":"integer","title":"Tier","default":2},"position":{"type":"integer","title":"Position","default":0},"extra_urls":{"items":{"type":"string"},"type":"array","title":"Extra Urls","default":[]},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"vat_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vat Number"},"krs_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Krs Number"},"nip":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nip"},"ico":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ico"},"iban":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Iban"},"cnpj":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cnpj"},"uen":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Uen"},"bce_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bce Number"},"kvk_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Kvk Number"}},"type":"object","required":["company_name","website"],"title":"CompetitorCreate"},"CompetitorUpdate":{"properties":{"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name"},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website"},"tier":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Tier"},"position":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Position"},"extra_urls":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Extra Urls"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"vat_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vat Number"},"krs_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Krs Number"},"nip":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nip"},"ico":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ico"},"iban":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Iban"},"cnpj":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cnpj"},"uen":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Uen"},"bce_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bce Number"},"kvk_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Kvk Number"}},"type":"object","title":"CompetitorUpdate"},"ContactMessage":{"properties":{"message":{"type":"string","title":"Message"}},"type":"object","required":["message"],"title":"ContactMessage"},"CreateKeyRequest":{"properties":{"name":{"type":"string","maxLength":100,"title":"Name","description":"Friendly label for this key","default":""},"mode":{"type":"string","enum":["live","test"],"title":"Mode","description":"test: an sk-sonar-test- sandbox key. It answers POST /v1/companies/lookup and the officers endpoint with fixed scenarios, never calls a register and is never charged; /v1/agents/* refuse it (403 SANDBOX_KEY)","default":"live"},"created_from":{"anyOf":[{"type":"string","enum":["dashboard","developers","docs","mcp","onboarding","other"]},{"type":"null"}],"title":"Created From","description":"Where the key was created (for SONAR's own analytics)"}},"type":"object","title":"CreateKeyRequest"},"DeleteAccountRequest":{"properties":{"confirm":{"type":"string","title":"Confirm"}},"type":"object","required":["confirm"],"title":"DeleteAccountRequest"},"DetectIndustryRequest":{"properties":{"website":{"type":"string","title":"Website"},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name"}},"type":"object","required":["website"],"title":"DetectIndustryRequest"},"DetectIndustryResponse":{"properties":{"industry":{"type":"string","title":"Industry"},"confidence":{"type":"number","title":"Confidence"},"reason":{"type":"string","title":"Reason"}},"type":"object","required":["industry","confidence","reason"],"title":"DetectIndustryResponse"},"DiscoverPreviewRequest":{"properties":{"company_name":{"type":"string","title":"Company Name"},"company_website":{"type":"string","title":"Company Website","default":""},"industry":{"type":"string","title":"Industry","default":""},"location":{"type":"string","title":"Location","default":""},"product_type":{"type":"string","title":"Product Type","default":"ci"},"company_size_range":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Size Range"},"exclude_names":{"items":{"type":"string"},"type":"array","title":"Exclude Names","default":[]}},"type":"object","required":["company_name"],"title":"DiscoverPreviewRequest"},"DiscoverRequest":{"properties":{"exclude_names":{"items":{"type":"string"},"type":"array","title":"Exclude Names","default":[]}},"type":"object","title":"DiscoverRequest","description":"Optional body for the profile-scoped discover endpoint. Same\n`exclude_names` contract as DiscoverPreviewRequest — used by the\nonboarding wizard's \"Refresh suggestions\" button to preserve the\nuser's current picks across regenerations."},"FeedbackEvent":{"properties":{"event":{"type":"string","enum":["inline_shown","slide_in_shown","dismiss"],"title":"Event"},"report_id":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Report Id"}},"type":"object","required":["event"],"title":"FeedbackEvent"},"FeedbackSubmit":{"properties":{"report_id":{"type":"string","maxLength":64,"minLength":1,"title":"Report Id"},"stars":{"type":"integer","maximum":5.0,"minimum":1.0,"title":"Stars"},"text":{"type":"string","maxLength":6000,"title":"Text"},"use_cases":{"items":{"type":"string","enum":["supplier","customer","investment","buying_through","other"]},"type":"array","maxItems":5,"title":"Use Cases"},"quote_consent":{"type":"boolean","title":"Quote Consent","default":false}},"type":"object","required":["report_id","stars","text"],"title":"FeedbackSubmit"},"FieldResult":{"properties":{"findings":{"items":{"$ref":"#/components/schemas/Finding"},"type":"array","title":"Findings","description":"May hold the screen's own 'nothing found' statement or check rows: count hits with field_status, never with the length of findings","default":[]},"confidence":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Confidence","description":"HIGH / MEDIUM / LOW, or null"},"confidence_score":{"type":"number","title":"Confidence Score","default":0.0}},"type":"object","title":"FieldResult"},"FilingOut":{"properties":{"date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"The register's category"},"description":{"type":"string","title":"Description","default":""}},"type":"object","title":"FilingOut"},"Finding":{"properties":{"value":{"type":"string","title":"Value","default":""},"detail":{"type":"string","title":"Detail","default":""},"sources":{"items":{"$ref":"#/components/schemas/SourceRef"},"type":"array","title":"Sources","default":[]},"source_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Date","default":""}},"type":"object","title":"Finding"},"FindingsPendingResponse":{"properties":{"job_id":{"type":"string","title":"Job Id"},"request_id":{"type":"string","title":"Request Id","default":""},"status":{"type":"string","title":"Status"},"agent":{"type":"string","title":"Agent"},"company":{"$ref":"#/components/schemas/CompanyInfo"},"poll_url":{"type":"string","title":"Poll Url","description":"Relative path (also in the Location header): GET it with the same key until 200; the call is already charged, do not POST again"},"retry_after_seconds":{"type":"integer","title":"Retry After Seconds","default":5}},"type":"object","required":["job_id","status","agent","company","poll_url"],"title":"FindingsPendingResponse","description":"202 from /findings when the collection did not finish within ``wait``\nseconds (R8): poll ``poll_url`` (GET /v1/agents/findings/{job_id})."},"FindingsRequest":{"properties":{"country":{"anyOf":[{"type":"string","maxLength":2,"minLength":2},{"type":"null"}],"title":"Country","description":"ISO 3166-1 alpha-2 country of registration (GB, FR, NO, CZ, DK, ...). Without it no national company register is searched (registry_match: NOT_SEARCHED)"},"state":{"anyOf":[{"type":"string","maxLength":2,"minLength":2},{"type":"null"}],"title":"State","description":"US only: the 2-letter state of formation, whose register is searched"},"registration_number":{"anyOf":[{"type":"string","maxLength":40,"minLength":1},{"type":"null"}],"title":"Registration Number","description":"The register's company number (GB company number, FR SIREN, CZ IČO, NO orgnr, ...). Needs country; checked against the country's format like the lookup"},"vat_number":{"anyOf":[{"type":"string","maxLength":20,"minLength":2},{"type":"null"}],"title":"Vat Number","description":"VAT number with its country prefix (validated against the EU VAT system)"},"company_name":{"type":"string","maxLength":200,"minLength":1,"title":"Company Name","description":"Company name to research"},"website":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Website","description":"Company website (optional, improves accuracy). A bare domain (tesco.com) is accepted; a private, loopback or non-http(s) address is 400 INVALID_INPUT, reason INVALID_URL"}},"type":"object","required":["company_name"],"title":"FindingsRequest"},"FindingsResponse":{"properties":{"request_id":{"type":"string","title":"Request Id"},"agent":{"type":"string","title":"Agent"},"company":{"$ref":"#/components/schemas/CompanyInfo"},"status":{"type":"string","title":"Status"},"fields":{"additionalProperties":{"$ref":"#/components/schemas/FieldResult"},"type":"object","title":"Fields","default":{}},"sources_checked":{"type":"integer","title":"Sources Checked","default":0},"fields_found":{"items":{"type":"string"},"type":"array","title":"Fields Found","description":"Exactly the fields whose field_status is found","default":[]},"fields_not_found":{"items":{"type":"string"},"type":"array","title":"Fields Not Found","description":"Every other field: not a clean result by itself, read field_status","default":[]},"field_status":{"additionalProperties":{"type":"string"},"type":"object","title":"Field Status","description":"Per field: found (a source returned something about the subject), checked_clean (screened, nothing found), not_run (not screened: a gap, never clean), company_not_found (registry_match is NOT_FOUND), below_confidence_floor. Treat an unknown value as not a clean result","default":{}},"ubo_graph":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Ubo Graph"},"registry_match":{"anyOf":[{"$ref":"#/components/schemas/RegistryMatch"},{"type":"null"}]},"generated_at":{"type":"string","title":"Generated At","default":""},"processing_time_ms":{"type":"integer","title":"Processing Time Ms","default":0}},"type":"object","required":["request_id","agent","company","status"],"title":"FindingsResponse"},"ForgetRequest":{"properties":{"requester_email":{"type":"string","format":"email","title":"Requester Email"},"page_url":{"type":"string","maxLength":512,"minLength":10,"title":"Page Url"},"reason":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Reason"}},"type":"object","required":["requester_email","page_url"],"title":"ForgetRequest"},"FunnelEvent":{"properties":{"event":{"type":"string","const":"cta_clicked","title":"Event"},"tool":{"type":"string","maxLength":48,"title":"Tool","description":"The CTA ref: tool_<tool>[_<cc>] or pseo"}},"type":"object","required":["event","tool"],"title":"FunnelEvent"},"FunnelSignup":{"properties":{"src":{"type":"string","maxLength":48,"title":"Src","description":"The CTA ref: tool_<tool>[_<cc>] or pseo"}},"type":"object","required":["src"],"title":"FunnelSignup"},"GenerateRequest":{"properties":{"report_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Report Days"},"claude_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Claude Model"}},"type":"object","title":"GenerateRequest","description":"Optional overrides when triggering a report."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"LandingBeacon":{"properties":{"referrer_host":{"type":"string","maxLength":253,"title":"Referrer Host","description":"document.referrer host only","default":""},"utm_source":{"type":"string","maxLength":200,"title":"Utm Source","default":""},"ref":{"type":"string","maxLength":200,"title":"Ref","description":"SONAR ?ref= short-link parameter","default":""},"path":{"type":"string","maxLength":300,"title":"Path","description":"Landing path (used to classify, not kept)","default":""}},"type":"object","title":"LandingBeacon"},"LookupDeletionResponse":{"properties":{"deleted_answers":{"type":"integer","title":"Deleted Answers","description":"Stored lookup answers deleted"},"usage_rows_cleared":{"type":"integer","title":"Usage Rows Cleared","description":"Usage rows whose company name / number was blanked; the rows stay as the record of what was charged"}},"type":"object","required":["deleted_answers","usage_rows_cleared"],"title":"LookupDeletionResponse"},"OfficerOut":{"properties":{"name":{"type":"string","title":"Name"},"role":{"type":"string","title":"Role","description":"The register's role, in English where SONAR maps it"},"kind":{"anyOf":[{"type":"string","enum":["person","company"]},{"type":"null"}],"title":"Kind"},"current":{"type":"boolean","title":"Current","description":"false: the officer has left the role"},"appointed_on":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Appointed On"},"resigned_on":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resigned On","description":"null with no reason while the officer is current"},"registration_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Registration Number","description":"A company officer's own registration number"},"field_reasons":{"additionalProperties":{"type":"string","enum":["not_in_registry","not_supported","redacted","register_unavailable"]},"type":"object","title":"Field Reasons","description":"Why each null date is null"}},"type":"object","required":["name","role","current"],"title":"OfficerOut"},"OfficersCompany":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"registration_number":{"type":"string","title":"Registration Number"}},"type":"object","required":["registration_number"],"title":"OfficersCompany"},"OfficersQuery":{"properties":{"country":{"type":"string","title":"Country"},"registration_number":{"type":"string","title":"Registration Number"}},"type":"object","required":["country","registration_number"],"title":"OfficersQuery"},"OfficersResponse":{"properties":{"query":{"$ref":"#/components/schemas/OfficersQuery"},"status":{"type":"string","enum":["FOUND","NOT_FOUND"],"title":"Status"},"found":{"type":"boolean","title":"Found"},"company":{"anyOf":[{"$ref":"#/components/schemas/OfficersCompany"},{"type":"null"}]},"officers":{"items":{"$ref":"#/components/schemas/OfficerOut"},"type":"array","title":"Officers","description":"Current officers first, then former ones"},"history":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"History","description":"true: the register lists former officers too (GB, CZ, SK); false: current officers only (NO, FR)"},"restricted":{"type":"boolean","title":"Restricted","description":"FR: the company opted out of publication in Sirene; company.name is null and no officers are given","default":false},"last_updated":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Updated","description":"When the register was read"},"checked_at":{"type":"string","title":"Checked At"},"price_cents":{"type":"integer","title":"Price Cents","description":"What this call cost: 0 when the company was not found or a free lookup paid"},"free_lookups_remaining":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Free Lookups Remaining"},"sandbox":{"type":"boolean","title":"Sandbox","default":false},"request_id":{"type":"string","title":"Request Id","description":"The api_usage id; the answer itself is not stored"}},"type":"object","required":["query","status","found","officers","checked_at","price_cents","request_id"],"title":"OfficersResponse"},"ProductOut":{"properties":{"product_type":{"type":"string","title":"Product Type"},"display_name":{"type":"string","title":"Display Name"},"entity_noun":{"type":"string","title":"Entity Noun"},"entity_noun_plural":{"type":"string","title":"Entity Noun Plural"},"visibility":{"type":"string","enum":["public","admin_only"],"title":"Visibility"}},"type":"object","required":["product_type","display_name","entity_noun","entity_noun_plural","visibility"],"title":"ProductOut"},"ProductsResponse":{"properties":{"products":{"items":{"$ref":"#/components/schemas/ProductOut"},"type":"array","title":"Products"},"default_product":{"type":"string","title":"Default Product"},"is_admin":{"type":"boolean","title":"Is Admin"}},"type":"object","required":["products","default_product","is_admin"],"title":"ProductsResponse"},"ProfileCreate":{"properties":{"name":{"type":"string","title":"Name"},"company_name":{"type":"string","title":"Company Name"},"company_website":{"type":"string","title":"Company Website","default":""},"system_prompt_role":{"type":"string","title":"System Prompt Role","default":""},"report_days":{"type":"integer","title":"Report Days","default":7},"report_language":{"type":"string","title":"Report Language","default":"English"},"reddit_subs":{"items":{"type":"string"},"type":"array","title":"Reddit Subs","default":[]},"industry":{"type":"string","title":"Industry","default":"custom_software"},"intelligence_modules":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Intelligence Modules"},"location":{"type":"string","title":"Location","default":""},"product_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Product Type"},"min_signal_confidence":{"type":"number","title":"Min Signal Confidence","default":0.0},"company_size_range":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Size Range"},"icp_profile":{"type":"string","title":"Icp Profile","default":""}},"type":"object","required":["name","company_name"],"title":"ProfileCreate"},"ProfileUpdate":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name"},"company_website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Website"},"system_prompt_role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"System Prompt Role"},"report_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Report Days"},"report_language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Language"},"reddit_subs":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Reddit Subs"},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry"},"intelligence_modules":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Intelligence Modules"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location"},"product_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Product Type"},"min_signal_confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Min Signal Confidence"},"company_size_range":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Size Range"},"icp_profile":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icp Profile"}},"type":"object","title":"ProfileUpdate"},"PublicCompanyLookupRequest":{"properties":{"country":{"type":"string","maxLength":2,"minLength":2,"title":"Country","description":"ISO-2 country code"},"query":{"type":"string","maxLength":200,"minLength":1,"title":"Query","description":"Exact registered name or number"}},"type":"object","required":["country","query"],"title":"PublicCompanyLookupRequest"},"PublicCompanyLookupResponse":{"properties":{"country":{"type":"string","title":"Country"},"query_kind":{"type":"string","enum":["name","number"],"title":"Query Kind"},"matches":{"items":{"$ref":"#/components/schemas/PublicCompanyMatch"},"type":"array","title":"Matches"},"truncated":{"type":"boolean","title":"Truncated"},"checked_at":{"type":"string","title":"Checked At","description":"When the register data was read"},"source_url":{"type":"string","title":"Source Url"},"cached":{"type":"boolean","title":"Cached"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note","description":"SG: why a valid UEN has no match (its type is not in SONAR's copy). CY, EE, LV, SG, IE: on a name with no exact match, the miss text with the partial-name suggestions in words. null otherwise"},"suggestions":{"items":{"$ref":"#/components/schemas/PublicCompanyMatch"},"type":"array","title":"Suggestions","description":"CY, EE, LV, SG, IE: a name with no exact match lists up to 10 ACTIVE companies whose registered name starts with it (exact name first, then names in alphabetical order of the first 200 per prefix). Never matches: the company asked for was not found"},"suggestion_prefix":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Suggestion Prefix","description":"The start of a name searched for suggestions (upper case, legal form removed); null when no partial search ran"}},"type":"object","required":["country","query_kind","matches","truncated","checked_at","source_url","cached"],"title":"PublicCompanyLookupResponse"},"PublicCompanyMatch":{"properties":{"name":{"type":"string","title":"Name"},"registration_number":{"type":"string","title":"Registration Number"},"status":{"type":"string","enum":["active","inactive","unknown"],"title":"Status"},"register_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Register Status","description":"The register's own wording"},"legal_form":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Legal Form"},"incorporated_on":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Incorporated On"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address"},"address_withheld":{"type":"boolean","title":"Address Withheld","description":"True for a sole trader or natural person: not shown on the free page","default":false},"restricted":{"type":"boolean","title":"Restricted","description":"True when the business opted out of publication (FR Sirene)","default":false},"vat_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vat Id"},"previous_names":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Previous Names","description":"None when the register does not give former names"},"good_standing":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Good Standing","description":"False when the register flags bankruptcy, liquidation or strike-off; None when it publishes no such marker"},"entity_kind":{"anyOf":[{"type":"string","enum":["company","branch","other"]},{"type":"null"}],"title":"Entity Kind"},"register_url":{"type":"string","title":"Register Url","description":"The company's page on the official register"}},"type":"object","required":["name","registration_number","status","register_url"],"title":"PublicCompanyMatch"},"RegisteredAgentOut":{"properties":{"name":{"type":"string","title":"Name","description":"The agent the state register names (a company or a person)"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address","description":"The agent's address in the state"}},"type":"object","required":["name"],"title":"RegisteredAgentOut"},"RegistryAgent":{"properties":{"name":{"type":"string","title":"Name"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address"}},"type":"object","required":["name"],"title":"RegistryAgent"},"RegistryMatch":{"properties":{"status":{"type":"string","enum":["FOUND","NOT_FOUND","NOT_SEARCHED","AMBIGUOUS"],"title":"Status","description":"FOUND: the register holds the company. NOT_FOUND: the register answered and holds no company of this exact name (or number). NOT_SEARCHED: no register answer (see reason); never read it as clean. AMBIGUOUS: more than one active company holds the name (see matches; send registration_number)"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Why NOT_SEARCHED: COUNTRY_NOT_PROVIDED, COUNTRY_NOT_SUPPORTED, STATE_NOT_SUPPORTED, NAME_SEARCH_NOT_SUPPORTED, REGISTRY_UNAVAILABLE. An open list: ignore values you do not know"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"},"searched_by":{"anyOf":[{"type":"string","enum":["name","registration_number"]},{"type":"null"}],"title":"Searched By"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"FOUND: the registered name"},"registration_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Registration Number","description":"FOUND: the register's number"},"company_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Status","description":"FOUND: active / inactive / unknown"},"legal_form":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Legal Form","description":"FOUND: the register's legal form"},"incorporated_on":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Incorporated On","description":"FOUND: date of incorporation"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address","description":"FOUND: registered address"},"vat_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vat Id","description":"FOUND: VAT number, where the register gives it"},"registered_agent":{"anyOf":[{"$ref":"#/components/schemas/RegistryAgent"},{"type":"null"}],"description":"FOUND, US: the agent"},"good_standing":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Good Standing","description":"FOUND: as in POST /v1/companies/lookup"},"previous_names":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Previous Names"},"jurisdiction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Jurisdiction","description":"US: state of formation if elsewhere"},"restricted":{"type":"boolean","title":"Restricted","description":"FOUND, FR: the business opted out of publication in Sirene; only the number, company_status and good_standing are given","default":false},"matches":{"items":{"$ref":"#/components/schemas/RegistryMatchCompany"},"type":"array","title":"Matches","default":[]},"last_updated":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Updated","description":"When the register was read"},"checked_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Checked At"}},"type":"object","required":["status"],"title":"RegistryMatch","description":"The company register's answer for the subject (2026-11-06): the same\nengine and name rule as ``POST /v1/companies/lookup``."},"RegistryMatchCompany":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"null only when restricted"},"registration_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Registration Number"},"status":{"type":"string","title":"Status","description":"active / inactive / unknown"},"legal_form":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Legal Form"},"incorporated_on":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Incorporated On"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address"},"vat_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vat Id"},"registered_agent":{"anyOf":[{"$ref":"#/components/schemas/RegistryAgent"},{"type":"null"}]},"good_standing":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Good Standing","description":"As in POST /v1/companies/lookup: null where the register has no markers"},"previous_names":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Previous Names"},"jurisdiction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Jurisdiction"},"restricted":{"type":"boolean","title":"Restricted","description":"FR: the business opted out of publication in Sirene; only the number, status and good_standing are given (as in POST /v1/companies/lookup)","default":false}},"type":"object","required":["name","status"],"title":"RegistryMatchCompany"},"RunRequest":{"properties":{"country":{"anyOf":[{"type":"string","maxLength":2,"minLength":2},{"type":"null"}],"title":"Country","description":"ISO 3166-1 alpha-2 country of registration (GB, FR, NO, CZ, DK, ...). Without it no national company register is searched (registry_match: NOT_SEARCHED)"},"state":{"anyOf":[{"type":"string","maxLength":2,"minLength":2},{"type":"null"}],"title":"State","description":"US only: the 2-letter state of formation, whose register is searched"},"registration_number":{"anyOf":[{"type":"string","maxLength":40,"minLength":1},{"type":"null"}],"title":"Registration Number","description":"The register's company number (GB company number, FR SIREN, CZ IČO, NO orgnr, ...). Needs country; checked against the country's format like the lookup"},"vat_number":{"anyOf":[{"type":"string","maxLength":20,"minLength":2},{"type":"null"}],"title":"Vat Number","description":"VAT number with its country prefix (validated against the EU VAT system)"},"company_name":{"type":"string","maxLength":200,"minLength":1,"title":"Company Name","description":"Company name to research"},"website":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Website","description":"Company website (optional; a bare domain is accepted)"}},"type":"object","required":["company_name"],"title":"RunRequest"},"RunShareResponse":{"properties":{"share_url":{"type":"string","title":"Share Url","description":"Absolute link to the report page, https://getsonar.report/shared/<token>"},"share_token":{"type":"string","title":"Share Token","description":"URL-safe 256-bit random token"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At","description":"ISO-8601 time the link stops working (410 Gone after it)"}},"type":"object","required":["share_url","share_token"],"title":"RunShareResponse","description":"A public link to a completed KYB run's report (no API key needed to\nopen it). The same link a web report's Share button makes."},"RunStatusResponse":{"properties":{"run_id":{"type":"string","title":"Run Id"},"agent":{"type":"string","title":"Agent"},"status":{"type":"string","title":"Status"},"company":{"$ref":"#/components/schemas/CompanyInfo"},"result":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result"},"report":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Report"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"created_at":{"type":"string","title":"Created At","default":""},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"}},"type":"object","required":["run_id","agent","status","company"],"title":"RunStatusResponse"},"RunSubmitResponse":{"properties":{"run_id":{"type":"string","title":"Run Id"},"status":{"type":"string","title":"Status"},"agent":{"type":"string","title":"Agent"},"company":{"$ref":"#/components/schemas/CompanyInfo"},"estimated_seconds":{"type":"integer","title":"Estimated Seconds","default":90},"poll_url":{"type":"string","title":"Poll Url"}},"type":"object","required":["run_id","status","agent","company","poll_url"],"title":"RunSubmitResponse"},"ScheduleUpdate":{"properties":{"day_of_week":{"type":"string","title":"Day Of Week","default":"monday"},"time_utc":{"type":"string","title":"Time Utc","default":"06:00"},"is_enabled":{"type":"boolean","title":"Is Enabled","default":true}},"type":"object","title":"ScheduleUpdate"},"ScreeningRunRequest":{"properties":{"profile_id":{"type":"string","maxLength":64,"title":"Profile Id"},"company_name":{"type":"string","maxLength":300,"title":"Company Name"},"website":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Website"},"tier":{"type":"integer","title":"Tier","default":2},"notes":{"type":"string","maxLength":5000,"title":"Notes","default":""},"country":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Country"},"vat_number":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Vat Number"},"krs_number":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Krs Number"},"nip":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Nip"},"ico":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Ico"},"iban":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Iban"},"cnpj":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Cnpj"},"uen":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Uen"},"bce_number":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Bce Number"},"kvk_number":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Kvk Number"},"registration_number":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Registration Number"},"state":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"State"},"funnel_src":{"anyOf":[{"type":"string","maxLength":48},{"type":"null"}],"title":"Funnel Src"}},"type":"object","required":["profile_id","company_name"],"title":"ScreeningRunRequest","description":"Request body for running a new KYB screening."},"SignupSource":{"properties":{"referrer_host":{"type":"string","maxLength":253,"title":"Referrer Host","description":"document.referrer host only","default":""},"utm_source":{"type":"string","maxLength":200,"title":"Utm Source","default":""},"ref":{"type":"string","maxLength":200,"title":"Ref","description":"SONAR ?ref= short-link parameter","default":""},"path":{"type":"string","maxLength":300,"title":"Path","description":"Landing path (used to classify, not kept)","default":""}},"type":"object","title":"SignupSource"},"SourceRef":{"properties":{"provider":{"type":"string","title":"Provider","description":"The kind of source, never its name (2026-11-06): company_register, beneficial_ownership_register, official_gazette, vat_register, lei_data, securities_filings, regulatory_records, sanctions_lists, pep_database, offshore_records, news_search, regulator_press_releases, domain_records, bank_data, company_data, web_profiles, sonar_analysis, public_records, zefix. An open list: read an unknown value as public_records","default":""},"url":{"type":"string","title":"Url","description":"Empty for a register or database record; a news article keeps its link","default":""},"excerpt":{"type":"string","title":"Excerpt","default":""},"retrieved_at":{"type":"string","title":"Retrieved At","default":""}},"type":"object","title":"SourceRef"},"UkCompanyCandidate":{"properties":{"company_number":{"type":"string","title":"Company Number"},"name":{"type":"string","title":"Name"},"status":{"type":"string","title":"Status"},"incorporated_on":{"type":"string","title":"Incorporated On"},"address":{"type":"string","title":"Address"},"register_url":{"type":"string","title":"Register Url"}},"type":"object","required":["company_number","name","status","incorporated_on","address","register_url"],"title":"UkCompanyCandidate"},"UkCompanyLookupRequest":{"properties":{"query":{"type":"string","maxLength":200,"minLength":1,"title":"Query","description":"Name or company number"}},"type":"object","required":["query"],"title":"UkCompanyLookupRequest"},"UkCompanyLookupResponse":{"properties":{"kind":{"type":"string","enum":["profile","candidates"],"title":"Kind"},"profile":{"anyOf":[{"$ref":"#/components/schemas/UkCompanyProfile"},{"type":"null"}]},"candidates":{"items":{"$ref":"#/components/schemas/UkCompanyCandidate"},"type":"array","title":"Candidates"},"checked_at":{"type":"string","title":"Checked At"},"source_url":{"type":"string","title":"Source Url"},"cached":{"type":"boolean","title":"Cached"}},"type":"object","required":["kind","candidates","checked_at","source_url","cached"],"title":"UkCompanyLookupResponse"},"UkCompanyProfile":{"properties":{"company_number":{"type":"string","title":"Company Number"},"name":{"type":"string","title":"Name"},"status":{"type":"string","title":"Status"},"company_type":{"type":"string","title":"Company Type"},"incorporated_on":{"type":"string","title":"Incorporated On"},"address":{"type":"string","title":"Address"},"sic_codes":{"items":{"type":"string"},"type":"array","title":"Sic Codes"},"active_officers":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Active Officers"},"source":{"type":"string","title":"Source"},"register_url":{"type":"string","title":"Register Url"}},"type":"object","required":["company_number","name","status","company_type","incorporated_on","address","sic_codes","source","register_url"],"title":"UkCompanyProfile"},"UsageResponse":{"properties":{"period":{"type":"string","title":"Period"},"total_requests":{"type":"integer","title":"Total Requests"},"free_trial_remaining":{"type":"integer","title":"Free Trial Remaining"},"balance_cents":{"type":"integer","title":"Balance Cents"},"free_lookups_remaining":{"type":"integer","title":"Free Lookups Remaining","default":0},"by_agent":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Agent","default":{}},"by_endpoint":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Endpoint","default":{}},"monthly_quota":{"type":"integer","title":"Monthly Quota","default":0},"remaining":{"type":"integer","title":"Remaining","default":0}},"type":"object","required":["period","total_requests","free_trial_remaining","balance_cents"],"title":"UsageResponse"},"UserSettingsUpdate":{"properties":{"slack_webhook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slack Webhook Url"},"slack_notifications_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Slack Notifications Enabled"},"xbees_notifications_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Xbees Notifications Enabled"},"email_alerts_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Email Alerts Enabled"},"email_alert_recipients":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email Alert Recipients"},"telegram_bot_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Telegram Bot Token"},"telegram_chat_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Telegram Chat Id"},"whatsapp_account_sid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Whatsapp Account Sid"},"whatsapp_auth_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Whatsapp Auth Token"},"whatsapp_from_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Whatsapp From Number"},"whatsapp_to_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Whatsapp To Number"},"has_completed_onboarding":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Completed Onboarding"},"signup_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signup Ref"},"signup_page":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signup Page"},"signup_unlock":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signup Unlock"},"utm_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Utm Source"},"utm_medium":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Utm Medium"},"utm_campaign":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Utm Campaign"},"utm_term":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Utm Term"},"utm_content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Utm Content"},"signup_referrer_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signup Referrer Url"},"signup_landing_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signup Landing Url"},"self_reported_source":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Self Reported Source"},"signup_plan":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Signup Plan"}},"type":"object","title":"UserSettingsUpdate"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VatCheckRequest":{"properties":{"country":{"type":"string","maxLength":2,"minLength":2,"title":"Country","description":"ISO / VIES country code"},"vat_number":{"type":"string","maxLength":32,"minLength":1,"title":"Vat Number"}},"type":"object","required":["country","vat_number"],"title":"VatCheckRequest"},"VatCheckResponse":{"properties":{"country_code":{"type":"string","title":"Country Code"},"vat_number":{"type":"string","title":"Vat Number"},"valid":{"type":"boolean","title":"Valid"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"None when the member state withholds it"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address"},"checked_at":{"type":"string","title":"Checked At"},"source_url":{"type":"string","title":"Source Url"},"cached":{"type":"boolean","title":"Cached"}},"type":"object","required":["country_code","vat_number","valid","checked_at","source_url","cached"],"title":"VatCheckResponse"}},"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"},"BearerKey":{"type":"http","scheme":"bearer","description":"Authorization: Bearer sk-sonar-... (the same key)"}}}}