Skip to main content
API docs by Redocly

COHORTome API (0.1.0)

Download OpenAPI specification:Download

Clinical and multimodal cohort exploration and analysis API.

COHORTome exposes a browser-facing API for governed multi-dataset workspaces, longitudinal clinical and assay exploration, cohort discovery, and traceable analysis.

ui

HTML entrypoints and static branding assets used by the web application shell.

Render the main application shell

Serves the COHORTome HTML shell with the current branding and authenticated user context.

Responses

Serve the configured branding logo

Returns the current instance branding logo file if one is configured.

Responses

Response samples

Content type
application/json
null

auth

Authentication state, local login, and user visibility endpoints.

Inspect configured LM status

Returns whether LM Studio is enabled plus the current model and base URL.

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "available": false,
  • "status": "disabled",
  • "base_url": "string",
  • "model": "string",
  • "detail": "",
  • "selected_provider_id": "system-default",
  • "provider": { },
  • "providers": [
    ]
}

Inspect approved LLM providers

Admin-only registry and health view for approved OpenAI-compatible LLM endpoints.

Responses

Response samples

Content type
application/json
{
  • "providers": [
    ],
  • "registry_error": ""
}

Create a managed LLM provider

Persists an OpenAI-compatible provider in protected runtime state. The API key is write-only.

Request Body schema: application/json
required
id
string (Id)
Default: ""

Stable provider ID used by persisted user settings.

label
string (Label)
Default: ""

User-facing provider label.

base_url
string (Base Url)
Default: ""

OpenAI-compatible API base URL, normally ending in /v1.

model
string (Model)
Default: ""

Model ID. Leave empty to use the first model reported by the provider.

api_key
string (Api Key)
Default: ""

Write-only API key. It is never returned by the API.

timeout_seconds
number (Timeout Seconds)
Default: 30

Provider request timeout in seconds.

enabled
boolean (Enabled)
Default: true

Whether users may select and use this provider.

data_boundary
string (Data Boundary)
Default: "external"
Enum: "local" "external"

Explicit deployment boundary used for private-data policy.

Responses

Request samples

Content type
application/json
{
  • "id": "",
  • "label": "",
  • "base_url": "",
  • "model": "",
  • "api_key": "",
  • "timeout_seconds": 30,
  • "enabled": true,
  • "data_boundary": "local"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "label": "string",
  • "base_url": "string",
  • "model": "string",
  • "enabled": true,
  • "data_boundary": "local",
  • "source": "configuration",
  • "managed": false,
  • "timeout_seconds": 30,
  • "api_key_configured": false
}

Update a managed LLM provider

Updates a runtime-managed provider. Environment-defined providers are read-only.

path Parameters
provider_id
required
string (Provider Id)
Request Body schema: application/json
required
Label (string) or Label (null) (Label)

Updated user-facing provider label.

Base Url (string) or Base Url (null) (Base Url)

Updated OpenAI-compatible API base URL.

Model (string) or Model (null) (Model)

Updated model ID; an empty value enables model discovery.

Api Key (string) or Api Key (null) (Api Key)

Replacement write-only API key. Empty values retain the stored key.

Timeout Seconds (number) or Timeout Seconds (null) (Timeout Seconds)

Updated provider request timeout in seconds.

Enabled (boolean) or Enabled (null) (Enabled)

Whether users may select and use this provider.

Data Boundary (string) or Data Boundary (null) (Data Boundary)

Updated deployment boundary.

Responses

Request samples

Content type
application/json
{
  • "label": "string",
  • "base_url": "string",
  • "model": "string",
  • "api_key": "string",
  • "timeout_seconds": 0,
  • "enabled": true,
  • "data_boundary": "local"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "label": "string",
  • "base_url": "string",
  • "model": "string",
  • "enabled": true,
  • "data_boundary": "local",
  • "source": "configuration",
  • "managed": false,
  • "timeout_seconds": 30,
  • "api_key_configured": false
}

Delete a managed LLM provider

Deletes a runtime-managed provider. Environment-defined providers cannot be deleted.

path Parameters
provider_id
required
string (Provider Id)

Responses

Response samples

Content type
application/json
{
  • "deleted": true,
  • "id": "",
  • "deleted_count": 0,
  • "deleted_generated_data": false,
  • "related_job_count": 0,
  • "deleted_job_count": 0,
  • "kept_job_count": 0,
  • "skipped_active_count": 0
}

Test an LLM provider

Runs an admin-only models-endpoint health check without exposing the configured API key.

path Parameters
provider_id
required
string (Provider Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "label": "string",
  • "base_url": "string",
  • "model": "string",
  • "enabled": true,
  • "data_boundary": "local",
  • "source": "configuration",
  • "managed": false,
  • "timeout_seconds": 30,
  • "api_key_configured": false
}

Get current authentication state

Returns the current local-auth session state and visible user identity.

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "mode": "none",
  • "provider": "none",
  • "authenticated": true,
  • "local_login_enabled": false,
  • "password_reset_enabled": false,
  • "user": {
    }
}

Start external OIDC login

Redirects to the configured OIDC provider when COHORTOME_AUTH_MODE=oidc.

Responses

Response samples

Content type
application/json
null

Log in with local credentials

Authenticates a local user and creates a session-backed login.

Request Body schema: application/json
required
username
string (Username)
Default: ""

Local username.

password
string (Password)
Default: ""

Local password.

Responses

Request samples

Content type
application/json
{
  • "username": "",
  • "password": ""
}

Response samples

Content type
application/json
{
  • "enabled": true,
  • "mode": "none",
  • "provider": "none",
  • "authenticated": true,
  • "local_login_enabled": false,
  • "password_reset_enabled": false,
  • "user": {
    }
}

