> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plexe.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Models API

> API reference for building, managing, and using machine learning models on the Plexe Platform.

The Models API provides endpoints for creating, managing, and using machine learning models on the Plexe Platform.

## Models Endpoints

### List Models

```http theme={null}
GET /models
```

#### Headers

| Header          | Value          | Description                     |
| --------------- | -------------- | ------------------------------- |
| `Authorization` | `Bearer TOKEN` | Required. Your API access token |

Retrieves a list of all models in your account.

#### Query Parameters

| Parameter  | Type    | Required | Description                                                    |
| ---------- | ------- | -------- | -------------------------------------------------------------- |
| `limit`    | integer | No       | Maximum number of models to return (default: 20, max: 100)     |
| `offset`   | integer | No       | Number of models to skip (default: 0)                          |
| `status`   | string  | No       | Filter by status: `DRAFT`, `BUILDING`, `READY`, `ERROR`        |
| `sort_by`  | string  | No       | Field to sort by: `created_at`, `name` (default: `created_at`) |
| `sort_dir` | string  | No       | Sort direction: `asc` or `desc` (default: `desc`)              |

#### Response

```json theme={null}
{
  "models": [
    {
      "model_name": "customer-churn-predictor",
      "model_version": "v1.0",
      "name": "Customer Churn Predictor",
      "intent": "Predict customer churn based on usage patterns",
      "status": "READY",
      "deployment_status": "DEPLOYED",
      "created_at": "2023-06-15T08:15:45Z",
      "updated_at": "2023-06-15T10:30:12Z"
    },
    {
      "model_name": "product-recommendation-engine",
      "model_version": "v2.1",
      "name": "Product Recommendation Engine",
      "intent": "Recommend products based on purchase history",
      "status": "BUILDING",
      "deployment_status": null,
      "created_at": "2023-06-16T14:22:33Z",
      "updated_at": "2023-06-16T14:22:33Z"
    }
  ],
  "pagination": {
    "total": 15,
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}
```

### Get Model

```http theme={null}
GET /models/{model_name}
```

#### Headers

| Header          | Value          | Description                     |
| --------------- | -------------- | ------------------------------- |
| `Authorization` | `Bearer TOKEN` | Required. Your API access token |

Retrieves detailed information about a specific model.

#### Path Parameters

| Parameter    | Type   | Required | Description              |
| ------------ | ------ | -------- | ------------------------ |
| `model_name` | string | Yes      | Name of the model to get |

#### Response

```json theme={null}
{
  "model_name": "customer-churn-predictor",
  "model_version": "v1.0",
  "name": "Customer Churn Predictor",
  "intent": "Predict customer churn based on usage patterns",
  "description": "Model predicts likelihood of customer churn in the next 30 days",
  "status": "READY",
  "deployment_status": "DEPLOYED",
  "endpoint": "https://api.plexe.ai/models/customer-churn-predictor/v1.0/infer",
  "metrics": {
    "accuracy": 0.92,
    "precision": 0.88,
    "recall": 0.85,
    "f1_score": 0.86
  },
  "dataset_id": "ds_stu901vwx234",
  "input_schema": {
    "usage_minutes": "float",
    "subscription_months": "integer",
    "support_tickets": "integer",
    "plan_type": "string"
  },
  "output_schema": {
    "churn_probability": "float"
  },
  "created_at": "2023-06-15T08:15:45Z",
  "updated_at": "2023-06-15T10:30:12Z",
  "created_by": "user_yza567bcd890",
  "tags": ["production", "customer-retention"]
}
```

### Create Model

```http theme={null}
POST /models/{model_name}
```

#### Headers

| Header          | Value              | Description                     |
| --------------- | ------------------ | ------------------------------- |
| `Authorization` | `Bearer TOKEN`     | Required. Your API access token |
| `Content-Type`  | `application/json` | Required                        |

Initiates the process of building a new model. This is an asynchronous operation that returns a job ID for tracking progress.

#### Path Parameters

