Skip to content

PowerMind InsightML REST API Documentation

This guide provides technical specifications for the PowerMind InsightML REST API. All endpoints are versioned under /api/v1 except for metadata, platform keys, and full AutoML helper endpoints.

1. Global API Parameters & Authentication

Base URL

  • Local Development: http://localhost:8000
  • Secure Instance: https://<your-server-ip>

Headers

  • Platform Operations: Include Authorization: Bearer <JWT> or x-api-key: <Platform_API_Key>
  • Inference Operations: Include x-api-key: <Deployment_API_Key>
  • Response Format: All endpoints return structured JSON with MIME-type application/json except model download which returns application/octet-stream.

2. Platform Service Endpoints

These endpoints require no authentication and can be used to verify the platform's status.

Health Check

GET /health

  • Description: Liveness probe.
  • Response: 
    {
  "status": "ok",
  "timestamp": "2026-06-02T12:00:00Z"
}

Readiness Check

GET /ready

  • Description: Readiness probe.
  • Response: 
    {
  "status": "ready"
}

Service Version

GET /version

  • Description: Retrieves service version info.
  • Response: 
    {
  "service": "powermind-insightml",
  "version": "1.0.0"
}

3. Authentication & Users

User Registration

POST /api/v1/auth/register

  • Body (JSON): 

    {
  "email": "user@example.com",
  "username": "developer1",
  "password": "strong_password_here_12_chars_min"
}

  • Response: 

    {
  "id": 1,
  "email": "user@example.com"
}

Login (Obtain Access Token)

POST /api/v1/auth/login

  • Headers: Content-Type: application/x-www-form-urlencoded
  • Form Fields:
    • username (string - email address)
    • password (string)

  • Response: 

    {
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 900
}

  • Cookies Set: __Host-refresh_token (HttpOnly, Secure, SameSite=Lax)

Token Refresh

POST /api/v1/auth/refresh

  • Headers: Requires active __Host-refresh_token cookie.

  • Response: 

    {
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 900
}

  • Cookies Rotated: A new rotated __Host-refresh_token cookie is set.

Logout

POST /api/v1/auth/logout

  • Headers: Clears the active __Host-refresh_token cookie.
  • Response: 
    {
  "message": "Logged out successfully"
}

List Active Sessions

GET /api/v1/auth/sessions

  • Auth: Platform Scope
  • Response: 
    [
  {
    "id": "7ac237f3-e5d2-43b9-b827-0cfc74a00bc9",
    "created_at": "2026-06-22T07:00:00Z",
    "expires_at": "2026-06-29T07:00:00Z",
    "is_current": true
  }
]

Revoke Session

DELETE /api/v1/auth/sessions/{session_id}

  • Auth: Platform Scope
  • Response: 
    {
  "message": "Session revoked successfully"
}

Revoke Other Sessions

DELETE /api/v1/auth/sessions

  • Auth: Platform Scope
  • Response: 
    {
  "message": "Revoked 1 other session(s) successfully"
}

Retrieve Logged-In User Details

GET /api/v1/auth/me

  • Auth: Platform Scope
  • Response: 
    {
  "id": 1,
  "email": "user@example.com",
  "username": "developer1"
}

4. Workspaces & FeatureHub Integration

Workspaces are the root multi-tenant containers. Workspaces control the FeatureHub synchronization context.

List Workspaces

GET /api/v1/workspaces/

  • Auth: Platform Scope
  • Response: 
    [
  {
    "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "name": "default-workspace",
    "owner_id": "9a8b7c6d-5e4f-3a2b-1c0d-e9f8a7b6c5d4",
    "is_active": true,
    "max_experiments": 100,
    "max_deployments": 5,
    "max_datasources": 10
  }
]

Create Workspace

POST /api/v1/workspaces/

  • Auth: Platform Scope

  • Body (JSON): 

    {
  "name": "Production Workspace"
}

  • Response: 

    {
  "id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
  "name": "Production Workspace",
  "owner_id": "9a8b7c6d-5e4f-3a2b-1c0d-e9f8a7b6c5d4",
  "is_active": true,
  "max_experiments": null,
  "max_deployments": null,
  "max_datasources": null
}

Get Workspace Details

GET /api/v1/workspaces/{workspace_id}

  • Auth: Platform Scope
  • Response: 
    {
  "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "name": "default-workspace",
  "owner_id": "9a8b7c6d-5e4f-3a2b-1c0d-e9f8a7b6c5d4",
  "is_active": true,
  "max_experiments": 100,
  "max_deployments": 5,
  "max_datasources": 10
}

