REST API Reference Guide

This document describes the REST API endpoints exposed by the PowerMind ComputeAI Controller. This API can be integrated into custom dashboard applications, automated CI/CD runners, or scripts.

1. API Base & Interactive Documentation

• API Base Path: https://<computeai-controller-host>/api
• OpenAPI JSON Spec: https://<computeai-controller-host>/api/swagger.json
• Interactive Swagger UI: https://<computeai-controller-host>/api/docs

2. Authentication Models

The client API uses two authentication mechanisms depending on the route category:

2.1 JSON Web Token (JWT)

Most platform management operations (files, jobs, deployments) require a Bearer token in the request header: * Header name: Authorization * Value format: Bearer <JWT_TOKEN>

2.2 Inference Key

Executing live model inference uses a deployment-scoped API access key: * Header name: X-API-Key * Value format: sk_xxxxxxxxxxxxxxxx

3. Route Reference Table

3.1 Authentication & Sessions

3.2 User & Quota Management (Admin Only)

3.3 Dataset & File Workspace

3.4 Job & Training Execution

3.5 Model serving & Deployment

3.6 Monitoring & System Health

4. Key Endpoint Specifications

4.1 Login (POST /api/auth/login)

Request Body:

{
  "username": "alice",
  "password": "StrongPassword123"
}

{
  "token": "eyJhbGciOi...",
  "user": {
    "username": "alice",
    "email": "alice@example.com",
    "role": "user"
  }
}

4.2 Submit Job (POST /api/jobs/submit)

Submits a Python training run. The script code is passed directly as a string in the "code" field (no pre-upload step required).

Request Body:

{
  "name": "digits_mnist",
  "framework": "pytorch",
  "resource_type": "gpu",
  "distributed": false,
  "num_nodes": 1,
  "checkpoint_interval": 5,
  "code": "import torch\nprint('Starting training loop...')"
}

{
  "job_id": "8a2d1f99-c1d0-42cf-961d-85068cc4adcf",
  "model_name": "digits_mnist",
  "framework": "pytorch",
  "status": "submitted"
}

4.3 Upload Model (POST /api/models/upload)

Used to register BYOB (bring-your-own-model) pre-trained weights. Requires multipart/form-data encoding.

Form Fields: * model_file: Binary file upload (e.g. .onnx, .pt, .h5). * model_name: String display name. * version: Integer string (e.g. "1"). * input_shape: JSON array string (e.g. "[[-1, 784]]"). * output_shape: JSON array string (e.g. "[[-1, 10]]"). * input_dtype (optional): JSON array of types, e.g. '["FP32"]'. Default: ["FP32"]. * output_dtype (optional): JSON array of types, e.g. '["FP32"]'. Default: ["FP32"]. * input_names (optional): JSON array of custom input tensor names, e.g. '["input_ids"]'. Default: ["INPUT__0"]. * output_names (optional): JSON array of custom output tensor names. Default: ["OUTPUT__0"].

4.4 Model Inference (POST /api/infer/{deployment_name})

Executes real-time inference against an active model serving deployment.

Authentication

• Header: X-API-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
• Header: Content-Type: application/json

Request Payload Structure

The JSON payload must include an "inputs" object mapping each expected input tensor name to its data matrix:

{
  "inputs": {
    "INPUT__0": [
      [0.12, 0.45, 0.78, ..., 0.05]
    ]
  }
}

Tensor Naming & Multi-Input Models

• Default Names: If the model was uploaded without custom tensor names, inputs are indexed as INPUT__0, INPUT__1, etc.
• Custom Names: If custom input names were specified during model registration (e.g. image_input, text_embeddings), use those exact keys in the inputs object.
• Multi-Input Example:

  {
    "inputs": {
      "numerical_features": [[1.2, 3.4, 5.6]],
      "categorical_ids": [[10, 42, 105]]
    }
  }
  

Supported Data Types & Conversions

The serving engine automatically casts JSON numerical arrays to the configured tensor precision:

Batching & Dimension Rules

• The outer dimension represents the Batch Dimension (e.g., batch_size = 1 for single sample [[...]], batch_size = N for [[...], [...]]).
• If the model defines shape [[-1, 784]], the -1 allows dynamic batch sizes up to the deployment's configured batch_size_limit (default: 256).
• Fixed dimensions (e.g., 784) must match the exact number of elements per row.

Response Payload (200 OK)

{
  "model_name": "digits_mnist",
  "model_version": "1",
  "outputs": [
    {
      "name": "OUTPUT__0",
      "datatype": "FP32",
      "shape": [1, 10],
      "data": [0.001, 0.002, 0.985, 0.003, 0.001, 0.002, 0.001, 0.002, 0.002, 0.001]
    }
  ]
}

5. Standard Status Codes & Error Resolution