3.2. Portal Redirects (Interactive Workflows)

Most of the core exercise operations (creating, editing, and executing) require an interactive graphical interface. Instead of building a complex frontend, you will redirect your users to the Exercise-Engine Portal.

All redirect endpoints follow a similar pattern: they require an exerciseKey (except for creation), your App token, and an optional meta field passed as query parameters.

The Role of the `meta` Field

The meta field is a critical tool for maintaining your application's state. You can pass any stringified data (such as your internal userId or sessionId) in this query parameter. The Portal does not process this data; it simply holds it and returns it to your backend via the Webhook and the callback URL once the user finishes their session.

A. Create Exercise

Endpoint:GET https://api.platform.hemscap.com/v1//api/platform/portal/info-swagger/exercise-redirect/create
Description: Initializes a new exercise with default values. It instantly generates a unique exerciseKey and redirects the user directly to the Modify interface so they can build their new exercise.
Success: HTTP 302 Found (Redirects browser to the builder URL).

Frontend Sample Code (TypeScript):

const PLATFORM_URL = 'https://api.platform.hemscap.com/v1//api/platform/portal/info-swagger/exercise-redirect';

const createNewExercise = (appToken: string, userMetaState: string): void => {
  // Construct the URL and navigate the browser
  const url = `${PLATFORM_URL}/create?token=${appToken}&meta=${encodeURIComponent(userMetaState)}`;
  window.location.href = url;
};

B. Modify Exercise

Endpoint:GET https://api.platform.hemscap.com/v1//api/platform/portal/info-swagger/exercise-redirect/{exerciseKey}/modify
Description: Redirects the user to the visual exercise builder/editor to update an existing exercise.

const openExerciseEditor = (exerciseKey: string, appToken: string, userMetaState: string): void => {
  const url = `${PLATFORM_URL}/${exerciseKey}/modify?token=${appToken}&meta=${encodeURIComponent(userMetaState)}`;
  window.location.href = url;
};

C. Exercise Animation

Endpoint:GET https://api.platform.hemscap.com/v1//api/platform/portal/info-swagger/exercise-redirect/{exerciseKey}/animation
Description: Redirects the user to the 3D animation builder page for a specific exercise.

const viewExerciseAnimation = (exerciseKey: string, appToken: string, userMetaState: string): void => {
  const url = `${PLATFORM_URL}/${exerciseKey}/animation?token=${appToken}&meta=${encodeURIComponent(userMetaState)}`;
  window.location.href = url;
};

D. Execute Exercise

Endpoint:GET https://api.platform.hemscap.com/v1//api/platform/portal/info-swagger/exercise-redirect/{exerciseKey}/execute
Description: Used when a user needs to perform the workout. It redirects them to the real-time AI tracking camera interface.

const startWorkoutSession = (exerciseKey: string, appToken: string, userMetaState: string): void => {
  const url = `${PLATFORM_URL}/${exerciseKey}/execute?token=${appToken}&meta=${encodeURIComponent(userMetaState)}`;
  window.location.href = url;
};

Error Handling for Redirects

If a validation failure (e.g., invalid token) or system error occurs before the redirect can happen, the endpoint will not issue a 302. Instead, it will return an HTTP error status along with the following JSON structure:

{
  "error": true,
  "message": "Description of the error (e.g., Token Not Found)",
  "result": {}
}