Integrate clinical analysis into your application

Arrange access

API access is configured with Helena for each installation. Before development, agree the application callback URL, Helena organization, participating users, permitted S3 connections and source folders. The organization needs the API entitlement and sufficient Case Credits for the requested analysis.

Your backend must verify that the initiating user can access the selected file and workspace in your application. Keep OAuth client secrets and access tokens on the trusted backend.

Authenticate the person starting the analysis

Use OpenID Connect Authorization Code with S256 PKCE and the confidential client registered for your installation. Discover the issuer at https://accounts.helena.bio/.well-known/openid-configuration. Validate the callback state and ID token, then use the product access token for API requests.

Authorization: Bearer <product-access-token>
Accept: application/json

Request openid for sign-in and the API scopes your workflow needs: analyses:create, analyses:read, results:read and, for balance and price information, credits:read. A client secret alone does not authorize an analysis. Version one uses human sign-in; it has no client-credentials flow or public self-service installation registration.

Submit, follow and retrieve an analysis

1. Check context. Call GET /context. Match the expected user, installation, client, organization and context binding. Use the returned profiles, scopes and permitted S3 roots. An empty context list means no currently admitted context; do not select another workspace as a fallback.
2. Freeze the command. Select one immutable S3 object version. Save the complete request, the user's cost ceiling and one unique Idempotency-Key durably before submitting.
3. Create the analysis. Call POST /analyses. A 202 response records the command and case. Import, validation and computation happen afterward.
4. Poll status. Call GET /analyses/{analysis_id}. Display the returned status, stage, errors, warnings and billing state. The stages are not a percentage or an estimated completion time.
5. Verify and ingest results. After succeeded, fetch the result manifest and its authenticated artifacts. Check the manifest hash, then each artifact's byte length and SHA-256 before importing it into your application.
6. Link to the case. Use links.folklore to open the same case in Folklore. Normal sign-in and case permissions apply. Opening the link does not start another analysis or charge.

Keep analysis, billing and delivery status separate. Continue checking unsettled billing after result delivery. A retry of a download or host import must not create another analysis.

API endpoints

Base URL: https://api.helena.bio/folklore/v1

Every operation requires a current bearer access token. context is an operation, not an OAuth scope. Analysis and artifact IDs are UUIDs. Handled responses include X-Request-ID and Cache-Control: no-store.

Create request

Use Content-Type: application/json and an Idempotency-Key of 1 to 200 characters. This example uses synthetic identifiers and a cost ceiling of 1 Case Credit; it is not a price quote or a provisioned connection.

POST https://api.helena.bio/folklore/v1/analyses
Authorization: Bearer <product-access-token>
Content-Type: application/json
Idempotency-Key: synthetic-host-action-001

{
  "context_binding_id": "44444444-4444-4444-8444-444444444444",
  "profile": "singleton-germline-v1",
  "external_reference": "SYNTHETIC-CASE-001",
  "input": {
    "kind": "s3_object",
    "connection_id": "66666666-6666-4666-8666-666666666666",
    "bucket": "synthetic-cases",
    "key": "pilot/SYNTHETIC-CASE-001.vcf.gz",
    "version_id": "synthetic-immutable-version-001"
  },
  "clinical": {
    "hpo_ids": ["HP:0001250"],
    "filtering_preset": "strict",
    "language": "en"
  },
  "outputs": ["json"],
  "max_cost_units": 1000
}

The required fields are context_binding_id, profile, input and max_cost_units. JSON output is mandatory; request ["json", "pdf"] for a PDF as well. Clinical parameters default to no HPO terms, strict filtering and English. Supported presets are strict, balanced and permissive. Supply at most 200 HPO identifiers in the form HP:0001250.

The S3 source must be a permitted .vcf or .vcf.gz object with an explicit immutable version. latest, null, presigned URLs, local file paths and direct file uploads are not accepted inputs. Do not include storage credentials in the request.

Cost authorization

One Case Credit equals 1000 integer units. max_cost_units must be an integer from 0 to 9223372036854775807; preserve its precision in your client. With credits:read, context includes the payer, observed balance and price availability. If price_status is unavailable, the price list is empty. Without that scope, billing is null, which must not be shown as a zero balance. The server checks the current price against your ceiling when reserving credits.

Status and result delivery