Complete external OIDC login

Handles the OIDC authorization-code callback and maps the external identity to a local COHORTome user.

query Parameters
code
string (Code)
Default: ""
state
string (State)
Default: ""
error
string (Error)
Default: ""

Responses

Response samples

Content type
application/json
null

Log out the current user

Clears the local session for the current user.

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "mode": "none",
  • "provider": "none",
  • "authenticated": true,
  • "local_login_enabled": false,
  • "password_reset_enabled": false,
  • "user": {
    }
}

Request a local password reset

Sends a password reset email when SMTP-backed local reset is configured. The response does not reveal whether the account exists.

Request Body schema: application/json
required
identifier
string (Identifier)
Default: ""

Username or email address for password reset.

Responses

Request samples

Content type
application/json
{
  • "identifier": ""
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "message": "string"
}

Confirm a local password reset

Consumes a password reset token and replaces the local password.

Request Body schema: application/json
required
token
string (Token)
Default: ""

Password reset token from the reset link.

password
string (Password)
Default: ""

New local password.

Responses

Request samples

Content type
application/json
{
  • "token": "",
  • "password": ""
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "message": "string"
}

Inspect auth diagnostics

Returns local-auth diagnostics useful during development and deployment troubleshooting.

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "mode": "string",
  • "provider": "none",
  • "user_count": 0,
  • "usernames": [
    ],
  • "roles": {
    },
  • "groups": {
    },
  • "source": "string"
}

List visible local users

Returns local users and groups. When auth is enabled, this endpoint is admin-only.

Responses

Response samples

Content type
application/json
{
  • "mode": "string",
  • "users": [
    ]
}

Create a local user

Creates a persisted local user with application role and groups. Admin-only when auth is enabled.

Request Body schema: application/json
required
username
string (Username)
Default: ""

Unique local username.

password
string (Password)
Default: ""

Initial local password.

display_name
string (Display Name)
Default: ""

User-facing display name.

email
string (Email)
Default: ""

Optional email address used for self-service password reset.

role
string (Role)
Default: "user"

Application role: user or admin.

groups
Array of strings (Groups)

Application groups used for dataset authorization.

enabled
boolean (Enabled)
Default: true

Whether the user can sign in.

Responses

Request samples

Content type
application/json
{
  • "username": "",
  • "password": "",
  • "display_name": "",
  • "email": "",
  • "role": "user",
  • "groups": [
    ],
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "username": "string",
  • "role": "string",
  • "display_name": "string",
  • "email": "",
  • "groups": [
    ],
  • "enabled": true,
  • "auth_source": "local",
  • "login_method": "local"
}

Update a local user

Updates display name, role, groups, or enabled state for a local user. Admin-only when auth is enabled.

path Parameters
username
required
string (Username)
Request Body schema: application/json
required
Display Name (string) or Display Name (null) (Display Name)

Updated display name.

Email (string) or Email (null) (Email)

Updated email address used for self-service password reset.

Role (string) or Role (null) (Role)

Updated application role.

Array of Groups (strings) or Groups (null) (Groups)

Replacement application groups.

Enabled (boolean) or Enabled (null) (Enabled)

Whether the user can sign in.

Responses

Request samples

Content type
application/json
{
  • "display_name": "string",
  • "email": "string",
  • "role": "string",
  • "groups": [
    ],
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "username": "string",
  • "role": "string",
  • "display_name": "string",
  • "email": "",
  • "groups": [
    ],
  • "enabled": true,
  • "auth_source": "local",
  • "login_method": "local"
}

Delete a local user

Deletes a persisted local user. Admin-only when auth is enabled.

path Parameters
username
required
string (Username)

Responses

Response samples

Content type
application/json
{
  • "deleted": true,
  • "id": "",
  • "deleted_count": 0,
  • "deleted_generated_data": false,
  • "related_job_count": 0,
  • "deleted_job_count": 0,
  • "kept_job_count": 0,
  • "skipped_active_count": 0
}

Reset a local user password

Replaces the password for a local user. Admin-only when auth is enabled.

path Parameters
username
required
string (Username)
Request Body schema: application/json
required
password
string (Password)
Default: ""

Replacement local password.

Responses

Request samples

Content type
application/json
{
  • "password": ""
}

Response samples

Content type
application/json
{
  • "username": "string",
  • "role": "string",
  • "display_name": "string",
  • "email": "",
  • "groups": [
    ],
  • "enabled": true,
  • "auth_source": "local",
  • "login_method": "local"
}

Get user UI settings

Returns persisted UI preferences for the current user.

Responses

Response samples

Content type
application/json
{
  • "version": 1,
  • "landing_tab_mode": "fixed",
  • "landing_tab": "dashboard",
  • "query_disclosure_default": "summary",
  • "query_default_mode": "auto",
  • "latest_query_details": true,
  • "analysis_auto_open_jobs": true,
  • "run_history_retention_days": 0,
  • "pheno_default_metric": "",
  • "pheno_advanced_open": false,
  • "pheno_render_heatmap": true,
  • "pheno_render_mds": true,
  • "pheno_render_graph": true,
  • "dashboard_assays_open": false,
  • "dataset_compact_view": false,
  • "llm_provider_id": "system-default"
}

Update user UI settings

Persists UI preferences for the current user.

