API referencehttps://staging.api.genome.computerhttps://api.genome.computer

Endpoint reference.

Methods, paths, request fields, and response shapes for the genome.computer API. Endpoints are shared by staging and production unless marked as staging-only.

Authentication

Send the API key in the Authorization header. Staging keys start with gc_test_. Production keys start with gc_live_.

Header

HTTP header
Authorization: Bearer $GC_API_KEY

OpenAPI

The API also exposes machine-readable OpenAPI JSON and Swagger UI for internal testing.

Endpoints

The table below is the daily working reference for partner engineers.

Orders

GET/v1/gvcf/jobs/{jobId}

Read FASTQ to gVCF job status.

ParameterInTypeRequiredDescription
jobIdpathstringYesPublic gVCF job id (gvj_...).

Response status codes: 200, 404.

GET/v1/orders

List recent orders.

Scope: orders:read

ParameterInTypeRequiredDescription
statusquerystringNoFilter by order status. Allowed: created, payment_pending, paid, kit_preparing, kit_shipped, kit_delivered, sample_registered, sample_returned, sample_received, lab_processing, sequencing, bioinformatics_processing, genome_bundle_generating, completed, failed, cancelled.
limitqueryintegerNoMaximum orders to return. Default: 50.

Response status codes: 200.

POST/v1/orders

Create a sequencing or genotyping order.

Scope: orders:write

Creates a 3x/30x whole-genome sequencing or GSA genotyping order and returns activation details. Send an Idempotency-Key header (required in production) so retries are safe.

ParameterInTypeRequiredDescription
idempotency-keyheaderstringNoIdempotency key. Required in production; retries with the same key+body are deduplicated.
typebodystringYesSequencing/genotyping product type. Allowed: wgs_3x, wgs_30x, gsa.
client_namebodystringNoLabel for the end customer shown on internal dashboards.
user_referencebodystringNoYour own identifier for this order; echoed back on reads and webhooks.
retentionbodystringNoHow long sequencing artifacts are retained. Allowed: delete_after_30_days, hosted_runtime. Default: "delete_after_30_days".
deliverablesbodystring[]NoWhich artifacts to deliver for the order.
customerbodyobjectNoFields: name, email, phone.
shipping_addressbodyobjectNoFields: line1, line2, city, state, region, postal_code, postalCode, country, country_code, countryCode.
shippingbodyobjectNoFree-form shipping metadata merged into the shipping payload.

Response status codes: 200, 201, 400.

GET/v1/orders/{orderId}

Read order status and activation details.

Scope: orders:read

ParameterInTypeRequiredDescription
orderIdpathstringYesPublic order id (ord_...).

Response status codes: 200, 404.

GET/v1/orders/{orderId}/events

Read order lifecycle events.

Scope: orders:read

ParameterInTypeRequiredDescription
orderIdpathstringYesPublic order id (ord_...).

Response status codes: 200, 404.

GET/v1/orders/{orderId}/files

Return signed links for completed deliverables.

Scope: orders:read

ParameterInTypeRequiredDescription
orderIdpathstringYesPublic order id (ord_...).

Response status codes: 200, 400, 404.

POST/v1/orders/{orderId}/gvcf

Queue FASTQ to gVCF generation for a WGS order.

ParameterInTypeRequiredDescription
orderIdpathstringYesPublic order id (ord_...).
sample_idbodystringNo
reference_uribodystringNo
fastq_r1bodyobjectNoFields: bucket, path.
fastq_r2bodyobjectNoFields: bucket, path.
output_bucketbodystringNo
output_pathbodystringNo

Response status codes: 202, 400, 404.

GET/v1/orders/{orderId}/shipment

Read shipment carrier and tracking data.

Scope: orders:read

Returns the active shipment from the current fulfillment attempt, including carrier scan history. Use /shipments to read every attempt and shipment.

ParameterInTypeRequiredDescription
orderIdpathstringYesPublic order id (ord_...).

