PowerMind FeatureHub User Guide - API Reference

FeatureHub exposes a REST API prefix at /api/v1 for managing workspaces, configuring features, and serving predictions.

Authentication and Scoping

FeatureHub supports two authentication modes:

1. User Authentication (JWT Bearer Token)

Used for user-facing applications and interactive sessions: - Endpoints: Register via POST /api/v1/auth/register or login via POST /api/v1/auth/login. - Header: Include the returned JWT in the Authorization header:

Authorization: Bearer <jwt_access_token>

- Workspace Scoping: Workspace-scoped endpoints require you to explicitly pass the workspace ID:

X-Workspace-Id: <workspace_id>

2. Service Integration (API Key)

Used for automated pipelines, external servers, and model serving instances: - Header: Pass the integration key directly:

X-Integration-Api-Key: <plaintext_integration_key>

- Workspace Scoping: The integration key is linked to a single workspace. FeatureHub resolves the workspace ID automatically. You do not need to send the X-Workspace-Id header (though you may include it as a safety guard; FeatureHub will reject the request if the key and header workspace IDs do not match).

1. Authentication Endpoints

Register User

Endpoint: POST /api/v1/auth/register

Request Body:

{
  "email": "user@example.com",
  "username": "ml_engineer",
  "password": "securepassword123",
  "full_name": "ML Engineer"
}

Response: Returns user info, a default workspace, and a JWT access token.

Endpoint: POST /api/v1/auth/login

Request Body:

{
  "identifier": "ml_engineer",
  "password": "securepassword123"
}

Response: Returns user info, active workspaces list, and a JWT access token.

2. Workspace & Integration Keys

Create Workspace

Endpoint: POST /api/v1/workspaces/
Headers: JWT auth required.

Request Body:

{
  "name": "Production ML",
  "description": "Production workspaces for fraud detection models"
}

Generate Integration Key

Endpoint: POST /api/v1/integration-keys/
Headers: JWT auth + X-Workspace-Id required.

Request Body:

{
  "name": "Pipeline Inference Key",
  "expires_in_days": 90
}

Response: Returns metadata along with the plaintext api_key (displayed only once).

3. Datasources

Upload CSV Datasource

Endpoint: POST /api/v1/datasources/csv
Headers: Auth + X-Workspace-Id required.
Request Format: Multipart form data.
name: string identifier
file: CSV file data
Response: Returns the registered datasource metadata and UUID string ID.

Register Remote Database Datasource

Endpoint: POST /api/v1/datasources/
Headers: Auth + X-Workspace-Id required.

Request Body:

{
  "name": "customer_database",
  "type": "postgres",
  "connection_config": {
    "uri": "postgresql://reader:password@db.example.com:5432/analytics",
    "table": "public.customer_features"
  }
}

(Supported database types in configuration include postgres, mysql, and s3)

Preview Datasource

Endpoint: POST /api/v1/datasources/{datasource_id}/preview
Headers: Auth + X-Workspace-Id required.
Response: Returns column names and the first 10 sample rows. Run this before designing feature views to check spelling.

4. Feature Views

Create Feature View

Endpoint: POST /api/v1/feature-views/
Headers: Auth + X-Workspace-Id required.

Request Body:

{
  "datasource_id": "8cf9a764-77a8-4226-bf75-b6d4db1a719f",
  "name": "customer_activity",
  "join_key": "customer_id",
  "event_timestamp_column": "created_at",
  "description": "Stored and derived customer features",
  "fields": [
    {
      "name": "lifetime_spend",
      "dtype": "float64",
      "feature_type": "stored",
      "source_column": "total_spend"
    },
    {
      "name": "order_count",
      "dtype": "int64",
      "feature_type": "stored",
      "source_column": "order_count"
    },
    {
      "name": "avg_order_value",
      "dtype": "float64",
      "feature_type": "stored",
      "expression": "total_spend / nullif(order_count, 0)"
    }
  ]
}

Materialize Feature View

Endpoint: POST /api/v1/feature-views/{feature_view_id}/materialize
Headers: Auth + X-Workspace-Id required.
Response: Initiates background transfer of pre-computed feature values from offline storage into the low-latency online database. Returns status metadata.

Activate Feature View Version

Endpoint: POST /api/v1/feature-views/{feature_view_id}/activate
Headers: Auth + X-Workspace-Id required.
Response: Sets this specific version as the active routing target for that feature view.

4b. Drift Monitoring & Baseline Management