| Parameter    | Type   | Required | Description            |
| ------------ | ------ | -------- | ---------------------- |
| `model_name` | string | Yes      | Name for the new model |

#### Request Body

```json theme={null}
{
  "intent": "Predict customer churn based on usage patterns",
  "name": "Customer Churn Predictor",
  "description": "Model predicts likelihood of customer churn in the next 30 days",
  "dataset_id": "ds_stu901vwx234",
  "input_schema": {
    "usage_minutes": "float",
    "subscription_months": "integer",
    "support_tickets": "integer",
    "plan_type": "string"
  },
  "output_schema": {
    "churn_probability": "float"
  },
  "tags": ["production", "customer-retention"]
}
```

| Field           | Type   | Required | Description                                        |
| --------------- | ------ | -------- | -------------------------------------------------- |
| `intent`        | string | Yes      | Natural language description of the model purpose  |
| `name`          | string | No       | Display name for the model (default: generated)    |
| `description`   | string | No       | Detailed description of the model                  |
| `dataset_id`    | string | Yes      | ID of the dataset to use for training              |
| `input_schema`  | object | No       | Schema of input fields (inferred if not provided)  |
| `output_schema` | object | No       | Schema of output fields (inferred if not provided) |
| `tags`          | array  | No       | List of tags for organizing models                 |

#### Response

```json theme={null}
{
  "job_id": "job_def456ghi789",
  "status": "PENDING",
  "model_name": "customer-churn-predictor",
  "model_version": "v1.0",
  "created_at": "2023-06-16T15:00:00Z"
}
```

### Deploy Model

```http theme={null}
POST /models/{model_name}/deploy
```

#### Headers

| Header          | Value              | Description                     |
| --------------- | ------------------ | ------------------------------- |
| `Authorization` | `Bearer TOKEN`     | Required. Your API access token |
| `Content-Type`  | `application/json` | Required                        |

Deploys a model, making it available for predictions. This is an asynchronous operation.

#### Path Parameters

| Parameter    | Type   | Required | Description                 |
| ------------ | ------ | -------- | --------------------------- |
| `model_name` | string | Yes      | Name of the model to deploy |

#### Request Body

```json theme={null}
{
  "environment": "production",
  "replicas": 2,
  "auto_scale": true
}
```

| Field         | Type    | Required | Description                                      |
| ------------- | ------- | -------- | ------------------------------------------------ |
| `environment` | string  | No       | Deployment environment (default: `production`)   |
| `replicas`    | integer | No       | Number of replicas to deploy (default: 1)        |
| `auto_scale`  | boolean | No       | Whether to enable auto-scaling (default: `true`) |

#### Response

```json theme={null}
{
  "deployment_id": "dep_pqr678stu901",
  "model_name": "customer-churn-predictor",
  "model_version": "v1.0",
  "status": "DEPLOYING",
  "endpoint": "https://api.plexe.ai/predict/dep_pqr678stu901",
  "environment": "production",
  "replicas": 2,
  "auto_scale": true,
  "created_at": "2023-06-16T15:10:00Z"
}
```

### Make Prediction

```http theme={null}
POST /models/{model_name}/{model_version}/infer
```

#### Headers

| Header         | Value              | Description                   |
| -------------- | ------------------ | ----------------------------- |
| `x-api-key`    | `YOUR_API_KEY`     | Required. Your API access key |
| `Content-Type` | `application/json` | Required                      |

Makes a prediction using a deployed model.

#### Path Parameters

| Parameter       | Type   | Required | Description                 |
| --------------- | ------ | -------- | --------------------------- |
| `model_name`    | string | Yes      | Name of the model to use    |
| `model_version` | string | Yes      | Version of the model to use |

#### Request Body

Input data matching the model's input schema. Example:

```json theme={null}
{
  "usage_minutes": 120.5,
  "subscription_months": 8,
  "support_tickets": 2,
  "plan_type": "premium"
}
```

#### Response

Output data matching the model's output schema. Example:

