Models API - Plexe Documentation

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

Models Endpoints

List Models

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

{
  "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

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

{
  "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

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

{
  "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

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

Deploy Model

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

{
  "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

{
  "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

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:

{
  "usage_minutes": 120.5,
  "subscription_months": 8,
  "support_tickets": 2,
  "plan_type": "premium"
}

Response

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

{
  "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

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

{
  "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

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

{
  "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

{
  "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

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

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

Retrain Model

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

{
  "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

{
  "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

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

{
  "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

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

{
  "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

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

{
  "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

{
  "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

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

{
  "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

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

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

Describe Model

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

{
  "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

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:

[
  {
    "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:

[
  {
    "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.

​Models Endpoints

​List Models

​Headers

​Query Parameters

​Response

​Get Model

​Headers

​Path Parameters

​Response

​Create Model

​Headers

​Path Parameters

​Request Body

​Response

​Deploy Model

​Headers

​Path Parameters

​Request Body

​Response

​Make Prediction

​Headers

​Path Parameters

​Request Body

​Response

​Get Model Status

​Headers

​Path Parameters

​Response

​Update Model

​Headers

​Path Parameters

​Request Body

​Response

​Delete Model

​Headers

​Path Parameters

​Response

​Retrain Model

​Headers

​Path Parameters

​Request Body

​Response

​Get Build Logs

​Headers

​Query Parameters

​Response

​Model Versions

​List Model Versions

​Headers

​Path Parameters

​Response

​Create Model Version

​Headers

​Path Parameters

​Request Body

​Response

​Model Deployments

​List Deployments

​Headers

​Path Parameters

​Response

​Undeploy Model

​Headers

​Path Parameters

​Response

​Describe Model

​Headers

​Path Parameters

​Response

​Batch Predictions

​Batch Predictions

​Headers

​Path Parameters

​Request Body

​Response

​Error Codes

Models Endpoints

List Models

Headers

Query Parameters

Response

Get Model

Headers

Path Parameters

Response

Create Model

Headers

Path Parameters

Request Body

Response

Deploy Model

Headers

Path Parameters

Request Body

Response

Make Prediction

Headers

Path Parameters

Request Body

Response

Get Model Status

Headers

Path Parameters

Response

Update Model

Headers

Path Parameters

Request Body

Response

Delete Model

Headers

Path Parameters

Response

Retrain Model

Headers

Path Parameters

Request Body

Response

Get Build Logs

Headers

Query Parameters

Response

Model Versions

List Model Versions

Headers

Path Parameters

Response

Create Model Version

Headers

Path Parameters

Request Body

Response

Model Deployments

List Deployments

Headers

Path Parameters

Response

Undeploy Model

Headers

Path Parameters

Response

Describe Model

Headers

Path Parameters

Response

Batch Predictions

Batch Predictions

Headers

Path Parameters

Request Body

Response

Error Codes