Inference API Overview

Every deployed model gets a REST endpoint for real-time scoring. Deployments of v2 (XGM) models additionally expose a suite of prescriptive endpoints — optimization, counterfactuals, and portfolio budget allocation — that answer "what should we change?" rather than just "what will happen?".

Base URL

https://inference.xplainable.io/v1

Authentication

All requests are authenticated with a deploy key passed in the api_key header:

api_key: <your-deploy-key>

Deploy keys are scoped to a single deployment and have an expiry date. Create one from the Python SDK:

# One-shot: deploy + activate + key in a single call
result = client.workflow.deploy_model(model_id)
deploy_key = result["deploy_key"]

# Or step by step
deployment = client.deployments.deploy(model_version_id=version_id)
client.deployments.activate_deployment(deployment.deployment_id)
deploy_key = client.deployments.generate_deploy_key(
    deployment_id=deployment.deployment_id,
    description="production scoring",
    days_until_expiry=90,
)

Keys can be revoked at any time with client.deployments.revoke_deploy_key(deployment_id, key_id).

Endpoints

Endpoint	Method	Models	Purpose
/predict	POST	v1 + v2	Score rows, with additive explanation breakdowns
/optimize	POST	v2 only	Budget-constrained optimization for a single row
/optimize/batch	POST	v2 only	Batch optimization over many rows
/counterfactual	POST	v2 only	Minimal-cost changes to reach a desired outcome
/portfolio	POST	v2 only	Allocate one shared budget across many rows

v1 vs v2: /predict serves every deployment. The four prescriptive endpoints require a v2 (XGM) deployment and return 400 Bad Request when called against a v1 model.

Preprocessing

If a preprocessing pipeline is attached to the deployment, it is applied automatically to /predict requests before scoring — send raw rows in the same shape as your source data. Preprocessing is not applied on the prescriptive endpoints; they expect rows in the model's fitted feature space.

IP allowlisting

Deployments can optionally restrict access to an IP allowlist (managed in the platform UI). Requests from other addresses receive 403 Forbidden.

Error responses

Transport and validation errors use standard HTTP status codes with a detail message:

Status	Meaning
401	Invalid or malformed deploy key
403	IP not allowed, or the deployment is not active
404	Deployment no longer exists
400	Prescriptive endpoint called on a non-v2 deployment
422	Input doesn't match the model signature, or a required field is missing
500	Internal server error

The prescriptive endpoints additionally return a result envelope — a solver failure (e.g. an intractable constraint combination) comes back as HTTP 200 with "status": "error" in the body. Always branch on the envelope's status field. See Optimization — the result envelope.