HLA-Verify Verify API

openapi: 3.2.0
info:
  title: HLA Verify 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: Verify
paths:
  /v1/verify:
    post:
      summary: Classify every allele-shaped token in HLA report text or model output
      description: 'Nomenclature checking against the pinned release, not interpretation of a case. Send HLA typing report text or model output about HLA typing with patient identifiers removed first: no names, medical record numbers, dates of birth, accession or case identifiers, or other patient details. The service neither needs nor wants them and does not store request bodies; de-identifying is the caller''s responsibility.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - text
              properties:
                text:
                  type: string
                  maxLength: 200000
                  description: HLA typing report text, or model output about HLA typing, to scan for allele names. Allele names and HLA content only, never patient identifiers.
      responses:
        '200':
          description: verdicts
          content:
            application/json:
              schema:
                type: object
                properties:
                  release:
                    type: string
                  clean:
                    type: boolean
                  counts:
                    type: object
                    additionalProperties:
                      type: integer
                  tokens:
                    type: array
                    items:
                      type: object
                      properties:
                        token:
                          type: string
                        status:
                          type: string
                          enum:
                          - valid
                          - group
                          - deleted
                          - fabricated_group
                          - hallucinated
                          - mac_code
                          - out_of_scope
                        note:
                          type: string
                        successor:
                          type: string
                        current_2field:
                          type: string
                        g_group:
                          type: string
                        flags:
                          type: array
                          items:
                            type: string
                        resolution:
                          type: object
                          description: 'valid tokens with fewer than four fields: {fields, level, distinguishes} — what this resolution does and does not distinguish.'
                  attribution:
                    type: string
        '422':
          description: invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Verify
      operationId: postV1Verify
      x-operation-id-source: derived
components:
  schemas:
    Error:
      type: object
      properties:
        detail:
          type: string
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key