FeatureHub tracks the statistical distribution of every feature on each materialization cycle and compares it against a reference baseline using PSI (Population Stability Index). The following endpoints let you read drift logs, customise alert thresholds, and intentionally reset the baseline after model retraining.

How the Baseline Lifecycle Works

Created automatically on first materialization. That snapshot is your permanent baseline.
Stable until you reset it. Every subsequent materialization compares live data against that original baseline, not the previous run.
Reset intentionally after model retraining or major data changes. The current live data becomes the new baseline from that point forward.

Get Drift Logs

Retrieves the history of drift events for a feature view, including schema changes, distribution warnings, and critical alerts.

Endpoint: GET /api/v1/feature-views/{feature_view_id}/drift-logs
Headers: Auth + X-Workspace-Id required.

Response:

{
  "items": [
    {
      "id": "a1b2c3d4-...",
      "feature_view_id": "8e888689-...",
      "feature_name": "income",
      "log_type": "data_drift_detected",
      "details": "PSI=0.34 (Critical drift). Baseline bins: [...]",
      "created_at": "2026-07-02T11:00:00Z"
    }
  ]
}

log_type values:

data_drift_warning — PSI ≥ warning threshold (default 0.10)
data_drift_detected — PSI ≥ critical threshold (default 0.20)
data_drift_low_confidence — < 50 rows; result based on mean shift instead of PSI
schema_drift — a feature column was added or removed

Reset Reference Baseline

Recalculates the full statistical profile from the current live data and replaces the stored baseline. Use this after retraining your model on new data, or after intentional ETL changes.

Endpoint: POST /api/v1/feature-views/{feature_view_id}/reset-baseline
Headers: Auth + X-Workspace-Id required.
Request Body: None.

Response:

{
  "message": "Baseline reset successfully."
}

Warning: This is destructive. The previous baseline is permanently overwritten. Only call this when you intentionally want to accept the current data as the new reference — e.g. after deploying a retrained model.

Update Drift Thresholds

Overrides the PSI alert thresholds for a specific feature view. Thresholds take effect on the next materialization cycle.

Endpoint: PUT /api/v1/feature-views/{feature_view_id}/drift-thresholds
Headers: Auth + X-Workspace-Id required.
Request Body:
```
{
  "warning_threshold_psi": 0.10,
  "drift_threshold_psi": 0.20
}
```
| Field | Default | Description | |---|---|---| | warning_threshold_psi | 0.10 | PSI at or above this value raises a Drift Warning. | | drift_threshold_psi | 0.20 | PSI at or above this value raises a Drift Critical alert. |

Response:

{
  "message": "Drift thresholds updated."
}

Tip: Financial and fraud models typically use tighter thresholds (e.g. 0.05 / 0.10). Lower-stakes recommendation models can use relaxed thresholds (e.g. 0.15 / 0.30).

5. Feature Services

Create Feature Service

Endpoint: POST /api/v1/feature-services/
Headers: Auth + X-Workspace-Id required.

Request Body:

{
  "name": "customer_scoring",
  "description": "Features for fraud model v1",
  "feature_refs": [
    "customer_activity:lifetime_spend",
    "customer_activity:avg_order_value"
  ]
}

(Feature references follow the format feature_view_base_name:feature_field_name)

6. Online Serving

Service-Based Serving (Recommended)

Retrieves pre-computed stored features and evaluates serving-time derived/scaled features using a registered, named serving contract.

Endpoint: POST /api/v1/features/online
Headers: Integration API Key (or User Auth + X-Workspace-Id) required.

Request Body:

{
  "feature_service_name": "customer_scoring",
  "entity_rows": [
    { "customer_id": "C001" },
    { "customer_id": "C002" }
  ],
  "request_features": {
    "current_cart_value": [120.50, 45.00]
  }
}

(Note: Request feature arrays must align with the position and length of the entity_rows array)

Response Payload:

{
  "metadata": {
    "workspace": "demo-s-workspace",
    "feature_refs": [
      "demo-s-workspace__customer_activity__v1:lifetime_spend",
      "demo-s-workspace__customer_activity__v1:avg_order_value"
    ],
    "request_features": [
      "current_cart_value"
    ],
    "feature_service_name": "customer_scoring"
  },
  "results": {
    "customer_id": ["C001", "C002"],
    "lifetime_spend": [1450.75, 280.00],
    "avg_order_value": [45.33, 70.00],
    "current_cart_value": [120.50, 45.00]
  }
}

Raw-Ref Serving (Debugging / Ad-hoc)

Bypasses the feature service contract. Useful for exploration.

Endpoint: POST /api/v1/features/online