Delete Workspace

DELETE /api/v1/workspaces/{workspace_id}

  • Auth: Platform Scope
  • Response: 
    {
  "message": "Workspace deleted"
}

Configure FeatureHub Connection

POST /api/v1/workspaces/{workspace_id}/datasources/featurehub

  • Auth: Platform Scope

  • Body (JSON): 

    {
  "base_url": "https://featurehub.example.com",
  "api_key": "fh_integration_api_key_string",
  "fhb_workspace_id": "fh_ws_123"
}

  • Response: 

    {
  "configured": true,
  "workspace_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "fhb_workspace_id": "fh_ws_123",
  "base_url": "https://featurehub.example.com",
  "key_prefix": "fh_integrati",
  "updated_at": "2026-06-22T07:00:00.000000"
}

Check FeatureHub Connection Status

GET /api/v1/workspaces/{workspace_id}/datasources/featurehub

  • Auth: Platform Scope
  • Response: 
    {
  "configured": true,
  "workspace_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "fhb_workspace_id": "fh_ws_123",
  "base_url": "https://featurehub.example.com",
  "key_prefix": "fh_integrati",
  "updated_at": "2026-06-22T07:00:00.000000"
}

5. Projects

Projects organize datasets, training runs, and model deployment registries.

List Projects

GET /api/v1/projects/

  • Auth: Platform Scope
  • Query Parameters:
    • limit (integer, default: 10)
    • offset (integer, default: 0)
  • Response: 
    {
  "total": 1,
  "limit": 10,
  "offset": 0,
  "data": [
    {
      "id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
      "workspace_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "name": "Credit Risk Prediction"
    }
  ]
}

Create Project

POST /api/v1/projects/

  • Auth: Platform Scope

  • Body (JSON): 

    {
  "workspace_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "name": "Customer Churn Analysis"
}

  • Response: 

    {
  "id": "4d5e6f7a-8b9c-0d1e-2f3a-4b5c6d7e8f9a",
  "workspace_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "name": "Customer Churn Analysis"
}

Get Project Details

GET /api/v1/projects/{project_id}

  • Auth: Platform Scope
  • Response: 
    {
  "id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
  "workspace_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "name": "Credit Risk Prediction"
}

Delete Project

DELETE /api/v1/projects/{project_id}

  • Auth: Platform Scope
  • Response: 
    {
  "message": "Project deleted"
}

6. Datasets Ingestion

Datasets are uploaded as CSV files or pulled from an offline FeatureHub datasource.

Upload CSV Dataset

POST /api/v1/datasets/upload

  • Auth: Platform Scope
  • Content-Type: multipart/form-data
  • Form Parameters:
    • project_id (UUID string)
    • name (string)
    • file (binary file)
  • Response: 
    {
  "id": "5e6f7a8b-9c0d-1e2f-3a4b-5c6d7e8f9a0b",
  "name": "churn-train-data",
  "project_id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
  "version": 1
}

Create FeatureHub Dataset

POST /api/v1/datasets/featurehub

  • Auth: Platform Scope
  • Content-Type: multipart/form-data
  • Form Parameters:
    • project_id (UUID string)
    • name (string)
    • feature_name (string - feature catalog table name)
  • Response: 
    {
  "id": "6f7a8b9c-0d1e-2f3a-4b5c-6d7e8f9a0b1c",
  "name": "marketing_features",
  "source_type": "featurehub",
  "feature_name": "user_demographics_v1"
}

List Project Datasets

GET /api/v1/datasets/project/{project_id}

  • Auth: Platform Scope
  • Query Parameters:
    • limit (integer, default: 10)
    • offset (integer, default: 0)
  • Response: 
    {
  "total": 1,
  "limit": 10,
  "offset": 0,
  "data": [
    {
      "id": "5e6f7a8b-9c0d-1e2f-3a4b-5c6d7e8f9a0b",
      "project_id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
      "name": "churn-train-data",
      "file_path": "workspaces/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d/projects/3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f/datasets/churn-train-data_v1.csv",
      "version": 1,
      "source_type": "csv",
      "featurehub_config": null
    }
  ]
}

Preview Dataset

GET /api/v1/datasets/{dataset_id}/preview

  • Auth: Platform Scope
  • Response: 
    {
  "columns": ["customer_id", "credit_score", "defaulted"],
  "rows": [
    {"customer_id": 1001, "credit_score": 720, "defaulted": 0},
    {"customer_id": 1002, "credit_score": 580, "defaulted": 1}
  ]
}

