# Migration guide v1 (deprecated) → v2

> Migrate from Wandelbots NOVA API v1 (deprecated) to v2. Understand the key changes and how to update your integration.

This migration guide highlights the changes in the Wandelbots NOVA API v2 compared to the Wandelbots NOVA API v1 (deprecated).
v2 comes with improvements like a less complex API and a more intuitive way to interact with the robot.
We're happy to announce that the v2 features consistent API behavior across endpoints as well as
less endpoints.

Read through the [NOVA API overview](/nova/26.7/nova-api/overview) and try it out using the [NOVA API v2 reference](https://portal.wandelbots.io/docs/api/v2/ui/#/)!
If you have any questions or need help, feel free to ask in the Wandelbots Robotics community.

## How to read this guide

With Wandelbots NOVA API v2, some workflows have changed in their functionality while other endpoints remain unchanged in their functionality.
Almost all endpoints have been renamed to be more intuitive and easier to use.
Some of them have been regrouped.

> **Info:** This guide skips endpoints that have only changed in their version from v1 (deprecated) to v2, e.g. `GET /api/v1/cells/{cell}/motion-groups` to `GET /api/v2/cells/{cell}/motion-groups`.
> This ensures that the guide focuses on the changes that are relevant for you and doesn't get to crowded.

To facilitate the migration from v1 (deprecated) to v2, this guide is structured as follows:

The parameter conversion section lists all **parameters that have changed in their name or functionality**.

[Parameter conversion](#parameter-conversion)

The general changes section describes **updates from v1 (deprecated) to v2 that apply to every endpoint and the v2 API structure**.

[General changes](#general-changes)

New functionalities include **features exclusively available with v2**.

[New functionalities](#new-functionalities)

Workflow updates lists all **relevant functionality updates when switching from v1 (deprecated) to v2**.
They are sorted by API endpoints and include a mapping from v1 (deprecated) to v2 in a table format.

[Workflow updates](#workflow-updates)

Regrouped endpoints include all **endpoints that have been regrouped with resulting path changes**.

[Regrouped endpoints](#regrouped-endpoints-resulting-in-new-paths)

Both workflow updates and name changes include a mapping table per endpoint that lists the version, group and endpoint for both v1 (deprecated) and v2.
If the endpoint name differs between v1 (deprecated) and v2, the v2 endpoint is listed with the renamed endpoint so that it's easier to find.

| Version | Group | Endpoint |
| - | - | - |
| v1 | v1 group | `GET /api/v1/v1group/endpoint` |
| v2 | v2 group | Renamed endpoint > `GET /api/v2/v2group/endpoint` |

Details about endpoints are provided in horizontal tabs.

## Parameter conversion

Refer to this table for the parameter conversion between v1 (deprecated) and v2:

| v1 parameter | v2 parameter |
| - | - |
| `id` | `identifier` |
| `planned motion` | `trajectory` |
| `reference_uid` | `reference_coordinate_system` |

## General changes

### Parameter case

v2 endpoints use snake\_case for the parameters, while v1 (deprecated) endpoints use camelCase.

### Separation of input and feedback

With v2, input and feedback are separated, which means that all output is provided by the state centrally,
not individually by each endpoint.

### Planning and execution endpoints

Planning and execution endpoints were separated.

### State and description endpoints

State endpoints fetch dynamically changing data, e.g. joint positions, controller operating modes.
Description endpoints fetch static data that is valid over the lifetime of a connection, e.g. configured TCPs, safety zones, limits.

### Managing coordinate systems on controllers

Adding and deleting coordinate systems on physical controllers is no longer supported in v2.
Use the original teaching pendant to add and delete coordinate systems on the controller.
Verify the correct data with [Motion Group Description](https://portal.wandelbots.io/docs/api/v2/ui/#/operations/getMotionGroupDescription), e.g., for mounting purposes.

For virtual controllers, you can still add and delete coordinate systems using the Virtual Robot Configuration endpoints.

### Typo fixed in motion group path of Virtual Robot Description endpoint

`motiongroups` was fixed to `motion-groups` in v2.

### Created controllers can immediately be listed

Performance upgrade: After adding a controller via `POST /api/v2/cells/{cell]/controllers`,
a subsequent `GET /api/v2/cells/{cell}/controllers` immediately lists the added controller, using an adequate status.

## New functionalities

### Group attributes

System state and cell service state provide a group attribute for each service with v2.

### Backup

You can now create a configuration backup of controller configurations, including filtering for specific services.

1. Use System > List Configuration Resources `GET /api/v2/system/configuration/resources`
   to list available configuration resources.
2. Use System > Retrieve Configuration Backup `GET /api/v2/system/configuration` and use the previously listed configuration resources.
   to create a backup.
3. Use System > Restore Configuration Backup `POST /api/v2/system/configuration` to restore a configuration backup.

### Activate and deactivate cells

Manage which cells are active or inactive with Cell > Operating State `PUT /api/v2/cells/{cell}/status`.
Inactive cells will not be displayed on the homescreen.

### Motion group state streams and description

Listing and (de)activating motion groups is no longer supported in v2,
but therefore a new state stream websocket as well as a state and description endpoints are available.

- Motion Group > Description `GET /api/v2/cells/{cell}/motion-groups/{motion-group}/description`\\
- Motion Group > State `GET /api/v2/cells/{cell}/motion-groups/{motion-group}/state`\\
- Motion Group > State Stream `GET /api/v2/cells/{cell}/motion-groups/{motion-group}/state-stream`

### Kinematics

You can now retrieve a list of reachable joint positions for a given TCP pose with Kinematics > Inverse kinematics > `POST /api/v2/cells/{cell}/kinematic/inverse`.

In this version, you can specify collision shapes; the endpoint will then return only non-colliding joint positions.

Additionally, you can calculate the TCP pose corresponding to a specific joint position using the Kinematics > Forward Kinematics > `POST /api/v2/cells/{cell}/kinematic/forward`.

Both endpoints support vectorized input samples, processing and returning results as batches.

### Plan collision-free trajectory

You can now select from different algorithms to plan a collision-free trajectory with Trajectory Planning > Plan Collision Free > `POST /api/v2/cells/{cell}/trajectory-planning/plan-collision-free`

### Trajectory caching

With v2, you can cache trajectories to avoid planning them again with the endpoint group labelled Trajectory Caching.

## Workflow updates

### List robot controllers

All information that was previously available in Controller > List Robot Controllers `GET /api/v1/cells/{cell}/controllers`
is now available in three different endpoints with additional information:

- Controller > List Robot Controllers `GET /api/v2/cells/{cell}/controllers`
- Controller > Description `GET /api/v2/cells/{cell}/controllers/{controller}/description`
- Motion Group > Description `GET /api/v2/cells/{cell}/controllers/{controller}/motion-groups/{motion-group}/description`

### Supported motion modes

| Version | Group | Endpoint |
| - | - | - |
| v1 | Controller | Supported Motion Modes > `GET /api/v1/cells/{cell}/controllers/{controller}/controller-capabilities` |
| v2 | Controller | Description > `GET /api/v2/cells/{cell}/controllers/{controller}/description` |

### Streaming controller mode changes

Streaming mode changes is possible, but information on previous modes and the cause of the mode change is not provided with v2.

| Version | Group | Endpoint |
| - | - | - |
| v1 | Controller | Stream Mode Changes > `GET /api/v1/cells/{cell}/controllers/{controller}/mode-stream` |
| v2 | Controller | Stream State > `GET /api/v2/ui/#/operations/streamRobotControllerState` |

### Program Operator deprecated in v2

The Program Operator endpoints have been deprecated in NOVA API v2.

The provided functionalities are replaced by the Python SDK, including OPC UA data subscription functionalities in
[Wandelbots NOVA Python SDK](https://github.com/wandelbotsgmbh/wandelbots-nova),
which offers more flexibility for custom app development.
Client-related Wandelscript (deprecated) features will remain unchanged until end of support for Wandelscript (deprecated).

### Updating virtual controller configurations

While in v1 (deprecated), Controller > Update Robot Controller Configuration `PUT /cells/{cell}/controllers/{controller}` was available (now also deprecated),
with v2, you need to delete and re-add the virtual controller with the updated configuration:

1. Use Controller > Delete Robot Controller `DELETE /cells/{cell}/controllers/{controller}` to delete the virtual controller.
2. Use Controller > Add Robot Controller `POST /cells/{cell}/controllers` to add a new virtual controller with the updated configuration.

### Generic capabilities

Capabilities of a controller were previously listed in Motion Group Infos > Capabilities and very specific, e.g. list\_tcps.
They are now replaced by Controller > Descriptions endpoint.

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion Group Infos | `GET /api/v1/cells/{cell}/motion-groups/{motion-group}/info-capabilities` |
| v2 | Controller | Description > `GET /api/v2/cell/{cells}/controllers/{controller}/description` |

### Current payload

Payloads are only supported by Motion Group > State and not by Motion Group > State Stream.
We're working on streaming active payloads in the future.

### Planning and executing trajectories for connected motion groups

API v2 features a bi-directional websocket to execute trajectories. The Trajectory Planning, Execution and Caching
endpoints replace the v1 (deprecated) Motion endpoints for planning and executing motions.

The common workflow with v2 is the following:

1. Fetch parameters for the connected motion group using getMotionGroupDescription.
2. planTrajectory.
3. executeTrajectory.

For a detailed mapping of v1 (deprecated) Motion endpoints to v2 Trajectory Planning, Execution and Caching endpoints,
see the section below.

**List All Motions**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion | `GET /api/v1/cells/{cell}/motions` |
| v2 | Trajectory Execution | List Trajectories > `GET /api/v2/cells/{cell}/trajectories` |

**Plan Motion**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion | `POST /api/v1/cells/{cell}/motions` |
| v2 | Trajectory Planning, Trajectory Caching | First, use Plan Trajectory then Add trajectory |

**Delete All Motions**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion | `DELETE /api/v1/cells/{cell}/motions` |
| v2 | Trajectory Execution | Clear trajectories > `DELETE /api/v2/cells/{cell}/trajectories` |

**Plan Trajectory**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion | `POST /api/v1/cells/{cell}/motion-planning/plan-trajectory` |
| v2 | Trajectory Planning | Plan Trajectory > `POST /api/v2/cells/{cell}/trajectory-planning/plan-trajectory` |

**Plan Collision Free PTP**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion | `POST /api/v1/cells/{cell}/motion-planning/plan-collision-free-ptp` |
| v2 | Trajectory Planning | Plan Collision Free > `POST /api/v2/cells/{cell}/trajectory-planning/plan-collision-free` |

**Motion Group Models for Planning**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion | `GET /api/v1/cells/{cell}/motion-planning/motion-group-models` |
| v2 | Motion Group Models | `GET /api/v2/cells/{cell}/motion-group-models` |

**Load Planned Motion**

| Version | Motion | Endpoint |
| - | - | - |
| v1 | Cells | `POST /api/v1/cells/{cell}/motion-planning/planned-motions` |
| v2 | Trajectory Caching | Add Trajectory > `POST /api/v2/cells/{cell}/trajectories` |

**Get Planned Motion**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion | `GET /api/v1/cells/{cell}/motion-planning/planned-motion` |
| v2 | Trajectory Caching | Get Trajectory > `GET /api/v2/cells/{cell}/trajectories/{trajectory}` |

**Remove**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion | `DELETE /api/v1/cells/{cell}/motions/{motion}/delete` |
| v2 | Trajectory Caching | Delete Trajectory > `DELETE /api/v2/cells/{cell}/trajectories/{trajectory}` |

**Stream Backward**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion | `GET /api/v1/cells/{cell}/motions/{motion}/executebackward` |
| v2 | Trajectory Execution | Execute Trajectory > `GET /api/v2/cells/{cell}/execution/trajectory`, use StartMovementRequest and set the direction parameter to backward |

**Stream Forward**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion | `GET /api/v1/cells/{cell}/motions/{motion}/executeforward` |
| v2 | Trajectory Execution | Execute Trajectory > `GET /api/v2/cells/{cell}/execution/trajectory`, use StartMovementRequest and set the direction parameter to forward |

**Stream to Trajectory**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion | `GET /api/v1/cells/{cell}/motions/{motion}/executetotrajectory` |
| v2 | Trajectory Planning, Trajectory Execution | First use Trajectory Planning > Plan Trajectory, then Trajectory Execution > Execute Trajectory to move to the start of another trajectory |

**Stop**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion | `PUT /api/v1/cells/{cell}/motions/{motion}/stop` |
| v2 | Trajectory Execution | Execute Trajectory > `GET /api/v2/cells/{cell}/execution/trajectory`, use PauseMovementRequest |

**Get Trajectory**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion | `GET /api/v1/cells/{cell}/motions/{motion}/trajectory` |
| v2 | Trajectory Caching | Get Trajectory > `GET /api/v2/cells/{cell}/trajectories/{trajectory}` |

**Get Trajectory Sample**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion | `GET /api/v1/cells/{cell}/motions/{motion}/trajectorysample` |
| v2 | - | - |

**Stream Move**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion | `GET /api/v1/cells/{cell}/motions/streammove` |
| v2 | Trajectory Execution | Execute Trajectory > `GET /api/v2/cells/{cell}/execution/trajectory` |

**Execute Trajectory**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion | `GET /api/v1/cells/{cell}/motions/executetrajectory` |
| v2 | Trajectory Execution | Execute Trajectory > `GET /api/v2/cells/{cell}/execution/trajectory` |

### Jogging motion groups

You now have a single bi-directional websocket for jogging functionalities:

Jogging > Execute Jogging `GET /api/v2/cells/{cell}/execution/jogging`

### Device Configuration

All Device Configuration endpoints were removed in v2.
To replace the functionalities, use the Controller endpoint and update the devices by updating controller configurations.

### Store Collision Scene

The Collision Scene type was replaced by `Store Collision Setup` in v2.

| Version | Group | Endpoint |
| - | - | - |
| v1 | Store Collision Scene | `/cells/{cell}/store/collision/scenes` |
| v2 | Store Collision Setup | `/cells/{cell}/store/collision/setups` |

For setups with a single motion group, use the `Collision Setup` type to define the shape of the motion group and its environment.

This change applies to all endpoints involving the shape of a single motion group and its environment:

- Trajectory Planning > Plan Collision-Free
- Trajectory Planning > Plan Trajectory
- Kinematics > Inverse Kinematics
- Store Collision Setups > Store Collision Setup

If you require specifying a collision scene for multiple motion groups, please contact Wandelbots Success. We are currently collecting feedback to better support this functionality in future releases.

## Regrouped endpoints resulting in new paths

The endpoints listed in this section have been regrouped in v2 but maintain the same functionality.

### Motion Group Infos

**Device Mounting**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion Group Infos | `GET /api/v1/cells/{cell}/motion-groups/{motion-group}/mounting` |
| v2 | Motion Group | Description > `GET /api/v2/cells/{cell}/motion-groups/{motion-group}/description` |

**Optimizer Configuration**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion Group Infos | `GET /api/v1/cells/{cell}/motion-groups/{motion-group}/optimizer-setup` |
| v2 | Motion Group | Description > `GET /api/v2/cells/{cell}/motion-groups/{motion-group}/description` |

**List Payloads**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion Group Infos | `GET /api/v1/cells/{cell}/motion-groups/{motion-group}/payloads` |
| v2 | Motion Group | Description > `GET /api/v2/cells/{cell}/motion-groups/{motion-group}/description` |

**Selected Payloads**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion Group Infos | `GET /api/v1/cells/{cell}/motion-groups/{motion-group}/payloads/current` |
| v2 | Motion Group | State > `GET /api/v2/cells/{cell}/motion-groups/{motion-group}/state` |

**Safety Setup and Limitations**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion Group Infos | `GET /api/v1/cells/{cell}/motion-groups/{motion-group}/safety-setup` |
| v2 | Motion Group | Description > `GET /api/v2/cells/{cell}/motion-groups/{motion-group}/description` |

**Get Static Properties**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion Group Infos | `GET /api/v1/cells/{cell}/motion-groups/{motion-group}/specification` |
| v2 | Motion Group | Description > `GET /api/v2/cells/{cell}/motion-groups/{motion-group}/description` |

**State of Device**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion Group Infos | `GET /api/v1/cells/{cell}/motion-groups/{motion-group}/state` |
| v2 | Motion Group | State > `GET /api/v2/cells/{cell}/motion-groups/{motion-group}/state` |

**Stream State of Device**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion Group Infos | `GET /api/v1/cells/{cell}/motion-groups/{motion-group}/state-stream` |
| v2 | Motion Group | Stream State > `GET /api/v2/cells/{cell}/motion-groups/{motion-group}/state-stream` |

**List TCPs**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion Group Infos | `GET /api/v1/cells/{cell}/motion-groups/{motion-group}/tcps` |
| v2 | Motion Group | Description > `GET /api/v2/cells/{cell}/motion-groups/{motion-group}/description` |

**Selected TCP**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion Group Infos | `GET /api/v1/cells/{cell}/motion-groups/{motion-group}/tcps/current` |
| v2 | Motion Group | State > `GET /api/v2/cells/{cell}/motion-groups/{motion-group}/state` |

### Motion Group Kinematic

**Capabilities**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion Group Kinematic | `GET /api/v1/cells/{cell}/motion-groups/{motion-group}/kinematic-capabilities` |
| v2 | Motion Group | `GET /api/v2/cells/{cell}/motion-groups/{motion-group}/description` |

**All Joint Positions from TCP Pose**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion Group Kinematic | `POST /api/v1/cells/{cell}/motion-groups/{motion-group}/calculate-all-joint-positions` |
| v2 | Kinematics | `POST /api/v2/cells/{cell}/kinematic/inverse` |

**Nearest Joint Position from TCP Pose**

This functionality is not part of the v2 API, since the selection of 'nearest' is application specific.
Use Kinematics > Inverse Kinematics to get all reachable joint positions
and then select the nearest one based on your application logic.

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion Group Kinematic | `POST /api/v1/cells/{cell}/motion-groups/{motion-group}/calculate-joint-position` |
| v2 | Kinematics | `POST /api/v2/cells/{cell}/kinematic/inverse` |

**TCP Pose from Joint Position**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Motion Group Kinematic | `POST /api/v1/cells/{cell}/motion-groups/{motion-group}/calculate-tcp-pose` |
| v2 | Kinematics | `POST /api/v2/cells/{cell}/kinematic/forward` |

### Virtual Robot

**Get I/O**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Virtual Robot | `GET /api/v1/cells/{cell}/controllers/{controller}/teach-pendant/ios` |
| v2 | Virtual Robot | Get Inputs/Outputs > `GET /api/v2/cells/{cell}/controllers/{controller}/teach-pendant/ios` |

**Set I/O**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Virtual Robot | `PUT /api/v1/cells/{cell}/controllers/{controller}/teach-pendant/ios` |
| v2 | Virtual Robot | Set Input/Output Values > `PUT /api/v2/cells/{cell}/controllers/{controller}/teach-pendant/ios` |

**Get Motion Group State**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Virtual Robot | `GET /api/v1/cells/{cell}/controllers/{controller}/teach-pendant/motion-groups` |
| v2 | Virtual Robot | `GET /api/v2/cells/{cell}/controllers/{controller}/teach-pendant/motion-groups` |

**Set Motion Group State**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Virtual Robot | `PUT /api/v1/cells/{cell}/controllers/{controller}/teach-pendant/motion-groups` |
| v2 | Virtual Robot | `PUT /api/v2/cells/{cell}/controllers/{controller}/teach-pendant/motion-groups` |

### Virtual Robot Mode

**Get E-Stop State**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Virtual Robot Mode | `GET /api/v1/cells/{cell}/controllers/{controller}/teach-pendant/estop` |
| v2 | Virtual Robot Mode | `GET /api/v2/cells/{cell}/controllers/{controller}/teach-pendant/emergency-stop` |

**Push E-Stop**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Virtual Robot Mode | `PUT /api/v1/cells/{cell}/controllers/{controller}/teach-pendant/estop/push` |
| v2 | Virtual Robot Mode | `PUT /api/v2/cells/{cell}/controllers/{controller}/teach-pendant/emergency-stop`, set active to `true` |

**Release E-Stop**

| Version | Group | Endpoint |
| - | - | - |
| v1 | Virtual Robot Mode | `PUT /api/v1/cells/{cell}/controllers/{controller}/teach-pendant/release` |
| v2 | Virtual Robot Mode | `PUT /api/v2/cells/{cell}/controllers/{controller}/teach-pendant/emergency-stop`, set active to `false` |