Request Body:

{
  "feature_refs": [
    "customer_activity:lifetime_spend"
  ],
  "entity_rows": [
    { "customer_id": "C001" }
  ]
}

Response Payload:

{
  "metadata": {
    "workspace": "demo-s-workspace",
    "feature_refs": [
      "demo-s-workspace__customer_activity__v1:lifetime_spend"
    ],
    "request_features": [],
    "feature_service_name": null
  },
  "results": {
    "customer_id": ["C001"],
    "lifetime_spend": [1450.75]
  }
}

7. Authentication Logout

Logout Session

Endpoint: POST /api/v1/auth/logout
Headers: JWT auth required.
Response:
```
{
  "message": "Logged out successfully"
}
```
(Note: This logs out the current user session and records a logout audit log event on the server)

8. Streaming Ingestion

Ingest Real-Time Event Data

Ingests real-time streaming records directly into the offline staging and online low-latency stores.

Endpoint: POST /api/v1/ingest/stream
Headers: Auth + X-Workspace-Id required (requires workspace admin permissions).
Query Parameters:
sync (boolean, default: true): If true, processes ingestion synchronously. If false, queues records in a high-throughput background queue.

Request Body:

{
  "datasource_id": "8cf9a764-77a8-4226-bf75-b6d4db1a719f",
  "records": [
    {
      "customer_id": "C001",
      "created_at": "2026-07-02T09:30:00Z",
      "total_spend": 510.25,
      "order_count": 13
    }
  ]
}

Response (Synchronous): Returns the ingested data details.
Response (Asynchronous/Queued):
```
{
  "status": "queued",
  "count": 1
}
```

9. Schema Guidance

These endpoints guide developers and users on required fields, datasets characteristics, scaling configurations, and feature creation checklists.

Get Feature View Requirements

Endpoint: GET /api/v1/schema-guide/feature-view-requirements
Response: Returns a structured checklist of required, optional, and conditional fields for feature view creation, explaining when each field is needed.

Get Datasource Strategies

Endpoint: GET /api/v1/schema-guide/datasource-strategies
Response: Lists outcomes and limitations for four data scenarios:
Data has both ID and timestamp
Data has ID, no timestamp
Data has timestamp, no natural ID
Data has neither ID nor timestamp

Get Feature Types Guide

Endpoint: GET /api/v1/schema-guide/feature-types-guide
Response: Explains the unified feature model and serving-time overrides, showing latency and update frequencies.

Get Scaling Guide

Endpoint: GET /api/v1/schema-guide/scaling-guide
Response: Documents the scale() function configurations (auto, standardize, min_max) and provides syntax examples.

Get Workflow Checklist

Endpoint: GET /api/v1/schema-guide/workflow-checklist
Response: Provides a checklist spanning 5 phases (preparation, datasource setup, feature design, creation, and materialization).

10. Platform Observability & Metrics

Prometheus Metrics

Exposes CPU, memory, network, storage, and application statistics (e.g. workspace, datasource, feature count) formatted for Prometheus scrapers.

Endpoints:
GET /metrics
GET /api/v1/metrics
Headers: No auth required.
Response: Plain text database and host resource counters.

Audit Logs (Admin Only)

Endpoint: GET /api/v1/admin/audit-logs
Headers: Admin JWT auth required.
Response: Page of audit records showing administrative and system actions (e.g. data_drift_detected, logouts).

PowerMind FeatureHub User Guide - API Reference

Authentication and Scoping

1. User Authentication (JWT Bearer Token)

2. Service Integration (API Key)

1. Authentication Endpoints

Register User

Login

2. Workspace & Integration Keys

Create Workspace

Generate Integration Key

3. Datasources

Upload CSV Datasource

Register Remote Database Datasource

Preview Datasource

4. Feature Views

Create Feature View

Materialize Feature View

Activate Feature View Version

4b. Drift Monitoring & Baseline Management

How the Baseline Lifecycle Works

Get Drift Logs

Reset Reference Baseline

Update Drift Thresholds

5. Feature Services

Create Feature Service

6. Online Serving

Service-Based Serving (Recommended)

Raw-Ref Serving (Debugging / Ad-hoc)

7. Authentication Logout

Logout Session

8. Streaming Ingestion

Ingest Real-Time Event Data

9. Schema Guidance

Get Feature View Requirements

Get Datasource Strategies

Get Feature Types Guide

Get Scaling Guide

Get Workflow Checklist

10. Platform Observability & Metrics

Prometheus Metrics

Audit Logs (Admin Only)