Developer Documentation

Introduction

The Gencove Consumer API provides programmatic access to your genomics data. You can use it to retrieve your profile information, list your kits, view PRS trait scores, ancestry composition, and download raw data files.

The API is organized around REST principles. All responses are returned in JSON format. All endpoints are read-only and use GET requests.

Quickstart

Pick the flow that fits what you’re building. Both are five-minute “hello world” paths.

curl https://consumer.gencove.com/api/v1/profile/ \
  -H "Authorization: Api-Key YOUR_API_KEY"

import requests
response = requests.get(
    "https://consumer.gencove.com/api/v1/profile/",
    headers={"Authorization": "Api-Key YOUR_API_KEY"}
)
print(response.json())

const response = await fetch(
  "https://consumer.gencove.com/api/v1/profile/",
  {
    headers: { "Authorization": "Api-Key YOUR_API_KEY" }
  }
);
const data = await response.json();
console.log(data);

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "user@example.com",
  "name": "Jane Doe",
  "date_joined": "2025-01-15T10:30:00Z",
  "marketing_emails_opt_in": true
}

claude mcp add --transport http gencove \
  https://consumer.gencove.com/mcp/ \
  --header "Authorization: Api-Key YOUR_API_KEY"

[mcp_servers.gencove]
url = "https://consumer.gencove.com/mcp/"
http_headers = { Authorization = "Api-Key YOUR_API_KEY" }

{
  "mcpServers": {
    "gencove": {
      "url": "https://consumer.gencove.com/mcp/",
      "headers": {
        "Authorization": "Api-Key YOUR_API_KEY"
      }
    }
  }
}

Authentication

The Gencove Consumer API uses API keys for authentication. Include your key in the Authorization header of every request.

Getting an API key

1. Log in to your Gencove account.
2. Navigate to Account → API Keys.
3. Click Create API Key and give it a descriptive name.
4. Copy the key immediately — it is only shown once.

Key permissions

Each API key grants full read access to all API endpoints for the account that created it. There are no per-endpoint scopes — any valid key can access any endpoint listed in this documentation.

Unauthenticated request

If you omit the API key or provide an invalid one, the API returns a 401 response:

HTTP 401 Unauthorized

{
  "detail": "Authentication credentials were not provided."
}

Quick reference

OAuth 2.0 for partner integrations

This page is for developers building a product that needs to read a Gencove customer's genomics data on the customer's behalf — for example, a partner health company whose users have Gencove accounts and want their kit status, PRS scores, ancestry, or raw download URLs surfaced inside your app.

You should not use OAuth if you just want to read your own data programmatically — personal API keys are simpler and grant full read access to your own account. OAuth exists specifically so that Gencove users can grant scoped access to a third party without handing over a full-power API key.

The protocol is the standard OAuth 2.0 Authorization Code flow with mandatory PKCE (RFC 7636). Both the REST API at /api/v1/ and the MCP server at /mcp/ accept OAuth bearer tokens.

The handshake at a glance

Three parties are involved: your app (the OAuth client), the Gencove user (the resource owner), and Gencove itself (the authorization server). PKCE ties the initial redirect to the final token exchange so an intercepted authorization code is useless to an attacker.

Getting started

Five one-time setup steps before you can make your first OAuth call:

