{"openapi":"3.1.0","info":{"title":"Grail Sold Data API","version":"0.1.0"},"paths":{"/api/billing/plans":{"get":{"tags":["billing"],"summary":"Api Billing Plans","description":"Public plan ladder + whether the money rail is currently usable.","operationId":"api_billing_plans_api_billing_plans_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Api Billing Plans Api Billing Plans Get"}}}}}}},"/api/billing/entitlement/{account_id}":{"get":{"tags":["billing"],"summary":"Api Billing Entitlement","operationId":"api_billing_entitlement_api_billing_entitlement__account_id__get","parameters":[{"name":"account_id","in":"path","required":true,"schema":{"type":"string","title":"Account Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Api Billing Entitlement Api Billing Entitlement  Account Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/billing/checkout":{"post":{"tags":["billing"],"summary":"Api Billing Checkout","description":"Create a Stripe checkout session for a plan. Test-only by construction.","operationId":"api_billing_checkout_api_billing_checkout_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Api Billing Checkout Api Billing Checkout Post"}}}}}}},"/api/billing/portal":{"post":{"tags":["billing"],"summary":"Api Billing Portal","description":"Create a Stripe billing-portal session so customers can manage/cancel.","operationId":"api_billing_portal_api_billing_portal_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Api Billing Portal Api Billing Portal Post"}}}}}}},"/api/billing/webhook":{"post":{"tags":["billing"],"summary":"Api Billing Webhook","description":"Verify and apply a Stripe webhook. Never crashes; honest failure.","operationId":"api_billing_webhook_api_billing_webhook_post","parameters":[{"name":"Stripe-Signature","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stripe-Signature"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Api Billing Webhook Api Billing Webhook Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/billing/grant":{"post":{"tags":["billing"],"summary":"Api Billing Grant","description":"Operator/test helper: set an entitlement directly. Refuses live plans.\n\nGuarded by GRAIL_BILLING_TEST_HOOK=1 so it can never be an open door in prod.","operationId":"api_billing_grant_api_billing_grant_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Api Billing Grant Api Billing Grant Post"}}}}}}},"/api/v2/health":{"get":{"tags":["v2-decision"],"summary":"Api V2 Health","description":"Trust readiness of the v2 spine (operator-facing).","operationId":"api_v2_health_api_v2_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Api V2 Health Api V2 Health Get"}}}}}}},"/api/v2/quote/{card_id}":{"get":{"tags":["v2-decision"],"summary":"Api V2 Quote","description":"Evidence-backed quote for one card. Never fabricates.","operationId":"api_v2_quote_api_v2_quote__card_id__get","parameters":[{"name":"card_id","in":"path","required":true,"schema":{"type":"string","title":"Card Id"}},{"name":"market_key","in":"query","required":false,"schema":{"type":"string","maxLength":40,"default":"raw:en","title":"Market Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Api V2 Quote Api V2 Quote  Card Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v2/decision/{card_id}":{"get":{"tags":["v2-decision"],"summary":"Api V2 Decision","description":"What to DO with this card + your real net, traced to evidence.\n\n`ask` (optional) underwrites a specific asking price: BUY / PASS.\n`account_id` (optional) applies the plan ladder; anonymous → free tier.","operationId":"api_v2_decision_api_v2_decision__card_id__get","parameters":[{"name":"card_id","in":"path","required":true,"schema":{"type":"string","title":"Card Id"}},{"name":"market_key","in":"query","required":false,"schema":{"type":"string","maxLength":40,"default":"raw:en","title":"Market Key"}},{"name":"ask","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":1000000,"minimum":0},{"type":"null"}],"title":"Ask"}},{"name":"account_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Account Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Api V2 Decision Api V2 Decision  Card Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v2/review/queue":{"get":{"tags":["v2-review"],"summary":"Api Review Queue","description":"Open review items, each with the observation vs. its candidate card.","operationId":"api_review_queue_api_v2_review_queue_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Api Review Queue Api V2 Review Queue Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v2/review/{review_id}/resolve":{"post":{"tags":["v2-review"],"summary":"Api Review Resolve","description":"Resolve one review item. Mutations are fail-closed + audited.","operationId":"api_review_resolve_api_v2_review__review_id__resolve_post","parameters":[{"name":"review_id","in":"path","required":true,"schema":{"type":"string","title":"Review Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Api Review Resolve Api V2 Review  Review Id  Resolve Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/grading-roi":{"get":{"tags":["grading-roi"],"summary":"Api Grading Roi","operationId":"api_grading_roi_api_grading_roi_get","parameters":[{"name":"company","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"PSA | BGS | CGC | TAG","title":"Company"},"description":"PSA | BGS | CGC | TAG"},{"name":"grade","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Exact grade, e.g. 10, 9.5, 9","title":"Grade"},"description":"Exact grade, e.g. 10, 9.5, 9"},{"name":"set_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Catalog set id, e.g. swsh7","title":"Set Id"},"description":"Catalog set id, e.g. swsh7"},{"name":"era","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"vintage | ex | bw | sm | swsh | sv","title":"Era"},"description":"vintage | ex | bw | sm | swsh | sv"},{"name":"min_profit","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"description":"Minimum USD profit","title":"Min Profit"},"description":"Minimum USD profit"},{"name":"min_roi","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Minimum ROI percent","title":"Min Roi"},"description":"Minimum ROI percent"},{"name":"profitable_only","in":"query","required":false,"schema":{"type":"boolean","description":"Only rows with profit > 0","default":true,"title":"Profitable Only"},"description":"Only rows with profit > 0"},{"name":"member","in":"query","required":false,"schema":{"type":"boolean","description":"Include Collectors Club member bulk tiers","default":false,"title":"Member"},"description":"Include Collectors Club member bulk tiers"},{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Accepted for API parity; no language rails exist yet","title":"Language"},"description":"Accepted for API parity; no language rails exist yet"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Page Size"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Api Grading Roi Api Grading Roi Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/grading/tiers":{"get":{"tags":["grading-roi"],"summary":"Api Grading Tiers","description":"Expose the fee config so the UI never hardcodes fees.","operationId":"api_grading_tiers_api_grading_tiers_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Api Grading Tiers Api Grading Tiers Get"}}}}}}},"/market":{"get":{"tags":["terminal"],"summary":"Market","operationId":"market_market_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/":{"get":{"tags":["terminal"],"summary":"Terminal Home","operationId":"terminal_home__get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/api/market":{"get":{"tags":["terminal"],"summary":"Api Market","description":"Ticker rows for the Next.js webapp. Real cleaned data-backed.","operationId":"api_market_api_market_get","parameters":[{"name":"market","in":"query","required":false,"schema":{"type":"string","default":"pokemon","title":"Market"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","default":"delta","title":"Sort"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":60,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Api Market Api Market Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/signals":{"get":{"tags":["terminal"],"summary":"Api Signals","description":"Product-shaped Radar feed: ranked signals with evidence and caveats.","operationId":"api_signals_api_signals_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":24,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Api Signals Api Signals Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/search":{"get":{"tags":["terminal"],"summary":"Api Search","description":"Catalog search for the webapp search page (same ranked search as the\nHTML /search - name/set/number prefix + substring).","operationId":"api_search_api_search_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","default":"","title":"Q"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Api Search Api Search Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/market/summary":{"get":{"tags":["terminal"],"summary":"Api Market Summary","operationId":"api_market_summary_api_market_summary_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Api Market Summary Api Market Summary Get"}}}}}}},"/api/market/index":{"get":{"tags":["terminal"],"summary":"Api Market Index","description":"Real normalized market index. History is limited to what Grail has\nactually captured; the response says exactly how much exists.","operationId":"api_market_index_api_market_index_get","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","default":90,"title":"Days"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Api Market Index Api Market Index Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/sets":{"get":{"tags":["terminal"],"summary":"Api Sets","operationId":"api_sets_api_sets_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":24,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Api Sets Api Sets Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/sets/{set_id}":{"get":{"tags":["terminal"],"summary":"Api Set","operationId":"api_set_api_sets__set_id__get","parameters":[{"name":"set_id","in":"path","required":true,"schema":{"type":"string","title":"Set Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Api Set Api Sets  Set Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/cards/batch":{"get":{"tags":["terminal"],"summary":"Api Cards Batch","description":"Compact live pricing for up to 50 card keys (watchlist page).\nLight path: catalog row + best pricing row per key (no full page build).","operationId":"api_cards_batch_api_cards_batch_get","parameters":[{"name":"keys","in":"query","required":false,"schema":{"type":"string","default":"","title":"Keys"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Api Cards Batch Api Cards Batch Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/cards/{card_id}/related":{"get":{"tags":["terminal"],"summary":"Api Card Related","description":"Related cards: same set, closest price tier with pricing. Powers the\nSSR 'More from this set' rail on card pages.","operationId":"api_card_related_api_cards__card_id__related_get","parameters":[{"name":"card_id","in":"path","required":true,"schema":{"type":"string","title":"Card Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":8,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Api Card Related Api Cards  Card Id  Related Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/cards/{card_id}":{"get":{"tags":["terminal"],"summary":"Api Card","description":"Full card detail for the webapp ticker page (webapp shape).","operationId":"api_card_api_cards__card_id__get","parameters":[{"name":"card_id","in":"path","required":true,"schema":{"type":"string","title":"Card Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Api Card Api Cards  Card Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/methodology":{"get":{"tags":["terminal"],"summary":"Api Methodology","description":"Coverage and valuation contract for the trust surface.","operationId":"api_methodology_api_methodology_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Api Methodology Api Methodology Get"}}}}}}},"/api/catalog/keys":{"get":{"tags":["terminal"],"summary":"Api Catalog Keys","description":"Lightweight catalog key list for the webapp sitemap (SEO surface).\n\nCatalog-only: returns every card id we can render a page for plus the\ndistinct set ids. No pricing join — this is a crawl map, not a product\npayload, so it stays cheap.","operationId":"api_catalog_keys_api_catalog_keys_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":30000,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Api Catalog Keys Api Catalog Keys Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/ops/comps":{"get":{"tags":["ops"],"summary":"Api Ops Comps","operationId":"api_ops_comps_api_ops_comps_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 Api Ops Comps Api Ops Comps Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pricing":{"get":{"tags":["pricing"],"summary":"Hub","operationId":"hub_pricing_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/search":{"get":{"tags":["pricing"],"summary":"Search","operationId":"search_search_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":80,"default":"","title":"Q"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/card/{card_id}":{"get":{"tags":["pricing"],"summary":"Card Page","operationId":"card_page_card__card_id__get","parameters":[{"name":"card_id","in":"path","required":true,"schema":{"type":"string","title":"Card Id"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/card/{card_id}/report":{"get":{"tags":["pricing"],"summary":"Report Listing","description":"PC-parity 'Report It' — record a bad/junky listing flag for manual\nreview (the crowdsourced-correction leg of our data recipe). Appends one\nJSONL line; no blocking, no auth (same as PC).","operationId":"report_listing_card__card_id__report_get","parameters":[{"name":"card_id","in":"path","required":true,"schema":{"type":"string","title":"Card Id"}},{"name":"url","in":"query","required":false,"schema":{"type":"string","maxLength":400,"default":"","title":"Url"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Report Listing Card  Card Id  Report Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/card/{card_id}/json":{"get":{"tags":["pricing"],"summary":"Card Json","operationId":"card_json_card__card_id__json_get","parameters":[{"name":"card_id","in":"path","required":true,"schema":{"type":"string","title":"Card Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Card Json Card  Card Id  Json Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/account/signup":{"post":{"tags":["account"],"summary":"Api Signup","description":"Instant-key signup (matches the benchmark's one-step flow).\n\nCreates the Supabase user **already email-confirmed** via the service-role\nadmin API, so there is no confirmation-email step. The client then signs in\nwith the same credentials to obtain a session and mints a key on /keys.\n\nFail-soft: when the admin API is unavailable the client falls back to the\nnormal Supabase signup (confirmation email).","operationId":"api_signup_api_account_signup_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupBody"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Api Signup Api Account Signup Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/account/keys":{"get":{"tags":["account"],"summary":"List Keys","operationId":"list_keys_api_account_keys_get","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-grail-tenant-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Grail-Tenant-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Keys Api Account Keys Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["account"],"summary":"Create Key","operationId":"create_key_api_account_keys_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-grail-tenant-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Grail-Tenant-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateKeyRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create Key Api Account Keys Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/account/keys/{key_id}/revoke":{"post":{"tags":["account"],"summary":"Revoke Key","description":"Revoke one active key owned by the tenant. Idempotent: a second call\nreturns ``revoked: false`` rather than erroring.","operationId":"revoke_key_api_account_keys__key_id__revoke_post","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"}},{"name":"x-grail-tenant-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Grail-Tenant-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Revoke Key Api Account Keys  Key Id  Revoke Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/account/keys/{key_id}/rotate":{"post":{"tags":["account"],"summary":"Rotate Key","description":"Rotate a key: revoke the old one and mint a replacement with the same\nlabel + plan. The new token is returned exactly once (never logged) so the\ncaller can swap it in atomically.","operationId":"rotate_key_api_account_keys__key_id__rotate_post","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"}},{"name":"x-grail-tenant-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Grail-Tenant-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Rotate Key Api Account Keys  Key Id  Rotate Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/account/usage":{"get":{"tags":["account"],"summary":"Usage","operationId":"usage_api_account_usage_get","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-grail-tenant-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Grail-Tenant-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Usage Api Account Usage Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/account/subscription":{"get":{"tags":["account"],"summary":"Subscription","operationId":"subscription_api_account_subscription_get","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-grail-tenant-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Grail-Tenant-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Subscription Api Account Subscription Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/status.json":{"get":{"tags":["comps"],"summary":"Api Status Json","description":"Machine-readable status digest with a stable contract version.\n\nSame non-secret data as ``/v1/status`` plus ``digest_version`` so monitors can\npin to a schema. The router carries a ``/v1`` prefix, so this is served at\n``/v1/status.json`` (reachable via the /v1 proxy). No key required; never\nexposes keys/cookies/row contents.","operationId":"api_status_json_v1_status_json_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Api Status Json V1 Status Json Get"}}}}}}},"/v1/status":{"get":{"tags":["comps"],"summary":"Api Status","description":"Public product status — no key required.\n\nHealth plus non-secret dataset scale (corpus/ledger row counts and healthy\nidentity count) and the configured acquisition provider name. Never exposes\nkeys, tokens, cookies, session material, or row contents.","operationId":"api_status_v1_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Api Status V1 Status Get"}}}}}}},"/v1/usage":{"get":{"tags":["comps"],"summary":"Usage","description":"Authenticated usage endpoint.\n\nLike SoldComps, this is free to call: checking quota should not consume it.","operationId":"usage_v1_usage_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 Usage V1 Usage Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/scrape":{"get":{"tags":["comps"],"summary":"Search sold (or active) listings","description":"GET /v1/scrape — SoldComps drop-in.\n\nItem objects are a superset of SoldComps' field set; unknown fields are\n``null``. ``conditionId``, ``includeCompleteListing``, ``sortOrder`` and\n``itemLocation`` are honored. Params we cannot honor (``sellerType``,\n``hydrateBoa``, ``buyingFormat=acceptsOffers``) return ``400\nunsupported_parameter`` — never a silent ignore.","operationId":"scrape_v1_scrape_get","parameters":[{"name":"keyword","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Search keyword (required).","title":"Keyword"},"description":"Search keyword (required)."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Result page (1-based).","default":1,"title":"Page"},"description":"Result page (1-based)."},{"name":"count","in":"query","required":false,"schema":{"type":"integer","description":"Items to return (1-240, default 240).","default":240,"title":"Count"},"description":"Items to return (1-240, default 240)."},{"name":"ebaySite","in":"query","required":false,"schema":{"type":"string","description":"eBay site, e.g. ebay.com, ebay.co.uk.","default":"ebay.com","title":"Ebaysite"},"description":"eBay site, e.g. ebay.com, ebay.co.uk."},{"name":"sortOrder","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"endedRecently | timeNewlyListed | pricePlusPostageLowest | pricePlusPostageHighest (distanceNearest unsupported).","title":"Sortorder"},"description":"endedRecently | timeNewlyListed | pricePlusPostageLowest | pricePlusPostageHighest (distanceNearest unsupported)."},{"name":"minPrice","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Minimum price filter.","title":"Minprice"},"description":"Minimum price filter."},{"name":"maxPrice","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Maximum price filter.","title":"Maxprice"},"description":"Maximum price filter."},{"name":"itemCondition","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"any | new | used (SoldComps alias).","title":"Itemcondition"},"description":"any | new | used (SoldComps alias)."},{"name":"categoryId","in":"query","required":false,"schema":{"type":"string","description":"eBay category id.","default":"0","title":"Categoryid"},"description":"eBay category id."},{"name":"conditionId","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"eBay numeric condition id (e.g. 1000 New, 3000 Used). Overrides itemCondition.","title":"Conditionid"},"description":"eBay numeric condition id (e.g. 1000 New, 3000 Used). Overrides itemCondition."},{"name":"buyingFormat","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"all | auction | buyItNow. 'acceptsOffers' is unsupported and returns 400.","title":"Buyingformat"},"description":"all | auction | buyItNow. 'acceptsOffers' is unsupported and returns 400."},{"name":"sellerType","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"EU-only seller-type filter. Unsupported — returns 400 unsupported_parameter if set.","title":"Sellertype"},"description":"EU-only seller-type filter. Unsupported — returns 400 unsupported_parameter if set."},{"name":"itemLocation","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"default | domestic | worldwide.","title":"Itemlocation"},"description":"default | domestic | worldwide."},{"name":"soldAfter","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO date lower bound (inclusive).","title":"Soldafter"},"description":"ISO date lower bound (inclusive)."},{"name":"soldBefore","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO date upper bound (inclusive).","title":"Soldbefore"},"description":"ISO date upper bound (inclusive)."},{"name":"sold","in":"query","required":false,"schema":{"type":"boolean","description":"true = sold listings, false = active.","default":true,"title":"Sold"},"description":"true = sold listings, false = active."},{"name":"relevance","in":"query","required":false,"schema":{"type":"boolean","description":"Grail-only option: apply deterministic relevance cleaning. Default false for SoldComps parity.","default":false,"title":"Relevance"},"description":"Grail-only option: apply deterministic relevance cleaning. Default false for SoldComps parity."},{"name":"exactMatch","in":"query","required":false,"schema":{"type":"boolean","description":"Strip loosened-match results, matching SoldComps' default.","default":true,"title":"Exactmatch"},"description":"Strip loosened-match results, matching SoldComps' default."},{"name":"aspectFilter","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"JSON facet filters (grade, brand, ...).","title":"Aspectfilter"},"description":"JSON facet filters (grade, brand, ...)."},{"name":"includeCompleteListing","in":"query","required":false,"schema":{"type":"boolean","description":"Include eBay completed-listing metadata (LH_Complete) for best-offer detection.","default":true,"title":"Includecompletelisting"},"description":"Include eBay completed-listing metadata (LH_Complete) for best-offer detection."},{"name":"hydrateBoa","in":"query","required":false,"schema":{"type":"boolean","description":"Best-Offer price hydration. Unsupported — returns 400 unsupported_parameter if true.","default":false,"title":"Hydrateboa"},"description":"Best-Offer price hydration. Unsupported — returns 400 unsupported_parameter if true."},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"X-eBay-Cookies","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ebay-Cookies"}}],"responses":{"200":{"description":"SoldComps-parity listing envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScrapeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/scrape/bulk":{"post":{"tags":["comps"],"summary":"Scrape Bulk","description":"POST /v1/scrape/bulk — up to 25 queries, each through the cache-first path.","operationId":"scrape_bulk_v1_scrape_bulk_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/BulkScrapeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/sold":{"get":{"tags":["comps"],"summary":"Sold Alias","description":"Friendly alias for /v1/scrape — `q` instead of `keyword`, sold always.\n\nSame contract, same cleaning, same metering; exists so the sold-comps\nsurface reads the way developers expect (GET /v1/sold?q=...).","operationId":"sold_alias_v1_sold_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"title":"Q"}},{"name":"count","in":"query","required":false,"schema":{"type":"integer","description":"Items to return: 60, 120, or 240.","default":240,"title":"Count"},"description":"Items to return: 60, 120, or 240."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"ebaySite","in":"query","required":false,"schema":{"type":"string","default":"ebay.com","title":"Ebaysite"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"X-eBay-Cookies","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ebay-Cookies"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/shipping/rates":{"post":{"tags":["comps"],"summary":"Shipping Rates","description":"POST /v1/shipping/rates — observed shipping from our corpus (+ labelled estimate).\n\nWe never fabricate carrier quotes: ``observed`` is the actual shipping sellers\ncharged on the sold listings we stored; ``estimate`` (only when ``weightOz`` is\ngiven) is a labelled planning heuristic. No basis available -> fail closed.","operationId":"shipping_rates_v1_shipping_rates_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/ShippingRateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/ledger/stats":{"get":{"tags":["comps"],"summary":"Ledger Stats","operationId":"ledger_stats_v1_ledger_stats_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"}}}}}}},"/v1/scrape/jobs":{"post":{"tags":["comps"],"summary":"Create Scrape Job","operationId":"create_scrape_job_v1_scrape_jobs_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/ScrapeJobRequest"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/scrape/jobs/{job_id}":{"get":{"tags":["comps"],"summary":"Get Scrape Job","operationId":"get_scrape_job_v1_scrape_jobs__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job 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/scrape/batch":{"post":{"tags":["comps"],"summary":"Create Batch Job","description":"POST /v1/scrape/batch — queue an async batch of up to 100 keywords.\n\nCategory-agnostic: each query runs the same service path as /v1/scrape, so\nbatch output can never drift from single-scrape output. Poll with\nGET /v1/scrape/batch/{job_id}.","operationId":"create_batch_job_v1_scrape_batch_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/BatchJobRequest"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/scrape/batch/{job_id}":{"get":{"tags":["comps"],"summary":"Get Batch Job","description":"GET /v1/scrape/batch/{job_id} — poll an async batch job.","operationId":"get_batch_job_v1_scrape_batch__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job 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/scrape/category":{"get":{"tags":["comps"],"summary":"Scrape Category","description":"GET /v1/scrape/category — SoldComps category-scoped search (drop-in).","operationId":"scrape_category_v1_scrape_category_get","parameters":[{"name":"keyword","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Search keyword (required).","title":"Keyword"},"description":"Search keyword (required)."},{"name":"categoryId","in":"query","required":true,"schema":{"type":"string","description":"eBay category id (required here).","title":"Categoryid"},"description":"eBay category id (required here)."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"count","in":"query","required":false,"schema":{"type":"integer","description":"Items to return: 60, 120, or 240.","default":240,"title":"Count"},"description":"Items to return: 60, 120, or 240."},{"name":"ebaySite","in":"query","required":false,"schema":{"type":"string","default":"ebay.com","title":"Ebaysite"}},{"name":"sortOrder","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sortorder"}},{"name":"minPrice","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Minprice"}},{"name":"maxPrice","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Maxprice"}},{"name":"itemCondition","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Itemcondition"}},{"name":"buyingFormat","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buyingformat"}},{"name":"itemLocation","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Itemlocation"}},{"name":"soldAfter","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Soldafter"}},{"name":"soldBefore","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Soldbefore"}},{"name":"sold","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Sold"}},{"name":"relevance","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Relevance"}},{"name":"exactMatch","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Exactmatch"}},{"name":"aspectFilter","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Aspectfilter"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"X-eBay-Cookies","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ebay-Cookies"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/scrape/max":{"post":{"tags":["comps"],"summary":"Create Max Job","description":"POST /v1/scrape/max — SoldComps Max Mode (drop-in). Queues an async job.\n\nHonors an ``Idempotency-Key`` header (same key -> same job, no double work)\nand enforces SoldComps' one-active-job guard per tenant.","operationId":"create_max_job_v1_scrape_max_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaxModeRequest"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/scrape/max/results/{job_id}":{"get":{"tags":["comps"],"summary":"Get Max Results","description":"GET /v1/scrape/max/results/{job_id} — SoldComps Max Mode result fetch.","operationId":"get_max_results_v1_scrape_max_results__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job 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/scrape/max/{job_id}":{"get":{"tags":["comps"],"summary":"Get Max Job","description":"GET /v1/scrape/max/{job_id} — SoldComps Max Mode status poll.","operationId":"get_max_job_v1_scrape_max__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job 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/scrape/max/{job_id}/cancel":{"post":{"tags":["comps"],"summary":"Cancel Max Job","description":"POST /v1/scrape/max/{jobId}/cancel — request cancellation of a live job.","operationId":"cancel_max_job_v1_scrape_max__job_id__cancel_post","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job 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/scrape/max/{job_id}/download.csv":{"get":{"tags":["comps"],"summary":"Download Max Csv","description":"GET /v1/scrape/max/{jobId}/download.csv — SoldComps Max Mode CSV export.","operationId":"download_max_csv_v1_scrape_max__job_id__download_csv_get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job 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/export/{export_id}.csv":{"get":{"tags":["comps"],"summary":"Download Export","description":"GET /v1/export/{exportId}.csv — fetch a stored export artifact (TTL).","operationId":"download_export_v1_export__export_id__csv_get","parameters":[{"name":"export_id","in":"path","required":true,"schema":{"type":"string","title":"Export 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/item/{item_id}":{"get":{"tags":["comps"],"summary":"Get Item","description":"GET /v1/item/{itemId} — SoldComps item detail (drop-in), corpus-backed.\n\nReturns the stored listing for that eBay item id in the same item shape as\n/v1/scrape. Fail-closed 404 when we have never seen the item — we never\ninvent fields.","operationId":"get_item_v1_item__item_id__get","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string","title":"Item 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/tcgplayer/search":{"get":{"tags":["comps"],"summary":"Tcgplayer Search","description":"GET /v1/tcgplayer/search — SoldComps TCGPlayer product search (drop-in).\n\nOne page of TCGPlayer product results with pricing aggregates and the\ncheapest seller listings, normalized to the SoldComps item schema.","operationId":"tcgplayer_search_v1_tcgplayer_search_get","parameters":[{"name":"keyword","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"TCGPlayer search term.","title":"Keyword"},"description":"TCGPlayer search term."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number (1-based).","default":1,"title":"Page"},"description":"Page number (1-based)."},{"name":"count","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Items per page (max 50).","default":24,"title":"Count"},"description":"Items per page (max 50)."},{"name":"sortOrder","in":"query","required":false,"schema":{"type":"string","description":"bestMatch | bestSelling | az | priceHighToLow | priceLowToHigh.","default":"bestMatch","title":"Sortorder"},"description":"bestMatch | bestSelling | az | priceHighToLow | priceLowToHigh."},{"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/tcgplayer/sales":{"get":{"tags":["comps"],"summary":"Tcgplayer Sales","description":"GET /v1/tcgplayer/sales — SoldComps TCGPlayer sales history (drop-in).","operationId":"tcgplayer_sales_v1_tcgplayer_sales_get","parameters":[{"name":"productId","in":"query","required":true,"schema":{"type":"integer","description":"TCGPlayer product id (from search results).","title":"Productid"},"description":"TCGPlayer product id (from search results)."},{"name":"condition","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"nearMint | lightlyPlayed | moderatelyPlayed | heavilyPlayed | damaged.","title":"Condition"},"description":"nearMint | lightlyPlayed | moderatelyPlayed | heavilyPlayed | damaged."},{"name":"variant","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Printing variant (e.g. Holofoil, Normal).","title":"Variant"},"description":"Printing variant (e.g. Holofoil, Normal)."},{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Card language (e.g. English).","title":"Language"},"description":"Card language (e.g. English)."},{"name":"listingType","in":"query","required":false,"schema":{"type":"string","description":"All | ListingWithPhotos | ListingWithoutPhotos.","default":"All","title":"Listingtype"},"description":"All | ListingWithPhotos | ListingWithoutPhotos."},{"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"}}}}}}},"/usage":{"get":{"tags":["compat"],"summary":"Usage Alias","description":"GET /usage — SoldComps root usage endpoint.","operationId":"usage_alias_usage_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 Usage Alias Usage Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/requests":{"get":{"tags":["compat"],"summary":"Request History Alias","description":"GET /requests — SoldComps-compatible request history endpoint.\n\nCursor/date filters are accepted for wire compatibility. The current store\nreturns newest-first history for the authenticated tenant, clamped to 100.","operationId":"request_history_alias_requests_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From"}},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"To"}},{"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 Request History Alias Requests Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/rapidapi/scrape-ebay":{"get":{"tags":["compat"],"summary":"Rapidapi Scrape Ebay","description":"GET /rapidapi/scrape-ebay — RapidAPI-channel alias for /v1/scrape.\n\nAuth precedence:\n  1. Explicit Grail credentials — `Authorization: Bearer <grail_…>`,\n     `X-Grail-API-Key`, or a Grail key placed in `X-RapidAPI-Key` (used for\n     our own tests / proof-of-door).\n  2. RapidAPI marketplace gateway trust — RapidAPI validates the caller's\n     subscription at its edge and then forwards the request to us with its\n     own gateway headers (`X-RapidAPI-Proxy-Secret` / `X-RapidAPI-User`).\n     When `GRAIL_RAPIDAPI_GATEWAY_KEY` is configured and the request carries\n     a gateway header, we authenticate it as the marketplace gateway\n     tenant. `GRAIL_RAPIDAPI_PROXY_SECRET` (when set) additionally pins the\n     exact proxy secret so direct spoofing of the header is rejected.\n\nResponse shape is identical to /v1/scrape, with SoldComps defaults.","operationId":"rapidapi_scrape_ebay_rapidapi_scrape_ebay_get","parameters":[{"name":"keyword","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"title":"Keyword"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"count","in":"query","required":false,"schema":{"type":"integer","default":240,"title":"Count"}},{"name":"ebaySite","in":"query","required":false,"schema":{"type":"string","default":"ebay.com","title":"Ebaysite"}},{"name":"sortOrder","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sortorder"}},{"name":"minPrice","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Minprice"}},{"name":"maxPrice","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Maxprice"}},{"name":"itemCondition","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Itemcondition"}},{"name":"categoryId","in":"query","required":false,"schema":{"type":"string","default":"0","title":"Categoryid"}},{"name":"conditionId","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Conditionid"}},{"name":"buyingFormat","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buyingformat"}},{"name":"sellerType","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sellertype"}},{"name":"itemLocation","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Itemlocation"}},{"name":"soldAfter","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Soldafter"}},{"name":"soldBefore","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Soldbefore"}},{"name":"sold","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Sold"}},{"name":"exactMatch","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Exactmatch"}},{"name":"aspectFilter","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Aspectfilter"}},{"name":"includeCompleteListing","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Includecompletelisting"}},{"name":"hydrateBoa","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Hydrateboa"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"X-RapidAPI-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Rapidapi-Key"}},{"name":"X-Grail-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Grail-Api-Key"}},{"name":"X-eBay-Cookies","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Ebay-Cookies"}},{"name":"X-RapidAPI-User","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Rapidapi-User"}},{"name":"X-RapidAPI-Proxy-Secret","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Rapidapi-Proxy-Secret"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/bulk-search":{"post":{"tags":["compat"],"summary":"Bulk Search Alias","description":"POST /api/bulk-search — SoldComps drop-in alias for /v1/scrape/bulk.","operationId":"bulk_search_alias_api_bulk_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/BulkScrapeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/send-export":{"post":{"tags":["compat"],"summary":"Send Export","description":"POST /send-export — rows/job/keyword -> downloadable CSV URL (SoldComps).","operationId":"send_export_send_export_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/SendExportRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/comps":{"get":{"tags":["comps"],"summary":"Comps","operationId":"comps_api_comps_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"title":"Q"}},{"name":"count","in":"query","required":false,"schema":{"type":"integer","maximum":240,"minimum":1,"default":120,"title":"Count"}},{"name":"condition","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Condition"}},{"name":"exact","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Exact"}},{"name":"relevance","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Relevance"}},{"name":"days","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Days"}},{"name":"minPrice","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Minprice"}},{"name":"maxPrice","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Maxprice"}},{"name":"ebaySite","in":"query","required":false,"schema":{"type":"string","default":"ebay.com","title":"Ebaysite"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"perPage","in":"query","required":false,"schema":{"type":"integer","default":25,"title":"Perpage"}},{"name":"sortOrder","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sortorder"}},{"name":"buyingFormat","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buyingformat"}},{"name":"itemLocation","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Itemlocation"}},{"name":"soldAfter","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Soldafter"}},{"name":"soldBefore","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Soldbefore"}},{"name":"mode","in":"query","required":false,"schema":{"type":"string","default":"clean","title":"Mode"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/ledger/stats":{"get":{"tags":["comps"],"summary":"Ledger Stats","operationId":"ledger_stats_api_ledger_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/shipping-rates":{"get":{"tags":["comps"],"summary":"Shipping Rates Web","description":"Same-origin shipping tool for the dashboard — no API key required.\n\nMirrors ``POST /v1/shipping/rates`` through the same service function so the\nweb tool and the paid API can never drift. Observed rates come from our own\nsold corpus; the estimate is explicitly labelled a heuristic.","operationId":"shipping_rates_web_api_shipping_rates_get","parameters":[{"name":"keyword","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Keyword"}},{"name":"weightOz","in":"query","required":false,"schema":{"anyOf":[{"type":"number","exclusiveMinimum":0},{"type":"null"}],"title":"Weightoz"}},{"name":"marketplace","in":"query","required":false,"schema":{"type":"string","default":"EBAY_US","title":"Marketplace"}},{"name":"sold","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Sold"}},{"name":"destinationCountry","in":"query","required":false,"schema":{"type":"string","default":"US","title":"Destinationcountry"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/research":{"get":{"tags":["research"],"summary":"Api Research","description":"Live card research for one card query (raw + PSA 9 / PSA 10).","operationId":"api_research_api_research_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":200,"title":"Q"}},{"name":"count","in":"query","required":false,"schema":{"type":"integer","maximum":240,"minimum":10,"default":120,"title":"Count"}},{"name":"ebay_site","in":"query","required":false,"schema":{"type":"string","maxLength":24,"default":"ebay.com","title":"Ebay Site"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Api Research Api Research Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/public/scrape":{"get":{"tags":["public"],"summary":"Keyless preview search (funnel)","description":"``GET /public/scrape`` — keyless SoldComps-parity sold search.\n\nReturns the same envelope as ``/v1/scrape`` (items carry the full\nSoldComps field set). Count is capped at 60; full counts are a paid\ncapability. Anonymous rate limit: 30 req/min/IP.","operationId":"public_scrape_public_scrape_get","parameters":[{"name":"keyword","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Search keyword (required).","title":"Keyword"},"description":"Search keyword (required)."},{"name":"count","in":"query","required":false,"schema":{"type":"integer","description":"Items (1-60 for the public funnel).","default":60,"title":"Count"},"description":"Items (1-60 for the public funnel)."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Result page (1-based).","default":1,"title":"Page"},"description":"Result page (1-based)."},{"name":"ebaySite","in":"query","required":false,"schema":{"type":"string","description":"eBay site, e.g. ebay.com, ebay.co.uk.","default":"ebay.com","title":"Ebaysite"},"description":"eBay site, e.g. ebay.com, ebay.co.uk."},{"name":"sold","in":"query","required":false,"schema":{"type":"boolean","description":"true = sold listings, false = active.","default":true,"title":"Sold"},"description":"true = sold listings, false = active."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/public/ebay-categories":{"get":{"tags":["public"],"summary":"eBay category taxonomy (public)","description":"``GET /public/ebay-categories`` — the real eBay category tree (cached).\n\nBacked by eBay's free Taxonomy API; never invented. Serves the flat,\nsearchable category list used by the ``/ebay-categories`` browser page.","operationId":"public_ebay_categories_public_ebay_categories_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Substring search over category names/paths.","title":"Q"},"description":"Substring search over category names/paths."},{"name":"parent","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"List direct children of this category id.","title":"Parent"},"description":"List direct children of this category id."},{"name":"level","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Restrict to a depth (1 = top level).","title":"Level"},"description":"Restrict to a depth (1 = top level)."},{"name":"leaf_only","in":"query","required":false,"schema":{"type":"boolean","description":"Only return leaf (buyable) categories.","default":false,"title":"Leaf Only"},"description":"Only return leaf (buyable) categories."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":2000,"minimum":1,"description":"Max categories returned.","default":200,"title":"Limit"},"description":"Max categories returned."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/public/track":{"post":{"tags":["public"],"summary":"Cookieless first-party pageview beacon","description":"``POST /public/track`` — record an anonymous pageview (funnel measurement).\n\nFire-and-forget: always 204, never blocks or errors the client. Disabled when\nthe public funnel is off. No cookies; IP and user-agent are stored only as\ntruncated SHA-256 hashes.","operationId":"public_track_public_track_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/healthz":{"get":{"summary":"Healthz","operationId":"healthz_healthz_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Healthz Healthz Get"}}}}}}}},"components":{"schemas":{"BatchJobRequest":{"properties":{"queries":{"items":{"type":"string","maxLength":200,"minLength":1},"type":"array","maxItems":100,"minItems":1,"title":"Queries"},"count":{"type":"integer","maximum":240.0,"minimum":1.0,"title":"Count","default":60},"page":{"type":"integer","minimum":1.0,"title":"Page","default":1},"ebaySite":{"type":"string","title":"Ebaysite","default":"ebay.com"},"sold":{"type":"boolean","title":"Sold","default":true},"relevance":{"type":"boolean","title":"Relevance","default":false},"exactMatch":{"type":"boolean","title":"Exactmatch","default":true},"minPrice":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Minprice"},"maxPrice":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Maxprice"},"itemCondition":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Itemcondition"},"sortOrder":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sortorder"},"itemLocation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Itemlocation"},"buyingFormat":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buyingformat"},"soldAfter":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Soldafter"},"soldBefore":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Soldbefore"},"aspectFilter":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Aspectfilter"}},"type":"object","required":["queries"],"title":"BatchJobRequest","description":"POST /v1/scrape/batch — async batch of many keywords (up to 100).\n\nSame filters as a single scrape, applied to every query; the sibling\n`/v1/scrape/bulk` stays synchronous and small (<=25) for interactive use,\nwhile this rides the durable job queue for large/estate-scale batches. Poll\nthe returned job with GET /v1/scrape/batch/{job_id}. Category-agnostic: each\nquery runs the same generic service path as /v1/scrape."},"BulkScrapeRequest":{"properties":{"queries":{"items":{"type":"string","maxLength":200,"minLength":1},"type":"array","maxItems":25,"minItems":1,"title":"Queries"},"count":{"type":"integer","maximum":240.0,"minimum":1.0,"title":"Count","default":120},"ebaySite":{"type":"string","title":"Ebaysite","default":"ebay.com"},"sold":{"type":"boolean","title":"Sold","default":true},"relevance":{"type":"boolean","title":"Relevance","default":false},"exactMatch":{"type":"boolean","title":"Exactmatch","default":true},"minPrice":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Minprice"},"maxPrice":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Maxprice"},"itemCondition":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Itemcondition"},"sortOrder":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sortorder"},"itemLocation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Itemlocation"},"buyingFormat":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buyingformat"},"soldAfter":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Soldafter"},"soldBefore":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Soldbefore"},"aspectFilter":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Aspectfilter"}},"type":"object","required":["queries"],"title":"BulkScrapeRequest","description":"POST /v1/scrape/bulk — many queries in one round trip.\n\nEach query runs through the same cache-first service path as GET /v1/scrape,\nso cached queries return with no live fetch. Capped at 25 queries to keep a\nsingle call bounded; larger batches belong in /v1/scrape/jobs."},"CreateKeyRequest":{"properties":{"name":{"type":"string","maxLength":120,"title":"Name","default":""}},"type":"object","title":"CreateKeyRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"MaxModeRequest":{"properties":{"keyword":{"type":"string","maxLength":200,"minLength":1,"title":"Keyword"},"count":{"type":"integer","title":"Count","description":"Items per page: 60, 120, or 240.","default":240},"maxPages":{"type":"integer","maximum":50.0,"minimum":1.0,"title":"Maxpages","description":"How many pages to walk.","default":1},"page":{"type":"integer","minimum":1.0,"title":"Page","default":1},"ebaySite":{"type":"string","title":"Ebaysite","default":"ebay.com"},"sortOrder":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sortorder"},"minPrice":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Minprice"},"maxPrice":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Maxprice"},"itemCondition":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Itemcondition"},"categoryId":{"type":"string","title":"Categoryid","default":"0"},"buyingFormat":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buyingformat"},"itemLocation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Itemlocation"},"soldAfter":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Soldafter"},"soldBefore":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Soldbefore"},"aspectFilter":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Aspectfilter"},"sold":{"type":"boolean","title":"Sold","default":true},"relevance":{"type":"boolean","title":"Relevance","default":false},"exactMatch":{"type":"boolean","title":"Exactmatch","default":true},"resultType":{"type":"string","title":"Resulttype","description":"How to deliver results: inline | email | download.","default":"inline"}},"type":"object","required":["keyword"],"title":"MaxModeRequest","description":"POST /v1/scrape/max — SoldComps Max Mode (async server-side pagination)."},"ResolveBody":{"properties":{"action":{"type":"string","title":"Action"},"reason":{"type":"string","title":"Reason","default":""},"canonical_card_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Card Id"}},"type":"object","required":["action"],"title":"ResolveBody"},"ScrapeItem":{"properties":{"itemId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Itemid","description":"eBay item id."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"Canonical eBay listing URL."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Listing title."},"thumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnailurl","description":"Search-card thumbnail."},"fullResThumbnailUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fullresthumbnailurl","description":"Full-resolution image, when available."},"epid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Epid","description":"eBay product (catalog) id."},"condition":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Condition","description":"Human-readable condition, e.g. 'Pre-Owned'."},"conditionId":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Conditionid","description":"eBay numeric condition id, e.g. 3000."},"buyingFormat":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buyingformat","description":"auction | buyItNow (null when unknown)."},"bidCount":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Bidcount","description":"Number of bids for auction listings."},"categoryId":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"null"}],"title":"Categoryid","description":"eBay category id, when known."},"listingType":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Listingtype","description":"'sold' or 'active'."},"shippingPrice":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Shippingprice","description":"Decimal string, e.g. '4.99'."},"shippingType":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Shippingtype","description":"'free' | 'paid'."},"totalPrice":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Totalprice","description":"soldPrice + shippingPrice as decimal string."},"sellerUsername":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sellerusername","description":"Seller handle."},"sellerPositivePercent":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sellerpositivepercent","description":"Seller positive feedback percentage."},"sellerFeedbackScore":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sellerfeedbackscore","description":"Seller feedback count."},"itemLocation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Itemlocation","description":"Item location string."},"scrapedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scrapedat","description":"ISO-8601 UTC scrape timestamp."},"endedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Endedat","description":"ISO-8601 sale date (sold listings)."},"soldPrice":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Soldprice","description":"Sold price as decimal string."},"soldCurrency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Soldcurrency","description":"ISO-4217 sold currency."},"bestOfferAccepted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Bestofferaccepted","description":"Best Offer accepted, when detectable."},"sellerType":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sellertype","description":"'private' | 'business' (EU sites only)."},"boaHydrated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Boahydrated","description":"Best-Offer price hydrated from eBay Price Guide."},"boaAcceptedPrice":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Boaacceptedprice","description":"Accepted Best Offer amount, when hydrated."},"boaAcceptedCurrency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Boaacceptedcurrency","description":"ISO-4217 currency of boaAcceptedPrice."},"boaOriginalPrice":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Boaoriginalprice","description":"Pre-hydration listing price on Best Offer sales."},"currentPrice":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currentprice","description":"Asking price on active listings."},"currentPriceMax":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currentpricemax","description":"Upper asking price on active listings."},"currentCurrency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currentcurrency","description":"ISO-4217 currency of currentPrice."},"watcherCount":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Watchercount","description":"Watcher count on active listings."},"unitsSold":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Unitssold","description":"Units sold on active listings."},"acceptsOffers":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Acceptsoffers","description":"Whether an active listing accepts offers."},"timeLeft":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Timeleft","description":"Time remaining on active listings."}},"additionalProperties":true,"type":"object","title":"ScrapeItem","description":"One sold/active listing in the SoldComps item shape.\n\nField types mirror SoldComps' published schema. ``extra=\"allow\"`` keeps any\nadditional keys our pipeline carries (superset guarantee)."},"ScrapeJobRequest":{"properties":{"keyword":{"type":"string","maxLength":200,"minLength":1,"title":"Keyword"},"page":{"type":"integer","minimum":1.0,"title":"Page","default":1},"count":{"type":"integer","maximum":240.0,"minimum":1.0,"title":"Count","default":120},"ebaySite":{"type":"string","title":"Ebaysite","default":"ebay.com"},"sold":{"type":"boolean","title":"Sold","default":true},"relevance":{"type":"boolean","title":"Relevance","default":false},"exactMatch":{"type":"boolean","title":"Exactmatch","default":true},"minPrice":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Minprice"},"maxPrice":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Maxprice"},"itemCondition":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Itemcondition"},"sortOrder":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sortorder"},"itemLocation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Itemlocation"},"buyingFormat":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buyingformat"},"soldAfter":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Soldafter"},"soldBefore":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Soldbefore"},"aspectFilter":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Aspectfilter"}},"type":"object","required":["keyword"],"title":"ScrapeJobRequest"},"ScrapeResponse":{"properties":{"keyword":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Keyword","description":"Echoed search keyword."},"page":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page","description":"Result page."},"totalItems":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Totalitems","description":"Cleaned items returned."},"totalResults":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Totalresults","description":"Raw upstream hit count (string)."},"hasNextPage":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Hasnextpage","description":"Whether more pages exist."},"autoSelectedCategory":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Autoselectedcategory","description":"Reserved for category auto-detection."},"rawMedian":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rawmedian","description":"Median of raw sold prices prior to cleaning."},"rawSampleCount":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rawsamplecount","description":"Sample size behind rawMedian."},"items":{"items":{"$ref":"#/components/schemas/ScrapeItem"},"type":"array","title":"Items","description":"Listing items."},"summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Summary","description":"Aggregate sold-price summary."}},"additionalProperties":true,"type":"object","title":"ScrapeResponse","description":"SoldComps-shaped `/v1/scrape` envelope. ``extra=\"allow\"`` preserves our extras."},"SendExportRequest":{"properties":{"items":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Items"},"jobId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Jobid"},"keyword":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Keyword"},"format":{"type":"string","title":"Format","default":"csv"},"method":{"type":"string","title":"Method","default":"download"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filename"},"count":{"type":"integer","title":"Count","default":240}},"additionalProperties":true,"type":"object","title":"SendExportRequest","description":"POST /send-export — SoldComps export surface.\n\nProvide exactly one of: ``items`` (rows), ``jobId`` (finished Max-Mode job),\nor ``keyword`` (inline scrape). We always return a downloadable CSV URL."},"ShippingRateRequest":{"properties":{"keyword":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Keyword"},"weightOz":{"anyOf":[{"type":"number","exclusiveMinimum":0.0},{"type":"null"}],"title":"Weightoz"},"marketplace":{"type":"string","title":"Marketplace","default":"EBAY_US"},"sold":{"type":"boolean","title":"Sold","default":true},"destinationCountry":{"type":"string","title":"Destinationcountry","default":"US"}},"type":"object","title":"ShippingRateRequest","description":"POST /v1/shipping/rates body — observed (keyword) and/or estimate (weightOz)."},"SignupBody":{"properties":{"email":{"type":"string","maxLength":254,"minLength":3,"title":"Email"},"password":{"type":"string","maxLength":200,"minLength":8,"title":"Password"}},"type":"object","required":["email","password"],"title":"SignupBody"},"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"}}}}