Delete Dataset

DELETE /api/v1/datasets/{dataset_id}

  • Auth: Platform Scope
  • Response: 
    {
  "message": "Dataset deleted"
}

7. AutoML Training (Asynchronous)

AutoML runs asynchronously in the background. Check experiment status using the retrieval route.

Run AutoML Experiment

POST /api/v1/experiments/run-automl

  • Auth: Platform Scope

  • Body (JSON): 

    {
  "name": "credit-risk-baseline",
  "project_id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
  "dataset_id": "5e6f7a8b-9c0d-1e2f-3a4b-5c6d7e8f9a0b",
  "problem_type": "classification",
  "target_column": "defaulted"
}

    • problem_type supports: classification, regression, clustering, time_series.
    • target_column must be omitted for clustering.
    • n_clusters (integer, e.g., 4) is optional only for clustering.
    • time_column and forecast_horizon (integer) are required only for time_series.
    • auto_create_lags (boolean, optional, default: true) tells AutoML whether to automatically create lag/rolling features for time_series models. If set to false, no lag features will be auto-created and the inference helper panel will be disabled for deployment.

  • Response: 

    {
  "experiment_id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
  "status": "queued",
  "problem_type": "classification",
  "n_clusters": null
}

List Project Experiments

GET /api/v1/experiments/project/{project_id}

  • Auth: Platform Scope
  • Query Parameters:
    • limit (integer, default: 10)
    • offset (integer, default: 0)
  • Response: 
    [
  {
    "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
    "project_id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
    "dataset_id": "5e6f7a8b-9c0d-1e2f-3a4b-5c6d7e8f9a0b",
    "name": "credit-risk-baseline",
    "status": "completed",
    "best_model": "ensemble_voting_classifier",
    "metrics": "{\"accuracy\": 0.942, \"f1\": 0.938, \"precision\": 0.945, \"recall\": 0.938}",
    "owner_id": "9a8b7c6d-5e4f-3a2b-1c0d-e9f8a7b6c5d4"
  }
]

Get Experiment Status

GET /api/v1/experiments/{experiment_id}

  • Auth: Platform Scope
  • Response: 
    {
  "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
  "name": "credit-risk-baseline",
  "status": "completed",
  "best_model": "ensemble_voting_classifier",
  "metrics": "{\"accuracy\": 0.942, \"f1\": 0.938, \"precision\": 0.945, \"recall\": 0.938}"
}

Delete Experiment

DELETE /api/v1/experiments/{experiment_id}

  • Auth: Platform Scope
  • Response: 
    {
  "message": "Experiment deleted"
}

One-Click Full AutoML (Helper Flow)

POST /automl/run-full

  • Auth: Platform Scope
  • Content-Type: multipart/form-data
  • Description: Creates/reuses a project, uploads/reuses a dataset, creates an experiment, and queues training in a single invocation.
  • Form Parameters:
    • workspace_id (UUID string)
    • project_name (string)
    • dataset_name (string)
    • problem_type (string)
    • file (binary CSV file)
    • target_column (string, optional)
    • n_clusters (integer, optional)
    • time_column (string, optional)
    • forecast_horizon (integer, optional)
    • auto_create_lags (boolean, optional, default: true)
  • Response: 
    {
  "project_id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
  "project_created": false,
  "dataset_id": "5e6f7a8b-9c0d-1e2f-3a4b-5c6d7e8f9a0b",
  "dataset_created": true,
  "experiment_id": "8b9c0d1e-2f3a-4b5c-6d7e-8f9a0b1c2d3e",
  "experiment_name": "AutoML_churn-train-data",
  "problem_type": "classification",
  "n_clusters": null,
  "status": "queued"
}

8. Model Registry

Trained models are automatically saved in the registry.

List Project Models

GET /api/v1/models/

  • Auth: Platform Scope
  • Query Parameters:
    • project_id (UUID string, required)
    • limit (integer, default: 10)
    • offset (integer, default: 0)
  • Response: 
    {
  "total": 2,
  "limit": 10,
  "offset": 0,
  "data": [
    {
      "id": "9b0c1d2e-3f4a-5b6c-7d8e-9f0a1b2c3d4e",
      "project_id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
      "experiment_id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
      "name": "random_forest",
      "version": 1,
      "stage": "staging",
      "metrics": {"accuracy": 0.912, "f1": 0.908},
      "created_at": "2026-06-22T07:05:00Z"
    }
  ]
}

