HTTP API Routes

This page is generated by scripts/generate_api_route_docs.py from the runtime Cement registry and the manually declared FastAPI routers.

This reference combines:

• routes created from @api-annotated Cement controller methods

• routes declared manually in vipr-api FastAPI routers

Summary

• Generated: 2026-03-13 16:16:11 UTC

• Total routes: 45

• Auto-generated Cement routes: 16

• Manual FastAPI routes: 29

Auto-generated Cement Routes

discovery

Method	Path	Operation	Python method	Request model	Response model	Tags
GET	/api/discovery/components	components	components	-	vipr.plugins.discovery.models.ComponentsResponse	discovery
GET	/api/discovery/data-loaders	data-loaders	data_loaders	-	list[vipr.plugins.discovery.models.HandlerEntry]	discovery
GET	/api/discovery/filter-types	filter-types	filter_types	-	list[str]	discovery
GET	/api/discovery/filters	filters	filters	-	dict[str, list[vipr.plugins.discovery.models.CallbackEntry]]	discovery
GET	/api/discovery/hook-types	hook-types	hook_types	-	list[str]	discovery
GET	/api/discovery/hooks	hooks	hooks	-	dict[str, list[vipr.plugins.discovery.models.CallbackEntry]]	discovery
GET	/api/discovery/model-loaders	model-loaders	model_loaders	-	list[vipr.plugins.discovery.models.HandlerEntry]	discovery
GET	/api/discovery/plugins	plugins	plugins	-	vipr.plugins.discovery.models.PluginSummaryResponse	discovery
GET	/api/discovery/postprocessors	postprocessors	postprocessors	-	list[vipr.plugins.discovery.models.HandlerEntry]	discovery
GET	/api/discovery/predictors	predictors	predictors	-	list[vipr.plugins.discovery.models.HandlerEntry]	discovery

Descriptions

• GET /api/discovery/components: Lists all available components. No input required for this GET endpoint.

• GET /api/discovery/data-loaders: Lists all available data loaders.

• GET /api/discovery/filter-types: Lists all available filter types.

• GET /api/discovery/filters: Lists all available filters.

• GET /api/discovery/hook-types: Lists all available hook types.

• GET /api/discovery/hooks: Lists all available hooks.

• GET /api/discovery/model-loaders: Lists all available model loaders.

• GET /api/discovery/plugins: Lists all available plugins by type.

• GET /api/discovery/postprocessors: Lists all available postprocessing handlers.

• GET /api/discovery/predictors: Lists all available prediction handlers.

ui

Method	Path	Operation	Python method	Request model	Response model	Tags
GET	/api/ui/result	get-result	get_result	-	vipr.plugins.api.controllers.StoredResultResponse[UIData]	ui
GET	/api/ui/result/config	get-result-config	get_result_config	-	dict	ui
GET	/api/ui/result/status	get-result-status	get_result_status	-	dict	ui
GET	/api/ui/results/list	list-results	list_results	-	dict	ui
POST	/api/ui/storage/cleanup	cleanup-storage	cleanup_storage	-	dict	ui
GET	/api/ui/storage/info	get-storage-info	get_storage_info	-	dict	ui

Descriptions

• GET /api/ui/result: Retrieve a stored UI result by ID (UUID or human-readable)

• GET /api/ui/result/config: Retrieve the configuration file used for a specific result

• GET /api/ui/result/status: Check if a UI result exists

• GET /api/ui/results/list: Get list of all stored UI results with metadata (sorted by date, newest first)

• POST /api/ui/storage/cleanup: Clean up old UI results and config files

• GET /api/ui/storage/info: Get statistics about UI result storage

Manual FastAPI Routes

debug

Method	Path	Operation	Python method	Request model	Response model	Tags
GET	/api/debug/api-mapping	get_api_mapping	get_api_mapping	-	list[dict[str, typing.Any]]	debug
GET	/api/debug/plugin-status	get_plugin_status	get_plugin_status	-	dict[str, typing.Any]	debug

Descriptions

