HLA-Verify Checkout API

openapi: 3.2.0
info:
  title: HLA-Verify Checkout 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: Checkout
paths:
  /v1/checkout:
    post:
      summary: Start a Stripe Checkout Session for a paid tier
      description: Not in use while keys are free; a free key is issued instantly at https://hlaverify.com/research. Creates a subscription-mode Stripe Checkout Session for the named tier at its current Stripe price and returns the hosted url to send the buyer to. metadata.tier is set on the session from the price's own tier metadata, which is what the webhook reads to issue the key. Promotion codes are accepted on Stripe's page; pass promotion_code to pre-apply one. Not billable against the daily quota, but rate limited like every other /v1/ route (60 requests/minute per IP without a key). 503 when self-serve checkout is not configured on the deployment or the tier has no live price — email hello@hlaverify.com in that case.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tier:
                  type: string
                  enum:
                  - starter
                  - lab
                  - scale
                  description: Which plan to buy.
                price:
                  type: string
                  description: A specific active Stripe price id, instead of (or as a cross-check on) tier.
                promotion_code:
                  type: string
                  maxLength: 64
                  description: A customer-facing promotion code to pre-apply, for example a launch discount.
      responses:
        '200':
          description: checkout session created
          content:
            application/json:
              schema:
                type: object
                required:
                - url
                - tier
                properties:
                  url:
                    type: string
                    description: Hosted Stripe Checkout url; send the buyer here.
                  session_id:
                    type: string
                  tier:
                    type: string
                  price:
                    type: string
                  amount:
                    type: integer
                    description: Unit amount in the currency's minor unit, as Stripe holds it.
                  currency:
                    type: string
                  interval:
                    type: string
                  promotion_code_applied:
                    type: boolean
        '422':
          description: unknown or missing tier, or a price that is not an active plan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: rate limited (60 req/min per IP; /v1/checkout does not consume daily quota)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Stripe rejected the session or was unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: self-serve checkout is not configured, or that tier is not on sale
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Checkout
      operationId: postV1Checkout
      x-operation-id-source: derived
components:
  schemas:
    Error:
      type: object
      properties:
        detail:
          type: string
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key