canonical: https://jentic.com/apis/haplotypefrequencycu/haplotypefrequencycu

# Haplotypefrequencycu Haplotype Frequency Curation Service

The Haplotype Frequency Curation Service stores and returns curated haplotype frequency datasets used in HLA typing, transplant matching, and population genetics research. The API exposes 10 endpoints to submit a curation, list submissions, and read back haplotype, cohort, population, label, and scope metadata for any submission ID. A separate `/hfc/population` endpoint returns canonical population definitions used across submissions. The service is read-mostly and does not include transactional patient data.

## For AI agents

Submit, list, and inspect curated haplotype frequency datasets for HLA and population genetics research.

## Scope

Does not handle individual patient genotypes, PHI, or sequence-level data - use for aggregated haplotype frequency curation only.

## Capabilities

- Submit a new haplotype frequency curation via POST /hfc
- List existing haplotype frequency submissions
- Retrieve the haplotype list for a specific submission
- Fetch cohort, population, label, and scope metadata for a submission
- Look up canonical population definitions used across submissions

## Use cases

### HLA Frequency Lookup for Transplant Matching

Pull curated haplotype frequencies for a specific donor population to inform HLA matching probability calculations. The API returns haplotypes, cohort, and population metadata for any submission ID, so research teams can reproduce or adjust matching models. Coverage depends on which submissions are loaded into the curation service.

Example prompt: Fetch haplotypes for submission ID 'sub-eu-2023' via GET `/hfc/sub-eu-2023/haplotypes` and summarise the top 10 frequencies.

### Population Genetics Research Catalogue

Browse all curated submissions through GET /hfc and drill into each via GET `/hfc/{submissionId}` to assemble a research catalogue. Each submission carries cohort, population, label, and scope metadata that researchers use to filter and compare studies. The catalogue is read-only from the API perspective once curations are submitted.

Example prompt: List all submissions via GET /hfc and produce a table of submissionId, cohort size, and population label.

### Submitting a New Haplotype Curation

Researchers contributing haplotype frequencies to the registry POST a structured payload to /hfc with cohort, population, scope, and the haplotype list. The service validates the payload and returns the assigned submission ID, which is then referenced by all downstream read endpoints. The submission step is the only write in the API.

Example prompt: Construct a POST /hfc body with cohort, population, scope, and haplotype list fields and submit it, returning the new submissionId.

### AI Agent Bioinformatics Lookup

Wire a bioinformatics assistant that can answer 'what's the frequency of haplotype X in population Y' by calling `/hfc/{submissionId}/haplotypes` and `/hfc/population` through Jentic. The API has no authentication, so Jentic still mediates discovery and schema loading without any vault step. The agent cannot mutate existing submissions.

Example prompt: When asked 'what populations are in submission sub-2024-01', call GET `/hfc/sub-2024-01/population` and return the population label and size.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/hfc` | List all submissions |
| POST | `/hfc` | Submit a new haplotype frequency curation |
| GET | `/hfc/{submissionId}` | Get a single submission |
| GET | `/hfc/{submissionId}/haplotypes` | Get haplotypes for a submission |
| GET | `/hfc/{submissionId}/cohort` | Get cohort metadata |
| GET | `/hfc/{submissionId}/population` | Get population for a submission |
| GET | `/hfc/population` | List canonical population definitions |

## Key resources

- **Submissions** — Curated haplotype frequency submissions
- **Haplotypes** — Per-submission haplotype lists with frequencies
- **Cohort** — Cohort metadata for a submission
- **Population** — Population definition for a submission and the canonical population catalogue
- **Labels** — Tags applied to a submission for filtering
- **Scope** — HLA loci or genetic region scope for a submission

## Why Jentic

- **Setup:** Wiring the Haplotype Frequency Curation Service by hand still means learning its /hfc submission paths and building each submission, haplotype, cohort, and population request yourself. Through Jentic you install once, import the Haplotype Frequency Curation Service from the API Directory, and your agent calls it, with no key to manage since the API is unauthenticated.
- **Permission scoping:** The Haplotype Frequency Curation Service is mostly submission lookups by id, so scope your agent to the operations it needs, such as listing submissions or reading a submission's haplotypes. You choose what it may call, so creating a submission is not included unless you add it.
- **Credential handling:** The Haplotype Frequency Curation Service has no security schemes, so there is no credential to store; your Jentic One instance mediates the call and returns only the operation result. Nothing secret enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list haplotype frequency submissions', and Jentic returns the GET /hfc operation with its input schema so the agent calls the right endpoint without finding the SwaggerHub specification.

## Related APIs

- **ClinicalTrials.gov** — Pair haplotype frequency lookups with clinical trial cohort discovery.
- **EBI** — Broader bioinformatics datasets (sequences, annotations) to enrich haplotype curations.
- **NCBI Datasets** — Reference genomes and gene metadata for context on haplotype regions.

## FAQ

### What authentication does the Haplotype Frequency Curation Service use?

The OpenAPI spec defines no securitySchemes for this service, so it is open access at the API level. Operators may put it behind a network gateway or API gateway in production; check with the hosting institution before submitting curations. Jentic still mediates schema discovery even when no credentials are needed.

### Can I submit a new haplotype curation via the API?

Yes. POST /hfc accepts a payload describing the cohort, population, scope, labels, and haplotype list, and returns the assigned submissionId. All read endpoints then take that submissionId as a path parameter.

### What are the rate limits for this API?

Rate limits are not specified in the OpenAPI spec. As a research curation service, throughput is expected to be low (a few submissions per day per researcher, occasional read bursts). Operators may apply gateway-level throttling that is not surfaced in the spec.

### How do I retrieve haplotypes for a submission through Jentic?

Search Jentic for 'get haplotypes for a submission', load the schema for GET `/hfc/{submissionId}/haplotypes`, and execute with the submissionId. Run pip install jentic and use the async client.search, client.load, and client.execute pattern.

### Does this API store patient-level genetic data?

No. The service stores curated frequency datasets aggregated across cohorts, plus cohort and population metadata. It does not hold individual patient genotypes or PHI. Use a dedicated EHR or genomics platform for patient-level data.

### Can I limit what my agent is allowed to do with the Haplotype Frequency Curation Service?

Yes. Because you self-host Jentic One, your own rules decide which of this service's operations the agent may call, so you can allow read-only lookups like listing submissions with GET /hfc or reading a submission's haplotypes, cohort, and population while excluding everything else. Creating a submission with POST /hfc is not available to the agent unless you explicitly add it. Since the API is unauthenticated there is no credential to hand over, and your instance still mediates each call so the agent only ever reaches the operations you permit.