```json theme={null}
{
  "request_id": "req_vwx234yza567",
  "result": {
    "churn_probability": 0.27
  },
  "model_name": "customer-churn-predictor",
  "model_version": "v1.0",
  "created_at": "2023-06-16T15:15:00Z"
}
```

### Get Model Status

```http theme={null}
GET /models/{model_name}/{model_version}/status
```

#### Headers

| Header          | Value          | Description                     |
| --------------- | -------------- | ------------------------------- |
| `Authorization` | `Bearer TOKEN` | Required. Your API access token |

Gets the current status of a specific model version.

#### Path Parameters

| Parameter       | Type   | Required | Description          |
| --------------- | ------ | -------- | -------------------- |
| `model_name`    | string | Yes      | Name of the model    |
| `model_version` | string | Yes      | Version of the model |

#### Response

```json theme={null}
{
  "model_name": "customer-churn-predictor",
  "model_version": "v1.0",
  "status": "READY",
  "deployment_status": "DEPLOYED",
  "last_updated": "2023-06-16T15:15:00Z",
  "build_progress": 100
}
```

### Update Model

```http theme={null}
PATCH /models/{model_name}
```

#### Headers

| Header          | Value              | Description                     |
| --------------- | ------------------ | ------------------------------- |
| `Authorization` | `Bearer TOKEN`     | Required. Your API access token |
| `Content-Type`  | `application/json` | Required                        |

Updates metadata for an existing model.

#### Path Parameters

| Parameter    | Type   | Required | Description                 |
| ------------ | ------ | -------- | --------------------------- |
| `model_name` | string | Yes      | Name of the model to update |

#### Request Body

```json theme={null}
{
  "name": "Enhanced Customer Churn Predictor",
  "description": "Updated model with improved accuracy",
  "tags": ["production", "customer-retention", "v2"]
}
```

| Field         | Type   | Required | Description                    |
| ------------- | ------ | -------- | ------------------------------ |
| `name`        | string | No       | New display name for the model |
| `description` | string | No       | New description of the model   |
| `tags`        | array  | No       | Updated list of tags           |

#### Response

```json theme={null}
{
  "model_name": "customer-churn-predictor",
  "model_version": "v1.0",
  "name": "Enhanced Customer Churn Predictor",
  "description": "Updated model with improved accuracy",
  "tags": ["production", "customer-retention", "v2"],
  "updated_at": "2023-06-16T16:00:00Z"
}
```

### Delete Model

```http theme={null}
DELETE /models/{model_name}
```

#### Headers

| Header          | Value          | Description                     |
| --------------- | -------------- | ------------------------------- |
| `Authorization` | `Bearer TOKEN` | Required. Your API access token |

Deletes a model and its deployments.

#### Path Parameters

| Parameter    | Type   | Required | Description                 |
| ------------ | ------ | -------- | --------------------------- |
| `model_name` | string | Yes      | Name of the model to delete |

#### Response

```json theme={null}
{
  "model_name": "customer-churn-predictor",
  "model_version": "v1.0",
  "status": "DELETED",
  "deleted_at": "2023-06-16T17:00:00Z"
}
```

### Retrain Model

```http theme={null}
POST /models/{model_name}/retrain
```

#### Headers

| Header         | Value              | Description                   |
| -------------- | ------------------ | ----------------------------- |
| `x-api-key`    | `YOUR_API_KEY`     | Required. Your API access key |
| `Content-Type` | `application/json` | Required                      |

Initiates retraining of an existing model with new data or updated configuration.

#### Path Parameters

| Parameter    | Type   | Required | Description                  |
| ------------ | ------ | -------- | ---------------------------- |
| `model_name` | string | Yes      | Name of the model to retrain |

#### Request Body

```json theme={null}
{
  "upload_id": "upload_def789ghi012",
  "goal": "Updated goal with new requirements",
  "metric": "accuracy",
  "max_iterations": 3
}
```

