API Reference

Developer Documentation

The Shok-IS API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and authentication.

🔗 Base URL: https://api.shok-is.com · All requests must use HTTPS. HTTP is not supported.

📄

OpenAPI Schema

Download .yaml →

🧪

Postman Collection

Import collection →

📦

Sandbox Datasets

Browse datasets →

Authentication

All API requests require a Bearer token passed in the Authorization header. API keys are workspace-scoped and prefixed with sk_live_ for production or sk_test_ for sandbox.

# Example authenticated request
curl -X POST https://api.shok-is.com/v1/predict \
  -H "Authorization: Bearer sk_live_••••••••••••" \
  -H "Content-Type: application/json" \
  -H "X-Workspace-ID: ws_9f3a21bc" \
  -d '{...}'

⚠️ Never expose your sk_live_ key in client-side code. Use environment variables or a secrets manager.

POST /v1/predict

Submit a synchronous prediction request. Returns a typed prediction vector with confidence score and feature attribution weights. Median latency: <50ms.

POST /v1/predict Synchronous inference

// Request body
{
  "model_id": "mdl_revenue_churn_v3",       // required
  "input_vector": {                          // required
    "tenure_days": 487,
    "mrr_gbp": 1240.00,
    "feature_usage_score": 0.83,
    "last_login_delta": 12
  },
  "output_format": "typed",              // "typed" | "raw" | "verbose"
  "confidence_threshold": 0.75           // optional, default: 0.5
}

Request Parameters

Parameter	Type	Required	Description
model_id	string	Required	The versioned model identifier. Format: `mdl_{name}_{version}`
input_vector	object	Required	Key-value pairs of feature names and their values. Must match the model's expected schema.
output_format	string	Optional	`typed` (default), `raw`, or `verbose` (includes SHAP values).
confidence_threshold	float	Optional	Minimum confidence to return a prediction. Default: 0.5. Range: 0.0–1.0.

200 OKSuccessful prediction

{
  "request_id": "req_7KqpZ2mNxT",
  "model_version": "3.4.1",
  "prediction": "HIGH_CHURN_RISK",
  "confidence": 0.91,
  "vector_weights": {
    "feature_usage_score": 0.44,
    "last_login_delta": 0.33,
    "tenure_days": 0.14,
    "mrr_gbp": 0.09
  },
  "latency_ms": 43,
  "timestamp": "2025-11-04T09:17:33.241Z"
}

Error Codes

Code	HTTP Status	Description
authentication_error	401	Invalid or missing API key.
model_not_found	404	The specified model_id does not exist in your workspace.
schema_mismatch	422	input_vector does not match the model's expected feature schema.
rate_limit_exceeded	429	You have exceeded your plan's rate limit. Retry after the X-RateLimit-Reset header value.
inference_timeout	504	The model took longer than 30 seconds to respond. Try again or contact support.

Rate Limits

Rate limits are applied per API key, per minute. Exceeded requests return a 429 status with a Retry-After header.

Plan	Requests / min	Burst	Monthly quota
Starter	60	—	1,000
Standard	500	750	100,000
Enterprise	Custom	Negotiated	Unlimited

Python SDK

# Install
pip install shokintelligence

# Basic usage
import shokintelligence as shok

client = shok.Client(api_key="sk_live_••••")

result = client.predict(
    model_id="mdl_churn_v3",
    input_vector={"tenure_days": 487}
)

print(result.prediction)    # HIGH_CHURN_RISK
print(result.confidence)    # 0.91
print(result.latency_ms)    # 43