Models

Les exemples utilisent $SPAVIK_BASE_URL et $SPAVIK_API_KEY, définis dans Démarrer.

POST /v1/datasets/validate

Vérifier un jeu de données avant d'entraîner

Ne crée rien, ne facture rien. Rend le même rapport de validation que l'entraînement, plus ce que le moteur fait des données : un essai qui ne conserve rien, avec ses métriques face à la réponse paresseuse (classe majoritaire ou moyenne). Servez-vous-en pour itérer sur un fichier jusqu'à ce qu'il tienne, puis entraînez dessus.

trial.verdict.level vaut usable, weak (trop beau pour être vrai, en général une colonne remplie après l'événement que vous prédisez) ou no_signal (les colonnes ne portent rien pour cette cible). Il est absent quand la validation a déjà échoué.

Pour une série temporelle, utilisez plutôt POST /v1/forecast/backtest : une série se juge sur sa longueur, son pas et ses trous, pas sur ses classes.

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

Corps de la requête

Nom	Type		Description
target	string	requis
engine	string	facultatif	Moteur de prédiction (voir GET /v1/engines). Requis à la création d'un modèle ; sur un modèle déjà entraîné, le moteur de la version précédente est repris par défaut.
name	string	facultatif	Nom du modèle.
explain	boolean	facultatif	Demande les caractéristiques les plus influentes (version.top_factors). Désactivé par défaut : les mesurer triple environ le temps d'entraînement.
auto_update	boolean	facultatif	Intègre les vérités sans attendre un appel à /refresh. Chaque envoi sur /outcomes déclenche alors une intégration : envoyez vos vérités par lots.
data	object[]	requis	Les lignes de données, un objet par ligne.

Cette route accepte aussi multipart/form-data, pour téléverser un fichier plutôt que de sérialiser les lignes en JSON.

Réponses

Code	Description
200	Succès
400	Données manquantes, cible manquante, ou CSV illisible.
401	Authentification requise, ou jeton invalide.
403	Cet appelant n'est pas autorisé à faire cette action.

Exemple

curl -X POST "$SPAVIK_BASE_URL/v1/datasets/validate" \
  -H 'X-API-Key: sk-spv-api-...' \
  -H 'Content-Type: application/json' \
  -d '{
  "target": "churn",
  "engine": "tabicl-v2",
  "data": [
    {
      "plan": "pro",
      "seats": 12,
      "tickets_90d": 3,
      "churn": 0
    },
    {
      "plan": "free",
      "seats": 1,
      "tickets_90d": 9,
      "churn": 1
    },
    {
      "plan": "pro",
      "seats": 40,
      "tickets_90d": 0,
      "churn": 0
    },
    {
      "plan": "free",
      "seats": 2,
      "tickets_90d": 7,
      "churn": 1
    },
    {
      "plan": "growth",
      "seats": 120,
      "tickets_90d": 1,
      "churn": 0
    },
    {
      "plan": "free",
      "seats": 1,
      "tickets_90d": 12,
      "churn": 1
    },
    {
      "plan": "pro",
      "seats": 25,
      "tickets_90d": 2,
      "churn": 0
    },
    {
      "plan": "free",
      "seats": 3,
      "tickets_90d": 5,
      "churn": 1
    },
    {
      "plan": "growth",
      "seats": 80,
      "tickets_90d": 4,
      "churn": 0
    },
    {
      "plan": "pro",
      "seats": 8,
      "tickets_90d": 11,
      "churn": 1
    },
    {
      "plan": "growth",
      "seats": 200,
      "tickets_90d": 0,
      "churn": 0
    },
    {
      "plan": "free",
      "seats": 4,
      "tickets_90d": 2,
      "churn": 0
    }
  ]
}'

GET /v1/engines

Les moteurs de prédiction disponibles

Le moteur se déclare à l'entraînement (engine). Un modèle reste servi par celui qui l'a produit : une montée de version de la plateforme ne change pas les prédictions des modèles existants.

Authentification : Route publique, aucune authentification

Réponses

Code	Description
200	Succès
503	ENGINE_CATALOGUE_MISMATCH : le catalogue n'a pas pu être lu auprès du moteur.

Exemple

curl -X GET "$SPAVIK_BASE_URL/v1/engines" \
  -H 'X-API-Key: sk-spv-api-...'

GET /v1/models

Lister les modèles du workspace

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

Paramètres

Nom	Où	Type		Description
limit	query	integer	facultatif
offset	query	integer	facultatif
status	query	archived	facultatif	Les modèles qui servent, par défaut. archived liste ceux mis de côté, pour les retrouver et les restaurer. Les modèles supprimés ne sont jamais listés.

Réponses

Code	Description
200	Succès
401	Authentification requise, ou jeton invalide.
403	Cet appelant n'est pas autorisé à faire cette action.

Exemple

curl -X GET "$SPAVIK_BASE_URL/v1/models" \
  -H 'X-API-Key: sk-spv-api-...'

POST /v1/models