| Field            | Type    | Required | Description                          |
| ---------------- | ------- | -------- | ------------------------------------ |
| `upload_id`      | string  | No       | ID of new dataset for retraining     |
| `goal`           | string  | No       | Updated natural language description |
| `metric`         | string  | No       | Primary metric to optimize           |
| `max_iterations` | integer | No       | Maximum training iterations          |

#### Response

```json theme={null}
{
  "job_id": "job_rst456uvw789",
  "status": "PENDING",
  "model_name": "customer-churn-predictor",
  "new_version": "v2.0",
  "created_at": "2023-06-20T10:00:00Z"
}
```

### Get Build Logs

```http theme={null}
GET /models/build-logs
```

#### Headers

| Header      | Value          | Description                   |
| ----------- | -------------- | ----------------------------- |
| `x-api-key` | `YOUR_API_KEY` | Required. Your API access key |

Retrieves build logs for model training processes.

#### Query Parameters

| Parameter | Type    | Required | Description                                            |
| --------- | ------- | -------- | ------------------------------------------------------ |
| `limit`   | integer | No       | Maximum number of log entries to return (default: 100) |
| `offset`  | integer | No       | Number of log entries to skip (default: 0)             |
| `job_id`  | string  | No       | Filter logs by specific build job ID                   |

#### Response

```json theme={null}
{
  "logs": [
    {
      "job_id": "job_def456ghi789",
      "model_name": "customer-churn-predictor",
      "timestamp": "2023-06-16T15:05:00Z",
      "level": "INFO",
      "message": "Starting model training with dataset ds_stu901vwx234"
    },
    {
      "job_id": "job_def456ghi789",
      "model_name": "customer-churn-predictor",
      "timestamp": "2023-06-16T15:08:30Z",
      "level": "INFO",
      "message": "Training completed. Model accuracy: 92.5%"
    }
  ],
  "pagination": {
    "total": 45,
    "limit": 100,
    "offset": 0,
    "has_more": false
  }
}
```

## Model Versions

### List Model Versions

```http theme={null}
GET /models/{model_name}/versions
```

#### Headers

| Header          | Value          | Description                     |
| --------------- | -------------- | ------------------------------- |
| `Authorization` | `Bearer TOKEN` | Required. Your API access token |

Lists all versions of a specific model.

#### Path Parameters

| Parameter    | Type   | Required | Description                            |
| ------------ | ------ | -------- | -------------------------------------- |
| `model_name` | string | Yes      | Name of the model to list versions for |

#### Response

```json theme={null}
{
  "model_name": "customer-churn-predictor",
  "model_version": "v1.0",
  "versions": [
    {
      "version_id": "ver_bcd890efg123",
      "version": 3,
      "status": "READY",
      "metrics": {
        "accuracy": 0.94,
        "precision": 0.92,
        "recall": 0.90,
        "f1_score": 0.91
      },
      "created_at": "2023-06-20T09:00:00Z"
    },
    {
      "version_id": "ver_hij456klm789",
      "version": 2,
      "status": "READY",
      "metrics": {
        "accuracy": 0.92,
        "precision": 0.88,
        "recall": 0.85,
        "f1_score": 0.86
      },
      "created_at": "2023-06-17T14:00:00Z"
    },
    {
      "version_id": "ver_nop012qrs345",
      "version": 1,
      "status": "READY",
      "metrics": {
        "accuracy": 0.89,
        "precision": 0.85,
        "recall": 0.82,
        "f1_score": 0.83
      },
      "created_at": "2023-06-16T15:00:00Z"
    }
  ]
}
```

### Create Model Version

```http theme={null}
POST /models/{model_name}/versions
```

#### Headers

| Header          | Value              | Description                     |
| --------------- | ------------------ | ------------------------------- |
| `Authorization` | `Bearer TOKEN`     | Required. Your API access token |
| `Content-Type`  | `application/json` | Required                        |

Creates a new version of an existing model. This is useful for iterative model improvement.

#### Path Parameters

| Parameter    | Type   | Required | Description                             |
| ------------ | ------ | -------- | --------------------------------------- |
| `model_name` | string | Yes      | Name of the model to create version for |