Response status codes: 200, 404.

GET/v1/orders/{orderId}/shipments

Read every shipment and its carrier tracking history.

Scope: orders:read

Returns shipments grouped by fulfillment attempt. The current attempt can be empty while a replacement shipment is being prepared.

ParameterInTypeRequiredDescription
orderIdpathstringYesPublic order id (ord_...).

Response status codes: 200, 404.

Uploads

POST/v1/uploads/gvcf

Upload an existing VCF/gVCF directly (multipart).

Scope: uploads:write

multipart/form-data with a single file field. Best for files within the multipart size limit; use the signed upload flow for larger files.

No request parameters.

Response status codes: 201, 400.

POST/v1/uploads/gvcf/complete

Finalize a signed VCF/gVCF upload after the file is sent to storage.

Scope: uploads:write

ParameterInTypeRequiredDescription
upload_idbodystringYesPublic upload id returned by initiate.
sha256bodystringYesHex SHA-256 of the uploaded file.
size_bytesbodyintegerYesActual uploaded size in bytes.

Response status codes: 200, 400, 404, 409.

POST/v1/uploads/gvcf/initiate

Begin a signed (resumable) VCF/gVCF upload for large files.

Scope: uploads:write

ParameterInTypeRequiredDescription
filenamebodystringYesOriginal VCF/gVCF filename (.hard-filtered.gvcf.gz, .vcf.gz, .g.vcf.gz, .gvcf.gz).
content_typebodystringNoMIME type of the upload.
size_bytesbodyintegerNoExpected file size in bytes.

Response status codes: 201, 400.

Conversions

POST/v1/conversions

Convert an uploaded VCF/gVCF into a .genome bundle.

Scope: conversions:write

Staging completes synchronously and returns 201; production enqueues the job and returns 202.

ParameterInTypeRequiredDescription
source_typebodystringYesLegacy API source-type identifier for supported VCF/gVCF uploads. Allowed: gvcf.
upload_idbodystringYesPublic id of a completed upload.
retentionbodystringNoRetention policy for the resulting genome. Allowed: delete_after_30_days, hosted_runtime. Default: "hosted_runtime".

Response status codes: 201, 202, 400, 404.

Genomes

GET/v1/genomes

List hosted genomes.

Scope: genomes:read

ParameterInTypeRequiredDescription
limitqueryintegerNoMaximum genomes to return. Default: 50.

Response status codes: 200.

GET/v1/genomes/{genomeId}

Read hosted genome runtime metadata.

Scope: genomes:read

ParameterInTypeRequiredDescription
genomeIdpathstringYesPublic genome id (gen_...).

Response status codes: 200, 404.

GET/v1/genomes/{genomeId}/bundle

Download a signed .genome bundle link.

Scope: genomes:read

ParameterInTypeRequiredDescription
genomeIdpathstringYesPublic genome id (gen_...).

Response status codes: 200, 404.

GET/v1/genomes/{genomeId}/files

Return signed links for a hosted genome's files.

Scope: genomes:read

ParameterInTypeRequiredDescription
genomeIdpathstringYesPublic genome id (gen_...).

Response status codes: 200, 404.

GET/v1/genomes/{genomeId}/manifest

Read the genome bundle manifest.

Scope: genomes:read

ParameterInTypeRequiredDescription
genomeIdpathstringYesPublic genome id (gen_...).

Response status codes: 200, 404.

PATCH/v1/genomes/{genomeId}/retention

Change whether the genome is hosted or deleted.

Scope: genomes:write

ParameterInTypeRequiredDescription
genomeIdpathstringYesPublic genome id (gen_...).
retentionbodystringYesNew retention policy. Allowed: delete_after_30_days, hosted_runtime.

Response status codes: 200, 400, 404.

Interpretations

GET/v1/genomes/{genomeId}/diffs/{range}

Compare two interpretation versions.

Scope: genomes:read