Request Body schema: application/json
required
Landing Tab Mode (string) or Landing Tab Mode (null) (Landing Tab Mode)
Landing Tab (string) or Landing Tab (null) (Landing Tab)
Query Disclosure Default (string) or Query Disclosure Default (null) (Query Disclosure Default)
Query Default Mode (string) or Query Default Mode (null) (Query Default Mode)
Latest Query Details (boolean) or Latest Query Details (null) (Latest Query Details)
Analysis Auto Open Jobs (boolean) or Analysis Auto Open Jobs (null) (Analysis Auto Open Jobs)
Run History Retention Days (integer) or Run History Retention Days (null) (Run History Retention Days)
Pheno Default Metric (string) or Pheno Default Metric (null) (Pheno Default Metric)
Pheno Advanced Open (boolean) or Pheno Advanced Open (null) (Pheno Advanced Open)
Pheno Render Heatmap (boolean) or Pheno Render Heatmap (null) (Pheno Render Heatmap)
Pheno Render Mds (boolean) or Pheno Render Mds (null) (Pheno Render Mds)
Pheno Render Graph (boolean) or Pheno Render Graph (null) (Pheno Render Graph)
Dashboard Assays Open (boolean) or Dashboard Assays Open (null) (Dashboard Assays Open)
Dataset Compact View (boolean) or Dataset Compact View (null) (Dataset Compact View)
Llm Provider Id (string) or Llm Provider Id (null) (Llm Provider Id)

Responses

Request samples

Content type
application/json
{
  • "landing_tab_mode": "fixed",
  • "landing_tab": "dashboard",
  • "query_disclosure_default": "summary",
  • "query_default_mode": "auto",
  • "latest_query_details": true,
  • "analysis_auto_open_jobs": true,
  • "run_history_retention_days": 0,
  • "pheno_default_metric": "",
  • "pheno_advanced_open": true,
  • "pheno_render_heatmap": true,
  • "pheno_render_mds": true,
  • "pheno_render_graph": true,
  • "dashboard_assays_open": true,
  • "dataset_compact_view": true,
  • "llm_provider_id": "string"
}

Response samples

Content type
application/json
{
  • "version": 1,
  • "landing_tab_mode": "fixed",
  • "landing_tab": "dashboard",
  • "query_disclosure_default": "summary",
  • "query_default_mode": "auto",
  • "latest_query_details": true,
  • "analysis_auto_open_jobs": true,
  • "run_history_retention_days": 0,
  • "pheno_default_metric": "",
  • "pheno_advanced_open": false,
  • "pheno_render_heatmap": true,
  • "pheno_render_mds": true,
  • "pheno_render_graph": true,
  • "dashboard_assays_open": false,
  • "dataset_compact_view": false,
  • "llm_provider_id": "system-default"
}

Delete current user's analysis chats

Deletes all saved analysis chats owned by the current user.

Responses

Response samples

Content type
application/json
{ }

Delete current user's completed jobs

Deletes terminal background jobs and generated artifacts owned by the current user. Active jobs are skipped.

Responses

Response samples

Content type
application/json
{ }

Delete current user's saved cohorts

Deletes saved cohorts owned by the current user when they are not referenced by saved analysis chats.

Responses

Response samples

Content type
application/json
{ }

datasets

Dataset registry, workspace selection, and dataset access policy management.

List authorized datasets

Returns datasets visible to the current user plus the currently active workspace selection.

Responses

Response samples

Content type
application/json
{
  • "datasets": [
    ],
  • "current_dataset_id": "",
  • "current_dataset_ids": [
    ],
  • "current_dataset_scope_id": "",
  • "current_dataset": {
    }
}

Register a dataset

Creates a new dataset registry entry. Admin-only.

Request Body schema: application/json
required
name
string (Name)
Default: ""

Human-readable dataset name.

root_path
string (Root Path)
Default: ""

Dataset root directory containing clinical/ and assays/ subdirectories.

description
string (Description)
Default: ""

Optional dataset description shown in the UI.

visibility
string (Visibility)
Default: "all_authenticated"

Dataset visibility policy: all_authenticated, restricted, or admin_only.

data_classification
string (Data Classification)
Default: "private"

Data egress classification: public or private. Private data cannot be sent to external AI providers.

allowed_users
Array of strings (Allowed Users)

Usernames with direct access when visibility is restricted.

allowed_groups
Array of strings (Allowed Groups)

Groups with access when visibility is restricted.

query_granularity_ceiling
string (Query Granularity Ceiling)
Default: "summary"

Maximum Query thread mode allowed for this dataset: summary or detailed.

ai_provider_access
string (Ai Provider Access)
Default: "detailed_allowed"

Maximum AI provider disclosure allowed after applying data classification and provider boundary.

enabled
boolean (Enabled)
Default: true

Whether the dataset can be selected in the UI.

Responses

Request samples

Content type
application/json
{
  • "name": "",
  • "root_path": "",
  • "description": "",
  • "visibility": "all_authenticated",
  • "data_classification": "private",
  • "allowed_users": [
    ],
  • "allowed_groups": [
    ],
  • "query_granularity_ceiling": "summary",
  • "ai_provider_access": "detailed_allowed",
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "dataset_id": "string",
  • "name": "string",
  • "description": "",
  • "root_path": "",
  • "enabled": true,
  • "visibility": "string",
  • "data_classification": "private",
  • "allowed_users": [
    ],
  • "allowed_groups": [
    ],
  • "query_granularity_ceiling": "summary",
  • "ai_provider_access": "detailed_allowed",
  • "created_by": "",
  • "created_at": "",
  • "updated_at": "",
  • "query_store_status": { }
}

Select the active dataset workspace

Applies one or more authorized dataset IDs as the current workspace for the authenticated user.

Request Body schema: application/json
required
dataset_id
string (Dataset Id)
Default: ""

Single dataset ID for backward compatibility.

dataset_ids
Array of strings (Dataset Ids)

Dataset IDs that define the active workspace. An empty list unloads it.

Responses

Request samples