1. Create a Gencove consumer account. Your app is registered under a Gencove user — typically a team email you control. Sign up at https://consumer.gencove.com/user/register/.
2. Enable two-factor authentication. Gencove requires 2FA before you can register or rotate OAuth credentials. Visit Two-Factor Auth.
3. Register your application. Go to Developer Integrations → Register application. Provide a descriptive name (end-users see it on the consent screen), one or more redirect URIs (where Gencove sends the auth code back — https:// in production, loopback http://localhost:… accepted in dev), and the scopes you'll request.
4. Copy your credentials. On save you'll see client_id and client_secret once. Put them in your secret manager; the secret is hashed server-side and cannot be retrieved. If you lose it, use Rotate secret to generate a new one.
5. (Before launch) Request verification. New apps start as Unverified and users see a warning on the consent screen. Unverified is fine for private / sandbox development. Once you're going live to your customers, email support@gencove.com with your client_id and a brief description of your integration.

Using a third-party OAuth library

Most teams should reach for a vetted OAuth 2.0 client library rather than reimplementing the flow. Gencove's OAuth server is spec-compliant, so any library that supports Authorization Code + PKCE (S256) and refresh-token rotation will work. The library handles PKCE generation, code exchange, refresh rotation, and sets the Authorization: Bearer header for you — replace only YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, and the redirect URI below.

# pip install "authlib" "requests"
from authlib.integrations.requests_client import OAuth2Session

AUTHORIZE_URL = "https://consumer.gencove.com/oauth/authorize/"
TOKEN_URL     = "https://consumer.gencove.com/oauth/token/"

session = OAuth2Session(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    scope="profile:read kits:read prs:read",
    redirect_uri="https://your-app.example.com/callback",
    code_challenge_method="S256",
)

# 1. Redirect the user to `url`. Persist `state` and
#    `session.code_verifier` for the callback.
url, state = session.create_authorization_url(AUTHORIZE_URL)

# 2. In your /callback handler:
token = session.fetch_token(
    TOKEN_URL,
    authorization_response=full_callback_url,  # e.g. str(request.url)
    code_verifier=stored_code_verifier,
)

# 3. Call the API — the session adds the Bearer header for you.
profile = session.get(
    "https://consumer.gencove.com/api/v1/profile/"
).json()

# 4. Refresh when needed (single-use rotation: store the new refresh_token).
token = session.refresh_token(TOKEN_URL, refresh_token=token["refresh_token"])

// npm install openid-client
import { Issuer, generators } from "openid-client";

const issuer = await Issuer.discover(
  "https://consumer.gencove.com/.well-known/oauth-authorization-server"
);
const client = new issuer.Client({
  client_id: "YOUR_CLIENT_ID",
  client_secret: "YOUR_CLIENT_SECRET",
  redirect_uris: ["https://your-app.example.com/callback"],
  response_types: ["code"],
});

// 1. Redirect the user to `url`. Persist `code_verifier` and `state`.
const code_verifier = generators.codeVerifier();
const code_challenge = generators.codeChallenge(code_verifier);
const state = generators.state();
const url = client.authorizationUrl({
  scope: "profile:read kits:read prs:read",
  code_challenge,
  code_challenge_method: "S256",
  state,
});

// 2. In your /callback handler:
const params = client.callbackParams(req);
const tokenSet = await client.callback(
  "https://your-app.example.com/callback",
  params,
  { code_verifier, state }
);

// 3. Call the API.
const res = await fetch(
  "https://consumer.gencove.com/api/v1/profile/",
  { headers: { Authorization: `Bearer ${tokenSet.access_token}` } }
);
const profile = await res.json();

// 4. Refresh when needed.
const refreshed = await client.refresh(tokenSet.refresh_token);

<?php
// composer require league/oauth2-client
use League\OAuth2\Client\Provider\GenericProvider;

$provider = new GenericProvider([
    'clientId'                => 'YOUR_CLIENT_ID',
    'clientSecret'            => 'YOUR_CLIENT_SECRET',
    'redirectUri'             => 'https://your-app.example.com/callback',
    'urlAuthorize'            => 'https://consumer.gencove.com/oauth/authorize/',
    'urlAccessToken'          => 'https://consumer.gencove.com/oauth/token/',
    'urlResourceOwnerDetails' => 'https://consumer.gencove.com/api/v1/profile/',
    'scopes'                  => ['profile:read', 'kits:read', 'prs:read'],
    'scopeSeparator'          => ' ', // RFC 6749 requires space; library defaults to ','
    'pkceMethod'              => GenericProvider::PKCE_METHOD_S256,
]);

// 1. Redirect the user. Persist state + PKCE code in the session.
$url = $provider->getAuthorizationUrl();
$_SESSION['oauth2state']    = $provider->getState();
$_SESSION['oauth2pkceCode'] = $provider->getPkceCode();

// 2. In your /callback handler:
$provider->setPkceCode($_SESSION['oauth2pkceCode']);
$token = $provider->getAccessToken('authorization_code', [
    'code' => $_GET['code'],
]);

// 3. Call the API — getParsedResponse signs the Bearer header.
$request = $provider->getAuthenticatedRequest(
    'GET',
    'https://consumer.gencove.com/api/v1/profile/',
    $token
);
$profile = $provider->getParsedResponse($request);

// 4. Refresh when needed.
$token = $provider->getAccessToken('refresh_token', [
    'refresh_token' => $token->getRefreshToken(),
]);

// go get golang.org/x/oauth2
import (
    "context"
    "net/http"

    "golang.org/x/oauth2"
)

var conf = &oauth2.Config{
    ClientID:     "YOUR_CLIENT_ID",
    ClientSecret: "YOUR_CLIENT_SECRET",
    RedirectURL:  "https://your-app.example.com/callback",
    Scopes:       []string{"profile:read", "kits:read", "prs:read"},
    Endpoint: oauth2.Endpoint{
        AuthURL:  "https://consumer.gencove.com/oauth/authorize/",
        TokenURL: "https://consumer.gencove.com/oauth/token/",
    },
}

// 1. Redirect the user. Persist `verifier` + `state`.
verifier := oauth2.GenerateVerifier()
url := conf.AuthCodeURL(
    "state-token",
    oauth2.AccessTypeOffline,
    oauth2.S256ChallengeOption(verifier),
)

// 2. In your /callback handler:
token, err := conf.Exchange(
    ctx,
    r.URL.Query().Get("code"),
    oauth2.VerifierOption(storedVerifier),
)

// 3. Call the API. conf.Client auto-refreshes on expiry.
client := conf.Client(ctx, token)
resp, _ := client.Get("https://consumer.gencove.com/api/v1/profile/")

If your stack has no mature OAuth client (or you want to see what the library is doing), the raw-HTTP walkthrough below is the authoritative reference and covers every protocol detail.

The integration flow

For every customer of your product who wants to connect their Gencove account, you repeat this six-step dance:

1. Generate a random code_verifier (43–128 URL-safe chars) and derive a SHA-256 code_challenge. Store the verifier server-side, keyed by a state value you also generate — you need the verifier again in step 4.
2. Redirect the user's browser to /oauth/authorize/ with the query parameters below.
3. Gencove asks the user to log in (if they aren't already) and shows a consent screen listing the scopes you requested. When they click Allow, Gencove redirects their browser back to your redirect_uri with ?code=…&state=…. Verify the state matches what you generated before trusting the code.
4. Your server POSTs to /oauth/token/ exchanging the code + PKCE verifier for tokens.
5. Gencove returns access_token (1 hour) and refresh_token (30 days). Store them against this user's record.
6. Call /api/v1/… or POST /mcp/ with Authorization: Bearer <access_token>. When the access token expires, use the refresh token to get a new pair.

Step 1 — generate PKCE

// Python (server-side)
import hashlib, secrets, base64

code_verifier = secrets.token_urlsafe(64)
challenge = base64.urlsafe_b64encode(
    hashlib.sha256(code_verifier.encode()).digest()
).rstrip(b"=").decode()

state = secrets.token_urlsafe(32)
# store {state: {code_verifier, user_id, …}} in your session cache

Step 2 — redirect to the authorize URL

Build a URL from these parameters and 302 the user's browser to it:

https://consumer.gencove.com/oauth/authorize/
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fyour-app.com%2Fgencove%2Fcallback
  &scope=profile%3Aread%20kits%3Aread%20prs%3Aread
  &state=OPAQUE_ANTI_CSRF_TOKEN
  &code_challenge=XYZ…
&code_challenge_method=S256

Step 3 — handle the callback

Gencove redirects the user back to your redirect_uri with ?code=…&state=…. On your server, first look up the state in the session cache you populated in step 1 — if it's missing or doesn't match, abort (this protects against CSRF and replay). Then recover the code_verifier stored against that state for step 4.

# Django / Flask / etc. callback handler
def gencove_callback(request):
    incoming_state = request.GET["state"]
    cached = session_cache.pop(incoming_state)  # raises if unknown / expired
    code = request.GET["code"]
    code_verifier = cached["code_verifier"]
    # … proceed to step 4 with `code` + `code_verifier`

Step 4 — exchange code for tokens

curl -X POST https://consumer.gencove.com/oauth/token/ \
  -u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \
  -d grant_type=authorization_code \
  -d code=CODE_FROM_CALLBACK \
  -d redirect_uri=https://your-app.com/gencove/callback \
  -d code_verifier=CODE_VERIFIER_FROM_STEP_1

Step 5 — store the tokens

The token endpoint returns JSON:

{
    "access_token":  "…",
    "refresh_token": "…",
    "token_type":    "Bearer",
    "expires_in":    3600,
    "scope":         "profile:read kits:read prs:read"
}

Save both tokens against this user's record in your DB, along with the scope actually granted (users can downgrade at the consent screen) and the expiry derived from expires_in. Encrypt refresh tokens at rest — the single-use / rotation rule under Refreshing access makes them a theft target.

Step 6 — call the API

curl https://consumer.gencove.com/api/v1/profile/ \
-H "Authorization: Bearer ACCESS_TOKEN"

Refreshing access

Before expires_in runs out (or on the next 401), swap the refresh token for a new pair:

curl -X POST https://consumer.gencove.com/oauth/token/ \
  -u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \
  -d grant_type=refresh_token \
  -d refresh_token=OLD_REFRESH_TOKEN

Scopes

Request the minimum scope set your features need. Users can grant a subset at the consent screen; requests for scopes your app did not register (in Developer Integrations) are rejected outright.

Connecting MCP clients (Claude, Cursor, ChatGPT)

MCP clients that support OAuth use dynamic discovery. Point your MCP client at https://consumer.gencove.com/mcp/. The client will receive a 401 with WWW-Authenticate: Bearer … resource_metadata=…, follow the URL to /.well-known/oauth-protected-resource, then to /.well-known/oauth-authorization-server, and walk the user through the same consent flow described above. You still need to register an application in Developer Integrations — the MCP client doesn't do that for you.

Endpoint reference

Token lifecycle

• Access token: valid for 1 hour.
• Refresh token: valid for 30 days, rotated on every use.
• Refresh reuse protection: presenting an already-rotated refresh token revokes the entire family. Protect your storage.
• User revoke: the user can revoke your app's access anytime from their Connected Accounts page. Handle 401 gracefully — don't retry aggressively.
• Developer delete: deleting an application from Developer Integrations immediately invalidates every token issued against it.

Authorization header

Every API or MCP call uses the standard bearer format:

Authorization: Bearer eyJhbGciOi…

Common errors

MCP — AI & Agents

Connect your AI tools to Gencove using the Model Context Protocol (MCP), an open standard that lets AI assistants access your genomics data — kits, PRS scores, ancestry composition, and raw data files — directly from tools you already use.

Instead of switching between your AI assistant and the Gencove dashboard, you can ask questions like “What are my kit statuses?” or “Show my ancestry breakdown” and get answers powered by your real data. The MCP server accepts the same API key or OAuth bearer token as the REST API and exposes the same underlying data.

How it fits together

The MCP server is a thin protocol adapter in front of your Gencove data. Your AI tool speaks MCP over HTTP; the server authenticates the request with an API key (or OAuth bearer token) and returns the same data the REST API would.

MCP Endpoint

Capabilities at a glance

Every capability below is callable from any MCP-speaking client — see Getting Started for per-client setup.

Key Concepts

These terms appear in tool responses. Understanding them helps AI assistants interpret results accurately.

Available Tools

The MCP server exposes the following tools. Each tool maps to a corresponding REST API endpoint and returns the same data.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "jane@example.com",
  "name": "Jane Doe",
  "date_joined": "2025-03-15T10:30:00Z",
  "marketing_emails_opt_in": true
}

{
  "count": 1,
  "next_offset": null,
  "results": [
    {
      "sample_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "kit_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
      "kit_created": "2025-06-01T14:22:00Z",
      "last_status": {
        "id": "11111111-2222-3333-4444-555555555555",
        "status": "Results Ready",
        "created": "2025-07-10T09:15:00Z"
      }
    }
  ]
}

{
  "sample_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "kit_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "kit_created": "2025-06-01T14:22:00Z",
  "last_status": {
    "id": "11111111-2222-3333-4444-555555555555",
    "status": "Results Ready",
    "created": "2025-07-10T09:15:00Z"
  }
}

{
  "count": 1,
  "next_offset": null,
  "results": [
    {
      "id": 42,
      "trait_key": "type_2_diabetes",
      "distribution_key": "gencove_v1",
      "distribution_version": "1.0",
      "value": 1.45,
      "percentile": 72.3,
      "risk_threshold": 80.0,
      "risk": "average"
    }
  ]
}

{
  "populations": [
    {
      "population_key": "NEUROPE",
      "population_name": "Northern European",
      "value": 0.65,
      "percentage": 65.0
    },
    {
      "population_key": "WAFR",
      "population_name": "West African",
      "value": 0.25,
      "percentage": 25.0
    },
    {
      "population_key": "EASIA",
      "population_name": "East Asian",
      "value": 0.1,
      "percentage": 10.0
    }
  ]
}

{
  "count": 1,
  "next_offset": null,
  "results": [
    {
      "id": "c3d4e5f6-7890-abcd-ef12-34567890abcd",
      "file_type": "impute-vcf",
      "size": 1073741824,
      "checksum_sha256": "e3b0c44298fc1c149afbf4c8996fb924...",
      "archive_status": "available",
      "download_url": "https://s3.amazonaws.com/..."
    }
  ]
}

Getting Started

Before connecting an AI tool, make sure you have an API key. Then follow the instructions for your tool below.

claude mcp add --transport http gencove \
  https://consumer.gencove.com/mcp/ \
  --header "Authorization: Api-Key YOUR_API_KEY"

[mcp_servers.gencove]
url = "https://consumer.gencove.com/mcp/"
http_headers = { Authorization = "Api-Key YOUR_API_KEY" }

{
  "mcpServers": {
    "gencove": {
      "url": "https://consumer.gencove.com/mcp/",
      "headers": {
        "Authorization": "Api-Key YOUR_API_KEY"
      }
    }
  }
}

{
  "servers": {
    "gencove": {
      "type": "http",
      "url": "https://consumer.gencove.com/mcp/",
      "headers": {
        "Authorization": "Api-Key YOUR_API_KEY"
      }
    }
  }
}

https://consumer.gencove.com/mcp/

{
  "mcpServers": {
    "gencove": {
      "url": "https://consumer.gencove.com/mcp/",
      "headers": {
        "Authorization": "Api-Key YOUR_API_KEY"
      }
    }
  }
}

Verify Your Connection

Once configured, ask your AI assistant something like “What are my Gencove kits?” — it should call the list_kits tool and return your kit data.

You can also test the MCP endpoint directly with curl:

curl -X POST https://consumer.gencove.com/mcp/ \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Tips for AI Tools

API Reference

All endpoints are read-only (GET) and require API key authentication. Click an endpoint to view its interactive documentation with response examples and the ability to test it live.

Status & Error Codes

The API uses standard HTTP status codes to indicate the outcome of a request.

Error response format

Error responses include a detail field describing the error:

{
  "detail": "Authentication credentials were not provided."
}

Pagination

Endpoints that return lists of items use limit-offset pagination. You control pagination with two query parameters:

Response format

Paginated responses are wrapped in an envelope with metadata:

{
  "meta": {
    "count": 42,
    "next": "https://consumer.gencove.com/api/v1/kits/?limit=20&offset=20",
    "previous": null
  },
  "results": [
    { "..." }
  ]
}

Rate Limiting

To ensure fair usage, the API enforces rate limits on all requests.

Rate limit exceeded

When you exceed the rate limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait before retrying:

HTTP 429 Too Many Requests
Retry-After: 1

{
  "detail": "Request was throttled. Expected available in 1 second."
}

Best practices

• Implement exponential backoff when you receive a 429 response.
• Always respect the Retry-After header value before retrying.
• Cache responses when possible to reduce the number of API calls.

Email Notifications

Gencove sends email notifications for important updates about your kits and account. These are not triggered via the API — they are sent automatically based on events in the system. This section documents what you can expect to receive.

Kit lifecycle

These emails track your kit from order to results: