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. Expired and revoked historical connections remain available, while customer identity and Genome Computer's canonical genome identifier are 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 in next_cursor by the previous page.
`client_user_reference`	query	string	No	Exact opaque client user reference to match.

Response status codes: 200, 400, 401, 403, 429.

POST/v2/genome_connections

Create a hosted genome connection

Scope: genome_connections:write

Creates a short-lived user URL from the client's authenticated backend. The user verifies by email, accepts the connection terms, and either shares an existing genome or orders a new one directly from Genome Computer.

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	Where Genome Computer sends the user after the hosted flow. Its exact HTTPS origin must be approved for the environment in Developer Console.

Response status codes: 201, 400, 401, 403, 409, 429.

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 connection identifier returned at creation.

Response status codes: 200, 401, 403, 404, 429.

GET/v2/genome_connections/{genome_connection_id}/bundle

Create a signed .genome bundle download link

Scope: genome_connections:read

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

Parameter	In	Type	Required	Description
`genome_connection_id`	path	string	Yes	The durable connection identifier returned at creation.

Response status codes: 200, 401, 403, 404, 429.

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 the previous permission request was declined or expired. It does not create a second connection or grant access by itself.

Parameter	In	Type	Required	Description
`genome_connection_id`	path	string	Yes	The durable connection identifier returned at creation.
`Idempotency-Key`	header	string	Yes	A unique key for this permission request. Reuse it only when retrying the same request.

Response status codes: 201, 401, 403, 404, 409, 429.

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 connection identifier returned at creation.

Response status codes: 200, 401, 403, 404, 429.

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. Findings are generated automatically when the genome is ready, access is active, and the user has an active Genome Computer subscription.

Parameter	In	Type	Required	Description
`genome_connection_id`	path	string	Yes	The durable connection identifier returned at creation.

Response status codes: 200, 401, 403, 404, 429.

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, evidence, citations, limitations, and clinical boundary. Raw genome files and user identity are not returned.

Parameter	In	Type	Required	Description
`genome_connection_id`	path	string	Yes	The durable connection identifier returned at creation.
`insight_panel_id`	path	string	Yes	The stable panel identifier configured for the organization.

Response status codes: 200, 401, 403, 404, 429.

Webhooks

GET/v2/webhooks

List webhook endpoints

Scope: webhooks:read

Lists webhook endpoints registered for this organization and API environment.

No request parameters.

Response status codes: 200, 401, 403, 429.

POST/v2/webhooks

Scope: webhooks:write

Registers an HTTPS endpoint for genome connection events. The signing secret is returned only once.

Parameter	In	Type	Required	Description
`url`	body	string	Yes	HTTPS endpoint that receives signed webhook requests.
`description`	body	string	No
`event_types`	body	string[]	No	Events to receive. Omit to subscribe to all supported connection and insight panel events.

Response status codes: 201, 400, 401, 403, 429.

DELETE/v2/webhooks/{webhookId}

Disable a webhook endpoint

Scope: webhooks:write

Stops future deliveries to the selected endpoint.

Parameter	In	Type	Required	Description
`webhookId`	path	string	Yes	The webhook endpoint identifier returned at creation.

Response status codes: 200, 401, 403, 404, 429.

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.