Content type
application/json
{
  • "dataset_id": "",
  • "dataset_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "selected": true,
  • "current_dataset_id": "",
  • "current_dataset_ids": [
    ],
  • "current_dataset_scope_id": ""
}

Update dataset metadata and access

Updates dataset metadata, visibility, or access policy. Admin-only.

path Parameters
dataset_id
required
string (Dataset Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)

Updated human-readable dataset name.

Root Path (string) or Root Path (null) (Root Path)

Updated dataset root directory.

Description (string) or Description (null) (Description)

Updated UI description.

Visibility (string) or Visibility (null) (Visibility)

Updated visibility policy.

Data Classification (string) or Data Classification (null) (Data Classification)

Updated data egress classification: public or private.

Array of Allowed Users (strings) or Allowed Users (null) (Allowed Users)

Replacement direct-access username list.

Array of Allowed Groups (strings) or Allowed Groups (null) (Allowed Groups)

Replacement allowed-group list.

Query Granularity Ceiling (string) or Query Granularity Ceiling (null) (Query Granularity Ceiling)

Updated maximum Query thread mode for this dataset.

Ai Provider Access (string) or Ai Provider Access (null) (Ai Provider Access)

Updated maximum AI provider access mode.

Enabled (boolean) or Enabled (null) (Enabled)

Whether the dataset remains selectable.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "root_path": "string",
  • "description": "string",
  • "visibility": "string",
  • "data_classification": "string",
  • "allowed_users": [
    ],
  • "allowed_groups": [
    ],
  • "query_granularity_ceiling": "string",
  • "ai_provider_access": "string",
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "dataset_id": "string",
  • "name": "string",
  • "description": "",
  • "root_path": "",
  • "enabled": true,
  • "visibility": "string",
  • "data_classification": "private",
  • "allowed_users": [
    ],
  • "allowed_groups": [
    ],
  • "query_granularity_ceiling": "summary",
  • "ai_provider_access": "detailed_allowed",
  • "created_by": "",
  • "created_at": "",
  • "updated_at": "",
  • "query_store_status": { }
}

Prepare dataset DuckDB store

Builds or rebuilds the admin-managed DuckDB store for one dataset. Admin-only.

path Parameters
dataset_id
required
string (Dataset Id)

Responses

Response samples

Content type
application/json
{
  • "dataset_id": "string",
  • "name": "string",
  • "description": "",
  • "root_path": "",
  • "enabled": true,
  • "visibility": "string",
  • "data_classification": "private",
  • "allowed_users": [
    ],
  • "allowed_groups": [
    ],
  • "query_granularity_ceiling": "summary",
  • "ai_provider_access": "detailed_allowed",
  • "created_by": "",
  • "created_at": "",
  • "updated_at": "",
  • "query_store_status": { }
}

patients

Patient lists, patient timelines, dashboard summaries, and cohort count helpers.

List patient summaries

Returns patient-level summaries for the active dataset or workspace scope.

query Parameters
dataset_id
string (Dataset Id)
Default: ""
data_dir
string (Data Dir)
Default: "/path/to/cohortome/default_dataset"

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a patient context

Returns the normalized clinical context for a single patient identifier.

path Parameters
patient_id
required
string (Patient Id)
query Parameters
dataset_id
string (Dataset Id)
Default: ""
data_dir
string (Data Dir)
Default: "/path/to/cohortome/default_dataset"

Responses

Response samples

Content type
application/json
{ }

Get a patient workspace view

Returns the timeline-oriented patient workspace payload used by the patient detail view.

path Parameters
patient_id
required
string (Patient Id)
query Parameters
dataset_id
string (Dataset Id)
Default: ""
data_dir
string (Data Dir)
Default: "/path/to/cohortome/default_dataset"

Responses

Response samples

Content type
application/json
{ }

Count medications in the workspace

Returns medication counts derived from the active workspace.

query Parameters
dataset_id
string (Dataset Id)
Default: ""
data_dir
string (Data Dir)
Default: "/path/to/cohortome/default_dataset"

Responses

Response samples

Content type
application/json
[
  • { }
]

Count diseases in the workspace

Returns disease counts derived from the active workspace.

query Parameters
dataset_id
string (Dataset Id)
Default: ""
data_dir
string (Data Dir)
Default: "/path/to/cohortome/default_dataset"

Responses

Response samples

Content type
application/json
[
  • { }
]

Build a medication workspace

Returns the deterministic medication-matched workspace subset for a single medication label.

query Parameters
medication
required
string (Medication)
dataset_id
string (Dataset Id)
Default: ""
data_dir
string (Data Dir)
Default: "/path/to/cohortome/default_dataset"

Responses

Response samples

Content type
application/json
{ }

Get the dashboard summary

Returns the dashboard summary payload used by the clinical and assay overview panels.

query Parameters
dataset_id
string (Dataset Id)
Default: ""
data_dir
string (Data Dir)
Default: "/path/to/cohortome/default_dataset"

Responses

Response samples

Content type
application/json
{ }

query

Deterministic and LLM-assisted natural-language workspace queries.

Run a simple GET workspace query

Executes a lightweight workspace query using query-string parameters. Prefer POST /query for full prompt history and planner mode control.

query Parameters
q
required
string (Q)
dataset_id
string (Dataset Id)
Default: ""
data_dir
string (Data Dir)
Default: "/path/to/cohortome/default_dataset"

Responses

Response samples

Content type
application/json
{ }

Run a workspace query

Executes a deterministic and/or LLM-assisted natural-language query against the active workspace.

Request Body schema: application/json
required
q
required
string (Q)

Natural-language workspace query.

dataset_id
string (Dataset Id)
Default: ""

