Référence API

Documentation Développeurs

L'API Shok-IS suit les principes REST. Elle expose des URLs orientées ressources, accepte des corps de requête encodés en JSON, retourne des réponses JSON et utilise les codes HTTP standard ainsi qu'une authentification par token.

🔗 URL de base : https://api.shok-is.com · Toutes les requêtes doivent utiliser HTTPS. HTTP n'est pas supporté.

📄

Schéma OpenAPI

Télécharger .yaml →

🧪

Collection Postman

Importer la collection →

📦

Jeux de données sandbox

Parcourir les données →

Authentification

Toutes les requêtes API nécessitent un token Bearer transmis dans l'en-tête Authorization. Les clés API sont scoped par espace de travail et préfixées par sk_live_ en production ou sk_test_ en sandbox.

# Exemple de requête authentifiée
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 '{...}'

⚠️ N'exposez jamais votre clé sk_live_ dans du code client. Utilisez des variables d'environnement ou un gestionnaire de secrets.

POST /v1/predict

Soumet une requête de prédiction synchrone. Retourne un vecteur de prédiction typé avec score de confiance et pondérations d'attribution. Latence médiane : <50ms.

POST /v1/predict Inférence synchrone

// Corps de la requête
{
  "model_id": "mdl_revenue_churn_v3",       // requis
  "input_vector": {                          // requis
    "tenure_days": 487,
    "mrr_eur": 1240.00,
    "feature_usage_score": 0.83,
    "last_login_delta": 12
  },
  "output_format": "typed",              // "typed" | "raw" | "verbose"
  "confidence_threshold": 0.75           // optionnel, défaut: 0.5
}

Paramètres de requête

Paramètre	Type	Obligatoire	Description
model_id	string	Requis	Identifiant versionné du modèle. Format : `mdl_{nom}_{version}`
input_vector	object	Requis	Paires clé-valeur des noms de features et leurs valeurs. Doit correspondre au schéma attendu par le modèle.
output_format	string	Optionnel	`typed` (défaut), `raw`, ou `verbose` (inclut les valeurs SHAP).
confidence_threshold	float	Optionnel	Confiance minimale pour retourner une prédiction. Défaut : 0.5. Plage : 0.0–1.0.

200 OKPrédiction réussie

{
  "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_eur": 0.09
  },
  "latency_ms": 43,
  "timestamp": "2025-11-04T09:17:33.241Z"
}

Codes d'erreur

Code	Statut HTTP	Description
authentication_error	401	Clé API invalide ou absente.
model_not_found	404	Le model_id spécifié n'existe pas dans votre espace de travail.
schema_mismatch	422	L'input_vector ne correspond pas au schéma de features attendu par le modèle.
rate_limit_exceeded	429	Limite de débit de votre plan dépassée. Réessayez après la valeur de l'en-tête X-RateLimit-Reset.
inference_timeout	504	Le modèle a mis plus de 30 secondes à répondre. Réessayez ou contactez le support.

Limites de débit

Les limites sont appliquées par clé API, par minute. Les requêtes dépassant la limite retournent un statut 429 avec un en-tête Retry-After.

Plan	Requêtes / min	Burst	Quota mensuel
Démarrage	60	—	1 000
Standard	500	750	100 000
Entreprise	Personnalisé	Négocié	Illimité

SDK Python

# Installation
pip install shokintelligence

# Utilisation de base
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

SDK Node.js

// Installation
npm install @shok-is/sdk

// Utilisation de base
import { ShokClient } from '@shok-is/sdk';

const client = new ShokClient({ apiKey: 'sk_live_••••' });

const result = await client.predict({
  model_id: 'mdl_churn_v3',
  input_vector: { tenure_days: 487 }
});

console.log(result.prediction);  // HIGH_CHURN_RISK

SDK Go

// Installation
go get github.com/shok-is/go-sdk

// Utilisation de base
import shok "github.com/shok-is/go-sdk"

client := shok.NewClient("sk_live_••••")

result, err := client.Predict(ctx, &shok.PredictRequest{
  ModelID:     "mdl_churn_v3",
  InputVector: map[string]interface{}{
    "tenure_days": 487,
  },
})

fmt.Println(result.Prediction) // HIGH_CHURN_RISK