ParameterInTypeRequiredDescription
genomeIdpathstringYesPublic genome id (gen_...).
rangepathstringYesVersion range as {from}..{to}.

Response status codes: 200.

GET/v1/genomes/{genomeId}/interpretations/{version}

Read a specific interpretation version.

Scope: genomes:read

ParameterInTypeRequiredDescription
genomeIdpathstringYesPublic genome id (gen_...).
versionpathstringYesInterpretation version string.

Response status codes: 200, 404.

GET/v1/genomes/{genomeId}/interpretations/latest

Read the latest interpretation for a genome.

Scope: genomes:read

ParameterInTypeRequiredDescription
genomeIdpathstringYesPublic genome id (gen_...).

Response status codes: 200, 404.

GET/v1/genomes/{genomeId}/interpretations/latest/artifact

Read the latest interpretation artifact.

Scope: genomes:read

ParameterInTypeRequiredDescription
genomeIdpathstringYesPublic genome id (gen_...).

Response status codes: 200, 404.

POST/v1/genomes/{genomeId}/reinterpret

Queue a fresh interpretation for a genome.

Scope: genomes:write

ParameterInTypeRequiredDescription
genomeIdpathstringYesPublic genome id (gen_...).

Response status codes: 202, 404.

Panels

GET/v1/genomes/{genomeId}/panels

List built panels for a genome.

Scope: contexts:read

ParameterInTypeRequiredDescription
genomeIdpathstringYesPublic genome id (gen_...).

Response status codes: 200, 404.

POST/v1/genomes/{genomeId}/panels/{panelId}/build

Build a genetic insight panel for a genome.

Scope: contexts:write

ParameterInTypeRequiredDescription
genomeIdpathstringYesPublic genome id (gen_...).
panelIdpathstringYesGenetic insight panel id to build.
include_sequence_contextbodybooleanNoWhen true, WGS-backed variant findings include GRCh38 reference sequence context.
sequence_window_bpbodyintegerNoOdd-sized reference window around the variant. Even values are rounded up.

Response status codes: 201, 400, 404, 409.

GET/v1/genomes/{genomeId}/panels/{panelResultId}

Read a built panel result.

Scope: contexts:read

ParameterInTypeRequiredDescription
genomeIdpathstringYesPublic genome id (gen_...).
panelResultIdpathstringYesPublic panel result id (pan_...).

Response status codes: 200, 404.

GET/v1/panels

List available genetic insight panel definitions.

Scope: contexts:read

No request parameters.

Response status codes: 200.

GET/v1/panels/{panelId}

Read a single panel definition.

Scope: contexts:read

ParameterInTypeRequiredDescription
panelIdpathstringYesGenetic insight panel id (e.g. nutrition_micronutrients).

Response status codes: 200, 400.

Context

GET/v1/context/{contextId}

Read a previously built context.

Scope: contexts:read

ParameterInTypeRequiredDescription
contextIdpathstringYesPublic context id (ctx_...).

Response status codes: 200, 404.

POST/v1/context/build

Build a bounded structured context for a genome (advanced).

Scope: contexts:write

ParameterInTypeRequiredDescription
genome_idbodystringYesPublic genome id (gen_...) to build context for.
domainbodystringNoContext domain. Allowed: nutrition_diet_response, taste_and_smell, sleep_and_chronotype, body_traits, fitness_and_movement, growth_repair_inflammation_context, longevity_healthy_aging, skin_and_collagen, hormone_and_vitality, recovery_and_resilience, micronutrients_and_vitamins, pharmacogenomics_safety, cognition_and_focus, methylation_pathways, general. Default: "general".
detail_levelbodystringNoLevel of structured detail. Allowed: brief, standard, deep. Default: "standard".

Response status codes: 201, 400, 404, 409.

Webhooks

GET/v1/webhooks

List registered webhook endpoints.

Scope: webhooks:read

No request parameters.

Response status codes: 200.