List Models Registered under an Experiment

GET /api/v1/models/experiments/{experiment_id}/models

  • Auth: Platform Scope
  • Query Parameters:
    • limit (integer, default: 10)
    • offset (integer, default: 0)
  • Response: 
    {
  "total": 1,
  "limit": 10,
  "offset": 0,
  "data": [
    {
      "id": "9b0c1d2e-3f4a-5b6c-7d8e-9f0a1b2c3d4e",
      "project_id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
      "experiment_id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
      "name": "random_forest",
      "version": 1,
      "stage": "staging",
      "metrics": {"accuracy": 0.912, "f1": 0.908},
      "created_at": "2026-06-22T07:05:00Z"
    }
  ]
}

Download Model Artifact

GET /api/v1/models/{model_id}/download

  • Auth: Platform Scope
  • Response: Binary model download stream (.joblib file).

Delete Model

DELETE /api/v1/models/{model_id}

  • Auth: Platform Scope
  • Response: 
    {
  "message": "Model deleted"
}

9. Platform API Keys Management

Create, list, and revoke platform-wide administrative keys.

Create Platform Key

POST /api-keys/

  • Auth: Platform Scope (JWT or Platform Key)
  • Query Parameters:
    • workspace_id (UUID string, required)
    • name (string, required)
  • Response: 
    {
  "api_key": "IML_live_platform_ab12cd34ef...",
  "name": "jenkins-ci-key",
  "workspace_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
}

List Platform Keys

GET /api-keys/

  • Auth: Platform Scope
  • Query Parameters:
    • workspace_id (UUID string, required)
  • Response: 
    [
  {
    "id": "e9f8a7b6-c5d4-3e2f-1a0b-9c8d7e6f5a4b",
    "name": "jenkins-ci-key",
    "prefix": "IML_live_pla",
    "created_at": "2026-06-22T07:00:00Z"
  }
]

Revoke Platform Key

DELETE /api-keys/{key_id}

  • Auth: Platform Scope
  • Response: 
    {
  "status": "revoked"
}

10. Deployments & Predictions

Deploy models to production, control running statuses, monitor health, and generate prediction keys.

Create Deployment

POST /api/v1/deployments

  • Auth: Platform Scope

  • Body (JSON): 

    {
  "model_id": "9b0c1d2e-3f4a-5b6c-7d8e-9f0a1b2c3d4e"
}

  • Response: 

    {
  "deployment_id": "ad9c8b7a-6e5d-4c3b-2a10-e9f8a7b6c5d4",
  "status": "queued"
}

Get Deployment Status & Metadata

GET /api/v1/deployments/{deployment_id}

  • Auth: Platform Scope
  • Response: 
    {
  "id": "ad9c8b7a-6e5d-4c3b-2a10-e9f8a7b6c5d4",
  "model_id": "9b0c1d2e-3f4a-5b6c-7d8e-9f0a1b2c3d4e",
  "version": "v1",
  "deployment_name": "random_forest_v1",
  "status": "running",
  "endpoint": "/api/v1/infer/random_forest_v1",
  "error_message": null,
  "metadata": {
    "project_id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
    "workspace_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "serving_model_name": "random_forest_v1",
    "input_feature_count": 4,
    "input_features": ["credit_score", "age", "loan_amount", "income"],
    "input_datatype": "FP32",
    "input_shape": [1, 4],
    "output_datatype": "FP32",
    "output_shape": [1, 1],
    "inference_requirements": null
  }
}

List Project Deployments

GET /api/v1/projects/{project_id}/deployments

  • Auth: Platform Scope
  • Query Parameters:
    • limit (integer, default: 10)
    • offset (integer, default: 0)
  • Response: 
    {
  "total": 1,
  "limit": 10,
  "offset": 0,
  "data": [
    {
      "id": "ad9c8b7a-6e5d-4c3b-2a10-e9f8a7b6c5d4",
      "model_id": "9b0c1d2e-3f4a-5b6c-7d8e-9f0a1b2c3d4e",
      "project_id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
      "workspace_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "version": "v1",
      "deployment_name": "random_forest_v1",
      "status": "running",
      "endpoint": "/api/v1/infer/random_forest_v1",
      "error_message": null,
      "created_at": "2026-06-22T07:10:00Z",
      "updated_at": "2026-06-22T07:11:00Z"
    }
  ]
}

Start Stopped Deployment