Dataset ID or multi-dataset scope ID to query against.

data_dir
string (Data Dir)
Default: "/path/to/cohortome/default_dataset"

Manual dataset directory fallback. Prefer dataset_id.

query_mode
string (Query Mode)
Default: "auto"

Query execution mode. Supported values include auto and planner_only.

granularity_mode
string (Granularity Mode)
Default: "detailed"

Disclosure mode requested by the Query UI. Supported values currently include summary and detailed.

Array of objects (History)
scoped_patient_ids
Array of strings (Scoped Patient Ids)

Optional prior subset patient IDs carried as app-level conversational scope for follow-up queries.

scoped_record_ids
Array of strings (Scoped Record Ids)

Optional prior subset sample or record IDs carried as app-level conversational scope.

scoped_id_type
string (Scoped Id Type)
Default: "patient"

The primary ID level used by the carried scoped context.

Responses

Request samples

Content type
application/json
{
  • "q": "How many patients take biologics in this workspace?",
  • "dataset_id": "",
  • "data_dir": "/path/to/cohortome/default_dataset",
  • "query_mode": "auto",
  • "granularity_mode": "detailed",
  • "history": [
    ],
  • "scoped_patient_ids": [
    ],
  • "scoped_record_ids": [
    ],
  • "scoped_id_type": "patient"
}

Response samples

Content type
application/json
{ }

analysis

Clinical, assay, imaging, and multimodal workspace analysis plus saved analysis sessions.

List curated analysis catalog entries

Returns curated analysis definitions plus computed availability for the current workspace.

query Parameters
dataset_id
string (Dataset Id)
Default: ""
data_dir
string (Data Dir)
Default: "/path/to/cohortome/default_dataset"

Responses

Response samples

Content type
application/json
{ }

Run a workspace analysis

Executes clinical or assay analysis over the active workspace or selected saved cohorts.

Request Body schema: application/json
required
prompt
required
string (Prompt)

Natural-language analysis prompt.

catalog_item_id
string (Catalog Item Id)
Default: ""

Optional Analysis Catalog item identifier used for structured curated analyses.

analysis_session_id
string (Analysis Session Id)
Default: ""

Current Analysis session identifier used to associate queued jobs back to the active session.

dataset_id
string (Dataset Id)
Default: ""

Dataset ID or multi-dataset scope ID for the analysis workspace.

assay_id
string (Assay Id)
Default: ""

Selected assay identifier for curated analyses that require one explicit transcriptomics source.

data_dir
string (Data Dir)
Default: "/path/to/cohortome/default_dataset"

Manual dataset directory fallback. Prefer dataset_id.

selected_patient_ids
string (Selected Patient Ids)
Default: ""

Comma-separated scope IDs for cohort A. May contain sample or patient IDs depending on the source tab.

scope_metadata
object (Scope Metadata)

Saved-cohort-shaped metadata for the Cohort A selection, including sample IDs, patient IDs, and source.

compare_mode
boolean (Compare Mode)
Default: false

Whether to run a compare-mode analysis using cohort A vs cohort B.

compare_selected_patient_ids
string (Compare Selected Patient Ids)
Default: ""

Comma-separated scope IDs for cohort B when compare_mode is enabled.

compare_scope_metadata
object (Compare Scope Metadata)

Saved-cohort-shaped metadata for the Cohort B selection.

llm_only
boolean (Llm Only)
Default: false

Force LLM-only analysis mode.

deterministic_only
boolean (Deterministic Only)
Default: false

Force deterministic-only analysis mode.

Array of objects (History)

Responses

Request samples

Content type
application/json
{
  • "prompt": "Summarize the main workspace patterns and tell me what stands out.",
  • "catalog_item_id": "",
  • "analysis_session_id": "",
  • "dataset_id": "",
  • "assay_id": "",
  • "data_dir": "/path/to/cohortome/default_dataset",
  • "selected_patient_ids": "",
  • "scope_metadata": { },
  • "compare_mode": false,
  • "compare_selected_patient_ids": "",
  • "compare_scope_metadata": { },
  • "llm_only": false,
  • "deterministic_only": false,
  • "history": [
    ]
}

Response samples

Content type
application/json
{ }

List saved analysis sessions

Returns persisted analysis sessions for the current user.

Responses

Response samples

Content type
application/json
{ }

Create or update an analysis session

Persists analysis session state, including prompt draft, scopes, and prior turns.

Request Body schema: application/json
required
id
required
string (Id)

Client-generated analysis session identifier.

title
string (Title)
Default: ""

Optional user-facing session title.

dataset_id
string (Dataset Id)
Default: ""

Dataset ID or multi-dataset scope ID for the session.

data_dir
string (Data Dir)
Default: "/path/to/cohortome/default_dataset"

Manual dataset directory fallback. Prefer dataset_id.

workspace_fingerprint
object (Workspace Fingerprint)

Workspace fingerprint snapshot captured when the session was first bound.

catalog_item_id
string (Catalog Item Id)
Default: ""

Selected Analysis Catalog item for this session, if any.

prompt_draft
string (Prompt Draft)
Default: ""

Current draft prompt stored for the session.

context_mode
string (Context Mode)
Default: "workspace"
Enum: "workspace" "general"

Whether the saved composer is using workspace context or general knowledge.

scope
string (Scope)
Default: ""

Comma-separated scope IDs for cohort A.

scope_metadata
object (Scope Metadata)

Saved-cohort-shaped metadata for Cohort A.

saved_cohort_id_a
string (Saved Cohort Id A)
Default: ""

Saved cohort ID currently assigned to cohort A, if any.

compare_mode
boolean (Compare Mode)
Default: false

