{"components":{"schemas":{"Matter":{"properties":{"attached_cases_count":{"nullable":true,"type":"integer"},"category":{"enum":["mass_tort","class_action","recall","regulatory","settlement"],"type":"string"},"eligibility_hint":{"nullable":true,"type":"string"},"headline":{"nullable":true,"type":"string"},"keywords":{"properties":{"brands":{"items":{"type":"string"},"type":"array"},"products":{"items":{"type":"string"},"type":"array"}},"type":"object"},"lifecycle":{"properties":{"claims_close_iso":{"nullable":true,"type":"string"},"claims_open_iso":{"nullable":true,"type":"string"},"first_seen_iso":{"type":"string"},"last_signal_iso":{"type":"string"},"mdl_filed_iso":{"nullable":true,"type":"string"},"narrative_generated_iso":{"nullable":true,"type":"string"},"settlement_announced_iso":{"nullable":true,"type":"string"}},"type":"object"},"links":{"properties":{"html":{"format":"uri","type":"string"},"primary":{"format":"uri","nullable":true,"type":"string"},"self":{"format":"uri","type":"string"}},"type":"object"},"matter_id":{"example":"mat_19e2a1f4f486e9","type":"string"},"name":{"type":"string"},"payout":{"properties":{"band":{"enum":["micro","small","medium","large","mass_tort"],"nullable":true,"type":"string"},"high_cents":{"nullable":true,"type":"integer"},"high_usd":{"nullable":true,"type":"integer"},"low_cents":{"nullable":true,"type":"integer"},"low_usd":{"nullable":true,"type":"integer"}},"type":"object"},"schema_version":{"example":1,"type":"integer"},"score":{"maximum":1,"minimum":0,"type":"number"},"score_30d":{"nullable":true,"type":"number"},"slug":{"example":"camp-lejeune","type":"string"},"status":{"enum":["rumored","emerging","litigated","settled","claims_open","closed"],"type":"string"},"subcategory":{"nullable":true,"type":"string"},"summary":{"nullable":true,"type":"string"},"velocity":{"nullable":true,"type":"number"}},"required":["matter_id","slug","name","category","status","score"],"type":"object"},"PushRegisterBody":{"properties":{"bundle_id":{"example":"com.commodifiedimage.claimscout","type":"string"},"device_token":{"description":"raw hex APNs token from iOS","type":"string"},"identity_id":{"description":"web_identities.identity_id; links this device to a SSO-authenticated user","nullable":true,"type":"string"},"install_id":{"description":"iOS-side install UUID for analytics","nullable":true,"type":"string"},"platform":{"default":"ios","enum":["ios","android"],"type":"string"},"push_environment":{"default":"production","enum":["production","sandbox"],"type":"string"}},"required":["device_token","bundle_id"],"type":"object"},"Signal":{"properties":{"first_seen_iso":{"type":"string"},"kind":{"example":"mdl_filing","type":"string"},"matter_id":{"description":"null until the entity resolver attaches the signal to a matter","nullable":true,"type":"string"},"provenance":{"additionalProperties":true,"description":"Source citation: {source_url, retrieved_at, author, confidence}","type":"object"},"resolution_confidence":{"nullable":true,"type":"number"},"resolved_by":{"description":"How the signal was linked to its matter. 'auto' = title+summary independently match matter keywords (containment >= 0.45). 'llm' = mid-confidence tie-break via Claude Haiku. 'search_context' = signal came from a per-matter targeted query against a high-precision source (regulations.gov, FDA FAERS/MAUDE/CAERS); attached at lower confidence (0.30) because the matter was known from query context, not derived from text. 'human' = manual override. 'pending' = not yet resolved.","enum":["auto","llm","search_context","human","pending"],"nullable":true,"type":"string"},"score":{"type":"number"},"signal_id":{"type":"string"},"source":{"example":"courtlistener_mdl","type":"string"},"source_id":{"type":"string"},"summary":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"},"url":{"format":"uri","nullable":true,"type":"string"}},"required":["signal_id","source","kind"],"type":"object"},"WatchCreateBody":{"properties":{"agent_origin":{"default":"web","type":"string"},"idempotency_key":{"nullable":true,"type":"string"},"matter_id":{"type":"string"},"notify_email":{"default":true,"type":"boolean"},"notify_push":{"default":true,"type":"boolean"},"source":{"default":"manual","enum":["audit_tick","manual","auto_lookalike","agent_subscribe"],"type":"string"},"user_id":{"description":"web_identities.identity_id or iOS apple_sub","type":"string"}},"required":["user_id","matter_id"],"type":"object"},"WatchUpdateBody":{"description":"Toggle per-watch notification channels. At least one of notify_email / notify_push must be present.","properties":{"notify_email":{"type":"boolean"},"notify_push":{"type":"boolean"}},"type":"object"}}},"info":{"contact":{"email":"ops@getclaimscout.com"},"description":"Read-only, no-auth-required API for the claimscout matters data layer. Each `matter` is one tort or class-action issue (Camp Lejeune water contamination, Philips CPAP recall, hair relaxer uterine cancer MDL, etc.) with a structured narrative card, eligibility hint, payout band, and lifecycle status. Each `signal` is an event updating a matter (court filing, FDA recall, news article, social-media cluster).\n\nDesigned for AI agents. Use `/api/v1/matters` to enumerate the universe, then `/api/v1/matters/{slug}` to get full detail including attached claims-administrator cases (when claims are open) and recent signals.\n\nAll responses include an ETag for conditional GETs and stable JSON envelopes (`{data, pagination, meta}` for lists, `{data, meta}` for items, `{error, meta}` for errors).\n\nWrites (lead submission, watch subscription) require an API key \u2014 see /v1/openapi.json for the authed partner API.\n\nCompanion file: GET /llms.txt for a token-cheap agent quickstart.","license":{"name":"Proprietary \u2014 public read access permitted"},"title":"claimscout matters API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/api/v1/health":{"get":{"responses":{"200":{"content":{"application/json":{}},"description":"ok"}},"summary":"Liveness + record counts.","tags":["system"]}},"/api/v1/matters":{"get":{"parameters":[{"in":"query","name":"category","schema":{"enum":["mass_tort","class_action","recall","regulatory","settlement"],"type":"string"}},{"in":"query","name":"status","schema":{"enum":["rumored","emerging","litigated","settled","claims_open","closed"],"type":"string"}},{"in":"query","name":"min_score","schema":{"type":"number"}},{"in":"query","name":"limit","schema":{"default":30,"maximum":100,"type":"integer"}},{"in":"query","name":"order_by","schema":{"default":"score","enum":["score","velocity","last_signal_iso","name"],"type":"string"}}],"responses":{"200":{"description":"list of matters"}},"summary":"List matters ordered by score (or velocity, last_signal_iso, name).","tags":["matters"]}},"/api/v1/matters/{slug}":{"get":{"parameters":[{"description":"e.g. 'camp-lejeune', 'philips-cpap'","in":"path","name":"slug","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"matter detail"},"404":{"description":"no matter with that slug"}},"summary":"Get one matter (full card + attached cases + recent signals).","tags":["matters"]}},"/api/v1/push/register":{"post":{"description":"Called by the iOS app on launch + after the user signs in via SSO. Idempotent on device_token. Linking via identity_id is optional but lets the nightly dispatcher fan one notification out to every device owned by a signed-in user.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushRegisterBody"}}},"required":true},"responses":{"200":{"description":"device token refreshed (already known)"},"201":{"description":"device token newly registered"},"400":{"description":"bad request"}},"summary":"Register an APNs device token (iOS push notifications).","tags":["watches"]}},"/api/v1/push/register/{device_token}":{"delete":{"parameters":[{"in":"path","name":"device_token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"token deleted (or not found - idempotent)"}},"summary":"Unregister an APNs device token (called on sign-out / app delete).","tags":["watches"]}},"/api/v1/signals":{"get":{"parameters":[{"in":"query","name":"matter_id","schema":{"type":"string"}},{"in":"query","name":"source","schema":{"type":"string"}},{"in":"query","name":"unresolved","schema":{"type":"boolean"}},{"in":"query","name":"limit","schema":{"default":30,"maximum":100,"type":"integer"}}],"responses":{"200":{"description":"list of signals"}},"summary":"Recent signals across all matters (or filtered).","tags":["signals"]}},"/api/v1/watches":{"get":{"parameters":[{"in":"query","name":"user_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"list of watches"}},"summary":"List a user's watches (matter info hydrated inline).","tags":["watches"]},"post":{"description":"Idempotent on (user_id, matter_id). Pass an idempotency_key in the body if you're an automated client that may retry. The nightly dispatcher reads matter_watches + device_tokens to fire APNs pushes when the matter has notification-worthy events (claims_open, velocity spike, status change).","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchCreateBody"}}},"required":true},"responses":{"200":{"description":"watch updated (was already present)"},"201":{"description":"watch created"},"404":{"description":"matter not found"}},"summary":"Subscribe a user to a matter (watchlist).","tags":["watches"]}},"/api/v1/watches/{watch_id}":{"delete":{"parameters":[{"in":"path","name":"watch_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"watch deleted (or not found - idempotent)"}},"summary":"Unsubscribe (delete a watch).","tags":["watches"]},"put":{"parameters":[{"in":"path","name":"watch_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchUpdateBody"}}},"required":true},"responses":{"200":{"description":"watch updated"}},"summary":"Toggle notify_email / notify_push on a watch.","tags":["watches"]}}},"servers":[{"description":"production","url":"https://getclaimscout.com"},{"description":"Fly direct","url":"https://claimscout.fly.dev"}],"tags":[{"description":"Upstream tort/class-action entities","name":"matters"},{"description":"Events updating a matter's score","name":"signals"},{"description":"Health + introspection","name":"system"}]}