Helena Bioinformatics Admin API
The admin API from Helena Bioinformatics — 9 operation(s) for admin.
The admin API from Helena Bioinformatics — 9 operation(s) for admin.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/helena-bio:helena-bio-admin-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Helix Insight - Variant Analysis Service Admin API
description: AI-powered variant analysis and interpretation service
version: 0.1.0
tags:
- name: Admin
paths:
/preprocessing/databases:
get:
tags:
- Admin
summary: Get All Databases Status
description: 'Get complete status of all reference databases.
Returns identity, source files, parquet conversion, reference_db loading,
freshness assessment, and validation results for each database.
Fast endpoint (< 2 seconds): filesystem stat() calls + one DuckDB query.'
operationId: get_all_databases_status_preprocessing_databases_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AllDatabasesStatusResponse'
/preprocessing/databases/{db_name}:
get:
tags:
- Admin
summary: Get Single Database Status
description: 'Get detailed status of a single database.
Includes everything from the list endpoint plus:
- Per-chromosome row counts (for partitioned databases)
- Column names in the DuckDB table
- Sample data (first 5 rows)
- Full conversion metadata JSON'
operationId: get_single_database_status_preprocessing_databases__db_name__get
parameters:
- name: db_name
in: path
required: true
schema:
type: string
title: Db Name
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/DatabaseDetailResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/preprocessing/databases/{db_name}/update:
post:
tags:
- Admin
summary: Update Single Database
description: 'Start the update pipeline for a single database.
Returns immediately with task_id. Poll GET /preprocessing/tasks/{task_id}
for progress.'
operationId: update_single_database_preprocessing_databases__db_name__update_post
parameters:
- name: db_name
in: path
required: true
schema:
type: string
title: Db Name
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateDatabaseRequest'
responses:
'202':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TaskCreatedResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/preprocessing/update-all:
post:
tags:
- Admin
summary: Update All Databases
description: 'Start the full preprocessing pipeline for all (or selected) databases.
Processes databases in priority order. Equivalent to the legacy
POST /preprocessing/start endpoint.'
operationId: update_all_databases_preprocessing_update_all_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAllRequest'
required: true
responses:
'202':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TaskCreatedResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/preprocessing/rebuild-reference-db:
post:
tags:
- Admin
summary: Rebuild Reference Db
description: 'Rebuild reference_db.duckdb from existing parquet files.
Does NOT re-download or re-convert. Creates a fresh DuckDB file
from all available parquet data with atomic replacement.
WARNING: Reference database is temporarily unavailable during rebuild.
Active analysis sessions may fail.'
operationId: rebuild_reference_db_preprocessing_rebuild_reference_db_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RebuildReferenceDBRequest'
required: true
responses:
'202':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TaskCreatedResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/preprocessing/tasks/{task_id}:
get:
tags:
- Admin
summary: Get Task Status
description: Get detailed progress for a running or completed task.
operationId: get_task_status_preprocessing_tasks__task_id__get
parameters:
- name: task_id
in: path
required: true
schema:
type: string
title: Task Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TaskStatusSchema'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/preprocessing/tasks:
get:
tags:
- Admin
summary: List Tasks
description: Get status of all preprocessing tasks (running and historical).
operationId: list_tasks_preprocessing_tasks_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TaskListResponse'
/preprocessing/vep-cache/stats:
get:
tags:
- Admin
summary: Get Vep Cache Stats
description: 'Get aggregated statistics for the VEP annotation cache.
Read-only endpoint. Opens vep_cache.duckdb with read_only=True.
Does not acquire any locks -- safe during concurrent pipeline runs.
Typical response time: < 1 second for ~50M rows.'
operationId: get_vep_cache_stats_preprocessing_vep_cache_stats_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/VepCacheStatsResponse'
/preprocessing/vep-cache/search:
get:
tags:
- Admin
summary: Search Vep Cache
description: 'Search the VEP annotation cache by variant coordinates or gene symbol.
Two modes:
- Variant lookup: provide chromosome + position (optionally ref + alt)
- Gene search: provide gene symbol
All queries use parameterized SQL (B1). Read-only, no locks.'
operationId: search_vep_cache_preprocessing_vep_cache_search_get
parameters:
- name: chromosome
in: query
required: false
schema:
type: string
title: Chromosome
- name: position
in: query
required: false
schema:
type: integer
title: Position
- name: ref
in: query
required: false
schema:
type: string
title: Ref
- name: alt
in: query
required: false
schema:
type: string
title: Alt
- name: gene
in: query
required: false
schema:
type: string
title: Gene
- name: limit
in: query
required: false
schema:
type: integer
default: 20
title: Limit
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/VepCacheSearchResult'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
DatabaseDetailResponse:
properties:
name:
type: string
title: Name
display_name:
type: string
title: Display Name
version:
anyOf:
- type: string
- type: 'null'
title: Version
description:
anyOf:
- type: string
- type: 'null'
title: Description
priority:
type: integer
title: Priority
enabled:
type: boolean
title: Enabled
default: true
license_required:
type: boolean
title: License Required
default: false
vep_required:
type: boolean
title: Vep Required
default: false
source_url:
anyOf:
- type: string
- type: 'null'
title: Source Url
source:
$ref: '#/components/schemas/SourceStatusSchema'
parquet:
$ref: '#/components/schemas/ParquetStatusSchema'
reference_db:
$ref: '#/components/schemas/ReferenceDBTableSchema'
freshness:
$ref: '#/components/schemas/FreshnessSchema'
validation:
$ref: '#/components/schemas/ValidationSchema'
detail:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Detail
type: object
required:
- name
- display_name
- priority
- source
- parquet
- reference_db
- freshness
- validation
title: DatabaseDetailResponse
description: Response for GET /preprocessing/databases/{db_name} with detail.
UpdateAllRequest:
properties:
databases:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Databases
force:
type: boolean
title: Force
default: false
type: object
title: UpdateAllRequest
description: Request for POST /preprocessing/update-all.
DatabaseStatusSchema:
properties:
name:
type: string
title: Name
display_name:
type: string
title: Display Name
version:
anyOf:
- type: string
- type: 'null'
title: Version
description:
anyOf:
- type: string
- type: 'null'
title: Description
priority:
type: integer
title: Priority
enabled:
type: boolean
title: Enabled
default: true
license_required:
type: boolean
title: License Required
default: false
vep_required:
type: boolean
title: Vep Required
default: false
source_url:
anyOf:
- type: string
- type: 'null'
title: Source Url
source:
$ref: '#/components/schemas/SourceStatusSchema'
parquet:
$ref: '#/components/schemas/ParquetStatusSchema'
reference_db:
$ref: '#/components/schemas/ReferenceDBTableSchema'
freshness:
$ref: '#/components/schemas/FreshnessSchema'
validation:
$ref: '#/components/schemas/ValidationSchema'
type: object
required:
- name
- display_name
- priority
- source
- parquet
- reference_db
- freshness
- validation
title: DatabaseStatusSchema
description: Complete status of one database.
VepCacheChromosomeEntry:
properties:
chromosome:
type: string
title: Chromosome
positive:
type: integer
title: Positive
negative:
type: integer
title: Negative
type: object
required:
- chromosome
- positive
- negative
title: VepCacheChromosomeEntry
description: Chromosome-level cache coverage.
VepCacheStatsResponse:
properties:
file_exists:
type: boolean
title: File Exists
file_size_bytes:
type: integer
title: File Size Bytes
default: 0
file_size_human:
type: string
title: File Size Human
default: 0 B
vep_version:
anyOf:
- type: string
- type: 'null'
title: Vep Version
positive_count:
type: integer
title: Positive Count
default: 0
negative_count:
type: integer
title: Negative Count
default: 0
total_count:
type: integer
title: Total Count
default: 0
oldest_entry:
anyOf:
- type: string
- type: 'null'
title: Oldest Entry
newest_entry:
anyOf:
- type: string
- type: 'null'
title: Newest Entry
dedup_cutoff:
anyOf:
- type: string
- type: 'null'
title: Dedup Cutoff
impact_distribution:
items:
$ref: '#/components/schemas/VepCacheDistributionEntry'
type: array
title: Impact Distribution
default: []
consequence_distribution:
items:
$ref: '#/components/schemas/VepCacheDistributionEntry'
type: array
title: Consequence Distribution
default: []
biotype_distribution:
items:
$ref: '#/components/schemas/VepCacheDistributionEntry'
type: array
title: Biotype Distribution
default: []
chromosome_distribution:
items:
$ref: '#/components/schemas/VepCacheChromosomeEntry'
type: array
title: Chromosome Distribution
default: []
sample_positive:
items:
additionalProperties: true
type: object
type: array
title: Sample Positive
default: []
sample_negative:
items:
additionalProperties: true
type: object
type: array
title: Sample Negative
default: []
query_time_ms:
type: integer
title: Query Time Ms
default: 0
type: object
required:
- file_exists
title: VepCacheStatsResponse
description: Response for GET /preprocessing/vep-cache/stats.
UpdateDatabaseRequest:
properties:
steps:
items:
type: string
type: array
title: Steps
default:
- download
- convert
- load
force:
type: boolean
title: Force
default: false
type: object
title: UpdateDatabaseRequest
description: Request for POST /preprocessing/databases/{db_name}/update.
AllDatabasesStatusResponse:
properties:
reference_db:
$ref: '#/components/schemas/ReferenceDBSummarySchema'
databases:
items:
$ref: '#/components/schemas/DatabaseStatusSchema'
type: array
title: Databases
type: object
required:
- reference_db
- databases
title: AllDatabasesStatusResponse
description: Response for GET /preprocessing/databases.
TaskCreatedResponse:
properties:
task_id:
type: string
title: Task Id
status:
type: string
title: Status
databases:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Databases
status_url:
type: string
title: Status Url
message:
anyOf:
- type: string
- type: 'null'
title: Message
warning:
anyOf:
- type: string
- type: 'null'
title: Warning
type: object
required:
- task_id
- status
- status_url
title: TaskCreatedResponse
description: Response for task creation endpoints (202 Accepted).
ValidationSchema:
properties:
passed:
type: boolean
title: Passed
checks:
additionalProperties: true
type: object
title: Checks
default: {}
type: object
required:
- passed
title: ValidationSchema
description: Validation results.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
TaskStatusSchema:
properties:
task_id:
type: string
title: Task Id
status:
type: string
title: Status
started_at:
anyOf:
- type: string
- type: 'null'
title: Started At
completed_at:
anyOf:
- type: string
- type: 'null'
title: Completed At
elapsed_seconds:
anyOf:
- type: number
- type: 'null'
title: Elapsed Seconds
databases:
additionalProperties: true
type: object
title: Databases
default: {}
current_database:
anyOf:
- type: string
- type: 'null'
title: Current Database
current_step:
anyOf:
- type: string
- type: 'null'
title: Current Step
log_tail:
items:
type: string
type: array
title: Log Tail
default: []
successful:
anyOf:
- type: integer
- type: 'null'
title: Successful
failed:
anyOf:
- type: integer
- type: 'null'
title: Failed
message:
anyOf:
- type: string
- type: 'null'
title: Message
type: object
required:
- task_id
- status
title: TaskStatusSchema
description: Task progress response.
RebuildReferenceDBRequest:
properties:
confirm:
type: boolean
title: Confirm
default: false
type: object
title: RebuildReferenceDBRequest
description: Request for POST /preprocessing/rebuild-reference-db.
TaskListResponse:
properties:
tasks:
items:
$ref: '#/components/schemas/TaskStatusSchema'
type: array
title: Tasks
total:
type: integer
title: Total
running:
type: integer
title: Running
type: object
required:
- tasks
- total
- running
title: TaskListResponse
description: Response for GET /preprocessing/tasks.
VepCacheSearchResult:
properties:
mode:
type: string
title: Mode
query_time_ms:
type: integer
title: Query Time Ms
default: 0
status:
anyOf:
- type: string
- type: 'null'
title: Status
positive_hits:
items:
additionalProperties: true
type: object
type: array
title: Positive Hits
default: []
negative_hits:
items:
additionalProperties: true
type: object
type: array
title: Negative Hits
default: []
gene:
anyOf:
- type: string
- type: 'null'
title: Gene
total_variants:
type: integer
title: Total Variants
default: 0
consequence_breakdown:
items:
$ref: '#/components/schemas/VepCacheConsequenceBreakdown'
type: array
title: Consequence Breakdown
default: []
sample_variants:
items:
additionalProperties: true
type: object
type: array
title: Sample Variants
default: []
type: object
required:
- mode
title: VepCacheSearchResult
description: Response for GET /preprocessing/vep-cache/search.
SourceStatusSchema:
properties:
exists:
type: boolean
title: Exists
path:
type: string
title: Path
files_found:
type: integer
title: Files Found
default: 0
files_expected:
type: integer
title: Files Expected
default: 0
total_size_bytes:
type: integer
title: Total Size Bytes
default: 0
total_size_human:
type: string
title: Total Size Human
default: 0 B
oldest_file_modified:
anyOf:
- type: string
- type: 'null'
title: Oldest File Modified
newest_file_modified:
anyOf:
- type: string
- type: 'null'
title: Newest File Modified
type: object
required:
- exists
- path
title: SourceStatusSchema
description: Source files on disk.
ParquetStatusSchema:
properties:
exists:
type: boolean
title: Exists
path:
type: string
title: Path
partitions:
type: integer
title: Partitions
default: 0
partitions_expected:
type: integer
title: Partitions Expected
default: 0
total_size_bytes:
type: integer
title: Total Size Bytes
default: 0
total_size_human:
type: string
title: Total Size Human
default: 0 B
last_modified:
anyOf:
- type: string
- type: 'null'
title: Last Modified
row_count:
anyOf:
- type: integer
- type: 'null'
title: Row Count
conversion_metadata:
anyOf:
- $ref: '#/components/schemas/ConversionMetadataSchema'
- type: 'null'
type: object
required:
- exists
- path
title: ParquetStatusSchema
description: Parquet conversion status.
ConversionMetadataSchema:
properties:
start_time:
anyOf:
- type: string
- type: 'null'
title: Start Time
elapsed_seconds:
anyOf:
- type: number
- type: 'null'
title: Elapsed Seconds
elapsed_human:
anyOf:
- type: string
- type: 'null'
title: Elapsed Human
successful_chromosomes:
anyOf:
- type: integer
- type: 'null'
title: Successful Chromosomes
failed_chromosomes:
anyOf:
- type: integer
- type: 'null'
title: Failed Chromosomes
type: object
title: ConversionMetadataSchema
description: Conversion metadata summary.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
ReferenceDBTableSchema:
properties:
loaded:
type: boolean
title: Loaded
table_name:
type: string
title: Table Name
row_count:
anyOf:
- type: integer
- type: 'null'
title: Row Count
column_count:
anyOf:
- type: integer
- type: 'null'
title: Column Count
type: object
required:
- loaded
- table_name
title: ReferenceDBTableSchema
description: Status of a table in reference_db.duckdb.
VepCacheDistributionEntry:
properties:
label:
type: string
title: Label
count:
type: integer
title: Count
pct:
type: number
title: Pct
default: 0.0
type: object
required:
- label
- count
title: VepCacheDistributionEntry
description: Single row in a distribution breakdown.
VepCacheConsequenceBreakdown:
properties:
consequence:
type: string
title: Consequence
impact:
type: string
title: Impact
count:
type: integer
title: Count
type: object
required:
- consequence
- impact
- count
title: VepCacheConsequenceBreakdown
description: Single row in gene consequence breakdown.
FreshnessSchema:
properties:
status:
type: string
title: Status
message:
type: string
title: Message
source_age_days:
anyOf:
- type: integer
- type: 'null'
title: Source Age Days
parquet_age_days:
anyOf:
- type: integer
- type: 'null'
title: Parquet Age Days
cache_ttl_days:
anyOf:
- type: integer
- type: 'null'
title: Cache Ttl Days
is_within_ttl:
anyOf:
- type: boolean
- type: 'null'
title: Is Within Ttl
suggested_action:
anyOf:
- type: string
- type: 'null'
title: Suggested Action
type: object
required:
- status
- message
title: FreshnessSchema
description: Freshness assessment.
ReferenceDBSummarySchema:
properties:
exists:
type: boolean
title: Exists
file_path:
type: string
title: File Path
file_size_bytes:
type: integer
title: File Size Bytes
default: 0
file_size_human:
type: string
title: File Size Human
default: 0 B
last_modified:
anyOf:
- type: string
- type: 'null'
title: Last Modified
tables:
items:
type: string
type: array
title: Tables
default: []
total_rows:
type: integer
title: Total Rows
default: 0
type: object
required:
- exists
- file_path
title: ReferenceDBSummarySchema
description: Summary of reference_db.duckdb.
securitySchemes:
HTTPBearer:
type: http
scheme: bearer