Whether the session is in compare mode.

compare_scope
string (Compare Scope)
Default: ""

Comma-separated scope IDs for cohort B.

compare_scope_metadata
object (Compare Scope Metadata)

Saved-cohort-shaped metadata for Cohort B.

saved_cohort_id_b
string (Saved Cohort Id B)
Default: ""

Saved cohort ID currently assigned to cohort B, if any.

history
Array of objects (History)
turns
Array of objects (Turns)
updated_at
string (Updated At)
Default: ""

Last-updated timestamp in ISO 8601 format.

created_at
string (Created At)
Default: ""

Creation timestamp in ISO 8601 format.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "title": "",
  • "dataset_id": "",
  • "data_dir": "/path/to/cohortome/default_dataset",
  • "workspace_fingerprint": { },
  • "catalog_item_id": "",
  • "prompt_draft": "",
  • "context_mode": "workspace",
  • "scope": "",
  • "scope_metadata": { },
  • "saved_cohort_id_a": "",
  • "compare_mode": false,
  • "compare_scope": "",
  • "compare_scope_metadata": { },
  • "saved_cohort_id_b": "",
  • "history": [
    ],
  • "turns": [
    ],
  • "updated_at": "",
  • "created_at": ""
}

Response samples

Content type
application/json
{ }

Rename an analysis session

Updates the title of a saved analysis session.

path Parameters
session_id
required
string (Session Id)
Request Body schema: application/json
required
title
string (Title)
Default: ""

New title for the analysis session.

Responses

Request samples

Content type
application/json
{
  • "title": ""
}

Response samples

Content type
application/json
{ }

Delete an analysis session

Deletes a saved analysis session for the current user.

path Parameters
session_id
required
string (Session Id)
query Parameters
delete_generated_data
boolean (Delete Generated Data)
Default: false
keep_generated_jobs
boolean (Keep Generated Jobs)
Default: false

Responses

Response samples

Content type
application/json
{
  • "deleted": true,
  • "id": "",
  • "deleted_count": 0,
  • "deleted_generated_data": false,
  • "related_job_count": 0,
  • "deleted_job_count": 0,
  • "kept_job_count": 0,
  • "skipped_active_count": 0
}

cohorts

Saved cohort persistence and cohort-scoped handoff utilities.

List saved cohorts

Returns saved cohorts for the current user within the active dataset workspace.

query Parameters
dataset_id
string (Dataset Id)
Default: ""
data_dir
string (Data Dir)
Default: "/path/to/cohortome/default_dataset"

Responses

Response samples

Content type
application/json
{
  • "cohorts": [
    ]
}

Create a saved cohort

Persists a saved cohort containing canonical sample IDs and derived patient IDs.

Request Body schema: application/json
required
name
string (Name)
Default: ""

User-facing saved cohort name.

dataset_id
string (Dataset Id)
Default: ""

Dataset ID or multi-dataset scope ID where the cohort was created.

dataset_ids
Array of strings (Dataset Ids)
data_dir
string (Data Dir)
Default: "/path/to/cohortome/default_dataset"

Manual dataset directory fallback. Prefer dataset_id.

sample_ids
Array of strings (Sample Ids)

Canonical sample/record IDs stored for the cohort.

patient_ids
Array of strings (Patient Ids)

Derived patient IDs stored alongside the cohort.

id_type
string (Id Type)
Default: "sample"

Canonical ID level used by the cohort payload.

source_kind
string (Source Kind)
Default: "manual"

How the cohort was created, for example manual or query.

source_prompt
string (Source Prompt)
Default: ""

Source prompt when the cohort came from Query.

Responses

Request samples

Content type
application/json
{
  • "name": "",
  • "dataset_id": "",
  • "dataset_ids": [
    ],
  • "data_dir": "/path/to/cohortome/default_dataset",
  • "sample_ids": [
    ],
  • "patient_ids": [
    ],
  • "id_type": "sample",
  • "source_kind": "manual",
  • "source_prompt": ""
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "dataset_id": "",
  • "dataset_ids": [
    ],
  • "data_dir": "",
  • "id_type": "sample",
  • "sample_ids": [
    ],
  • "patient_ids": [
    ],
  • "sample_count": 0,
  • "patient_count": 0,
  • "is_full_dataset": false,
  • "source": {
    },
  • "created_at": "",
  • "updated_at": ""
}

Delete a saved cohort

Deletes a saved cohort owned by the current user.

path Parameters
cohort_id
required
string (Cohort Id)

Responses

Response samples

Content type
application/json
{
  • "deleted": true,
  • "id": "",
  • "deleted_count": 0,
  • "deleted_generated_data": false,
  • "related_job_count": 0,
  • "deleted_job_count": 0,
  • "kept_job_count": 0,
  • "skipped_active_count": 0
}

assays

Multimodal assay inventory, feature matrices, DICOM metadata, and expression summaries.

List assays in scope

Returns assay datasets visible in the current workspace.

query Parameters
dataset_id
string (Dataset Id)
Default: ""
data_dir
string (Data Dir)
Default: "/path/to/cohortome/default_dataset"

Responses

Response samples

Content type
application/json
{
  • "datasets": [
    ]
}

Get multimodal analysis readiness

Returns workspace-level multimodal coverage, overlap, linkage issues, and deterministic next-step suggestions.

query Parameters
dataset_id
string (Dataset Id)
Default: ""
data_dir
string (Data Dir)
Default: "/path/to/cohortome/default_dataset"

Responses

Response samples

Content type
application/json
{
  • "workspace": { },
  • "modalities": [
    ],
  • "pairwise_overlaps": [
    ],
  • "issues": [
    ],
  • "suggestions": [
    ]
}

