HLA-Verify Pgx API

openapi: 3.2.0
info:
  title: HLA-Verify Pgx 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: Pgx
paths:
  /v1/pgx/table:
    get:
      summary: The hla-pgx-open HLA pharmacogenomics table (CPIC + PharmGKB), JSON or CSV.
      description: CC BY-SA 4.0 (hla-pgx-open). Every pgx response carries pgx_snapshot (UTC date and git commit of the table), the scope sentence and the attribution block. Guideline lookup over published CPIC and PharmGKB associations, keyed by two-field HLA allele. Decision support only; not a medical device. After an allogeneic transplant the recipient's blood carries the donor's genome, and which genome should drive an HLA-mediated drug alert is an open question (NCT06856226); this lookup reports both and decides nothing.
      parameters:
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - json
          - csv
      responses:
        '200':
          description: release, pgx_snapshot, scope, license, attribution, row_count, columns, rows (or text/csv)
        '503':
          description: table not available on this deployment
      tags:
      - Pgx
      operationId: getV1PgxTable
      x-operation-id-source: derived
  /v1/pgx/screen:
    post:
      summary: Which drugs an HLA typing carries a published pharmacogenomic association for…
      description: Exactly one of typing or alleles. Each name is normalized as /v1/normalize does, then joined to the table on its two-field form; summary.actionable is the CPIC level-A, allele-positive subset. Billable like /v1/normalize. Guideline lookup over published CPIC and PharmGKB associations, keyed by two-field HLA allele. Decision support only; not a medical device. After an allogeneic transplant the recipient's blood carries the donor's genome, and which genome should drive an HLA-mediated drug alert is an open question (NCT06856226); this lookup reports both and decides nothing.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                typing:
                  $ref: '#/components/schemas/Typing'
                alleles:
                  type: array
                  maxItems: 96
                  items:
                    type: string
                    maxLength: 64
      responses:
        '200':
          description: release, pgx_snapshot, scope, alleles[] (reported, current_name, allele_2field, flags, associations[]), summary, license, attribution
        '422':
          description: invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: table not available on this deployment
      tags:
      - Pgx
      operationId: postV1PgxScreen
      x-operation-id-source: derived
  /v1/pgx/pair:
    post:
      summary: 'Donor and recipient: which genome carries each actionable HLA-drug association'
      description: Screens both sides as /v1/pgx/screen does and marks every actionable association in_recipient, in_donor, discordant and whose_hla. Billable like /v1/match. Guideline lookup over published CPIC and PharmGKB associations, keyed by two-field HLA allele. Decision support only; not a medical device. After an allogeneic transplant the recipient's blood carries the donor's genome, and which genome should drive an HLA-mediated drug alert is an open question (NCT06856226); this lookup reports both and decides nothing.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - recipient
              - donor
              properties:
                recipient:
                  $ref: '#/components/schemas/PgxInput'
                donor:
                  $ref: '#/components/schemas/PgxInput'
      responses:
        '200':
          description: release, pgx_snapshot, scope, recipient, donor, actionable[], summary, license, attribution
        '422':
          description: invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: table not available on this deployment
      tags:
      - Pgx
      operationId: postV1PgxPair
      x-operation-id-source: derived
components:
  schemas:
    PgxInput:
      type: object
      description: 'One side of a pgx lookup: exactly one of typing (a Typing object) or alleles (a flat list of reported names). Allele strings only, never patient identifiers.'
      properties:
        typing:
          $ref: '#/components/schemas/Typing'
        alleles:
          type: array
          maxItems: 96
          items:
            type: string
            maxLength: 64
      example:
        alleles:
        - B*57:01
        - A*31:01
    Error:
      type: object
      properties:
        detail:
          type: string
    Typing:
      type: object
      description: 'locus -> up to 4 reported allele names. Allele strings only: never patient names, medical record numbers, dates of birth, or accession or case identifiers.'
      additionalProperties:
        type: array
        items:
          type: string
        maxItems: 4
      example:
        A:
        - A*02:01
        - A*24:02
        B:
        - B*07:02
        - B*44:02
        C:
        - C*07:02
        - C*05:01
        DRB1:
        - DRB1*15:01
        - DRB1*04:01
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key