HLA-Verify Allele API

openapi: 3.2.0
info:
  title: HLA-Verify Allele API
  version: 1.0.0
  description: 'Deterministic validation of HLA nomenclature and donor-recipient match arithmetic against IPD-IMGT/HLA 3.66.0. No LLM; nothing stored. What to send: allele names, typing strings, GL strings and report text about HLA typing. What never to send: patient identifiers of any kind (names, medical record numbers, dates of birth, accession or case identifiers, other patient details). The service neither needs nor wants them, request bodies are processed in memory and never stored, and de-identifying before sending is the caller''s responsibility. This is a nomenclature and reference-release checker: not a diagnostic aid, not clinical decision support, and it does not recommend a donor. Limits are a daily call quota plus a per-call batch cap, both per tier: free 100 calls/day per IP and 250 typings per /v1/normalize call, free_key 1,000/250 (the instant self-serve key), starter 500/250, lab 10,000/5,000, scale 1,000,000/5,000, enterprise uncapped/5,000, academic 10,000/5,000 (hand-issued to accredited institutions, never sold); ''pro'' is the legacy name for ''lab''. Quotas reset at UTC midnight and every billable response carries x-hla-verify-daily-limit, -daily-remaining, -daily-reset and -max-typings. /healthz, /docs, /openapi.json, /pricing, /v1/checkout, /v1/beta-signup, /v1/research-access, /v1/keys, /v1/report and /v1/usage are not billable. Per-key usage reporting: GET /v1/usage returns the caller''s own calls and units for today/7d/30d, by endpoint and by status, plus the tier''s daily quota; cached 60s per key; 401 without a key. Free for anyone: anonymous access stays open, and anyone can get a free API key instantly (1,000 calls/day, 250 typings per call) at https://hlaverify.com/research or with POST /v1/research-access. Verified labs that need more can have the Lab tier (10,000 calls/day) by request. Nothing is for sale. Enterprise and self-hosting: hello@hlaverify.com.'
  contact:
    email: hello@hlaverify.com
    url: https://hlaverify.com
servers:
- url: https://api.hlaverify.com
- url: https://hlaverify.com
security:
- {}
- ApiKey: []
tags:
- name: Allele
paths:
  /v1/allele/{name}/history:
    get:
      summary: Every name the allele behind this name has had, release by release since 1.05.0
      description: The HLA ID(s) behind a name as written in any IPD-IMGT/HLA release, the current name, the first and last release that used this name, the full timeline of names (oldest first), and the deletion note if the name was retired; as_of adds the name in that release. From Allelelist_history.txt and Deleted_alleles.txt. Billable like /v1/allele.
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
          example: A*0101
      - name: as_of
        in: query
        required: false
        schema:
          type: string
          example: 3.40.0
          description: An IPD-IMGT/HLA release this history covers (GET /v1/releases).
      responses:
        '200':
          description: the allele(s) and their timelines
        '404':
          description: not a name in any release
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: as_of is not a release in the history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Allele
      operationId: getV1AlleleByNameHistory
      x-operation-id-source: derived
  /v1/allele/{name}:
    get:
      summary: Facts for one allele, prefix, group, deleted name, or reported shorthand
      description: 'Accepts what /v1/normalize accepts: current names at 1-4 fields, legacy spellings (A*0101, Cw*0702, Cw*07:02), deleted names, G/P group names, the XX code (A*02:XX), two-field A*02:01g and an optional HLA- prefix. A shorthand answers with the facts of the name it stands for plus ''resolves_to'' and a flag (deprecated_name, xx_code, lg_notation); an NMDP multiple allele code (A*02:AB) returns status mac_code, recognised but not expanded. ''serology'' values are WMDA serological equivalents as published in rel_dna_ser.txt: an antigen number, ''?'' for an undetermined equivalent, or ''∅'' for none (null); the lab routes report these as ''uncertain'' and ''null''. valid_prefix results also carry ''resolution'' ({fields, level, distinguishes}): what a name with fewer than four fields does and does not distinguish, so a lab that typed to that resolution on purpose knows the member count is not telling it the typing is ambiguous. Class I (A/B/C) names carry a trailing ''ligands'' object (leader_21, bw, c_group, kir_ligand; see /v1/typing/check).'
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
        example: A*24:09N
      responses:
        '200':
          description: assigned | valid_prefix | group | deleted | mac_code (+ resolves_to and flags for a shorthand)
        '404':
          description: not in this release
      tags:
      - Allele
      operationId: getV1AlleleByName
      x-operation-id-source: derived
components:
  schemas:
    Error:
      type: object
      properties:
        detail:
          type: string
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key