HLA-Verify Research Access API

openapi: 3.2.0
info:
  title: HLA-Verify Research Access 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: Research Access
paths:
  /v1/research-access:
    post:
      summary: Get a free API key, instantly (or apply for the Lab tier)
      description: 'Issues a free API key (tier free_key: 1,000 calls/day, 250 typings per call, 60 requests/minute) at once, in the response. The key is shown once and never again. One key per email address: asking again returns already_issued with the key''s first 8 characters (key_ref), never the key; a lost key is replaced by emailing hello@hlaverify.com. Disposable-inbox addresses are refused (422). At most 3 new keys per connection per UTC day (429); the connection is counted under a salted daily digest and no IP address is stored. The email address is stored with the key and used for service notices only. Keys can be revoked for abuse. With "tier": "lab" plus institution and use_case, it instead records an application for the Lab tier (10,000 calls/day, 5,000 typings per call) for verified labs: status recorded or already_recorded; the institution is verified and an approved Lab key is emailed. Not billable against the daily quota, but rate limited like every other /v1/ route (60 requests/minute per IP without a key).'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  maxLength: 254
                  example: you@lab.example
                  description: Stored with the key; used for service notices only.
                tier:
                  type: string
                  enum:
                  - lab
                  description: Omit for a free key now. "lab" applies for the Lab tier instead (institution and use_case then required).
                institution:
                  type: string
                  maxLength: 200
                  example: Example University
                  description: Optional for a free key; required with tier lab.
                use_case:
                  type: string
                  maxLength: 1000
                  description: Optional for a free key; required with tier lab. No patient details.
                expected_volume:
                  type: string
                  maxLength: 120
                  example: about 20,000 typings a month
                source:
                  type: string
                  maxLength: 120
                  description: 'Free-text hint: site, mcp, docs.'
      responses:
        '200':
          description: issued (with the key), already_issued, recorded or already_recorded
          content:
            application/json:
              schema:
                type: object
                required:
                - ok
                - status
                - message
                - release
                properties:
                  ok:
                    type: boolean
                  status:
                    type: string
                    enum:
                    - issued
                    - already_issued
                    - recorded
                    - already_recorded
                  key:
                    type: string
                    description: Only when status is issued. Shown once.
                  key_ref:
                    type:
                    - string
                    - 'null'
                  issued:
                    type:
                    - string
                    - 'null'
                  tier:
                    type: string
                  limits:
                    type: object
                  usage:
                    type: object
                  message:
                    type: string
                  release:
                    type: string
        '403':
          description: access for this address was withdrawn
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: invalid or disposable email, a missing required field, or an oversized field
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: rate limited (60 req/min per IP) or 3 new keys from this connection today
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: the key store is not available on this deployment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Research Access
      operationId: postV1ResearchAccess
      x-operation-id-source: derived
components:
  schemas:
    Error:
      type: object
      properties:
        detail:
          type: string
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key