#### Request Body

```json theme={null}
{
  "dataset_id": "ds_tuv678wxy901",
  "intent": "Predict customer churn with added seasonality factor",
  "input_schema": {
    "usage_minutes": "float",
    "subscription_months": "integer",
    "support_tickets": "integer",
    "plan_type": "string",
    "season": "string"
  }
}
```

| Field           | Type   | Required | Description                                      |
| --------------- | ------ | -------- | ------------------------------------------------ |
| `dataset_id`    | string | Yes      | ID of the dataset to use for training            |
| `intent`        | string | No       | Updated intent (defaults to original if omitted) |
| `input_schema`  | object | No       | Updated input schema (defaults to original)      |
| `output_schema` | object | No       | Updated output schema (defaults to original)     |

#### Response

```json theme={null}
{
  "job_id": "job_zab234cde567",
  "status": "PENDING",
  "model_name": "customer-churn-predictor",
  "model_version": "v1.0",
  "version_id": "ver_fgh890ijk123",
  "version": 4,
  "created_at": "2023-06-21T10:00:00Z"
}
```

## Model Deployments

### List Deployments

```http theme={null}
GET /models/{model_name}/deployments
```

#### Headers

| Header          | Value          | Description                     |
| --------------- | -------------- | ------------------------------- |
| `Authorization` | `Bearer TOKEN` | Required. Your API access token |

Lists all active deployments for a model.

#### Path Parameters

| Parameter    | Type   | Required | Description                               |
| ------------ | ------ | -------- | ----------------------------------------- |
| `model_name` | string | Yes      | Name of the model to list deployments for |

#### Response

```json theme={null}
{
  "model_name": "customer-churn-predictor",
  "model_version": "v1.0",
  "deployments": [
    {
      "deployment_id": "dep_lmn456opq789",
      "environment": "production",
      "status": "ACTIVE",
      "version_id": "ver_bcd890efg123",
      "version": 3,
      "endpoint": "https://api.plexe.ai/predict/dep_lmn456opq789",
      "replicas": 2,
      "auto_scale": true,
      "created_at": "2023-06-20T10:00:00Z"
    },
    {
      "deployment_id": "dep_rst012uvw345",
      "environment": "staging",
      "status": "ACTIVE",
      "version_id": "ver_hij456klm789",
      "version": 2,
      "endpoint": "https://api.plexe.ai/predict/dep_rst012uvw345",
      "replicas": 1,
      "auto_scale": false,
      "created_at": "2023-06-19T16:00:00Z"
    }
  ]
}
```

### Undeploy Model

```http theme={null}
DELETE /models/{model_name}/deployments/{deployment_id}
```

#### Headers

| Header          | Value          | Description                     |
| --------------- | -------------- | ------------------------------- |
| `Authorization` | `Bearer TOKEN` | Required. Your API access token |

Removes a specific deployment of a model.

#### Path Parameters

| Parameter       | Type   | Required | Description                    |
| --------------- | ------ | -------- | ------------------------------ |
| `model_id`      | string | Yes      | ID of the model                |
| `deployment_id` | string | Yes      | ID of the deployment to remove |

#### Response

```json theme={null}
{
  "model_name": "customer-churn-predictor",
  "model_version": "v1.0",
  "deployment_id": "dep_rst012uvw345",
  "status": "UNDEPLOYING",
  "undeployed_at": "2023-06-21T11:00:00Z"
}
```

### Describe Model

```http theme={null}
GET /models/{model_name}/{model_version}/describe
```

#### Headers

| Header      | Value          | Description                   |
| ----------- | -------------- | ----------------------------- |
| `x-api-key` | `YOUR_API_KEY` | Required. Your API access key |

Gets detailed information and metadata about a specific model version.

#### Path Parameters

| Parameter       | Type   | Required | Description          |
| --------------- | ------ | -------- | -------------------- |
| `model_name`    | string | Yes      | Name of the model    |
| `model_version` | string | Yes      | Version of the model |