Créer un modèle (données + cible) et l'entraîner

Créer un modèle, c'est l'entraîner : les données partent dans le même appel, en JSON (data) ou en CSV (le champ file). La réponse porte l'identifiant à utiliser ensuite pour prédire (POST /v1/models/{id}/predict), sans renvoyer les données.

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

TIP

Accepte Idempotency-Key : rejouer le même appel avec la même clé rend la réponse déjà calculée, sans nouveau débit.

Corps de la requête

Nom	Type		Description
target	string	requis
engine	string	facultatif	Moteur de prédiction (voir GET /v1/engines). Requis à la création d'un modèle ; sur un modèle déjà entraîné, le moteur de la version précédente est repris par défaut.
name	string	facultatif	Nom du modèle.
explain	boolean	facultatif	Demande les caractéristiques les plus influentes (version.top_factors). Désactivé par défaut : les mesurer triple environ le temps d'entraînement.
auto_update	boolean	facultatif	Intègre les vérités sans attendre un appel à /refresh. Chaque envoi sur /outcomes déclenche alors une intégration : envoyez vos vérités par lots.
data	object[]	requis	Les lignes de données, un objet par ligne.

Cette route accepte aussi multipart/form-data, pour téléverser un fichier plutôt que de sérialiser les lignes en JSON.

Réponses

Code	Description
201	Modèle entraîné
401	Authentification requise, ou jeton invalide.
402	Plus de prédictions : le volume mensuel et le solde sont épuisés.
403	Cet appelant n'est pas autorisé à faire cette action.
413	Corps de requête trop volumineux.
422	La validation des données a échoué.

Exemple

curl -X POST "$SPAVIK_BASE_URL/v1/models" \
  -H 'X-API-Key: sk-spv-api-...' \
  -H 'Content-Type: application/json' \
  -d '{
  "target": "churn",
  "engine": "tabicl-v2",
  "data": [
    {
      "plan": "pro",
      "seats": 12,
      "tickets_90d": 3,
      "churn": 0
    },
    {
      "plan": "free",
      "seats": 1,
      "tickets_90d": 9,
      "churn": 1
    },
    {
      "plan": "pro",
      "seats": 40,
      "tickets_90d": 0,
      "churn": 0
    },
    {
      "plan": "free",
      "seats": 2,
      "tickets_90d": 7,
      "churn": 1
    },
    {
      "plan": "growth",
      "seats": 120,
      "tickets_90d": 1,
      "churn": 0
    },
    {
      "plan": "free",
      "seats": 1,
      "tickets_90d": 12,
      "churn": 1
    },
    {
      "plan": "pro",
      "seats": 25,
      "tickets_90d": 2,
      "churn": 0
    },
    {
      "plan": "free",
      "seats": 3,
      "tickets_90d": 5,
      "churn": 1
    },
    {
      "plan": "growth",
      "seats": 80,
      "tickets_90d": 4,
      "churn": 0
    },
    {
      "plan": "pro",
      "seats": 8,
      "tickets_90d": 11,
      "churn": 1
    },
    {
      "plan": "growth",
      "seats": 200,
      "tickets_90d": 0,
      "churn": 0
    },
    {
      "plan": "free",
      "seats": 4,
      "tickets_90d": 2,
      "churn": 0
    }
  ]
}'

GET /v1/models/{id}

Détail d'un modèle

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

Réponses

Code	Description
200	Succès
401	Authentification requise, ou jeton invalide.
403	Cet appelant n'est pas autorisé à faire cette action.
404	Modèle inconnu.

Exemple

curl -X GET "$SPAVIK_BASE_URL/v1/models/{id}" \
  -H 'X-API-Key: sk-spv-api-...'

PATCH /v1/models/{id}

Renommer un modèle

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

Corps de la requête

Nom	Type		Description
name	string	facultatif

Réponses

Code	Description
200	Succès
401	Authentification requise, ou jeton invalide.
403	Cet appelant n'est pas autorisé à faire cette action.
409	La cible et la tâche sont figées une fois le modèle entraîné.

Exemple

curl -X PATCH "$SPAVIK_BASE_URL/v1/models/{id}" \
  -H 'X-API-Key: sk-spv-api-...' \
  -H 'Content-Type: application/json' \
  -d '{ }'

DELETE /v1/models/{id}

Supprimer un modèle pour de bon

Irréversible : les artefacts sont purgés chez le moteur et les vérités en attente partent avec eux. Pour cesser de servir un modèle sans le perdre, archivez-le plutôt.

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

Réponses

Code	Description
204	Supprimé
401	Authentification requise, ou jeton invalide.
403	Cet appelant n'est pas autorisé à faire cette action.

Exemple

curl -X DELETE "$SPAVIK_BASE_URL/v1/models/{id}" \
  -H 'X-API-Key: sk-spv-api-...'

POST /v1/models/{id}/archive

Mettre un modèle de côté