Build multimodal feature matrix preview

Returns a bounded sample-level multimodal matrix preview with clinical covariates, selected assay features, DICOM viewer metadata, missingness, and provenance.

query Parameters
dataset_id
string (Dataset Id)
Default: ""
data_dir
string (Data Dir)
Default: "/path/to/cohortome/default_dataset"
max_features_per_dataset
integer (Max Features Per Dataset)
Default: 3
max_rows
integer (Max Rows)
Default: 25

Responses

Response samples

Content type
application/json
{
  • "metadata": { },
  • "columns": [
    ],
  • "rows": [
    ],
  • "missingness": [
    ],
  • "feature_groups": [
    ],
  • "warnings": [
    ]
}

Search features in an assay

Returns gene identifiers for a selected assay with optional search and limit filtering.

query Parameters
assay_id
required
string (Assay Id)
dataset_id
string (Dataset Id)
Default: ""
data_dir
string (Data Dir)
Default: "/path/to/cohortome/default_dataset"
q
string (Q)
Default: ""
limit
integer (Limit)
Default: 50

Responses

Response samples

Content type
application/json
{ }

Summarize assay expression

Returns scoped gene expression summaries for one assay, optionally comparing cohort A and cohort B.

Request Body schema: application/json
required
assay_id
required
string (Assay Id)

Assay identifier to inspect.

gene_id
required
string (Gene Id)

Gene identifier or symbol to summarize.

dataset_id
string (Dataset Id)
Default: ""

Dataset ID or multi-dataset scope ID for assay lookups.

data_dir
string (Data Dir)
Default: "/path/to/cohortome/default_dataset"

Manual dataset directory fallback. Prefer dataset_id.

selected_patient_ids
string (Selected Patient Ids)
Default: ""

Optional comma-separated scope IDs for cohort A filtering.

compare_selected_patient_ids
string (Compare Selected Patient Ids)
Default: ""

Optional comma-separated scope IDs for cohort B filtering.

Responses

Request samples

Content type
application/json
{
  • "assay_id": "string",
  • "gene_id": "string",
  • "dataset_id": "",
  • "data_dir": "/path/to/cohortome/default_dataset",
  • "selected_patient_ids": "",
  • "compare_selected_patient_ids": ""
}

Response samples

Content type
application/json
{ }

dicom

DICOM study discovery and OHIF launch integration.

List DICOM studies in scope

Returns DICOM studies configured for the current workspace with OHIF launch URLs.

query Parameters
dataset_id
string (Dataset Id)
Default: ""
data_dir
string (Data Dir)
Default: "/path/to/cohortome/default_dataset"

Responses

Response samples

Content type
application/json
{
  • "enabled": false,
  • "studies": [
    ]
}

Get DICOM integration status

Returns DICOM/OHIF/Orthanc configuration status for the current workspace.

query Parameters
dataset_id
string (Dataset Id)
Default: ""
data_dir
string (Data Dir)
Default: "/path/to/cohortome/default_dataset"

Responses

Response samples

Content type
application/json
{
  • "enabled": false,
  • "study_count": 0
}

pheno-ranker

Pheno-Ranker planning, execution, result download, and explanation endpoints.

Run Pheno-Ranker

Runs Pheno-Ranker for the active workspace using either patient mode or cohort mode.

Request Body schema: application/json
required
prompt
string (Prompt)
Default: ""

Current Pheno-Ranker prompt used for run metadata and queued job labels.

action
string (Action)
Default: "compare"

Pheno-Ranker action, typically compare.

mode
string (Mode)
Default: "cohort"

Pheno-Ranker mode, such as cohort or patient.

dataset_id
string (Dataset Id)
Default: ""

Dataset ID or multi-dataset scope ID for the workspace.

data_dir
string (Data Dir)
Default: "/path/to/cohortome/default_dataset"

Manual dataset directory fallback. Prefer dataset_id.

patient_id
string (Patient Id)
Default: ""

Single target sample/patient ID for patient mode.

selected_patient_ids
string (Selected Patient Ids)
Default: ""

Comma-separated scope IDs for cohort mode.

selected_saved_cohort_ids
Array of strings (Selected Saved Cohort Ids)
disease_filter
string (Disease Filter)
Default: ""

Optional disease label filter for eligible reference files.

include_terms
Array of strings (Include Terms)
exclude_terms
Array of strings (Exclude Terms)
similarity_metric_cohort
string (Similarity Metric Cohort)
Default: ""

Similarity metric to use for cohort comparison.

sort_by
string (Sort By)
Default: ""

Sort strategy for rank output.

max_out
integer (Max Out)
Default: 10

Maximum number of ranked output matches to keep.

align
boolean (Align)
Default: true

Whether to compute term alignment details.

render_heatmap
boolean (Render Heatmap)
Default: true

Whether to generate the interactive heatmap artifact.

render_mds
boolean (Render Mds)
Default: true

Whether to generate the interactive MDS artifact.

render_graph
boolean (Render Graph)
Default: true

Whether to generate the interactive Cytoscape graph artifact.

Graph Min Weight (number) or Graph Min Weight (null) (Graph Min Weight)

Optional minimum edge weight for Pheno-Ranker graph export.

Graph Max Weight (number) or Graph Max Weight (null) (Graph Max Weight)

Optional maximum edge weight for Pheno-Ranker graph export.

granularity_ceiling
string (Granularity Ceiling)
Default: "detailed"

Internal workspace ceiling used to guard Pheno-Ranker access.

ai_provider_access
string (Ai Provider Access)
Default: "detailed_allowed"

Effective AI provider policy used for Pheno-Ranker planner/explanation paths.

Responses

Request samples

Content type
application/json
{
  • "prompt": "",
  • "action": "compare",
  • "mode": "cohort",
  • "dataset_id": "",
  • "data_dir": "/path/to/cohortome/default_dataset",
  • "patient_id": "",
  • "selected_patient_ids": "",
  • "selected_saved_cohort_ids": [
    ],
  • "disease_filter": "",
  • "include_terms": [
    ],
  • "exclude_terms": [
    ],
  • "similarity_metric_cohort": "",
  • "sort_by": "",
  • "max_out": 10,
  • "align": true,
  • "render_heatmap": true,
  • "render_mds": true,
  • "render_graph": true,
  • "graph_min_weight": 0,
  • "graph_max_weight": 0,
  • "granularity_ceiling": "detailed",
  • "ai_provider_access": "detailed_allowed"
}

Response samples

Content type
application/json
{ }

Plan a Pheno-Ranker run

Converts a natural-language request into a normalized Pheno-Ranker execution plan.

Request Body schema: application/json
required
text
required
string (Text)

Natural-language instruction to convert into a Pheno-Ranker plan.

dataset_id
string (Dataset Id)
Default: ""

Dataset ID or multi-dataset scope ID for planning.

data_dir
string (Data Dir)
Default: "/path/to/cohortome/default_dataset"

Manual dataset directory fallback. Prefer dataset_id.

selected_patient_ids
string (Selected Patient Ids)
Default: ""

Optional comma-separated scope IDs already selected in the UI.

Responses

Request samples

Content type
application/json
{
  • "text": "string",
  • "dataset_id": "",
  • "data_dir": "/path/to/cohortome/default_dataset",
  • "selected_patient_ids": ""
}

Response samples

Content type
application/json
{ }

List Pheno-Ranker scope IDs

Returns the sample-level identifiers currently available to Pheno-Ranker in the active workspace.

query Parameters
dataset_id
string (Dataset Id)
Default: ""
data_dir
string (Data Dir)
Default: "/path/to/cohortome/default_dataset"

Responses

Response samples

Content type
application/json
{ }

Download a Pheno-Ranker result file

Returns a generated Pheno-Ranker result artifact for a specific job.

path Parameters
job_id
required
string (Job Id)
filename
required
string (Filename)

Responses

Response samples

Content type
application/json
null

Get alignment details for one match

Returns the term-level alignment details between a target and a selected Pheno-Ranker match.

path Parameters
job_id
required
string (Job Id)
query Parameters
reference_id
required
string (Reference Id)
target_id
string (Target Id)
Default: ""

Responses

Response samples

Content type
application/json
{ }

Explain Pheno-Ranker results deterministically

Builds a deterministic summary from the top ranked Pheno-Ranker matches.

path Parameters
job_id
required
string (Job Id)
query Parameters
top_n
integer (Top N)
Default: 3

Responses

Response samples

Content type
application/json
{ }

Explain Pheno-Ranker results with the LLM

Builds an LLM-assisted explanation from the top ranked Pheno-Ranker matches.

path Parameters
job_id
required
string (Job Id)
query Parameters
top_n
integer (Top N)
Default: 3

Responses

Response samples

Content type
application/json
{ }

llm

Ask a general-knowledge question

Sends the prompt and recent General-question turns to the selected model provider without workspace or dataset context.

Request Body schema: application/json
required
prompt
required
string (Prompt) [ 1 .. 12000 ] characters

General-knowledge question sent without workspace or dataset context.

Array of objects (History)

Recent turns from General question mode only.

Responses

Request samples

Content type
application/json
{
  • "prompt": "What is aspirin?",
  • "history": [
    ]
}

Response samples

Content type
application/json
{ }

jobs

List recent background jobs

Returns recent background jobs visible to the current user across supported product surfaces.

Responses

Response samples

Content type
application/json
{ }

Get one background job

Returns detailed status plus the completed payload for one background job visible to the current user.

path Parameters
job_id
required
string (Job Id)

Responses

Response samples

Content type
application/json
{ }

Delete one terminal job

Deletes one completed, failed, or cancelled job and its generated artifacts for the current user.

path Parameters
job_id
required
string (Job Id)

Responses

Response samples

Content type
application/json
{
  • "deleted": true,
  • "id": "",
  • "deleted_count": 0,
  • "deleted_generated_data": false,
  • "related_job_count": 0,
  • "deleted_job_count": 0,
  • "kept_job_count": 0,
  • "skipped_active_count": 0
}

Download one background job artifact

Returns one persisted artifact for a background job visible to the current user.

path Parameters
job_id
required
string (Job Id)
filename
required
string (Filename)

Responses

Response samples

Content type
application/json
null

List generated run history

Returns all generated analysis and Pheno-Ranker runs visible to the current user.

Responses

Response samples

Content type
application/json
{ }

Delete terminal generated runs

Deletes completed, failed, or cancelled generated runs and artifacts owned by the current user. Active runs are skipped.

Responses

Response samples

Content type
application/json
{
  • "deleted": true,
  • "id": "",
  • "deleted_count": 0,
  • "deleted_generated_data": false,
  • "related_job_count": 0,
  • "deleted_job_count": 0,
  • "kept_job_count": 0,
  • "skipped_active_count": 0
}

Delete one generated run

Deletes one completed, failed, or cancelled generated run and its artifacts for the current user.

path Parameters
job_id
required
string (Job Id)

Responses

Response samples

Content type
application/json
{
  • "deleted": true,
  • "id": "",
  • "deleted_count": 0,
  • "deleted_generated_data": false,
  • "related_job_count": 0,
  • "deleted_job_count": 0,
  • "kept_job_count": 0,
  • "skipped_active_count": 0
}