Analysis status is queued, running, succeeded or failed. Stages are import, validation, admission, analysis, publication and complete. A status request can return HTTP 200 with status: "failed"; inspect its error object.

Synthetic status response after publication, with credit settlement still pending:

{
  "analysis_id": "77777777-7777-4777-8777-777777777777",
  "case_id": "88888888-8888-4888-8888-888888888888",
  "status": "succeeded",
  "stage": "complete",
  "created_at": "2026-10-15T00:00:00Z",
  "updated_at": "2026-10-15T00:20:00Z",
  "error": null,
  "cost": {"reserved_units": 1000},
  "billing": {"state": "settlement_pending"},
  "warnings": [],
  "links": {
    "self": "/folklore/v1/analyses/77777777-7777-4777-8777-777777777777",
    "results": "/folklore/v1/analyses/77777777-7777-4777-8777-777777777777/results",
    "folklore": "https://folklore.helena.bio/app/analysis/88888888-8888-4888-8888-888888888888"
  }
}

The result manifest identifies the analysis, case, frozen generation, available artifacts and expires_at retention deadline. Each artifact descriptor supplies its ID, kind, content type, byte length, SHA-256 and authenticated download route. Save the manifest and delivery receipt with the imported result.

To verify manifest_sha256, remove that field and serialize the remaining object as UTF-8 JSON with recursively sorted keys, compact comma/colon separators and ASCII escaping. Hash those bytes with SHA-256. For artifacts, hash the exact downloaded bytes and compare both hash and byte length. Validate the expected API route before downloading.

JSON output

The JSON export contains schema_version, analysis_id, case_id, generation_id, summary and genes. The genes array contains records with type: "metadata", type: "gene" and type: "complete". Read gene aggregates from the data field of gene records.

Gene aggregates include counts by ACMG class, impact counts and available priority scores. This export does not provide individual variant records. Preserve record types, missing values and the returned classifier version. The optional PDF belongs to the same frozen generation; if requested, publication waits for it.

Selected fields from a synthetic JSON export, shortened to show record handling:

{
  "schema_version": "1",
  "genes": [
    {"type": "metadata", "total_genes": 1, "total_variants": 1},
    {"type": "gene", "data": {
      "gene_symbol": "SYNTHETIC1",
      "variant_count": 1,
      "best_acmg_class": "VUS"
    }},
    {"type": "complete", "total_streamed": 1}
  ]
}

A later reanalysis can change the interactive case while this export remains pinned to its original generation. Download before expires_at. Hashes verify byte integrity, not clinical validity. Qualified professionals must review results before clinical use.

Retries and errors

After a timeout or uncertain create response, retry the original saved request with the same idempotency key and admitted identity. An exact replay returns the original analysis and case. Changing the source version, clinical parameters, outputs or cost ceiling under that key produces a conflict.

• 401: authenticate the intended human again and resume the saved command.
• 403: resolve the permission or entitlement denial. Repeated sign-in does not grant permission.
• 404: the analysis or artifact is missing or unavailable in the admitted context.
• 409: inspect the error code. idempotency_conflict requires reconciling the saved command; results_not_ready requires checking analysis status.
• 410: the artifact retention deadline has passed.
• 422: correct the invalid request.
• 503: the API, admission or artifact is temporarily unavailable. Preserve command identity and use bounded retry with backoff.

Handled request errors contain error.code, error.message, error.retryable and request_id. Retain the request ID for support. Intermediary errors may have a different response format. Accepted work can continue after a browser credential expires; current authority is still required to read or download.

Current integration scope

Version one supports one versioned S3 VCF per singleton-germline-v1 command, English output and optional HPO terms. The generated clinical profile records sex as unknown. This profile does not enable screening or literature expansion. FASTQ, BAM/CRAM, batch and family workflows are outside this API profile.

Clients poll for updates. The five-operation contract has no webhook, cancellation, live variant pagination, embedded interface or delegated host SSO operation.

You can implement the API directly or discuss an operator-hosted connector with Helena. The reusable connector handles authentication, command journaling, polling and download verification. Each host still needs its own reviewed adapter and native interface, result ingestion and acceptance testing.

For public gene, disease and single-variant evidence in an AI client, use the separate public MCP connector. It requires no account and does not accept patient datasets.

To plan an integration, send the intended workflow, source-storage setup, user and workspace model, and required result format to vladimir@helena.bio. Hosting arrangements and commercial terms are agreed for the installation.