POST /api/v1/deployments/{deployment_id}/start

  • Auth: Platform Scope
  • Response: Same structure as Get Deployment Status & Metadata but transitions state to pending/running.

Stop Running Deployment

POST /api/v1/deployments/{deployment_id}/stop

  • Auth: Platform Scope
  • Response: 
    {
  "deployment": {
    "id": "ad9c8b7a-6e5d-4c3b-2a10-e9f8a7b6c5d4",
    "model_id": "9b0c1d2e-3f4a-5b6c-7d8e-9f0a1b2c3d4e",
    "version": "v1",
    "deployment_name": "random_forest_v1",
    "status": "stopped",
    "endpoint": "/api/v1/infer/random_forest_v1",
    "error_message": null
  },
  "unload": {
    "deployment_id": "ad9c8b7a-6e5d-4c3b-2a10-e9f8a7b6c5d4",
    "status": "stopped",
    "unload_attempted": true,
    "unloaded": true,
    "detail": "unload_success"
  }
}

Get Deployment Health Status

GET /api/v1/deployments/{deployment_id}/health

  • Auth: Platform Scope
  • Response: 
    {
  "deployment_id": "ad9c8b7a-6e5d-4c3b-2a10-e9f8a7b6c5d4",
  "status": "running",
  "ready": true,
  "detail": "Model is loaded and ready"
}

Delete Deployment

DELETE /api/v1/deployments/{deployment_id}

  • Auth: Platform Scope
  • Response: 
    {
  "message": "Deployment deleted"
}

Create Deployment API Key (Inference Scoped)

POST /api/v1/deployments/{deployment_id}/api-keys

  • Auth: Platform Scope

  • Body (JSON): 

    {
  "name": "production-client-app"
}

  • Response: 

    {
  "id": "b1c2d3e4-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
  "name": "production-client-app",
  "prefix": "IML_live_deploy",
  "api_key": "IML_live_deploy_xy98zw76..."
}

List Deployment API Keys

GET /api/v1/deployments/{deployment_id}/api-keys

  • Auth: Platform Scope
  • Response: 
    [
  {
    "id": "b1c2d3e4-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
    "name": "production-client-app",
    "prefix": "IML_live_deploy",
    "created_at": "2026-06-22T07:12:00Z",
    "last_used_at": "2026-06-22T07:15:00Z"
  }
]

Revoke Deployment API Key

DELETE /api/v1/deployments/{deployment_id}/api-keys/{key_id}

  • Auth: Platform Scope
  • Response: 
    {
  "status": "revoked"
}

Compute Lag Features (Time-Series Only)

POST /api/v1/deployments/{deployment_id}/compute-lags

  • Auth: Platform Scope

  • Body (JSON): 

    {
  "historical_data": [
    {"date": "2026-06-01", "sales": 100},
    {"date": "2026-06-02", "sales": 120},
    {"date": "2026-06-03", "sales": 150},
    {"date": "2026-06-04", "sales": 110},
    {"date": "2026-06-05", "sales": 130},
    {"date": "2026-06-06", "sales": 140},
    {"date": "2026-06-07", "sales": 160}
  ],
  "target_column": "sales",
  "time_column": "date"
}

  • Response: 

    {
  "features": {
    "lag_1": 160.0,
    "lag_2": 140.0,
    "lag_3": 130.0,
    "lag_7": 100.0,
    "rolling_mean_3": 143.33,
    "rolling_std_3": 15.27,
    "day": 8,
    "month": 6,
    "dayofweek": 0,
    "weekofyear": 24
  },
  "triton_payload": {
    "inputs": [
      {
        "name": "input__0",
        "shape": [1, 10],
        "datatype": "BYTES",
        "data": [["160.0", "140.0", "130.0", "100.0", "143.33", "15.27", "8", "6", "0", "24"]]
      }
    ]
  }
}

Call Online Inference

POST /api/v1/infer/{deployment_name}

  • Auth: Deployment Scope (x-api-key: IML_live_deploy_...)

  • Body (JSON): 

    {
  "inputs": [
    {
      "name": "input__0",
      "shape": [1, 4],
      "datatype": "FP32",
      "data": [720.0, 34.0, 15000.0, 5500.0]
    }
  ]
}

  • Response: 

    {
  "model_name": "random_forest_v1",
  "model_version": "1",
  "outputs": [
    {
      "name": "output__0",
      "datatype": "FP32",
      "shape": [1, 1],
      "data": [0.034]
    }
  ]
}