#### Response

```json theme={null}
{
  "model_name": "customer-churn-predictor",
  "model_version": "v1.0",
  "description": "Detailed model description and capabilities",
  "input_schema": {
    "usage_minutes": "float",
    "subscription_months": "integer",
    "support_tickets": "integer",
    "plan_type": "string"
  },
  "output_schema": {
    "churn_probability": "float"
  },
  "performance_metrics": {
    "accuracy": 0.92,
    "precision": 0.88,
    "recall": 0.85,
    "f1_score": 0.86
  },
  "training_info": {
    "dataset_size": 10000,
    "training_time_minutes": 15,
    "algorithm": "ensemble",
    "feature_importance": {
      "usage_minutes": 0.45,
      "support_tickets": 0.30,
      "subscription_months": 0.15,
      "plan_type": 0.10
    }
  }
}
```

## Batch Predictions

### Batch Predictions

```http theme={null}
POST /models/{model_name}/{model_version}/predictions
```

#### Headers

| Header         | Value              | Description                   |
| -------------- | ------------------ | ----------------------------- |
| `x-api-key`    | `YOUR_API_KEY`     | Required. Your API access key |
| `Content-Type` | `application/json` | Required                      |

Makes batch predictions using a deployed model by sending an array of input data.

#### Path Parameters

| Parameter       | Type   | Required | Description                 |
| --------------- | ------ | -------- | --------------------------- |
| `model_name`    | string | Yes      | Name of the model to use    |
| `model_version` | string | Yes      | Version of the model to use |

#### Request Body

Array of input objects matching the model's input schema. Example:

```json theme={null}
[
  {
    "credit_score": 42,
    "employment_type": "sample string",
    "infrastructure_score": 42,
    "years_employed": 3.14,
    "payment_to_income_ratio": 3.14,
    "population_growth_trend": "sample string",
    "loan_year": 42,
    "permit_fees_aed": 42,
    "market_conditions": "sample string",
    "land_area_sqm": 42,
    "interest_rate_percent": 3.14,
    "land_value_aed": 42,
    "debt_to_income_ratio": 3.14,
    "monthly_income_aed": 42,
    "construction_delay_months": 3.14,
    "loan_to_value_ratio": 3.14,
    "market_activity_level": "sample string",
    "borrower_age": 42,
    "loan_term_years": 42,
    "building_area_sqm": 42,
    "monthly_payment_aed": 42,
    "cost_overrun_percentage": 3.14,
    "distance_to_center_km": 3.14,
    "district": "sample string",
    "building_type": "sample string",
    "estimated_monthly_rental_aed": 42
  },
  {
    "credit_score": 45,
    "employment_type": "full-time",
    "infrastructure_score": 38,
    "years_employed": 2.5,
    "payment_to_income_ratio": 2.8
    // ... additional fields for second prediction
  }
]
```

#### Response

Array of prediction results corresponding to each input:

```json theme={null}
[
  {
    "prediction": {
      "loan_approval_probability": 0.85,
      "risk_score": 0.15
    }
  },
  {
    "prediction": {
      "loan_approval_probability": 0.72,
      "risk_score": 0.28
    }
  }
]
```

## Error Codes

| HTTP Status | Error Code            | Description                              |
| ----------- | --------------------- | ---------------------------------------- |
| 400         | `invalid_request`     | Malformed request or missing parameters  |
| 401         | `unauthorized`        | Missing or invalid API key               |
| 403         | `forbidden`           | Insufficient permissions for operation   |
| 404         | `not_found`           | Model, deployment, or resource not found |
| 409         | `conflict`            | Resource conflict (e.g., duplicate name) |
| 422         | `validation_error`    | Invalid input data or schema             |
| 429         | `rate_limit_exceeded` | API rate limit exceeded                  |
| 500         | `internal_error`      | Server-side error                        |
| 503         | `service_unavailable` | Service temporarily unavailable          |

For all API errors, the response will include details about the error and, where appropriate, suggestions for resolution.