Genomic Intelligence Health API

openapi: 3.2.0
info:
  title: Genomic Intelligence Health API
  description: 'REST API for DNA sequence analysis with transformer language models. Six tasks — promoter, splice, enhancer, chromatin, annotation, expression — each with its own `POST /v1/tasks/{task}/predict` operation, plus one composite workflow under `/v1/workflows/`.


    **This document is the contract.** It is self-contained: request bounds, closed `options` objects, error codes, response headers and both async body shapes are all declared here, so a generated client needs nothing else.


    **Auth.** Every `/v1/*` route requires `Authorization: Bearer gi_…`, with two exceptions. `/health`, `/docs`, `/redoc` and `/v1/openapi.json` are public, and so is capability discovery: `GET /v1/tasks/{task}/models` needs no key, so you can read every model''s `bio_spec` — organism, window geometry, output formats, `request_max_bp` — before you have one. It is rate-limited per source IP rather than per partner.


    **Envelopes.** Success is `{data, meta}`; `data` is a union discriminated on `task`. Errors are `{error: {code, message, request_id, details?}}`, with `error.code` drawn from a published enum.


    **Sequence length.** Each task''s request schema publishes `minLength`/`maxLength` on `sequence`, measured after whitespace is stripped. One bound per task, applying to every model of that task: promoter 300 bp, splice 100 bp, enhancer 50 bp, chromatin 200 bp, annotation 1,000 bp, expression 9,198 bp (with the TSS at least 4,599 bp from each end) — all capped at 500,000 bp. Out-of-range requests are rejected with `422 validation_failed` before any model is loaded. These are the bounds this document previously advertised as 1-500,000 bp for all six.


    A floor is admission control, not a claim about regime. Where a model slides a window (promoter, splice, enhancer, chromatin), a request above the floor but shorter than that model''s `bio_spec.context_window_bp` is accepted and scored against a padded window. Compare your length against that field to know whether the model saw real sequence or padding. Expression models read around the TSS instead: fetch each model''s `bio_spec.recommended_flank_bp` on each side of it.


    **Body size.** Requests are also capped at 16 MiB of raw body, enforced before parsing; over that is `413 payload_too_large` regardless of sequence length.


    **Async.** Send `Prefer: respond-async` for a `202` with a `job_id`, then poll `GET /v1/tasks/jobs/{job_id}`. Two operations *require* it above a size threshold: the composite workflow above 50,000 bp and `POST /v1/tasks/annotation/predict` above 200,000 bp, both of which return `413 sync_too_large` to a synchronous JSON request over their threshold. Each threshold is published as `x-sync-limit-bp` on its own operation — read it from there rather than from this sentence, and take the absence of that extension on the other five predict operations as the statement that they have no sync cap. Async is JSON-only, so the cap governs JSON delivery: a BED/GFF3 response above the threshold is still served synchronously and can run long enough to hit a gateway timeout.


    **Rate limits.** Every response carries `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` and `RateLimit-Policy`; a `429` adds `Retry-After`. `RateLimit-Limit` is a *burst* capacity — one tenth of a minute''s allowance (rpm / 6, published at the document root as `x-rate-limit-burst-divisor`), refilling continuously — so your sustained ceiling is 6 times it per minute. Pacing off the header alone budgets 6x low.'
  contact:
    name: Genomic Intelligence Support
    url: https://docs.genomicintelligence.ai/
    email: contact@genomicintelligence.ai
  version: 2026.10.19.2 (afabae26)
servers:
- url: https://api.genomicintelligence.ai
  description: Production
security:
- BearerAuth: []
tags:
- name: Health
  description: Liveness probe and service banner. Public.
paths:
  /health:
    get:
      tags:
      - Health
      summary: Health Check
      description: Liveness probe. Public; no auth required.
      operationId: health_check_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
      security: []
components:
  schemas:
    HealthResponse:
      properties:
        status:
          type: string
          enum:
          - healthy
          - degraded
          title: Status
          description: '`healthy` when the service is ready to accept inference; `degraded` only when configured for CUDA but the GPU is unreachable.'
          examples:
          - healthy
        version:
          type: string
          title: Version
          description: Build identifier in `YYYY.MM.DD.iteration (commit_hash)` form. Quote this in any bug report so we can pin the exact code.
          examples:
          - 2026.05.02.1 (abc1234)
      type: object
      required:
      - status
      - version
      title: HealthResponse
      description: 'Public health check response — liveness only.


        Minimum-disclosure: no GPU model, no loaded-model state, no driver

        string. For the full operator payload, call ``/health/detailed``.'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: gi_…
      description: Partner API key. Issued out of band; see https://docs.genomicintelligence.ai/rest-api.md#2-get-a-key.
x-contract-revision: 19
x-rate-limit-burst-divisor: 6