# 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