# \BpmnInstanceApi
All URIs are relative to */api*
Method | HTTP request | Description
------------- | ------------- | -------------
[**bulk_migrate_bpmn_instances**](BpmnInstanceApi.md#bulk_migrate_bpmn_instances) | **POST** /w/{workspace}/bpmn/instances/migrate | migrate every running instance pinned to a definition version
[**cancel_bpmn_instance**](BpmnInstanceApi.md#cancel_bpmn_instance) | **POST** /w/{workspace}/bpmn/instances/cancel/{id} | cancel BPMN process instance
[**check_bpmn_instance_migration**](BpmnInstanceApi.md#check_bpmn_instance_migration) | **GET** /w/{workspace}/bpmn/instances/{id}/migration/check | check whether this instance can be migrated to a target version
[**check_bpmn_version_pair**](BpmnInstanceApi.md#check_bpmn_version_pair) | **GET** /w/{workspace}/bpmn/migration/check/p/{path} | check whether one BPMN definition version can be migrated to another
[**get_bpmn_instance**](BpmnInstanceApi.md#get_bpmn_instance) | **GET** /w/{workspace}/bpmn/instances/get/{id} | get BPMN process instance
[**get_bpmn_instance_status**](BpmnInstanceApi.md#get_bpmn_instance_status) | **GET** /w/{workspace}/bpmn/instances/get/{id}/status | get BPMN process instance status
[**list_bpmn_incidents**](BpmnInstanceApi.md#list_bpmn_incidents) | **GET** /w/{workspace}/bpmn/instances/{id}/incidents | list BPMN process instance incidents
[**list_bpmn_instances**](BpmnInstanceApi.md#list_bpmn_instances) | **GET** /w/{workspace}/bpmn/instances/list | list BPMN process instances
[**migrate_bpmn_instance**](BpmnInstanceApi.md#migrate_bpmn_instance) | **POST** /w/{workspace}/bpmn/instances/{id}/migrate | migrate one running BPMN process instance to another definition version
[**preview_bpmn_instance**](BpmnInstanceApi.md#preview_bpmn_instance) | **POST** /w/{workspace}/bpmn/run/preview | run BPMN process preview (undeployed diagram)
[**retry_bpmn_incident**](BpmnInstanceApi.md#retry_bpmn_incident) | **POST** /w/{workspace}/bpmn/instances/{id}/incidents/{job_id}/retry | retry a BPMN process instance incident
[**start_bpmn_instance**](BpmnInstanceApi.md#start_bpmn_instance) | **POST** /w/{workspace}/bpmn/run/p/{path} | start BPMN process instance
## bulk_migrate_bpmn_instances
> models::BpmnMigrationResult bulk_migrate_bpmn_instances(workspace, bulk_migrate_bpmn_instances_request)
migrate every running instance pinned to a definition version
Bulk identity migration (#922). One validation for the whole batch, because eligibility is a property of the version pair, not of an instance. `from_version` is the whole bulk key -- a `bpmn_flow_version` row belongs to exactly one flow -- and both versions are checked to belong to the same flow before anything moves. Matching no running instance is a 200 with an empty `migrated`, not an error.
### Parameters
Name | Type | Description | Required | Notes
------------- | ------------- | ------------- | ------------- | -------------
**workspace** | **String** | | [required] |
**bulk_migrate_bpmn_instances_request** | [**BulkMigrateBpmnInstancesRequest**](BulkMigrateBpmnInstancesRequest.md) | | [required] |
### Return type
[**models::BpmnMigrationResult**](BpmnMigrationResult.md)
### Authorization
[cookieAuth](../README.md#cookieAuth), [bearerAuth](../README.md#bearerAuth)
### HTTP request headers
- **Content-Type**: application/json
- **Accept**: application/json, text/plain
[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
## cancel_bpmn_instance
> String cancel_bpmn_instance(workspace, id, cancel_bpmn_instance)
cancel BPMN process instance
### Parameters
Name | Type | Description | Required | Notes
------------- | ------------- | ------------- | ------------- | -------------
**workspace** | **String** | | [required] |
**id** | **uuid::Uuid** | | [required] |
**cancel_bpmn_instance** | [**CancelBpmnInstance**](CancelBpmnInstance.md) | cancel reason | [required] |
### Return type
**String**
### Authorization
[cookieAuth](../README.md#cookieAuth), [bearerAuth](../README.md#bearerAuth)
### HTTP request headers
- **Content-Type**: application/json
- **Accept**: text/plain
[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
## check_bpmn_instance_migration
> models::BpmnMigrationCheck check_bpmn_instance_migration(workspace, id, target_version)
check whether this instance can be migrated to a target version
The same per-pair verdict as checkBpmnVersionPair, but resolving this instance's own current pin and its runtime preconditions (it must not be an inline preview run, and it must still be running).
### Parameters
Name | Type | Description | Required | Notes
------------- | ------------- | ------------- | ------------- | -------------
**workspace** | **String** | | [required] |
**id** | **uuid::Uuid** | | [required] |
**target_version** | **i64** | | [required] |
### Return type
[**models::BpmnMigrationCheck**](BpmnMigrationCheck.md)
### Authorization
[cookieAuth](../README.md#cookieAuth), [bearerAuth](../README.md#bearerAuth)
### HTTP request headers
- **Content-Type**: Not defined
- **Accept**: application/json, text/plain
[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
## check_bpmn_version_pair
> models::BpmnMigrationCheck check_bpmn_version_pair(workspace, path, from_version, to_version)
check whether one BPMN definition version can be migrated to another
Runs the identity-migration contract (#922) over two compiled definitions of the same flow and reports every blocker, grouped by rule. Reads no runtime state at all, so the verdict is a property of the (from_version, to_version) *pair* and applies to every instance pinned to from_version -- which is what makes it answerable with no instance and cacheable per version.
### Parameters
Name | Type | Description | Required | Notes
------------- | ------------- | ------------- | ------------- | -------------
**workspace** | **String** | | [required] |
**path** | **String** | | [required] |
**from_version** | **i64** | | [required] |
**to_version** | **i64** | | [required] |
### Return type
[**models::BpmnMigrationCheck**](BpmnMigrationCheck.md)
### Authorization
[cookieAuth](../README.md#cookieAuth), [bearerAuth](../README.md#bearerAuth)
### HTTP request headers
- **Content-Type**: Not defined
- **Accept**: application/json, text/plain
[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
## get_bpmn_instance
> models::BpmnInstanceDetail get_bpmn_instance(workspace, id)
get BPMN process instance
### Parameters
Name | Type | Description | Required | Notes
------------- | ------------- | ------------- | ------------- | -------------
**workspace** | **String** | | [required] |
**id** | **uuid::Uuid** | | [required] |
### Return type
[**models::BpmnInstanceDetail**](BpmnInstanceDetail.md)
### Authorization
[cookieAuth](../README.md#cookieAuth), [bearerAuth](../README.md#bearerAuth)
### HTTP request headers
- **Content-Type**: Not defined
- **Accept**: application/json, text/plain
[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
## get_bpmn_instance_status
> models::ProcessInstanceStatus get_bpmn_instance_status(workspace, id)
get BPMN process instance status
Frontend-facing projection of the process instance's live runtime state (lifecycle, per-activity status, variables, history, incidents), consumed by the live process token overlay. 404 if the instance isn't in the workspace, or if the engine has not picked it up yet (no runtime state).
### Parameters
Name | Type | Description | Required | Notes
------------- | ------------- | ------------- | ------------- | -------------
**workspace** | **String** | | [required] |
**id** | **uuid::Uuid** | | [required] |
### Return type
[**models::ProcessInstanceStatus**](ProcessInstanceStatus.md)
### Authorization
[cookieAuth](../README.md#cookieAuth), [bearerAuth](../README.md#bearerAuth)
### HTTP request headers
- **Content-Type**: Not defined
- **Accept**: application/json, text/plain
[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
## list_bpmn_incidents
> Vec<models::BpmnIncident> list_bpmn_incidents(workspace, id)
list BPMN process instance incidents
### Parameters
Name | Type | Description | Required | Notes
------------- | ------------- | ------------- | ------------- | -------------
**workspace** | **String** | | [required] |
**id** | **uuid::Uuid** | | [required] |
### Return type
[**Vec<models::BpmnIncident>**](BpmnIncident.md)
### Authorization
[cookieAuth](../README.md#cookieAuth), [bearerAuth](../README.md#bearerAuth)
### HTTP request headers
- **Content-Type**: Not defined
- **Accept**: application/json, text/plain
[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
## list_bpmn_instances
> Vec<models::BpmnInstanceSummary> list_bpmn_instances(workspace, page, per_page)
list BPMN process instances
### Parameters
Name | Type | Description | Required | Notes
------------- | ------------- | ------------- | ------------- | -------------
**workspace** | **String** | | [required] |
**page** | Option<**i32**> | which page to return (start at 1, default 1) | |
**per_page** | Option<**i32**> | number of items to return for a given page (default 30, max 100) | |
### Return type
[**Vec<models::BpmnInstanceSummary>**](BpmnInstanceSummary.md)
### Authorization
[cookieAuth](../README.md#cookieAuth), [bearerAuth](../README.md#bearerAuth)
### HTTP request headers
- **Content-Type**: Not defined
- **Accept**: application/json, text/plain
[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
## migrate_bpmn_instance
> models::BpmnMigrationResult migrate_bpmn_instance(workspace, id, migrate_bpmn_instance_request)
migrate one running BPMN process instance to another definition version
Validated pointer swap (#922). Validates the (current, target) pair against the identity-migration contract and, only if it passes, moves `v2_job.runnable_id` to the target version, refreshes the denormalised `bpmn_process_status.bpmn_version` (which no engine writer ever refreshes) and appends a `bpmn_instance_migration` ledger row -- all in one transaction. `process_status` is never written and `suspend_until` is never nudged; the instance runs on the target version from its next step, because the engine re-resolves the pinned definition on every step. A pair that fails the contract is refused with a 400 naming every offending identifier -- it is never migrated and flagged.
### Parameters
Name | Type | Description | Required | Notes
------------- | ------------- | ------------- | ------------- | -------------
**workspace** | **String** | | [required] |
**id** | **uuid::Uuid** | | [required] |
**migrate_bpmn_instance_request** | [**MigrateBpmnInstanceRequest**](MigrateBpmnInstanceRequest.md) | | [required] |
### Return type
[**models::BpmnMigrationResult**](BpmnMigrationResult.md)
### Authorization
[cookieAuth](../README.md#cookieAuth), [bearerAuth](../README.md#bearerAuth)
### HTTP request headers
- **Content-Type**: application/json
- **Accept**: application/json, text/plain
[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
## preview_bpmn_instance
> String preview_bpmn_instance(workspace, preview_bpmn_instance)
run BPMN process preview (undeployed diagram)
Start a process instance from an undeployed diagram (#710 stage 3), the \"run without deploying\" counterpart to `POST /bpmn/run/p/{path}`. The submitted XML is parsed and validated exactly as a real deploy would -- nothing is written to `bpmn_flow`/`bpmn_flow_version`.
### Parameters
Name | Type | Description | Required | Notes
------------- | ------------- | ------------- | ------------- | -------------
**workspace** | **String** | | [required] |
**preview_bpmn_instance** | [**PreviewBpmnInstance**](PreviewBpmnInstance.md) | inline BPMN XML plus initial process variables | [required] |
### Return type
**String**
### Authorization
[cookieAuth](../README.md#cookieAuth), [bearerAuth](../README.md#bearerAuth)
### HTTP request headers
- **Content-Type**: application/json
- **Accept**: text/plain, application/json
[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
## retry_bpmn_incident
> String retry_bpmn_incident(workspace, id, job_id)
retry a BPMN process instance incident
Validates the ActivityFailed incident, identified by the original failed child job's id, and records a retry intent on the process instance. The execution engine does not yet act on this intent: retrying an incident is not yet functional end-to-end. This endpoint only validates ownership of the incident and records the intent for a future engine version to consume.
### Parameters
Name | Type | Description | Required | Notes
------------- | ------------- | ------------- | ------------- | -------------
**workspace** | **String** | | [required] |
**id** | **uuid::Uuid** | | [required] |
**job_id** | **uuid::Uuid** | the failed child job id identifying the incident to retry (Incident.job) | [required] |
### Return type
**String**
### Authorization
[cookieAuth](../README.md#cookieAuth), [bearerAuth](../README.md#bearerAuth)
### HTTP request headers
- **Content-Type**: Not defined
- **Accept**: text/plain
[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
## start_bpmn_instance
> String start_bpmn_instance(workspace, path, start_bpmn_instance)
start BPMN process instance
### Parameters
Name | Type | Description | Required | Notes
------------- | ------------- | ------------- | ------------- | -------------
**workspace** | **String** | | [required] |
**path** | **String** | | [required] |
**start_bpmn_instance** | [**StartBpmnInstance**](StartBpmnInstance.md) | initial process variables | [required] |
### Return type
**String**
### Authorization
[cookieAuth](../README.md#cookieAuth), [bearerAuth](../README.md#bearerAuth)
### HTTP request headers
- **Content-Type**: application/json
- **Accept**: text/plain
[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)