POST/v1/webhooks

Register a lifecycle webhook endpoint.

Scope: webhooks:write

Endpoints may not target private or local hosts; production endpoints must be HTTPS. Supported event types: order.created, order.payment_pending, order.paid, order.kit_preparing, order.kit_shipped, order.kit_delivered, order.sample_registered, order.sample_returned, order.sample_received, order.lab_processing, order.sequencing, order.bioinformatics_processing, order.genome_bundle_generating, order.completed, order.failed, order.cancelled, conversion.completed, genome.created, interpretation.updated, context.generated, panel.generated.

ParameterInTypeRequiredDescription
urlbodystringYesHTTPS endpoint that will receive events.
descriptionbodystringNoHuman-readable label.
event_typesbodystring[]NoEvent types to subscribe to. Defaults to all. Default: ["order.created","order.payment_pending","order.paid","order.kit_preparing","order.kit_shipped","order.kit_delivered","order.sample_registered","order.sample_returned","order.sample_received","order.lab_processing","order.sequencing","order.bioinformatics_processing","order.genome_bundle_generating","order.completed","order.failed","order.cancelled","conversion.completed","genome.created","interpretation.updated","context.generated","panel.generated"].

Response status codes: 201, 400.

DELETE/v1/webhooks/{webhookId}

Disable a webhook endpoint.

Scope: webhooks:write

ParameterInTypeRequiredDescription
webhookIdpathstringYesPublic webhook id (wh_...).

Response status codes: 200, 404.

Usage

GET/v1/usage

List metered usage events.

Scope: usage:read

ParameterInTypeRequiredDescription
limitqueryintegerNoMaximum events to return. Default: 100.
event_typequerystringNoFilter by usage event type.

Response status codes: 200.

GET/v1/usage/rollups

List daily usage rollups (up to 90 days).

Scope: usage:read

No request parameters.

Response status codes: 200.

Billing

GET/v1/billing/account

Read the billing account.

Scope: billing:read or usage:read

No request parameters.

Response status codes: 200.

PATCH/v1/billing/account

Update the billing account.

Scope: billing:write

ParameterInTypeRequiredDescription
modebodystringYesBilling mode for the account. Allowed: card_on_file, enterprise_prepaid, invoice_arrears.
stripe_customer_idbodystringNo
stripe_payment_method_idbodystringNo
invoice_terms_daysbodyintegerNo
monthly_minimum_centsbodyintegerNo
enterprise_upfront_credit_centsbodyintegerNo
auto_chargebodybooleanNo
metadatabodyobjectNo

Response status codes: 200, 400.

GET/v1/billing/balance-transactions

List billing balance transactions.

Scope: billing:read or usage:read

No request parameters.

Response status codes: 200.

GET/v1/billing/periods

List billing periods.

Scope: billing:read or usage:read

No request parameters.

Response status codes: 200.

GET/v1/billing/periods/{yearMonth}/charges

Read charges for a billing period.

Scope: billing:read or usage:read

ParameterInTypeRequiredDescription
yearMonthpathstringYesBilling period as YYYY-MM.

Response status codes: 200, 404.

POST/v1/billing/periods/{yearMonth}/finalize

Finalize a billing period into an invoice.

Scope: billing:write

ParameterInTypeRequiredDescription
yearMonthpathstringYesBilling period as YYYY-MM.

Response status codes: 200, 400.

POST/v1/billing/periods/{yearMonth}/generate

Generate charges for a billing period.

Scope: billing:write

ParameterInTypeRequiredDescription
yearMonthpathstringYesBilling period as YYYY-MM.

Response status codes: 200, 400.

API keys

GET/v1/api-keys

List API keys for the organisation.

Scope: api-keys:read

No request parameters.

Response status codes: 200.

DELETE/v1/api-keys/{apiKeyId}

Revoke an API key.

Scope: api-keys:write

ParameterInTypeRequiredDescription
apiKeyIdpathstringYesAPI key id (UUID).

Response status codes: 200, 404.

Staging

GET/v1/test/genomes

Seed and list the sandbox genome (staging keys only).

Scope: genomes:read

No request parameters.

Response status codes: 200, 403.

POST/v1/test/genomes/seed

Seed the sandbox genome (staging keys only).

Scope: genomes:write

No request parameters.

Response status codes: 201, 403.

POST/v1/test/orders/{orderId}/advance

Advance a sandbox order to a new status (staging keys only).

Scope: orders:write

ParameterInTypeRequiredDescription
orderIdpathstringYesPublic order id (ord_...).
statusbodystringYesTarget order status to transition the sandbox order to.

Response status codes: 200, 400, 404.

Common Responses

These examples show the fields most clients build on directly.

Order

Order response
{
  "order_id": "ord_01JZ8N8A4P2Y",
  "type": "wgs_3x",
  "type_label": "3x whole genome sequencing",
  "client_name": "Acme Health",
  "user_reference": "user_123",
  "status": "created",
  "status_label": "Order created",
  "activation_code": "ACT-7HD2-9QK4",
  "activation_url": "https://sample.bio/activate/ACT-7HD2-9QK4",
  "deliverables": ["genome_bundle"],
  "retention": "hosted_runtime",
  "price_cents": 29900,
  "shipping_fee_cents": 0,
  "total_cents": 29900,
  "currency": "usd",
  "estimated_completion_date": null,
  "shipment": null,
  "genome_id": null,
  "storage_expires_at": null,
  "created_at": "2026-05-21T10:20:05.000Z",
  "updated_at": "2026-05-21T10:20:05.000Z"
}

Panel

Panel response
{
  "panel_result_id": "pan_9y2m1q",
  "panel_id": "nutrition_diet_response",
  "title": "Nutrition & Diet Response",
  "genome_id": "gen_test_nutrition_001",
  "interpretation_version": "2026.05.1",
  "summary": "Inherited tendencies in how this user processes foods and drinks, with high-to-moderate evidence. Suitable for an evidence summary card, not diagnosis or treatment.",
  "sections": [
    {
      "section_id": "food_drink_metabolism",
      "title": "Food & Drink Metabolism",
      "evidence_level": "high",
      "findings": [
        {
          "id": "rs4988235",
          "type": "variant",
          "title": "MCM6 rs4988235",
          "gene": "MCM6",
          "variant_id": "rs4988235",
          "result": { "genotype": "GA", "alleles": ["G", "A"] },
          "result_label": "One copy of G and one copy of A",
          "meaning": "The main lactase-persistence variant in European-ancestry populations; the persistence allele is associated with digesting dairy into adulthood. Separate persistence variants in African and Middle Eastern populations are not captured by this SNP, so a non-persistence call here does not rule out persistence in those ancestries.",
          "evidence_level": "high",
          "evidence": {
            "basis": "GWAS Catalog",
            "clinical_review": "Review food & drink metabolism context alongside labs, history, medications, and clinician oversight.",
            "validated_populations": ["European"]
          },
          "sequence_context": {
            "type": "reference_context_with_observed_variant",
            "available": true,
            "source": "wgs_vcf_plus_grch38_reference",
            "reference_genome": "GRCh38",
            "chromosome": "2",
            "position": 135851076,
            "window_bp": 41,
            "left_flank": "GAGTTCCTTTGAGGCCAGGG",
            "observed_variant": "G/A",
            "right_flank": "CTACATTATCTTATCTGTAT",
            "display_sequence": "GAGTTCCTTTGAGGCCAGGG[G/A]CTACATTATCTTATCTGTAT",
            "personalized_flanks": false
          }
        },
        {
          "id": "rs762551",
          "type": "variant",
          "title": "CYP1A2 rs762551",
          "gene": "CYP1A2",
          "variant_id": "rs762551",
          "result": { "genotype": "AC", "alleles": ["A", "C"] },
          "result_label": "One copy of A and one copy of C",
          "meaning": "Associated with CYP1A2 inducibility and caffeine-metabolism rate; the *1F allele links to higher inducible activity in some studies. Smoking and other inducers also strongly affect CYP1A2, so genotype is only part of the picture.",
          "evidence_level": "moderate",
          "evidence": {
            "basis": "PharmGKB, GWAS Catalog",
            "clinical_review": "Review food & drink metabolism context alongside labs, history, medications, and clinician oversight.",
            "validated_populations": ["broad"]
          }
        }
      ]
    },
    {
      "section_id": "diet_composition",
      "title": "Diet Composition Response",
      "evidence_level": "moderate",
      "findings": [
        {
          "id": "rs174537",
          "type": "variant",
          "title": "FADS1 rs174537",
          "gene": "FADS1",
          "variant_id": "rs174537",
          "result": { "genotype": "GT", "alleles": ["G", "T"] },
          "result_label": "One copy of G and one copy of T",
          "meaning": "FADS1 is associated with the efficiency of converting plant ALA into long-chain omega-3 (EPA/DHA); some versions are associated with lower conversion in studies. Diet decisions should weigh intake, labs, and clinician guidance, not genotype alone.",
          "evidence_level": "moderate",
          "evidence": {
            "basis": "GWAS Catalog, gnomAD",
            "clinical_review": "Review diet composition response context alongside labs, history, medications, and clinician oversight.",
            "validated_populations": ["broad"]
          }
        }
      ]
    }
  ],
  "citations": [
    {
      "source": "GWAS Catalog",
      "url": "https://www.ebi.ac.uk/gwas/",
      "accessed_at": "2026-05-20"
    },
    {
      "source": "gnomAD",
      "url": "https://gnomad.broadinstitute.org/",
      "accessed_at": "2026-05-20"
    }
  ],
  "limitations": [
    "DNA does not measure current folate, B12, homocysteine, or other nutrient levels.",
    "This panel does not diagnose a deficiency or recommend a diet, dose, or supplement.",
    "Genetic tendencies describe inherited likelihood, not current diet or symptoms."
  ],
  "clinical_boundary": "Use as inherited context for education and clinician review. Do not present as diagnosis, treatment, or dosing guidance.",
  "model_name": "deterministic-genetic-insight-panel-v1",
  "created_at": "2026-05-21T10:24:13.000Z"
}

Advanced context

Context response
{
  "context_id": "ctx_7v1a9k",
  "genome_id": "gen_test_nutrition_001",
  "domain": "nutrition_diet_response",
  "detail_level": "standard",
  "summary": "Genome gen_test_nutrition_001 context for nutrition_diet_response. Bounded structured findings are included, each with the user's result and what it means. This is biological context for software use, not clinical diagnosis.",
  "structured_findings": [
    {
      "id": "rs4988235",
      "title": "MCM6 rs4988235",
      "domain": "nutrition_diet_response",
      "evidence_level": "high",
      "summary": "Has one copy of G and one copy of A. The main lactase-persistence variant in European-ancestry populations; the persistence allele is associated with digesting dairy into adulthood.",
      "result": { "genotype": "GA", "alleles": ["G", "A"] },
      "result_label": "One copy of G and one copy of A",
      "meaning": "The main lactase-persistence variant in European-ancestry populations; the persistence allele is associated with digesting dairy into adulthood. Other persistence variants in African and Middle Eastern populations are not captured by this SNP.",
      "validated_populations": ["European"]
    }
  ],
  "citations": [
    { "source": "gwas_catalog", "version": "2026.05-sandbox" }
  ],
  "interpretation_version": "2026.05.1",
  "cost_cents": 5,
  "currency": "usd"
}
Use the interpretation record for quick status and version display. Use panel results for structured product UI, and use the full interpretation artifact or context response only when you need lower-level provenance or deterministic grounding.