• GET /api/debug/api-mapping: Shows all Plugin → API mappings for debugging and documentation. Returns: List of all HTTP ↔ CLI command mappings

• GET /api/debug/plugin-status: Shows the status of the plugin introspection system. Returns: Status information about plugin discovery

files

Method	Path	Operation	Python method	Request model	Response model	Tags
GET	/api/fetch_file/{file_path:path}	fetch_file	fetch_file	-	-	files
POST	/api/fileupload	upload_file	upload_file	fastapi._compat.Body_upload_file_fileupload_post	vipr_reflectometry.reflectorch.models.FileValidationResponse	files
GET	/api/hdf5_metadata/{file_path:path}	get_hdf5_metadata	get_hdf5_metadata	-	vipr_api.web.routers.files.HDF5Metadata	files
POST	/api/hdf5_preview	get_hdf5_preview	get_hdf5_preview	typing.Dict[str, typing.Any]	vipr_api.web.routers.files.HDF5PreviewData	files

Descriptions

• GET /api/fetch_file/{file_path:path}: Fetch file content from server based on data_path. This endpoint handles both relative paths (using VIPR’s resolve_file_path) and absolute paths (like /tmp files) to provide file access for the frontend. Args: file_path: The path to the file to fetch Returns: FileResponse: The file content with appropriate headers Raises: HTTPException: If file is not found, access denied, or other errors

• POST /api/fileupload: Validates and saves an uploaded file. Supports both text-based files (CSV, TXT, etc.) and HDF5 files with appropriate validation for each type. Args: file: The uploaded file (UTF-8 text format for CSV/TXT or binary for HDF5) Returns: FileValidationResponse: Validation result with file path on success Raises: HTTPException: With appropriate status code and detail message on failure

• GET /api/hdf5_metadata/{file_path:path}: Get metadata from HDF5 file including available datasets and spectrum counts. This endpoint uses the SpectraReader from the HDF5SpectraReaderDataLoader to extract metadata from HDF5 files. Args: file_path: The path to the HDF5 file Returns: HDF5Metadata: Metadata containing datasets, spectrum counts, and file info Raises: HTTPException: If file is not found, not HDF5, or metadata extraction fails

• POST /api/hdf5_preview: Get preview data for a specific dataset/spectrum combination from HDF5 file. Args: request: Dictionary containing: - filePath: Path to HDF5 file - datasetName: Name of dataset to preview - spectrumIndex: Index of spectrum (optional, for single spectrum preview) - batchProcessing: Whether to preview batch data (optional) Returns: HDF5PreviewData: Preview data with Q/intensity ranges and metadata Raises: HTTPException: If file access fails or preview extraction fails

inference

Method	Path	Operation	Python method	Request model	Response model	Tags
POST	/api/inference/cancel/{task_id}	cancel_task	cancel_task	-	dict[str, typing.Any]	inference
POST	/api/inference/export-cli-yaml	export_cli_yaml	export_cli_yaml	vipr_api.web.models.streaming.VIPRConfigWithStreaming	-	inference
GET	/api/inference/health	health_check	health_check	-	vipr_api.web.models.progress.HealthCheckResponse	inference
GET	/api/inference/progress/{task_id}	get_task_progress	get_task_progress	-	vipr_api.web.models.progress.TaskProgressResponse	inference
POST	/api/inference/run	run_inference_async	run_inference_async	vipr.plugins.inference.models.VIPRInference	dict[str, typing.Any]	inference

Descriptions

• POST /api/inference/cancel/{task_id}: Cancel a running VIPR inference task. Args: task_id: Unique identifier of the Celery task to cancel Returns: Dict containing cancellation status Raises: HTTPException: If cancellation fails

• POST /api/inference/export-cli-yaml: Export frontend configuration as CLI-compatible YAML file. Generates semantic result_id: config_name + short_uuid for: - Human readability: “PTCDI-C3_XRR_a1b2c3d4” - Uniqueness: UUID prevents collisions - Traceability: Config name is part of the ID Args: config: VIPRInference containing VIPR configuration Returns: StreamingResponse: YAML file download with semantic filename Raises: HTTPException: If export fails

• GET /api/inference/health: Health check endpoint for Celery backend status. Returns information about: - Celery execution mode (eager/async) - Whether tasks can be executed - Redis availability (for async mode) - Helpful error messages if service is unavailable Returns: HealthCheckResponse containing health status information

• GET /api/inference/progress/{task_id}: Get progress of a running VIPR inference task. Args: task_id: Unique identifier of the Celery task Returns: TaskProgressResponse containing task status, progress, and results Raises: HTTPException: If task not found or invalid

• POST /api/inference/run: Run VIPR inference using Celery background tasks. This is a generic, domain-agnostic endpoint that validates configuration against the registry before starting a Celery task. Provides defense against malicious configs and ensures only registry-approved hooks/filters are used. Args: config: VIPRInference containing VIPR configuration Returns: Dict containing task_id for progress tracking Raises: HTTPException: If configuration validation fails or task creation fails

panpe

Method	Path	Operation	Python method	Request model	Response model	Tags
GET	/api/panpe/models	get_available_panpe_models	get_available_panpe_models	-	list[vipr_api.web.models.reflectometry.AvailableModel]	panpe
GET	/api/panpe/{config_name}/parameters	get_panpe_parameters	get_panpe_parameters	-	vipr_api.web.models.reflectometry.ReflectometryModelParameters	panpe

Descriptions

• GET /api/panpe/models: Get available PANPE models for reflectometry analysis. Returns: List[AvailableModel]: List of available PANPE models with their configurations Raises: HTTPException: If the configuration directory is not found

• GET /api/panpe/{config_name}/parameters: Get parameters for a specific PANPE model configuration (like Reflectorch). Args: config_name (str): Name of the PANPE config (e.g., ‘panpe-2layers-xrr’) Returns: ReflectometryModelParameters: Parameters for the model Raises: HTTPException: If the config is not found or cannot be parsed

plugins

Method	Path	Operation	Python method	Request model	Response model	Tags
GET	/api/plugins/	list_plugins	list_plugins	-	vipr_api.web.models.plugins.PluginListResponse	plugins
DELETE	/api/plugins/batch	batch_delete_plugins	batch_delete_plugins	typing.List[str]	vipr_api.web.models.plugins.PluginBatchDeleteResponse	plugins
POST	/api/plugins/batch/toggle	batch_toggle_plugins	batch_toggle_plugins	typing.List[vipr_api.web.models.plugins.PluginBatchOperation]	vipr_api.web.models.plugins.PluginBatchToggleResponse	plugins
POST	/api/plugins/upload	upload_plugin	upload_plugin	fastapi._compat.Body_upload_plugin_plugins_upload_post	vipr_api.web.models.plugins.PluginUploadResponse	plugins
DELETE	/api/plugins/{plugin_name}	delete_plugin	delete_plugin	-	vipr_api.web.models.plugins.PluginDeleteResponse	plugins
PUT	/api/plugins/{plugin_name}/toggle	toggle_plugin	toggle_plugin	vipr_api.web.models.plugins.PluginToggleRequest	vipr_api.web.models.plugins.PluginToggleResponse	plugins

Descriptions

• GET /api/plugins/: List all builtin and runtime plugins with their status.

• DELETE /api/plugins/batch: Delete multiple runtime plugins in a single operation.

• POST /api/plugins/batch/toggle: Enable or disable multiple runtime plugins in a single operation.

• POST /api/plugins/upload: Upload and validate a new runtime plugin.

• DELETE /api/plugins/{plugin_name}: Delete a runtime plugin (builtin plugins cannot be deleted).

• PUT /api/plugins/{plugin_name}/toggle: Enable or disable a runtime plugin.

reflectorch

Method	Path	Operation	Python method	Request model	Response model	Tags
GET	/api/reflectorch/models	get_available_models	get_available_models	-	list[vipr_api.web.models.reflectometry.AvailableModel]	reflectorch
GET	/api/reflectorch/standard-config	get_standard_config	get_standard_config	-	vipr.plugins.inference.models.VIPRInference	reflectorch
POST	/api/reflectorch/validate-config	validate_config	validate_config	vipr_api.web.models.streaming.VIPRConfigWithStreaming	typing.Dict[str, typing.Any]	reflectorch
GET	/api/reflectorch/{model}/parameters	get_parameters	get_parameters	-	vipr_api.web.models.reflectometry.ReflectometryModelParameters	reflectorch

Descriptions

• GET /api/reflectorch/models: Get available models for reflectometry analysis. Returns: List[AvailableModel]: List of available models with their configurations Raises: HTTPException: If the configuration directory is not found

• GET /api/reflectorch/standard-config: Generate standard Reflectorch configuration. This endpoint migrated from vipr-core to vipr-framework. It calls the VIPR runner to generate standard configuration. Returns: Dict containing standard VIPR configuration Raises: HTTPException: If config generation fails

• POST /api/reflectorch/validate-config: Validate configuration without running prediction. Also completes configuration by adding missing parameters with defaults. Uses the same security validation as the /run endpoint.

• GET /api/reflectorch/{model}/parameters: Get parameters for a specific reflectometry model. Args: model (str): Name of the model Returns: ReflectometryModelParameters: Parameters for the model Raises: HTTPException: If the model configuration is not found

streaming

Method	Path	Operation	Python method	Request model	Response model	Tags
GET	/api/streaming/consumers	list_active_consumers	list_active_consumers	-	dict[str, typing.Any]	streaming
POST	/api/streaming/start	start_streaming_prediction	start_streaming_prediction	vipr_api.web.models.streaming.VIPRConfigWithStreaming	vipr_api.web.models.streaming.StreamingResponse	streaming
GET	/api/streaming/stats/{consumer_id}	get_consumer_stats	get_consumer_stats	-	vipr_api.web.models.streaming.ConsumerStatsResponse	streaming
POST	/api/streaming/stop-all	stop_all_streaming_consumers	stop_all_streaming_consumers	-	dict[str, typing.Any]	streaming
POST	/api/streaming/stop/{consumer_id}	stop_streaming_prediction	stop_streaming_prediction	-	dict[str, typing.Any]	streaming
GET	/api/streaming/tasks/{consumer_id}	get_consumer_tasks	get_consumer_tasks	-	vipr_api.web.models.streaming.ConsumerTasksResponse	streaming

Descriptions

• GET /api/streaming/consumers: List all active streaming consumers. Returns: Dict containing list of active consumer IDs and summary stats

• POST /api/streaming/start: Start streaming prediction consumer for real-time processing. This endpoint starts a RabbitMQ consumer that listens for spectral data messages and triggers individual VIPR inference tasks for each subscan message. Args: request: StreamingStartRequest containing config and RabbitMQ settings Returns: StreamingResponse with consumer ID and status Raises: HTTPException: If consumer startup fails

• GET /api/streaming/stats/{consumer_id}: Get statistics for a specific streaming consumer. Args: consumer_id: Unique identifier of the consumer Returns: ConsumerStatsResponse with detailed consumer statistics Raises: HTTPException: If consumer not found

• POST /api/streaming/stop-all: Stop all active streaming consumers. Returns: Dict containing final statistics for all stopped consumers Raises: HTTPException: If operation fails

• POST /api/streaming/stop/{consumer_id}: Stop a running streaming prediction consumer. Args: consumer_id: Unique identifier of the consumer to stop Returns: Dict containing final consumer statistics Raises: HTTPException: If consumer not found or stop fails

• GET /api/streaming/tasks/{consumer_id}: Get task list for a specific streaming consumer. Args: consumer_id: Unique identifier of the consumer limit: Maximum number of tasks to return (most recent first) since: ISO timestamp to filter tasks triggered after this time Returns: ConsumerTasksResponse containing task list and metadata Raises: HTTPException: If consumer not found