openapi: 3.1.0 info: title: COHORTome API summary: Clinical and multimodal cohort exploration and analysis API. description: >- COHORTome exposes a browser-facing API for governed multi-dataset workspaces, longitudinal clinical and assay exploration, cohort discovery, and traceable analysis. version: 0.1.0 paths: /: get: tags: - ui summary: Render the main application shell description: >- Serves the COHORTome HTML shell with the current branding and authenticated user context. operationId: index__get responses: '200': description: Successful Response content: text/html: schema: type: string /patients: get: tags: - patients summary: List patient summaries description: >- Returns patient-level summaries for the active dataset or workspace scope. operationId: get_patients_patients_get parameters: - name: dataset_id in: query required: false schema: type: string default: '' title: Dataset Id - name: data_dir in: query required: false schema: type: string default: /path/to/cohortome/default_dataset title: Data Dir responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/PatientSummaryResponse' title: Response Get Patients Patients Get '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /patients/{patient_id}: get: tags: - patients summary: Get a patient context description: Returns the normalized clinical context for a single patient identifier. operationId: get_patient_patients__patient_id__get parameters: - name: patient_id in: path required: true schema: type: string title: Patient Id - name: dataset_id in: query required: false schema: type: string default: '' title: Dataset Id - name: data_dir in: query required: false schema: type: string default: /path/to/cohortome/default_dataset title: Data Dir responses: '200': description: Successful Response content: application/json: schema: type: object title: Response Get Patient Patients Patient Id Get '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /patients/{patient_id}/workspace: get: tags: - patients summary: Get a patient workspace view description: >- Returns the timeline-oriented patient workspace payload used by the patient detail view. operationId: get_patient_workspace_patients__patient_id__workspace_get parameters: - name: patient_id in: path required: true schema: type: string title: Patient Id - name: dataset_id in: query required: false schema: type: string default: '' title: Dataset Id - name: data_dir in: query required: false schema: type: string default: /path/to/cohortome/default_dataset title: Data Dir responses: '200': description: Successful Response content: application/json: schema: type: object title: >- Response Get Patient Workspace Patients Patient Id Workspace Get '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /cohorts/medications: get: tags: - patients summary: Count medications in the workspace description: Returns medication counts derived from the active workspace. operationId: get_medication_counts_cohorts_medications_get parameters: - name: dataset_id in: query required: false schema: type: string default: '' title: Dataset Id - name: data_dir in: query required: false schema: type: string default: /path/to/cohortome/default_dataset title: Data Dir responses: '200': description: Successful Response content: application/json: schema: type: array items: type: object title: Response Get Medication Counts Cohorts Medications Get '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /cohorts/diseases: get: tags: - patients summary: Count diseases in the workspace description: Returns disease counts derived from the active workspace. operationId: get_disease_counts_cohorts_diseases_get parameters: - name: dataset_id in: query required: false schema: type: string default: '' title: Dataset Id - name: data_dir in: query required: false schema: type: string default: /path/to/cohortome/default_dataset title: Data Dir responses: '200': description: Successful Response content: application/json: schema: type: array items: type: object title: Response Get Disease Counts Cohorts Diseases Get '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /cohorts/medications/search: get: tags: - patients summary: Build a medication workspace description: >- Returns the deterministic medication-matched workspace subset for a single medication label. operationId: search_medication_cohort_cohorts_medications_search_get parameters: - name: medication in: query required: true schema: type: string title: Medication - name: dataset_id in: query required: false schema: type: string default: '' title: Dataset Id - name: data_dir in: query required: false schema: type: string default: /path/to/cohortome/default_dataset title: Data Dir responses: '200': description: Successful Response content: application/json: schema: type: object title: >- Response Search Medication Cohort Cohorts Medications Search Get '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /query: get: tags: - query summary: Run a simple GET workspace query description: >- Executes a lightweight workspace query using query-string parameters. Prefer POST /query for full prompt history and planner mode control. operationId: query_app_query_get parameters: - name: q in: query required: true schema: type: string title: Q - name: dataset_id in: query required: false schema: type: string default: '' title: Dataset Id - name: data_dir in: query required: false schema: type: string default: /path/to/cohortome/default_dataset title: Data Dir responses: '200': description: Successful Response content: application/json: schema: type: object title: Response Query App Query Get '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' post: tags: - query summary: Run a workspace query description: >- Executes a deterministic and/or LLM-assisted natural-language query against the active workspace. operationId: query_app_post_query_post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/QueryRequest' responses: '200': description: Successful Response content: application/json: schema: type: object title: Response Query App Post Query Post '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /lm-status: get: tags: - auth summary: Inspect configured LM status description: >- Returns whether LM Studio is enabled plus the current model and base URL. operationId: get_lm_status_lm_status_get responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/LmStatusResponse' /lm-providers: get: tags: - auth summary: Inspect approved LLM providers description: >- Admin-only registry and health view for approved OpenAI-compatible LLM endpoints. operationId: get_lm_providers_lm_providers_get responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/LmProvidersResponse' post: tags: - auth summary: Create a managed LLM provider description: >- Persists an OpenAI-compatible provider in protected runtime state. The API key is write-only. operationId: create_lm_provider_lm_providers_post requestBody: content: application/json: schema: $ref: '#/components/schemas/LmProviderCreateRequest' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/LmProviderResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /lm-providers/{provider_id}: patch: tags: - auth summary: Update a managed LLM provider description: >- Updates a runtime-managed provider. Environment-defined providers are read-only. operationId: update_lm_provider_lm_providers__provider_id__patch parameters: - name: provider_id in: path required: true schema: type: string title: Provider Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LmProviderUpdateRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/LmProviderResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' delete: tags: - auth summary: Delete a managed LLM provider description: >- Deletes a runtime-managed provider. Environment-defined providers cannot be deleted. operationId: delete_lm_provider_lm_providers__provider_id__delete parameters: - name: provider_id in: path required: true schema: type: string title: Provider Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/DeleteResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /lm-providers/{provider_id}/test: post: tags: - auth summary: Test an LLM provider description: >- Runs an admin-only models-endpoint health check without exposing the configured API key. operationId: test_lm_provider_route_lm_providers__provider_id__test_post parameters: - name: provider_id in: path required: true schema: type: string title: Provider Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/LmProviderResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /auth/me: get: tags: - auth summary: Get current authentication state description: Returns the current local-auth session state and visible user identity. operationId: get_auth_status_auth_me_get responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AuthStatusResponse' /auth/login: get: tags: - auth summary: Start external OIDC login description: Redirects to the configured OIDC provider when COHORTOME_AUTH_MODE=oidc. operationId: login_oidc_auth_login_get responses: '200': description: Successful Response content: application/json: schema: {} post: tags: - auth summary: Log in with local credentials description: Authenticates a local user and creates a session-backed login. operationId: login_local_auth_login_post requestBody: content: application/json: schema: $ref: '#/components/schemas/LoginRequest' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AuthStatusResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /auth/oidc/callback: get: tags: - auth summary: Complete external OIDC login description: >- Handles the OIDC authorization-code callback and maps the external identity to a local COHORTome user. operationId: oidc_callback_auth_oidc_callback_get parameters: - name: code in: query required: false schema: type: string default: '' title: Code - name: state in: query required: false schema: type: string default: '' title: State - name: error in: query required: false schema: type: string default: '' title: Error responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /auth/logout: post: tags: - auth summary: Log out the current user description: Clears the local session for the current user. operationId: logout_local_auth_logout_post responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AuthStatusResponse' /auth/password-reset/request: post: tags: - auth summary: Request a local password reset description: >- Sends a password reset email when SMTP-backed local reset is configured. The response does not reveal whether the account exists. operationId: request_auth_password_reset_auth_password_reset_request_post requestBody: content: application/json: schema: $ref: '#/components/schemas/AuthPasswordResetStartRequest' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AuthPasswordResetResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /auth/password-reset/confirm: post: tags: - auth summary: Confirm a local password reset description: Consumes a password reset token and replaces the local password. operationId: confirm_auth_password_reset_auth_password_reset_confirm_post requestBody: content: application/json: schema: $ref: '#/components/schemas/AuthPasswordResetConfirmRequest' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AuthPasswordResetResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /auth/debug: get: tags: - auth summary: Inspect auth diagnostics description: >- Returns local-auth diagnostics useful during development and deployment troubleshooting. operationId: get_auth_diagnostics_auth_debug_get responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AuthDiagnosticsResponse' /auth/users: get: tags: - auth summary: List visible local users description: >- Returns local users and groups. When auth is enabled, this endpoint is admin-only. operationId: get_auth_users_auth_users_get responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AuthUsersResponse' post: tags: - auth summary: Create a local user description: >- Creates a persisted local user with application role and groups. Admin-only when auth is enabled. operationId: create_auth_user_auth_users_post requestBody: content: application/json: schema: $ref: '#/components/schemas/AuthUserCreateRequest' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AuthUserResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /auth/users/{username}: patch: tags: - auth summary: Update a local user description: >- Updates display name, role, groups, or enabled state for a local user. Admin-only when auth is enabled. operationId: update_auth_user_auth_users__username__patch parameters: - name: username in: path required: true schema: type: string title: Username requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AuthUserUpdateRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AuthUserResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' delete: tags: - auth summary: Delete a local user description: Deletes a persisted local user. Admin-only when auth is enabled. operationId: delete_auth_user_auth_users__username__delete parameters: - name: username in: path required: true schema: type: string title: Username responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/DeleteResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /auth/users/{username}/password: post: tags: - auth summary: Reset a local user password description: Replaces the password for a local user. Admin-only when auth is enabled. operationId: reset_auth_user_password_auth_users__username__password_post parameters: - name: username in: path required: true schema: type: string title: Username requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AuthPasswordResetRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AuthUserResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /user-settings: get: tags: - auth summary: Get user UI settings description: Returns persisted UI preferences for the current user. operationId: get_user_settings_user_settings_get responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/UserSettingsResponse' patch: tags: - auth summary: Update user UI settings description: Persists UI preferences for the current user. operationId: update_user_settings_user_settings_patch requestBody: content: application/json: schema: $ref: '#/components/schemas/UserSettingsUpdateRequest' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/UserSettingsResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /datasets: get: tags: - datasets summary: List authorized datasets description: >- Returns datasets visible to the current user plus the currently active workspace selection. operationId: get_datasets_datasets_get responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/DatasetsResponse' post: tags: - datasets summary: Register a dataset description: Creates a new dataset registry entry. Admin-only. operationId: create_dataset_route_datasets_post requestBody: content: application/json: schema: $ref: '#/components/schemas/DatasetRegistrationRequest' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/DatasetRecordResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /datasets/select: post: tags: - datasets summary: Select the active dataset workspace description: >- Applies one or more authorized dataset IDs as the current workspace for the authenticated user. operationId: select_dataset_datasets_select_post requestBody: content: application/json: schema: $ref: '#/components/schemas/DatasetSelectionRequest' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/DatasetSelectionResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /datasets/{dataset_id}: patch: tags: - datasets summary: Update dataset metadata and access description: Updates dataset metadata, visibility, or access policy. Admin-only. operationId: update_dataset_route_datasets__dataset_id__patch parameters: - name: dataset_id in: path required: true schema: type: string title: Dataset Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DatasetUpdateRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/DatasetRecordResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /datasets/{dataset_id}/prepare-store: post: tags: - datasets summary: Prepare dataset DuckDB store description: >- Builds or rebuilds the admin-managed DuckDB store for one dataset. Admin-only. operationId: prepare_dataset_route_datasets__dataset_id__prepare_store_post parameters: - name: dataset_id in: path required: true schema: type: string title: Dataset Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/DatasetRecordResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /branding/logo: get: tags: - ui summary: Serve the configured branding logo description: Returns the current instance branding logo file if one is configured. operationId: get_branding_logo_branding_logo_get responses: '200': description: Successful Response content: application/json: schema: {} /saved-cohorts: get: tags: - cohorts summary: List saved cohorts description: >- Returns saved cohorts for the current user within the active dataset workspace. operationId: get_saved_cohorts_saved_cohorts_get parameters: - name: dataset_id in: query required: false schema: type: string default: '' title: Dataset Id - name: data_dir in: query required: false schema: type: string default: /path/to/cohortome/default_dataset title: Data Dir responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SavedCohortsResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' post: tags: - cohorts summary: Create a saved cohort description: >- Persists a saved cohort containing canonical sample IDs and derived patient IDs. operationId: create_saved_cohort_saved_cohorts_post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SavedCohortRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SavedCohortResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /saved-cohorts/{cohort_id}: delete: tags: - cohorts summary: Delete a saved cohort description: Deletes a saved cohort owned by the current user. operationId: remove_saved_cohort_saved_cohorts__cohort_id__delete parameters: - name: cohort_id in: path required: true schema: type: string title: Cohort Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/DeleteResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /user-data/analysis-sessions: delete: tags: - auth summary: Delete current user's analysis chats description: Deletes all saved analysis chats owned by the current user. operationId: delete_user_analysis_sessions_user_data_analysis_sessions_delete responses: '200': description: Successful Response content: application/json: schema: type: object title: >- Response Delete User Analysis Sessions User Data Analysis Sessions Delete /user-data/jobs: delete: tags: - auth summary: Delete current user's completed jobs description: >- Deletes terminal background jobs and generated artifacts owned by the current user. Active jobs are skipped. operationId: delete_user_completed_jobs_user_data_jobs_delete responses: '200': description: Successful Response content: application/json: schema: type: object title: Response Delete User Completed Jobs User Data Jobs Delete /user-data/saved-cohorts: delete: tags: - auth summary: Delete current user's saved cohorts description: >- Deletes saved cohorts owned by the current user when they are not referenced by saved analysis chats. operationId: delete_user_saved_cohorts_user_data_saved_cohorts_delete responses: '200': description: Successful Response content: application/json: schema: type: object title: >- Response Delete User Saved Cohorts User Data Saved Cohorts Delete /llm/general: post: tags: - llm summary: Ask a general-knowledge question description: >- Sends the prompt and recent General-question turns to the selected model provider without workspace or dataset context. operationId: general_llm_app_llm_general_post requestBody: content: application/json: schema: $ref: '#/components/schemas/GeneralLlmRequest' required: true responses: '200': description: Successful Response content: application/json: schema: type: object title: Response General Llm App Llm General Post '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /analysis/catalog: get: tags: - analysis summary: List curated analysis catalog entries description: >- Returns curated analysis definitions plus computed availability for the current workspace. operationId: get_analysis_catalog_analysis_catalog_get parameters: - name: dataset_id in: query required: false schema: type: string default: '' title: Dataset Id - name: data_dir in: query required: false schema: type: string default: /path/to/cohortome/default_dataset title: Data Dir responses: '200': description: Successful Response content: application/json: schema: type: object title: Response Get Analysis Catalog Analysis Catalog Get '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /analysis: post: tags: - analysis summary: Run a workspace analysis description: >- Executes clinical or assay analysis over the active workspace or selected saved cohorts. operationId: analysis_app_analysis_post requestBody: content: application/json: schema: $ref: '#/components/schemas/AnalysisRequest' required: true responses: '200': description: Successful Response content: application/json: schema: type: object title: Response Analysis App Analysis Post '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /jobs: get: tags: - jobs summary: List recent background jobs description: >- Returns recent background jobs visible to the current user across supported product surfaces. operationId: get_jobs_jobs_get responses: '200': description: Successful Response content: application/json: schema: type: object title: Response Get Jobs Jobs Get /jobs/{job_id}: get: tags: - jobs summary: Get one background job description: >- Returns detailed status plus the completed payload for one background job visible to the current user. operationId: get_job_jobs__job_id__get parameters: - name: job_id in: path required: true schema: type: string title: Job Id responses: '200': description: Successful Response content: application/json: schema: type: object title: Response Get Job Jobs Job Id Get '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' delete: tags: - jobs summary: Delete one terminal job description: >- Deletes one completed, failed, or cancelled job and its generated artifacts for the current user. operationId: remove_job_jobs__job_id__delete parameters: - name: job_id in: path required: true schema: type: string title: Job Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/DeleteResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /jobs/{job_id}/artifacts/{filename}: get: tags: - jobs summary: Download one background job artifact description: >- Returns one persisted artifact for a background job visible to the current user. operationId: get_job_artifact_jobs__job_id__artifacts__filename__get parameters: - name: job_id in: path required: true schema: type: string title: Job Id - name: filename in: path required: true schema: type: string title: Filename responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /run-history: get: tags: - jobs summary: List generated run history description: >- Returns all generated analysis and Pheno-Ranker runs visible to the current user. operationId: get_run_history_run_history_get responses: '200': description: Successful Response content: application/json: schema: type: object title: Response Get Run History Run History Get delete: tags: - jobs summary: Delete terminal generated runs description: >- Deletes completed, failed, or cancelled generated runs and artifacts owned by the current user. Active runs are skipped. operationId: delete_run_history_run_history_delete responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/DeleteResponse' /run-history/{job_id}: delete: tags: - jobs summary: Delete one generated run description: >- Deletes one completed, failed, or cancelled generated run and its artifacts for the current user. operationId: remove_run_history_item_run_history__job_id__delete parameters: - name: job_id in: path required: true schema: type: string title: Job Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/DeleteResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /assays: get: tags: - assays summary: List assays in scope description: Returns assay datasets visible in the current workspace. operationId: get_assay_datasets_assays_get parameters: - name: dataset_id in: query required: false schema: type: string default: '' title: Dataset Id - name: data_dir in: query required: false schema: type: string default: /path/to/cohortome/default_dataset title: Data Dir responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AssayDatasetsResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /assays/readiness: get: tags: - assays summary: Get multimodal analysis readiness description: >- Returns workspace-level multimodal coverage, overlap, linkage issues, and deterministic next-step suggestions. operationId: get_assay_readiness_assays_readiness_get parameters: - name: dataset_id in: query required: false schema: type: string default: '' title: Dataset Id - name: data_dir in: query required: false schema: type: string default: /path/to/cohortome/default_dataset title: Data Dir responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AssayReadinessResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /assays/matrix: get: tags: - assays summary: Build multimodal feature matrix preview description: >- Returns a bounded sample-level multimodal matrix preview with clinical covariates, selected assay features, DICOM viewer metadata, missingness, and provenance. operationId: get_assay_feature_matrix_assays_matrix_get parameters: - name: dataset_id in: query required: false schema: type: string default: '' title: Dataset Id - name: data_dir in: query required: false schema: type: string default: /path/to/cohortome/default_dataset title: Data Dir - name: max_features_per_dataset in: query required: false schema: type: integer default: 3 title: Max Features Per Dataset - name: max_rows in: query required: false schema: type: integer default: 25 title: Max Rows responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AssayFeatureMatrixResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /assays/features: get: tags: - assays summary: Search features in an assay description: >- Returns gene identifiers for a selected assay with optional search and limit filtering. operationId: get_assay_features_assays_features_get parameters: - name: assay_id in: query required: true schema: type: string title: Assay Id - name: dataset_id in: query required: false schema: type: string default: '' title: Dataset Id - name: data_dir in: query required: false schema: type: string default: /path/to/cohortome/default_dataset title: Data Dir - name: q in: query required: false schema: type: string default: '' title: Q - name: limit in: query required: false schema: type: integer default: 50 title: Limit responses: '200': description: Successful Response content: application/json: schema: type: object title: Response Get Assay Features Assays Features Get '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /assays/expression: post: tags: - assays summary: Summarize assay expression description: >- Returns scoped gene expression summaries for one assay, optionally comparing cohort A and cohort B. operationId: get_assay_expression_assays_expression_post requestBody: content: application/json: schema: $ref: '#/components/schemas/AssayExpressionRequest' required: true responses: '200': description: Successful Response content: application/json: schema: type: object title: Response Get Assay Expression Assays Expression Post '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /dicom/studies: get: tags: - dicom summary: List DICOM studies in scope description: >- Returns DICOM studies configured for the current workspace with OHIF launch URLs. operationId: get_dicom_studies_dicom_studies_get parameters: - name: dataset_id in: query required: false schema: type: string default: '' title: Dataset Id - name: data_dir in: query required: false schema: type: string default: /path/to/cohortome/default_dataset title: Data Dir responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/DicomStudiesResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /dicom/status: get: tags: - dicom summary: Get DICOM integration status description: >- Returns DICOM/OHIF/Orthanc configuration status for the current workspace. operationId: get_dicom_status_dicom_status_get parameters: - name: dataset_id in: query required: false schema: type: string default: '' title: Dataset Id - name: data_dir in: query required: false schema: type: string default: /path/to/cohortome/default_dataset title: Data Dir responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/DicomStatusResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /analysis-sessions: get: tags: - analysis summary: List saved analysis sessions description: Returns persisted analysis sessions for the current user. operationId: get_analysis_sessions_analysis_sessions_get responses: '200': description: Successful Response content: application/json: schema: type: object title: Response Get Analysis Sessions Analysis Sessions Get post: tags: - analysis summary: Create or update an analysis session description: >- Persists analysis session state, including prompt draft, scopes, and prior turns. operationId: create_or_update_analysis_session_analysis_sessions_post requestBody: content: application/json: schema: $ref: '#/components/schemas/AnalysisSessionRequest' required: true responses: '200': description: Successful Response content: application/json: schema: type: object title: >- Response Create Or Update Analysis Session Analysis Sessions Post '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /analysis-sessions/{session_id}: patch: tags: - analysis summary: Rename an analysis session description: Updates the title of a saved analysis session. operationId: update_analysis_session_title_analysis_sessions__session_id__patch parameters: - name: session_id in: path required: true schema: type: string title: Session Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AnalysisSessionRenameRequest' responses: '200': description: Successful Response content: application/json: schema: type: object title: >- Response Update Analysis Session Title Analysis Sessions Session Id Patch '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' delete: tags: - analysis summary: Delete an analysis session description: Deletes a saved analysis session for the current user. operationId: remove_analysis_session_analysis_sessions__session_id__delete parameters: - name: session_id in: path required: true schema: type: string title: Session Id - name: delete_generated_data in: query required: false schema: type: boolean default: false title: Delete Generated Data - name: keep_generated_jobs in: query required: false schema: type: boolean default: false title: Keep Generated Jobs responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/DeleteResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /pheno-ranker/run: post: tags: - pheno-ranker summary: Run Pheno-Ranker description: >- Runs Pheno-Ranker for the active workspace using either patient mode or cohort mode. operationId: run_pheno_ranker_route_pheno_ranker_run_post requestBody: content: application/json: schema: $ref: '#/components/schemas/PhenoRankerRequest' required: true responses: '200': description: Successful Response content: application/json: schema: type: object title: Response Run Pheno Ranker Route Pheno Ranker Run Post '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /pheno-ranker/plan: post: tags: - pheno-ranker summary: Plan a Pheno-Ranker run description: >- Converts a natural-language request into a normalized Pheno-Ranker execution plan. operationId: plan_pheno_ranker_route_pheno_ranker_plan_post requestBody: content: application/json: schema: $ref: '#/components/schemas/PhenoRankerPlanRequest' required: true responses: '200': description: Successful Response content: application/json: schema: type: object title: Response Plan Pheno Ranker Route Pheno Ranker Plan Post '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /pheno-ranker/patient-ids: get: tags: - pheno-ranker summary: List Pheno-Ranker scope IDs description: >- Returns the sample-level identifiers currently available to Pheno-Ranker in the active workspace. operationId: get_pheno_ranker_patient_ids_pheno_ranker_patient_ids_get parameters: - name: dataset_id in: query required: false schema: type: string default: '' title: Dataset Id - name: data_dir in: query required: false schema: type: string default: /path/to/cohortome/default_dataset title: Data Dir responses: '200': description: Successful Response content: application/json: schema: type: object title: >- Response Get Pheno Ranker Patient Ids Pheno Ranker Patient Ids Get '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /pheno-ranker/results/{job_id}/{filename}: get: tags: - pheno-ranker summary: Download a Pheno-Ranker result file description: Returns a generated Pheno-Ranker result artifact for a specific job. operationId: get_pheno_ranker_result_pheno_ranker_results__job_id___filename__get parameters: - name: job_id in: path required: true schema: type: string title: Job Id - name: filename in: path required: true schema: type: string title: Filename responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /pheno-ranker/alignment/{job_id}: get: tags: - pheno-ranker summary: Get alignment details for one match description: >- Returns the term-level alignment details between a target and a selected Pheno-Ranker match. operationId: get_pheno_ranker_alignment_pheno_ranker_alignment__job_id__get parameters: - name: job_id in: path required: true schema: type: string title: Job Id - name: reference_id in: query required: true schema: type: string title: Reference Id - name: target_id in: query required: false schema: type: string default: '' title: Target Id responses: '200': description: Successful Response content: application/json: schema: type: object title: >- Response Get Pheno Ranker Alignment Pheno Ranker Alignment Job Id Get '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /pheno-ranker/explain/{job_id}: get: tags: - pheno-ranker summary: Explain Pheno-Ranker results deterministically description: Builds a deterministic summary from the top ranked Pheno-Ranker matches. operationId: explain_pheno_ranker_results_pheno_ranker_explain__job_id__get parameters: - name: job_id in: path required: true schema: type: string title: Job Id - name: top_n in: query required: false schema: type: integer default: 3 title: Top N responses: '200': description: Successful Response content: application/json: schema: type: object title: >- Response Explain Pheno Ranker Results Pheno Ranker Explain Job Id Get '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /pheno-ranker/explain-llm/{job_id}: get: tags: - pheno-ranker summary: Explain Pheno-Ranker results with the LLM description: >- Builds an LLM-assisted explanation from the top ranked Pheno-Ranker matches. operationId: explain_pheno_ranker_results_llm_pheno_ranker_explain_llm__job_id__get parameters: - name: job_id in: path required: true schema: type: string title: Job Id - name: top_n in: query required: false schema: type: integer default: 3 title: Top N responses: '200': description: Successful Response content: application/json: schema: type: object title: >- Response Explain Pheno Ranker Results Llm Pheno Ranker Explain Llm Job Id Get '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /dashboard: get: tags: - patients summary: Get the dashboard summary description: >- Returns the dashboard summary payload used by the clinical and assay overview panels. operationId: get_dashboard_dashboard_get parameters: - name: dataset_id in: query required: false schema: type: string default: '' title: Dataset Id - name: data_dir in: query required: false schema: type: string default: /path/to/cohortome/default_dataset title: Data Dir responses: '200': description: Successful Response content: application/json: schema: type: object title: Response Get Dashboard Dashboard Get '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: AnalysisRequest: properties: prompt: type: string title: Prompt description: Natural-language analysis prompt. examples: - Summarize the main workspace patterns and tell me what stands out. catalog_item_id: type: string title: Catalog Item Id description: >- Optional Analysis Catalog item identifier used for structured curated analyses. default: '' analysis_session_id: type: string title: Analysis Session Id description: >- Current Analysis session identifier used to associate queued jobs back to the active session. default: '' dataset_id: type: string title: Dataset Id description: Dataset ID or multi-dataset scope ID for the analysis workspace. default: '' assay_id: type: string title: Assay Id description: >- Selected assay identifier for curated analyses that require one explicit transcriptomics source. default: '' data_dir: type: string title: Data Dir description: Manual dataset directory fallback. Prefer dataset_id. default: /path/to/cohortome/default_dataset selected_patient_ids: type: string title: Selected Patient Ids description: >- Comma-separated scope IDs for cohort A. May contain sample or patient IDs depending on the source tab. default: '' scope_metadata: type: object title: Scope Metadata description: >- Saved-cohort-shaped metadata for the Cohort A selection, including sample IDs, patient IDs, and source. compare_mode: type: boolean title: Compare Mode description: Whether to run a compare-mode analysis using cohort A vs cohort B. default: false compare_selected_patient_ids: type: string title: Compare Selected Patient Ids description: Comma-separated scope IDs for cohort B when compare_mode is enabled. default: '' compare_scope_metadata: type: object title: Compare Scope Metadata description: Saved-cohort-shaped metadata for the Cohort B selection. llm_only: type: boolean title: Llm Only description: Force LLM-only analysis mode. default: false deterministic_only: type: boolean title: Deterministic Only description: Force deterministic-only analysis mode. default: false history: items: $ref: '#/components/schemas/QueryTurn' type: array title: History type: object required: - prompt title: AnalysisRequest AnalysisSessionRenameRequest: properties: title: type: string title: Title description: New title for the analysis session. default: '' type: object title: AnalysisSessionRenameRequest AnalysisSessionRequest: properties: id: type: string title: Id description: Client-generated analysis session identifier. title: type: string title: Title description: Optional user-facing session title. default: '' dataset_id: type: string title: Dataset Id description: Dataset ID or multi-dataset scope ID for the session. default: '' data_dir: type: string title: Data Dir description: Manual dataset directory fallback. Prefer dataset_id. default: /path/to/cohortome/default_dataset workspace_fingerprint: type: object title: Workspace Fingerprint description: >- Workspace fingerprint snapshot captured when the session was first bound. catalog_item_id: type: string title: Catalog Item Id description: Selected Analysis Catalog item for this session, if any. default: '' prompt_draft: type: string title: Prompt Draft description: Current draft prompt stored for the session. default: '' context_mode: type: string enum: - workspace - general title: Context Mode description: >- Whether the saved composer is using workspace context or general knowledge. default: workspace scope: type: string title: Scope description: Comma-separated scope IDs for cohort A. default: '' scope_metadata: type: object title: Scope Metadata description: Saved-cohort-shaped metadata for Cohort A. saved_cohort_id_a: type: string title: Saved Cohort Id A description: Saved cohort ID currently assigned to cohort A, if any. default: '' compare_mode: type: boolean title: Compare Mode description: Whether the session is in compare mode. default: false compare_scope: type: string title: Compare Scope description: Comma-separated scope IDs for cohort B. default: '' compare_scope_metadata: type: object title: Compare Scope Metadata description: Saved-cohort-shaped metadata for Cohort B. saved_cohort_id_b: type: string title: Saved Cohort Id B description: Saved cohort ID currently assigned to cohort B, if any. default: '' history: items: type: object type: array title: History turns: items: type: object type: array title: Turns updated_at: type: string title: Updated At description: Last-updated timestamp in ISO 8601 format. default: '' created_at: type: string title: Created At description: Creation timestamp in ISO 8601 format. default: '' type: object required: - id title: AnalysisSessionRequest AssayDatasetResponse: properties: assay_id: type: string title: Assay Id default: '' additionalProperties: true type: object title: AssayDatasetResponse AssayDatasetsResponse: properties: datasets: items: $ref: '#/components/schemas/AssayDatasetResponse' type: array title: Datasets type: object title: AssayDatasetsResponse AssayExpressionRequest: properties: assay_id: type: string title: Assay Id description: Assay identifier to inspect. gene_id: type: string title: Gene Id description: Gene identifier or symbol to summarize. dataset_id: type: string title: Dataset Id description: Dataset ID or multi-dataset scope ID for assay lookups. default: '' data_dir: type: string title: Data Dir description: Manual dataset directory fallback. Prefer dataset_id. default: /path/to/cohortome/default_dataset selected_patient_ids: type: string title: Selected Patient Ids description: Optional comma-separated scope IDs for cohort A filtering. default: '' compare_selected_patient_ids: type: string title: Compare Selected Patient Ids description: Optional comma-separated scope IDs for cohort B filtering. default: '' type: object required: - assay_id - gene_id title: AssayExpressionRequest AssayFeatureMatrixResponse: properties: metadata: type: object title: Metadata columns: items: type: object type: array title: Columns rows: items: type: object type: array title: Rows missingness: items: type: object type: array title: Missingness feature_groups: items: type: object type: array title: Feature Groups warnings: items: type: object type: array title: Warnings additionalProperties: true type: object title: AssayFeatureMatrixResponse AssayReadinessResponse: properties: workspace: type: object title: Workspace modalities: items: type: object type: array title: Modalities pairwise_overlaps: items: type: object type: array title: Pairwise Overlaps issues: items: type: object type: array title: Issues suggestions: items: type: object type: array title: Suggestions additionalProperties: true type: object title: AssayReadinessResponse AuthDiagnosticsResponse: properties: enabled: type: boolean title: Enabled mode: type: string title: Mode provider: type: string title: Provider default: none user_count: type: integer title: User Count usernames: items: type: string type: array title: Usernames roles: additionalProperties: type: string type: object title: Roles groups: additionalProperties: items: type: string type: array type: object title: Groups source: type: string title: Source type: object required: - enabled - mode - user_count - source title: AuthDiagnosticsResponse AuthPasswordResetConfirmRequest: properties: token: type: string title: Token description: Password reset token from the reset link. default: '' password: type: string title: Password description: New local password. default: '' type: object title: AuthPasswordResetConfirmRequest AuthPasswordResetRequest: properties: password: type: string title: Password description: Replacement local password. default: '' type: object title: AuthPasswordResetRequest AuthPasswordResetResponse: properties: ok: type: boolean title: Ok default: true message: type: string title: Message type: object required: - message title: AuthPasswordResetResponse AuthPasswordResetStartRequest: properties: identifier: type: string title: Identifier description: Username or email address for password reset. default: '' type: object title: AuthPasswordResetStartRequest AuthStatusResponse: properties: enabled: type: boolean title: Enabled mode: type: string title: Mode default: none provider: type: string title: Provider default: none authenticated: type: boolean title: Authenticated local_login_enabled: type: boolean title: Local Login Enabled default: false password_reset_enabled: type: boolean title: Password Reset Enabled default: false user: anyOf: - $ref: '#/components/schemas/AuthUserResponse' - type: 'null' type: object required: - enabled - authenticated title: AuthStatusResponse AuthUserCreateRequest: properties: username: type: string title: Username description: Unique local username. default: '' password: type: string title: Password description: Initial local password. default: '' display_name: type: string title: Display Name description: User-facing display name. default: '' email: type: string title: Email description: Optional email address used for self-service password reset. default: '' role: type: string title: Role description: 'Application role: user or admin.' default: user groups: items: type: string type: array title: Groups description: Application groups used for dataset authorization. enabled: type: boolean title: Enabled description: Whether the user can sign in. default: true type: object title: AuthUserCreateRequest AuthUserResponse: properties: username: type: string title: Username role: type: string title: Role display_name: type: string title: Display Name email: type: string title: Email default: '' groups: items: type: string type: array title: Groups enabled: type: boolean title: Enabled default: true auth_source: type: string title: Auth Source default: local login_method: type: string title: Login Method default: local additionalProperties: true type: object required: - username - role - display_name title: AuthUserResponse AuthUserUpdateRequest: properties: display_name: anyOf: - type: string - type: 'null' title: Display Name description: Updated display name. email: anyOf: - type: string - type: 'null' title: Email description: Updated email address used for self-service password reset. role: anyOf: - type: string - type: 'null' title: Role description: Updated application role. groups: anyOf: - items: type: string type: array - type: 'null' title: Groups description: Replacement application groups. enabled: anyOf: - type: boolean - type: 'null' title: Enabled description: Whether the user can sign in. type: object title: AuthUserUpdateRequest AuthUsersResponse: properties: mode: type: string title: Mode users: items: $ref: '#/components/schemas/AuthUserResponse' type: array title: Users type: object required: - mode title: AuthUsersResponse DatasetRecordResponse: properties: dataset_id: type: string title: Dataset Id name: type: string title: Name description: type: string title: Description default: '' root_path: type: string title: Root Path default: '' enabled: type: boolean title: Enabled visibility: type: string title: Visibility data_classification: type: string title: Data Classification default: private allowed_users: items: type: string type: array title: Allowed Users allowed_groups: items: type: string type: array title: Allowed Groups query_granularity_ceiling: type: string title: Query Granularity Ceiling default: summary ai_provider_access: type: string title: Ai Provider Access default: detailed_allowed created_by: type: string title: Created By default: '' created_at: type: string title: Created At default: '' updated_at: type: string title: Updated At default: '' query_store_status: type: object title: Query Store Status additionalProperties: true type: object required: - dataset_id - name - enabled - visibility title: DatasetRecordResponse DatasetRegistrationRequest: properties: name: type: string title: Name description: Human-readable dataset name. default: '' root_path: type: string title: Root Path description: >- Dataset root directory containing clinical/ and assays/ subdirectories. default: '' description: type: string title: Description description: Optional dataset description shown in the UI. default: '' visibility: type: string title: Visibility description: >- Dataset visibility policy: all_authenticated, restricted, or admin_only. default: all_authenticated data_classification: type: string title: Data Classification description: >- Data egress classification: public or private. Private data cannot be sent to external AI providers. default: private allowed_users: items: type: string type: array title: Allowed Users description: Usernames with direct access when visibility is restricted. allowed_groups: items: type: string type: array title: Allowed Groups description: Groups with access when visibility is restricted. query_granularity_ceiling: type: string title: Query Granularity Ceiling description: >- Maximum Query thread mode allowed for this dataset: summary or detailed. default: summary ai_provider_access: type: string title: Ai Provider Access description: >- Maximum AI provider disclosure allowed after applying data classification and provider boundary. default: detailed_allowed enabled: type: boolean title: Enabled description: Whether the dataset can be selected in the UI. default: true type: object title: DatasetRegistrationRequest DatasetSelectionRequest: properties: dataset_id: type: string title: Dataset Id description: Single dataset ID for backward compatibility. default: '' dataset_ids: items: type: string type: array title: Dataset Ids description: >- Dataset IDs that define the active workspace. An empty list unloads it. type: object title: DatasetSelectionRequest DatasetSelectionResponse: properties: selected: type: boolean title: Selected current_dataset_id: type: string title: Current Dataset Id default: '' current_dataset_ids: items: type: string type: array title: Current Dataset Ids current_dataset_scope_id: type: string title: Current Dataset Scope Id default: '' type: object required: - selected title: DatasetSelectionResponse DatasetUpdateRequest: properties: name: anyOf: - type: string - type: 'null' title: Name description: Updated human-readable dataset name. root_path: anyOf: - type: string - type: 'null' title: Root Path description: Updated dataset root directory. description: anyOf: - type: string - type: 'null' title: Description description: Updated UI description. visibility: anyOf: - type: string - type: 'null' title: Visibility description: Updated visibility policy. data_classification: anyOf: - type: string - type: 'null' title: Data Classification description: 'Updated data egress classification: public or private.' allowed_users: anyOf: - items: type: string type: array - type: 'null' title: Allowed Users description: Replacement direct-access username list. allowed_groups: anyOf: - items: type: string type: array - type: 'null' title: Allowed Groups description: Replacement allowed-group list. query_granularity_ceiling: anyOf: - type: string - type: 'null' title: Query Granularity Ceiling description: Updated maximum Query thread mode for this dataset. ai_provider_access: anyOf: - type: string - type: 'null' title: Ai Provider Access description: Updated maximum AI provider access mode. enabled: anyOf: - type: boolean - type: 'null' title: Enabled description: Whether the dataset remains selectable. type: object title: DatasetUpdateRequest DatasetsResponse: properties: datasets: items: $ref: '#/components/schemas/DatasetRecordResponse' type: array title: Datasets current_dataset_id: type: string title: Current Dataset Id default: '' current_dataset_ids: items: type: string type: array title: Current Dataset Ids current_dataset_scope_id: type: string title: Current Dataset Scope Id default: '' current_dataset: anyOf: - $ref: '#/components/schemas/DatasetRecordResponse' - type: 'null' type: object title: DatasetsResponse DeleteResponse: properties: deleted: type: boolean title: Deleted id: type: string title: Id default: '' deleted_count: type: integer title: Deleted Count default: 0 deleted_generated_data: type: boolean title: Deleted Generated Data default: false related_job_count: type: integer title: Related Job Count default: 0 deleted_job_count: type: integer title: Deleted Job Count default: 0 kept_job_count: type: integer title: Kept Job Count default: 0 skipped_active_count: type: integer title: Skipped Active Count default: 0 type: object required: - deleted title: DeleteResponse DicomStatusResponse: properties: enabled: type: boolean title: Enabled default: false study_count: type: integer title: Study Count default: 0 additionalProperties: true type: object title: DicomStatusResponse DicomStudiesResponse: properties: enabled: type: boolean title: Enabled default: false studies: items: $ref: '#/components/schemas/DicomStudyResponse' type: array title: Studies type: object title: DicomStudiesResponse DicomStudyResponse: properties: study_instance_uid: type: string title: Study Instance Uid default: '' additionalProperties: true type: object title: DicomStudyResponse GeneralLlmRequest: properties: prompt: type: string maxLength: 12000 minLength: 1 title: Prompt description: >- General-knowledge question sent without workspace or dataset context. examples: - What is aspirin? history: items: $ref: '#/components/schemas/QueryTurn' type: array title: History description: Recent turns from General question mode only. type: object required: - prompt title: GeneralLlmRequest HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError LmProviderCreateRequest: properties: id: type: string title: Id description: Stable provider ID used by persisted user settings. default: '' label: type: string title: Label description: User-facing provider label. default: '' base_url: type: string title: Base Url description: OpenAI-compatible API base URL, normally ending in /v1. default: '' model: type: string title: Model description: >- Model ID. Leave empty to use the first model reported by the provider. default: '' api_key: type: string title: Api Key description: Write-only API key. It is never returned by the API. default: '' writeOnly: true timeout_seconds: type: number title: Timeout Seconds description: Provider request timeout in seconds. default: 30 enabled: type: boolean title: Enabled description: Whether users may select and use this provider. default: true data_boundary: type: string enum: - local - external title: Data Boundary description: Explicit deployment boundary used for private-data policy. default: external type: object title: LmProviderCreateRequest LmProviderResponse: properties: id: type: string title: Id label: type: string title: Label base_url: type: string title: Base Url model: anyOf: - type: string - type: 'null' title: Model enabled: type: boolean title: Enabled default: true data_boundary: type: string enum: - local - external title: Data Boundary default: external source: type: string title: Source default: configuration managed: type: boolean title: Managed default: false timeout_seconds: type: number title: Timeout Seconds default: 30 api_key_configured: type: boolean title: Api Key Configured default: false additionalProperties: true type: object required: - id - label - base_url title: LmProviderResponse LmProviderUpdateRequest: properties: label: anyOf: - type: string - type: 'null' title: Label description: Updated user-facing provider label. base_url: anyOf: - type: string - type: 'null' title: Base Url description: Updated OpenAI-compatible API base URL. model: anyOf: - type: string - type: 'null' title: Model description: Updated model ID; an empty value enables model discovery. api_key: anyOf: - type: string - type: 'null' title: Api Key description: Replacement write-only API key. Empty values retain the stored key. writeOnly: true timeout_seconds: anyOf: - type: number - type: 'null' title: Timeout Seconds description: Updated provider request timeout in seconds. enabled: anyOf: - type: boolean - type: 'null' title: Enabled description: Whether users may select and use this provider. data_boundary: anyOf: - type: string enum: - local - external - type: 'null' title: Data Boundary description: Updated deployment boundary. type: object title: LmProviderUpdateRequest LmProvidersResponse: properties: providers: items: $ref: '#/components/schemas/LmProviderResponse' type: array title: Providers registry_error: type: string title: Registry Error default: '' type: object title: LmProvidersResponse LmStatusResponse: properties: enabled: type: boolean title: Enabled available: type: boolean title: Available default: false status: type: string title: Status default: disabled base_url: type: string title: Base Url model: anyOf: - type: string - type: 'null' title: Model detail: type: string title: Detail default: '' selected_provider_id: type: string title: Selected Provider Id default: system-default provider: type: object title: Provider providers: items: type: object type: array title: Providers type: object required: - enabled - base_url title: LmStatusResponse LoginRequest: properties: username: type: string title: Username description: Local username. default: '' password: type: string title: Password description: Local password. default: '' type: object title: LoginRequest PatientSummaryResponse: properties: patient_id: type: string title: Patient Id default: '' additionalProperties: true type: object title: PatientSummaryResponse PhenoRankerPlanRequest: properties: text: type: string title: Text description: Natural-language instruction to convert into a Pheno-Ranker plan. dataset_id: type: string title: Dataset Id description: Dataset ID or multi-dataset scope ID for planning. default: '' data_dir: type: string title: Data Dir description: Manual dataset directory fallback. Prefer dataset_id. default: /path/to/cohortome/default_dataset selected_patient_ids: type: string title: Selected Patient Ids description: Optional comma-separated scope IDs already selected in the UI. default: '' type: object required: - text title: PhenoRankerPlanRequest PhenoRankerRequest: properties: prompt: type: string title: Prompt description: >- Current Pheno-Ranker prompt used for run metadata and queued job labels. default: '' action: type: string title: Action description: Pheno-Ranker action, typically compare. default: compare mode: type: string title: Mode description: Pheno-Ranker mode, such as cohort or patient. default: cohort dataset_id: type: string title: Dataset Id description: Dataset ID or multi-dataset scope ID for the workspace. default: '' data_dir: type: string title: Data Dir description: Manual dataset directory fallback. Prefer dataset_id. default: /path/to/cohortome/default_dataset patient_id: type: string title: Patient Id description: Single target sample/patient ID for patient mode. default: '' selected_patient_ids: type: string title: Selected Patient Ids description: Comma-separated scope IDs for cohort mode. default: '' selected_saved_cohort_ids: items: type: string type: array title: Selected Saved Cohort Ids disease_filter: type: string title: Disease Filter description: Optional disease label filter for eligible reference files. default: '' include_terms: items: type: string type: array title: Include Terms exclude_terms: items: type: string type: array title: Exclude Terms similarity_metric_cohort: type: string title: Similarity Metric Cohort description: Similarity metric to use for cohort comparison. default: '' sort_by: type: string title: Sort By description: Sort strategy for rank output. default: '' max_out: type: integer title: Max Out description: Maximum number of ranked output matches to keep. default: 10 align: type: boolean title: Align description: Whether to compute term alignment details. default: true render_heatmap: type: boolean title: Render Heatmap description: Whether to generate the interactive heatmap artifact. default: true render_mds: type: boolean title: Render Mds description: Whether to generate the interactive MDS artifact. default: true render_graph: type: boolean title: Render Graph description: Whether to generate the interactive Cytoscape graph artifact. default: true graph_min_weight: anyOf: - type: number - type: 'null' title: Graph Min Weight description: Optional minimum edge weight for Pheno-Ranker graph export. graph_max_weight: anyOf: - type: number - type: 'null' title: Graph Max Weight description: Optional maximum edge weight for Pheno-Ranker graph export. granularity_ceiling: type: string title: Granularity Ceiling description: Internal workspace ceiling used to guard Pheno-Ranker access. default: detailed ai_provider_access: type: string title: Ai Provider Access description: >- Effective AI provider policy used for Pheno-Ranker planner/explanation paths. default: detailed_allowed type: object title: PhenoRankerRequest QueryRequest: properties: q: type: string title: Q description: Natural-language workspace query. examples: - How many patients take biologics in this workspace? dataset_id: type: string title: Dataset Id description: Dataset ID or multi-dataset scope ID to query against. default: '' data_dir: type: string title: Data Dir description: Manual dataset directory fallback. Prefer dataset_id. default: /path/to/cohortome/default_dataset query_mode: type: string title: Query Mode description: >- Query execution mode. Supported values include auto and planner_only. default: auto granularity_mode: type: string title: Granularity Mode description: >- Disclosure mode requested by the Query UI. Supported values currently include summary and detailed. default: detailed history: items: $ref: '#/components/schemas/QueryTurn' type: array title: History scoped_patient_ids: items: type: string type: array title: Scoped Patient Ids description: >- Optional prior subset patient IDs carried as app-level conversational scope for follow-up queries. scoped_record_ids: items: type: string type: array title: Scoped Record Ids description: >- Optional prior subset sample or record IDs carried as app-level conversational scope. scoped_id_type: type: string title: Scoped Id Type description: The primary ID level used by the carried scoped context. default: patient type: object required: - q title: QueryRequest QueryTurn: properties: role: type: string title: Role content: type: string title: Content type: object required: - role - content title: QueryTurn SavedCohortRequest: properties: name: type: string title: Name description: User-facing saved cohort name. default: '' dataset_id: type: string title: Dataset Id description: Dataset ID or multi-dataset scope ID where the cohort was created. default: '' dataset_ids: items: type: string type: array title: Dataset Ids data_dir: type: string title: Data Dir description: Manual dataset directory fallback. Prefer dataset_id. default: /path/to/cohortome/default_dataset sample_ids: items: type: string type: array title: Sample Ids description: Canonical sample/record IDs stored for the cohort. patient_ids: items: type: string type: array title: Patient Ids description: Derived patient IDs stored alongside the cohort. id_type: type: string title: Id Type description: Canonical ID level used by the cohort payload. default: sample source_kind: type: string title: Source Kind description: How the cohort was created, for example manual or query. default: manual source_prompt: type: string title: Source Prompt description: Source prompt when the cohort came from Query. default: '' type: object title: SavedCohortRequest SavedCohortResponse: properties: id: type: string title: Id name: type: string title: Name dataset_id: type: string title: Dataset Id default: '' dataset_ids: items: type: string type: array title: Dataset Ids data_dir: type: string title: Data Dir default: '' id_type: type: string title: Id Type default: sample sample_ids: items: type: string type: array title: Sample Ids patient_ids: items: type: string type: array title: Patient Ids sample_count: type: integer title: Sample Count default: 0 patient_count: type: integer title: Patient Count default: 0 is_full_dataset: type: boolean title: Is Full Dataset default: false source: $ref: '#/components/schemas/SavedCohortSourceResponse' created_at: type: string title: Created At default: '' updated_at: type: string title: Updated At default: '' additionalProperties: true type: object required: - id - name title: SavedCohortResponse SavedCohortSourceResponse: properties: kind: type: string title: Kind default: '' prompt: type: string title: Prompt default: '' type: object title: SavedCohortSourceResponse SavedCohortsResponse: properties: cohorts: items: $ref: '#/components/schemas/SavedCohortResponse' type: array title: Cohorts type: object title: SavedCohortsResponse UserSettingsResponse: properties: version: type: integer title: Version default: 1 landing_tab_mode: type: string enum: - fixed - last title: Landing Tab Mode default: fixed landing_tab: type: string enum: - dashboard - datasets - query - analysis - pheno title: Landing Tab default: dashboard query_disclosure_default: type: string enum: - summary - detailed title: Query Disclosure Default default: detailed query_default_mode: type: string enum: - auto - planner_only title: Query Default Mode default: auto latest_query_details: type: boolean title: Latest Query Details default: true analysis_auto_open_jobs: type: boolean title: Analysis Auto Open Jobs default: true run_history_retention_days: type: integer enum: - 0 - 7 - 30 - 90 - 180 - 365 title: Run History Retention Days default: 30 pheno_default_metric: type: string enum: - '' - hamming - jaccard title: Pheno Default Metric default: '' pheno_advanced_open: type: boolean title: Pheno Advanced Open default: false pheno_render_heatmap: type: boolean title: Pheno Render Heatmap default: true pheno_render_mds: type: boolean title: Pheno Render Mds default: true pheno_render_graph: type: boolean title: Pheno Render Graph default: true dashboard_assays_open: type: boolean title: Dashboard Assays Open default: false dataset_compact_view: type: boolean title: Dataset Compact View default: false llm_provider_id: type: string title: Llm Provider Id default: system-default type: object title: UserSettingsResponse UserSettingsUpdateRequest: properties: landing_tab_mode: anyOf: - type: string enum: - fixed - last - type: 'null' title: Landing Tab Mode landing_tab: anyOf: - type: string enum: - dashboard - datasets - query - analysis - pheno - type: 'null' title: Landing Tab query_disclosure_default: anyOf: - type: string enum: - summary - detailed - type: 'null' title: Query Disclosure Default query_default_mode: anyOf: - type: string enum: - auto - planner_only - type: 'null' title: Query Default Mode latest_query_details: anyOf: - type: boolean - type: 'null' title: Latest Query Details analysis_auto_open_jobs: anyOf: - type: boolean - type: 'null' title: Analysis Auto Open Jobs run_history_retention_days: anyOf: - type: integer enum: - 0 - 7 - 30 - 90 - 180 - 365 - type: 'null' title: Run History Retention Days pheno_default_metric: anyOf: - type: string enum: - '' - hamming - jaccard - type: 'null' title: Pheno Default Metric pheno_advanced_open: anyOf: - type: boolean - type: 'null' title: Pheno Advanced Open pheno_render_heatmap: anyOf: - type: boolean - type: 'null' title: Pheno Render Heatmap pheno_render_mds: anyOf: - type: boolean - type: 'null' title: Pheno Render Mds pheno_render_graph: anyOf: - type: boolean - type: 'null' title: Pheno Render Graph dashboard_assays_open: anyOf: - type: boolean - type: 'null' title: Dashboard Assays Open dataset_compact_view: anyOf: - type: boolean - type: 'null' title: Dataset Compact View llm_provider_id: anyOf: - type: string - type: 'null' title: Llm Provider Id type: object title: UserSettingsUpdateRequest ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError tags: - name: ui description: >- HTML entrypoints and static branding assets used by the web application shell. - name: auth description: Authentication state, local login, and user visibility endpoints. - name: datasets description: >- Dataset registry, workspace selection, and dataset access policy management. - name: patients description: >- Patient lists, patient timelines, dashboard summaries, and cohort count helpers. - name: query description: Deterministic and LLM-assisted natural-language workspace queries. - name: analysis description: >- Clinical, assay, imaging, and multimodal workspace analysis plus saved analysis sessions. - name: cohorts description: Saved cohort persistence and cohort-scoped handoff utilities. - name: assays description: >- Multimodal assay inventory, feature matrices, DICOM metadata, and expression summaries. - name: dicom description: DICOM study discovery and OHIF launch integration. - name: pheno-ranker description: >- Pheno-Ranker planning, execution, result download, and explanation endpoints.