HLA-Verify Usage API

openapi: 3.2.0
info:
  title: HLA-Verify Usage 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: Usage
paths:
  /v1/usage:
    get:
      summary: 'The caller''s own usage: calls/units today, 7d and 30d, by endpoint and status…'
      description: 'Scoped strictly to the presented key''s own label (index1 in the Analytics Engine dataset); no cross-key view. Requires an API key: anonymous callers are counted per IP-day for quota purposes, not per caller, so there is nothing to report back to them. Answers are cached 60 seconds per key so a dashboard refresh cannot turn into Analytics Engine SQL API traffic. Not billable against the daily quota.'
      security:
      - ApiKey: []
      responses:
        '200':
          description: usage
          content:
            application/json:
              schema:
                type: object
                properties:
                  release:
                    type: string
                  tier:
                    type: string
                  daily_quota:
                    oneOf:
                    - type: integer
                    - type: string
                      enum:
                      - unlimited
                  max_typings:
                    type: integer
                  usage:
                    type: object
                    properties:
                      today:
                        type: object
                      7d:
                        type: object
                      30d:
                        type: object
        '401':
          description: missing or invalid X-API-Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: usage reporting not configured on this deployment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Usage
      operationId: getV1Usage
      x-operation-id-source: derived
components:
  schemas:
    Error:
      type: object
      properties:
        detail:
          type: string
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key