GeneBe Hub REST API

Most people manage GeneBe Hub databases through GeneBeClient (annotation push, annotation pull, ...). If you are integrating GeneBe Hub into your own tooling instead, the same functionality is also available as a REST API, under https://api.genebe.net/cloud/api-public/v1/hub/*.

Interactive, always up to date documentation (with a "Try it out" button) is available at https://api.genebe.net/cloud/gb-api-doc/swagger-ui/index.html. Below is a human-curated reference of the endpoints most useful for external integrations.

Authentication uses the same API key as the rest of the GeneBe API, sent as a Basic or Bearer credential.

Browsing and reading databases

These endpoints are read-only. Most of them do not require authentication -- an API key is only needed to see your own private databases.

Browse databases

Method	URL
POST	/api-public/v1/hub/browse

Search/list databases matching a filter. All fields in the request body are optional.

Request body:

{
  "name": "abraom",
  "type": "VARIANT",
  "genome": "GRCh38",
  "status": "ACTIVE"
}

Response (200) -- array of database summaries:

[
  {
    "id": "@genebe/abraom:0.0.1",
    "owner": "@genebe",
    "name": "abraom",
    "version": "0.0.1",
    "status": "ACTIVE",
    "createdDate": "2026-09-10T18:29:27.926Z",
    "labels": ["frequency", "population", "brazilian"],
    "title": "ABraOM/SABE allele frequencies",
    "genome": "GRCh38",
    "species": "homo_sapiens",
    "type": "VARIANT",
    "publiclyAvailable": true,
    "licenseType": "NOT_SPECIFIED"
  }
]

Get a database's page model

Method	URL
GET	/api-public/v1/hub/find

Parameters

Name	In	Description	Required
id	query	Database identifier, formatted as owner/name:version	Required

Returns the description, license text, creation date, status and available versions of a database -- everything needed to render a database's page.

Example: GET /api-public/v1/hub/find?id=@genebe/abraom:0.0.1

List versions of a database

Method	URL
GET	/api-public/v1/hub/versions

Parameters

Name	In	Description	Required
id	query	Database identifier, formatted as owner/name:version (the version part is ignored)	Required

Response (200):

["0.0.3-20260205170148", "0.0.2", "0.0.1"]

List databases by owner

Method	URL
GET	/api-public/v1/hub/owner/{owner}

Parameters

Name	In	Description	Required
owner	path	Database owner, e.g. @genebe for an organization, or a username	Required
showAllTypes	query	If true and you can access the owner's private databases, also include non-active statuses (e.g. during upload)	Optional

Returns the newest version of each database belonging to the given owner.

Get a database entity

Method	URL
GET	/api-public/v1/hub/owner/{owner}/name/{name}
GET	/api-public/v1/hub/owner/{owner}/name/{name}/version/{version}

Returns the full database entity: metadata, column descriptions and files. Omit version (use the first form) to get the newest version accessible to you.

Response (200):

{
  "id": "@genebe/abraom:0.0.1",
  "owner": "@genebe",
  "name": "abraom",
  "version": "0.0.1",
  "status": "ACTIVE",
  "title": "ABraOM/SABE allele frequencies",
  "genome": "GRCh38",
  "species": "homo_sapiens",
  "type": "VARIANT",
  "publiclyAvailable": true,
  "licenseType": "NOT_SPECIFIED",
  "columns": [
    { "name": "af", "type": "float64", "description": "Alternate allele frequency in ABraOM/SABE." },
    { "name": "ac", "type": "int32", "description": "Alternate allele count in ABraOM/SABE." }
  ],
  "files": [
    { "fileName": "parquet/_seq=1/part-00000-061081da.c000.zstd.parquet", "size": 41460999, "xxh32sum": "688ea158" }
  ]
}

Download a database

Method	URL
POST	/api-public/v1/hub/download

Requires authentication. Generates time-limited download URLs for a database's files -- this is what powers annotation pull in GeneBeClient.

Request body:

{
  "owner": "@genebe",
  "name": "abraom",
  "version": "0.0.1",
  "format": "parquet"
}

The response includes a files map of relative file path to download URL, plus the database's description, descriptionText and licenseText.

Query rows from a database

Method	URL
POST	/api-public/v1/hub/view

Requires authentication. Runs a query directly against a database's rows on the server and returns matching rows as JSON -- useful for quick lookups without downloading the whole database.

Request body:

{
  "owner": "@genebe",
  "name": "abraom",
  "version": "0.0.1",
  "seq": "17",
  "start": 43000000,
  "end": 43100000
}

seq/start/end are optional but recommended: querying without at least seq is much slower, since it can't take advantage of the database's Hive partitioning.

Managing your own databases

Update database metadata

Method	URL
POST	/api-public/v1/hub/save

Requires authentication and ownership of the database. Updates metadata (title, description, license, visibility, labels, column descriptions, ...) of an existing database entry -- it does not create new databases or upload files.

Delete a database

Method	URL
DELETE	/api-public/v1/hub/delete

Parameters

Name	In	Description	Required
id	query	Database identifier, formatted as owner/name:version	Required

Requires authentication and ownership of the database.

Uploading new databases (admin only)

Creating brand new databases through the API -- POST /api-public/v1/hub/upload, POST /api-public/v1/hub/upload/complete, POST /api-public/v1/hub/initiate-multipart and POST /api-public/v1/hub/complete-multipart -- is currently restricted to GeneBe administrators. If you want to publish your own database, use GeneBeClient annotation push as described in Creating a database; it drives this same upload flow for you.