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

A small connection API.

Methods, fields, and response shapes for the Genome Computer API. Use these endpoints to create and list genome connections, read their state, and follow progress.

The API evolves through additive fields and webhook event types. A breaking change requires a new major API version.

Authentication

Send an environment-scoped bearer key from your backend. Staging access is provisioned explicitly; production requires separate approval and setup.

Header

Authorization: Bearer $GC_API_KEY

OpenAPI schema

Download the same schema used to render this endpoint reference.

OpenAPI JSON

Endpoints

Create, list, and read durable genome connections, then follow their normalized progress. User-facing actions happen only in the hosted Genome Computer flow.

Genome connections

GET/v2/genome_connections

List genome connections.

Scope: genome_connections:read

Returns this organization's connections for the API key environment, newest first. User identity is never returned.

Parameter	In	Type	Required	Description
`limit`	query	integer	No	Maximum number of connections to return. Default: 25.
`cursor`	query	string	No	Opaque cursor returned by the previous page.
`client_user_reference`	query	string	No	Exact opaque client user reference to match.

Response status codes: 200, 400, 403.

POST/v2/genome_connections

Create a hosted genome connection.

Scope: genome_connections:write

Creates a short-lived Genome Computer URL from the client's authenticated backend.

Parameter	In	Type	Required	Description
`idempotency-key`	header	string	Yes	A unique key for this create attempt. Reuse it only when retrying the same request.
`client_user_reference`	body	string	Yes	Your opaque reference for the signed-in user. Do not send an email address, name, or other direct identifier.
`return_url`	body	string	Yes	An HTTPS URL whose origin has been approved for your organization.

Response status codes: 201, 400, 403, 409, 503.

GET/v2/genome_connections/{genome_connection_id}

Get a genome connection.

Scope: genome_connections:read

Returns the durable client-scoped connection and its current access state. User identity is never returned.

Parameter	In	Type	Required	Description
`genome_connection_id`	path	string	Yes	The durable genome connection identifier.

Response status codes: 200, 403, 404.

GET/v2/genome_connections/{genome_connection_id}/bundle

Create a signed .genome bundle download link.

Scope: genome_connections:read

Returns a short-lived signed link only when bundle downloads are enabled for the organization and the connection still has an active genome grant.

Parameter	In	Type	Required	Description
`genome_connection_id`	path	string	Yes	The durable genome connection identifier.

Response status codes: 200, 403, 404.

POST/v2/genome_connections/{genome_connection_id}/permission_requests

Request customer permission again.

Scope: genome_connections:write

Creates a fresh short-lived customer URL for the same durable connection after its previous permission request was declined or expired.

Parameter	In	Type	Required	Description
`genome_connection_id`	path	string	Yes	The durable genome connection identifier.
`idempotency-key`	header	string	Yes	A unique key for this create attempt. Reuse it only when retrying the same request.

Response status codes: 201, 403, 404, 409, 503.

Progress

GET/v2/genome_connections/{genome_connection_id}/progress

Get normalized genome progress.

Scope: genome_connections:read

Returns the latest coarse progress stage for either a shared existing genome or a new Genome Computer order.

Parameter	In	Type	Required	Description
`genome_connection_id`	path	string	Yes	The durable genome connection identifier.

Response status codes: 200, 403, 404.

Insight panels

GET/v2/genome_connections/{genome_connection_id}/insight_panels

List insight panels for a connection.

Scope: insight_panels:read

Returns the panels enabled for the organization and their current status.

Parameter	In	Type	Required	Description
`genome_connection_id`	path	string	Yes	The durable genome connection identifier.

Response status codes: 200, 403, 404.

GET/v2/genome_connections/{genome_connection_id}/insight_panels/{insight_panel_id}

Get an insight panel.

Scope: insight_panels:read

Returns the current panel state and, when ready, its derived findings. Raw genome files and user identity are not returned.

Parameter	In	Type	Required	Description
`genome_connection_id`	path	string	Yes	The durable genome connection identifier.
`insight_panel_id`	path	string	Yes	A stable insight panel identifier configured for the organization.

Response status codes: 200, 403, 404.

Webhooks

GET/v2/webhooks

List registered webhook endpoints.

Scope: webhooks:read

No request parameters.

Response status codes: 200.

POST/v2/webhooks

Scope: webhooks:write

Endpoints may not target private or local hosts; production endpoints must be HTTPS. Supported event types: genome_connection.connected, genome_connection.progress.updated, genome_connection.ready, genome_connection.access.revoked, insight_panel.status.updated.

Parameter	In	Type	Required	Description
`url`	body	string	Yes	HTTPS endpoint that will receive events.
`description`	body	string	No	Human-readable label.
`event_types`	body	string[]	No	Event types to subscribe to. Defaults to all. Default: ["genome_connection.connected","genome_connection.progress.updated","genome_connection.ready","genome_connection.access.revoked","insight_panel.status.updated"].

Response status codes: 201, 400.

DELETE/v2/webhooks/{webhookId}

Disable a webhook endpoint.

Scope: webhooks:write

Parameter	In	Type	Required	Description
`webhookId`	path	string	Yes	Public webhook id (wh_...).

Response status codes: 200, 404.

Representative responses

Examples use only client-scoped identifiers. User identity and Genome Computer's canonical genome identifier are not exposed.

Create connection

{
  "genome_connection": {
    "genome_connection_id": "gconn_01K4J92BRY7M",
    "client_user_reference": "user_8f3c2a",
    "status": "awaiting_customer",
    "access_status": null,
    "journey": null,
    "client_genome_id": null,
    "created_at": "2026-09-03T04:15:22.000Z",
    "connected_at": null,
      "permissions": [
      { "permission": "genome_connection", "status": "pending" },
      { "permission": "insight_panels", "status": "pending" }
    ]
  },
  "customer_url": "https://connect.genome.computer/c/gc_link_xxx",
  "customer_url_expires_at": "2026-09-03T04:30:22.000Z"
}

Progress

{
  "genome_connection_id": "gconn_01K4J92BRY7M",
  "client_genome_id": null,
  "stage": "inbound_to_lab",
  "updated_at": "2026-09-14T01:42:17.000Z"
}

Use the browser return only to restore your product experience. Read the resource or process a verified webhook before changing durable state in your system.