API Reference

The genoCDS REST API provides structured access to oncology genomic testing recommendations, evidence sources, and payer coverage data for integration into EMR systems and clinical workflows.

Request API Access →View Disease Browser

Authentication

All API endpoints require an API key passed in the X-Api-Key request header. Keys are prefixed with gcds_ and are issued per-organization after approval.

curl https://genocds.locusoncology.com/api/v1/tests \
-H "X-Api-Key: gcds_your_key_here"

Invalid or missing keys return 401 Unauthorized with {"error":"...","code":"UNAUTHORIZED"}.

Response Format

All list endpoints return a FHIR-aligned Bundle envelope. Individual resources use a resourceType discriminator for easy EMR integration.

{ "resourceType": "Bundle", "type": "collection", "total": 14, "entry": [ { "resource": { "resourceType": "GenomicTest", "id": "...", ... } } ] }

Error responses: {"error":"message","code":"ERROR_CODE"} with appropriate HTTP status.

Base URL

https://genocds.locusoncology.com/api/v1

Endpoints

GET

/api/v1/diseases

List all published disease groups (NSCLC, Breast, Colorectal, Lymphomas, etc.)

No query parameters. Returns all published disease groups with ICD-10 and SNOMED codes.

GET

/api/v1/tests

Genomic test catalog with LOINC codes, specimen types, gene targets, and FDA companion Dx status.

Query Parameters

`panel_type`	string	Filter by panel type: single_gene, hotspot_panel, comprehensive_panel, IHC, FISH, cytogenetics, karyotype, flow_cytometry, PCR, NGS, methylation, other
`fda_companion_dx_status`	string	Filter by FDA companion diagnostic status: approved, cleared, none

GET /api/v1/tests?panel_type=NGS&fda_companion_dx_status=approved { "resourceType": "Bundle", "total": 1, "entry": [{ "resource": { "resourceType": "GenomicTest", "id": "...", "slug": "ngs-comprehensive", "name": "Comprehensive Genomic Profiling (NGS)", "coding": { "loinc": "94076-7", "snomed": null }, "panelType": "NGS", "genesTargeted": ["EGFR", "ALK", "ROS1", "BRAF", ...], "specimenTypes": [ { "type": "FFPE tissue", "minTumorContent": "20%" } ], "fdaCompanionDx": { "status": "approved", "url": "https://..." } } }] }

GET

/api/v1/indications

Clinical indications — the context (diagnosis, monitoring, reflex) in which testing occurs, linked to disease subtype and staging category.

Query Parameters

`group`	string	Disease group slug (e.g. nsclc). Required when subtype is provided.
`subtype`	string	Disease subtype slug (e.g. adenocarcinoma). Requires group.
`stage`	string	Staging category URL slug (e.g. iva, iiib-iiic, ecog-0-1).
`context`	string	Testing context: pre_staging, at_diagnosis, post_staging, monitoring, reflex, any

GET

/api/v1/recommendations

Test recommendations with full evidence grading (OncoKB tiers, NCCN categories), source citations, and reflex testing paths.

Query Parameters

`group`	string	Disease group slug. Narrows results to a disease.
`subtype`	string	Disease subtype slug. Requires group.
`stage`	string	Staging category URL slug (e.g. iva).
`indication_id`	uuid	Return recommendations for a single clinical indication.
`priority`	string	Filter by priority: required, recommended, optional, conditional

GET /api/v1/recommendations?group=nsclc&subtype=adenocarcinoma&stage=iva&priority=required { "entry": [{ "resource": { "resourceType": "TestRecommendation", "id": "...", "priority": "required", "test": { "name": "Comprehensive Genomic Profiling (NGS)", ... }, "evidence": [{ "oncokbTier": "1", "nccnCategory": "1", "source": { "sourceType": "NCCN", "guidelineVersion": "NCCN NSCLC v3.2024", "url": "https://nccn.org/..." } }], "reflexPaths": [{ "triggerResult": "EGFR exon 19 deletion or L858R detected", "toTest": { "name": "EGFR Mutation Analysis", ... } }] } }] }

GET

/api/v1/payer-coverage

Payer coverage policies for genomic tests across CMS (Medicare) and major commercial insurers. Includes policy numbers and source URLs.

Query Parameters

`test_id`	uuid	Filter by specific genomic test ID.
`payer`	string	Filter by payer: CMS, UHC, ANTHEM_BCBS, HUMANA, CIGNA, AETNA
`subtype_id`	uuid	Return policies for a specific subtype plus global (non-indication-specific) policies.
`coverage_status`	string	Filter by status: covered, not_covered, prior_auth_required, investigational, varies_by_indication, unknown

POST

/api/v1/access/request

Submit an API access request. Does not require an API key.

Request Body (JSON)

`organizationName`*	string	Name of the requesting organization or health system.
`contactEmail`*	email	Primary contact email for the API key.
`contactName`*	string	Full name of the API requester.
`intendedUse`*	string	Description of the intended integration use case.
`accessType`	string	health_system (default) or commercial

Rate Limits & Usage

Current limits for standard API keys:

1,000 requests / hour per API key
No per-endpoint sublimits
Rate limit headers: X-RateLimit-Remaining, X-RateLimit-Reset (coming in Phase 2)

Commercial licensees may request higher limits. Contact Locus Oncology for details.

Data Accuracy Disclaimer

Recommendations returned by this API are derived from published guidelines and regulatory sources and may contain errors or lag behind current evidence. They do not constitute clinical advice and must not be used as a substitute for professional clinical judgment. Full disclaimer →