HLA-Verify Releases API

openapi: 3.2.0
info:
  title: HLA-Verify Releases 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: Releases
paths:
  /v1/releases/diff:
    get:
      summary: Allele names added, removed and renamed between two IPD-IMGT/HLA releases
      description: Complete counts, and lists cut at `limit` (default 500, max 5000) with `truncated` set when cut. Removed names carry the deletion reason and successor. Optional locus filter; either direction works. One billable call.
      parameters:
      - name: from
        in: query
        required: true
        schema:
          type: string
          example: 3.40.0
          description: An IPD-IMGT/HLA release this history covers (GET /v1/releases).
      - name: to
        in: query
        required: true
        schema:
          type: string
          example: 3.40.0
          description: An IPD-IMGT/HLA release this history covers (GET /v1/releases).
      - name: locus
        in: query
        required: false
        schema:
          type: string
          example: A
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 5000
          default: 500
      responses:
        '200':
          description: counts and the added, removed and renamed names
        '422':
          description: a missing or unknown release, an unknown locus, or a bad limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Releases
      operationId: getV1ReleasesDiff
      x-operation-id-source: derived
  /v1/releases:
    get:
      summary: The IPD-IMGT/HLA releases the history covers, oldest first
      description: Every release from 1.05.0 to the current one, and the loci in the history, plus a pin object (release, tag, and a note when the pinned tag is a pre-release ahead of the latest official release). Free; not counted against the daily quota.
      responses:
        '200':
          description: releases, latest, count, loci and pin
      tags:
      - Releases
      operationId: getV1Releases
      x-operation-id-source: derived
components:
  schemas:
    Error:
      type: object
      properties:
        detail:
          type: string
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key