Rien n'est détruit : les artefacts entraînés sont conservés, le modèle cesse simplement de servir et de compter dans le quota de modèles. Restaurez-le quand vous en aurez de nouveau besoin. Prédire sur un modèle archivé répond 409 MODEL_ARCHIVED.

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

Réponses

Code	Description
204	Archivé
401	Authentification requise, ou jeton invalide.
403	Cet appelant n'est pas autorisé à faire cette action.
404	Modèle inconnu.

Exemple

curl -X POST "$SPAVIK_BASE_URL/v1/models/{id}/archive" \
  -H 'X-API-Key: sk-spv-api-...'

POST /v1/models/{id}/outcomes

Remonter ce qui est réellement arrivé

Les vérités s'accumulent, puis rejoignent les données de contexte du modèle (POST /v1/models/{id}/refresh) et servent aux prédictions suivantes. Chaque vérité s'identifie par le request_id de la prédiction d'origine (les caractéristiques sont retrouvées) ou porte ses caractéristiques complètes. Envoyez les vérités par lots : un appel vaut un lot, et sur un modèle en mise à jour automatique (auto_update) un lot déclenche une intégration. Les envoyer une par une déclencherait donc un entraînement par vérité.

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

TIP

Accepte Idempotency-Key : rejouer le même appel avec la même clé rend la réponse déjà calculée, sans nouveau débit.

Corps de la requête

Nom	Type		Description
outcomes	object[]	requis

Réponses

Code	Description
201	Succès
401	Authentification requise, ou jeton invalide.
403	Cet appelant n'est pas autorisé à faire cette action.
404	Modèle inconnu.

Exemple

curl -X POST "$SPAVIK_BASE_URL/v1/models/{id}/outcomes" \
  -H 'X-API-Key: sk-spv-api-...' \
  -H 'Content-Type: application/json' \
  -d '{
  "outcomes": [
    {
      "request_id": "4fa2ebd6-e347-43d4-b40d-a043c9a3121a",
      "actual": 1
    },
    {
      "features": {
        "plan": "free",
        "seats": 2,
        "tickets_90d": 10
      },
      "actual": 0
    }
  ]
}'

GET /v1/models/{id}/performance

La performance réelle, face aux métriques d'entraînement

Compare ce qui a été prédit à ce qui est arrivé (les vérités remontées). observed reste null tant qu'aucune vérité ne peut être rapprochée d'une prédiction.

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

Paramètres

Nom	Où	Type		Description
days	query	integer	facultatif

Réponses

Code	Description
200	Succès
401	Authentification requise, ou jeton invalide.
403	Cet appelant n'est pas autorisé à faire cette action.
503	PERFORMANCE_UNAVAILABLE : le journal (BigQuery) n'a pas pu être lu.

Exemple

curl -X GET "$SPAVIK_BASE_URL/v1/models/{id}/performance" \
  -H 'X-API-Key: sk-spv-api-...'

POST /v1/models/{id}/refresh

Intégrer les vérités en attente aux données de contexte

Produit une NOUVELLE version, qui sert aussitôt les prédictions ; la précédente reste consultable, donc le retour en arrière est possible. Aucun poids ne change : c'est l'ensemble d'exemples que le modèle regarde qui grandit.

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

TIP

Accepte Idempotency-Key : rejouer le même appel avec la même clé rend la réponse déjà calculée, sans nouveau débit.

Réponses

Code	Description
201	Nouvelle version
401	Authentification requise, ou jeton invalide.
403	Cet appelant n'est pas autorisé à faire cette action.
409	Aucune vérité en attente, ou une mise à jour est déjà en cours.

Exemple

curl -X POST "$SPAVIK_BASE_URL/v1/models/{id}/refresh" \
  -H 'X-API-Key: sk-spv-api-...'

POST /v1/models/{id}/restore

Remettre en service un modèle archivé

Reprend une place dans le quota de modèles, et peut donc être refusé quand le plan est plein. Un modèle supprimé pour de bon ne se restaure pas (409 MODEL_DELETED). Si le moteur a évolué entre-temps, le modèle est restauré mais sa version peut ne plus être servable : la prochaine prédiction le dit (409 ENGINE_MISMATCH), et un refresh en produit une sur le moteur courant.

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

Réponses

Code	Description
200	Succès
401	Authentification requise, ou jeton invalide.
402	QUOTA_MODELS_EXCEEDED : le plan n'a plus de place libre.
403	Cet appelant n'est pas autorisé à faire cette action.
404	Modèle inconnu.
409	MODEL_DELETED : supprimé pour de bon, rien à restaurer.

Exemple

curl -X POST "$SPAVIK_BASE_URL/v1/models/{id}/restore" \
  -H 'X-API-Key: sk-spv-api-...'

GET /v1/models/{id}/versions

Lister les versions

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

Réponses

Code	Description
200	Succès
401	Authentification requise, ou jeton invalide.
403	Cet appelant n'est pas autorisé à faire cette action.

Exemple

curl -X GET "$SPAVIK_BASE_URL/v1/models/{id}/versions" \
  -H 'X-API-Key: sk-spv-api-...'