{"name":"LCFA Trial Finder Public API","version":"v1","base_url":"/api/v1","contact":"trials@lungcancerfoundation.org","auth":{"type":"api_key","description":"All endpoints except /api/v1/docs require an API key. Request one from the LCFA Trial Finder team.","header":"Authorization: Bearer <key>","fallback_header":"X-API-Key: <key>"},"rate_limits":{"description":"Each key has two limits: a DAILY request quota (resets at UTC midnight) and a PER-MINUTE burst limit. Check X-RateLimit-Limit and X-RateLimit-Remaining response headers, or GET /api/v1/meta.","tiers":{"free":"100 requests/day","standard":"1,000 requests/day","partner":"10,000 requests/day"},"burst_per_minute":{"free":10,"standard":60,"partner":300},"responses":{"401":"Missing or invalid key","403":"Key revoked or disabled","429":"Rate limit exceeded — either burst (short Retry-After) or daily (Retry-After = seconds until UTC midnight). Inspect error.code: rate_limit_exceeded vs quota_exceeded."}},"endpoints":[{"method":"GET","path":"/api/v1/trials","description":"Search trials. Supports diagnosis, location, biomarker, mutation, phase, status, age/gender, and ZIP-radius filters. Paginated. Returns a 5-location sample per trial.","query_parameters":{"diagnosisType":"nsclc | sclc | unknown (default: unknown)","cancerStage":"SCLC only: limited | extensive — restricts results to that stage. Inclusive: rows that mention the chosen stage OR have no stage signal at all are included; rows that explicitly mention the opposite stage are excluded.","country":"us | international","state":"Two-letter US state code (e.g. CA)","gender":"male | female","age":"Integer (years)","trialPhase":"Phase I | Phase II | Phase III | Phase IV | Interventional | Observational | All Phases","trialStatus":"Recruiting | Enrolling | Active | Completed | Closed","statusBuckets":"Comma-separated: recruiting,active,completed,unknown (default: recruiting,active,unknown)","biomarkers":"Comma-separated: EGFR, ALK, ROS1, KRAS, BRAF, MET, RET, NTRK, HER2, PD-L1","mutations":"biomarker:mutationId pairs, e.g. EGFR:L858R,KRAS:G12C","firstPostedAfter":"ISO date (YYYY-MM-DD) — only trials first posted on/after this date","zip":"US ZIP code (5 digits) — requires radius","radius":"Miles (max 500) — requires zip","limit":"Integer 1-200 (default 50)","offset":"Integer (default 0)"}},{"method":"GET","path":"/api/v1/trials/:nct_id","description":"Full detail for a single trial, including inclusion/exclusion criteria, outcomes, all locations with lat/lng, and structured biomarker requirements."},{"method":"GET","path":"/api/v1/sources","description":"List of data sources (ClinicalTrials.gov + 19 pharma registries) with approximate trial counts."},{"method":"GET","path":"/api/v1/meta","description":"Returns the calling key's label, tier, and today's quota usage. Does NOT count against the quota — safe to poll."},{"method":"GET","path":"/api/v1/docs","description":"Machine-readable JSON version of this documentation. Unauthenticated."}],"response_envelope":{"success":"{ data: T | T[], meta: { total?, limit?, offset?, quota_used, quota_limit } }","error":"{ error: { code: string, message: string } }"},"fields":{"trial":["nct_id","official_title","brief_summary","phase","status","sponsor","conditions","url","pharma_url","pharma_source_slug","study_type","study_start","first_posted","primary_completion","last_updated","location_count","locations_sample"],"trial_detail_additional":["detailed_description","conditions_arr","intervention","enrollment","age_min","age_max","sexes_eligible","inclusion_criteria","exclusion_criteria","mesh_terms","keywords","study_completion","source","plain_language_summary","primary_outcomes","secondary_outcomes","study_documents","publications","locations","biomarkers"]},"example":{"curl":"curl -H \"Authorization: Bearer lcfa_pk_...\" \"https://lcfa-trial-finder.vercel.app/api/v1/trials?trialStatus=Recruiting&biomarkers=EGFR&mutations=EGFR:L858R&limit=5\""}}