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

Models Endpoints

List Models

GET /models

Headers

HeaderValueDescription
AuthorizationBearer TOKENRequired. Your API access token
Retrieves a list of all models in your account.

Query Parameters

ParameterTypeRequiredDescription
limitintegerNoMaximum number of models to return (default: 20, max: 100)
offsetintegerNoNumber of models to skip (default: 0)
statusstringNoFilter by status: DRAFT, BUILDING, READY, ERROR
sort_bystringNoField to sort by: created_at, name (default: created_at)
sort_dirstringNoSort 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

HeaderValueDescription
AuthorizationBearer TOKENRequired. Your API access token
Retrieves detailed information about a specific model.

Path Parameters

ParameterTypeRequiredDescription
model_namestringYesName 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

HeaderValueDescription
AuthorizationBearer TOKENRequired. Your API access token
Content-Typeapplication/jsonRequired
Initiates the process of building a new model. This is an asynchronous operation that returns a job ID for tracking progress.

Path Parameters

ParameterTypeRequiredDescription
model_namestringYesName 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"]
}
FieldTypeRequiredDescription
intentstringYesNatural language description of the model purpose
namestringNoDisplay name for the model (default: generated)
descriptionstringNoDetailed description of the model
dataset_idstringYesID of the dataset to use for training
input_schemaobjectNoSchema of input fields (inferred if not provided)
output_schemaobjectNoSchema of output fields (inferred if not provided)
tagsarrayNoList 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

HeaderValueDescription
AuthorizationBearer TOKENRequired. Your API access token
Content-Typeapplication/jsonRequired
Deploys a model, making it available for predictions. This is an asynchronous operation.

Path Parameters

ParameterTypeRequiredDescription
model_namestringYesName of the model to deploy

Request Body

{
  "environment": "production",
  "replicas": 2,
  "auto_scale": true
}
FieldTypeRequiredDescription
environmentstringNoDeployment environment (default: production)
replicasintegerNoNumber of replicas to deploy (default: 1)
auto_scalebooleanNoWhether 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

HeaderValueDescription
x-api-keyYOUR_API_KEYRequired. Your API access key
Content-Typeapplication/jsonRequired
Makes a prediction using a deployed model.

Path Parameters

ParameterTypeRequiredDescription
model_namestringYesName of the model to use
model_versionstringYesVersion 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

HeaderValueDescription
AuthorizationBearer TOKENRequired. Your API access token
Gets the current status of a specific model version.

Path Parameters

ParameterTypeRequiredDescription
model_namestringYesName of the model
model_versionstringYesVersion 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

HeaderValueDescription
AuthorizationBearer TOKENRequired. Your API access token
Content-Typeapplication/jsonRequired
Updates metadata for an existing model.

Path Parameters

ParameterTypeRequiredDescription
model_namestringYesName of the model to update

Request Body

{
  "name": "Enhanced Customer Churn Predictor",
  "description": "Updated model with improved accuracy",
  "tags": ["production", "customer-retention", "v2"]
}
FieldTypeRequiredDescription
namestringNoNew display name for the model
descriptionstringNoNew description of the model
tagsarrayNoUpdated 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

HeaderValueDescription
AuthorizationBearer TOKENRequired. Your API access token
Deletes a model and its deployments.

Path Parameters

ParameterTypeRequiredDescription
model_namestringYesName 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

HeaderValueDescription
x-api-keyYOUR_API_KEYRequired. Your API access key
Content-Typeapplication/jsonRequired
Initiates retraining of an existing model with new data or updated configuration.

Path Parameters

ParameterTypeRequiredDescription
model_namestringYesName of the model to retrain

Request Body

{
  "upload_id": "upload_def789ghi012",
  "goal": "Updated goal with new requirements",
  "metric": "accuracy",
  "max_iterations": 3
}
FieldTypeRequiredDescription
upload_idstringNoID of new dataset for retraining
goalstringNoUpdated natural language description
metricstringNoPrimary metric to optimize
max_iterationsintegerNoMaximum 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

HeaderValueDescription
x-api-keyYOUR_API_KEYRequired. Your API access key
Retrieves build logs for model training processes.

Query Parameters

ParameterTypeRequiredDescription
limitintegerNoMaximum number of log entries to return (default: 100)
offsetintegerNoNumber of log entries to skip (default: 0)
job_idstringNoFilter 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

HeaderValueDescription
AuthorizationBearer TOKENRequired. Your API access token
Lists all versions of a specific model.

Path Parameters

ParameterTypeRequiredDescription
model_namestringYesName 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

HeaderValueDescription
AuthorizationBearer TOKENRequired. Your API access token
Content-Typeapplication/jsonRequired
Creates a new version of an existing model. This is useful for iterative model improvement.

Path Parameters

ParameterTypeRequiredDescription
model_namestringYesName 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"
  }
}
FieldTypeRequiredDescription
dataset_idstringYesID of the dataset to use for training
intentstringNoUpdated intent (defaults to original if omitted)
input_schemaobjectNoUpdated input schema (defaults to original)
output_schemaobjectNoUpdated 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

HeaderValueDescription
AuthorizationBearer TOKENRequired. Your API access token
Lists all active deployments for a model.

Path Parameters

ParameterTypeRequiredDescription
model_namestringYesName 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

HeaderValueDescription
AuthorizationBearer TOKENRequired. Your API access token
Removes a specific deployment of a model.

Path Parameters

ParameterTypeRequiredDescription
model_idstringYesID of the model
deployment_idstringYesID 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

HeaderValueDescription
x-api-keyYOUR_API_KEYRequired. Your API access key
Gets detailed information and metadata about a specific model version.

Path Parameters

ParameterTypeRequiredDescription
model_namestringYesName of the model
model_versionstringYesVersion 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

Batch Predictions

POST /models/{model_name}/{model_version}/predictions

Headers

HeaderValueDescription
x-api-keyYOUR_API_KEYRequired. Your API access key
Content-Typeapplication/jsonRequired
Makes batch predictions using a deployed model by sending an array of input data.

Path Parameters

ParameterTypeRequiredDescription
model_namestringYesName of the model to use
model_versionstringYesVersion 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 StatusError CodeDescription
400invalid_requestMalformed request or missing parameters
401unauthorizedMissing or invalid API key
403forbiddenInsufficient permissions for operation
404not_foundModel, deployment, or resource not found
409conflictResource conflict (e.g., duplicate name)
422validation_errorInvalid input data or schema
429rate_limit_exceededAPI rate limit exceeded
500internal_errorServer-side error
503service_unavailableService temporarily unavailable
For all API errors, the response will include details about the error and, where appropriate, suggestions for resolution.
I