Models

Examples use $SPAVIK_BASE_URL and $SPAVIK_API_KEY, set in Get started.

`POST /v1/datasets/validate`

Check a dataset before training on it

Creates nothing, charges nothing. Returns the same validation report as training does, plus what the engine makes of the data: a trial run that persists nothing, with its metrics against the lazy answer (majority class or mean). Use it to iterate on a file until it holds, then train on it.

trial.verdict.level is usable, weak (suspiciously good, usually a column filled in after the event you predict) or no_signal (the columns carry nothing for this target). It is absent when validation already failed.

For a time series, use POST /v1/forecast/backtest instead: a series is judged on its length, its interval and its gaps, not on its classes.

Authentication : API key (X-API-Key) or web session (Authorization: Bearer)

Request body

Name	Type		Description
`target`	string	required
`engine`	string	optional	Prediction engine (see GET /v1/engines). Required when creating a model; on an already trained model, the previous version engine is used by default.
`name`	string	optional	Model name.
`explain`	boolean	optional	Asks for the most influential features (version.top_factors). Off by default: measuring them roughly triples training time.
`auto_update`	boolean	optional	Fold outcomes in without waiting for a call to /refresh. Each post to /outcomes then triggers an integration: send your outcomes in batches.
`data`	object[]	required	Data rows, one object per row.

This route also accepts multipart/form-data, to upload a file instead of serialising rows as JSON.

Responses

Code	Description
`200`	Success
`400`	Data missing, target missing, or unreadable CSV.
`401`	Authentication required, or invalid token.
`403`	This caller is not allowed to perform this action.

Example

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`

Available prediction engines

The engine is declared at training time (engine). A model keeps being served by the one that produced it: upgrading the platform does not change the predictions of existing models.

Authentication : Public route, no authentication

Responses

Code	Description
`200`	Success
`503`	ENGINE_CATALOGUE_MISMATCH: the catalogue could not be read from the engine.

Example

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

`GET /v1/models`

List the workspace models

Authentication : API key (X-API-Key) or web session (Authorization: Bearer)

Parameters

Name	In	Type		Description
`limit`	query	integer	optional
`offset`	query	integer	optional
`status`	query	`archived`	optional	Serving models by default. `archived` lists what was set aside, so it can be found again and restored. Deleted models are never listed.

Responses

Code	Description
`200`	Success
`401`	Authentication required, or invalid token.
`403`	This caller is not allowed to perform this action.

Example

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

`POST /v1/models`

Create a model (data + target) and train it

Creating a model is training it: the data goes in the same call, as JSON ('data') or CSV (the 'file' field). The response carries the identifier to use afterwards to predict (POST /v1/models/{id}/predict), without sending the data again.

Authentication : API key (X-API-Key) or web session (Authorization: Bearer)

TIP

Accepts Idempotency-Key: replaying the same call with the same key returns the already computed response, with no second charge.

Request body

Name	Type		Description
`target`	string	required
`engine`	string	optional	Prediction engine (see GET /v1/engines). Required when creating a model; on an already trained model, the previous version engine is used by default.
`name`	string	optional	Model name.
`explain`	boolean	optional	Asks for the most influential features (version.top_factors). Off by default: measuring them roughly triples training time.
`auto_update`	boolean	optional	Fold outcomes in without waiting for a call to /refresh. Each post to /outcomes then triggers an integration: send your outcomes in batches.
`data`	object[]	required	Data rows, one object per row.

This route also accepts multipart/form-data, to upload a file instead of serialising rows as JSON.

Responses

Code	Description
`201`	Model trained
`401`	Authentication required, or invalid token.
`402`	Out of predictions: monthly allowance and balance are both empty.
`403`	This caller is not allowed to perform this action.
`413`	Payload too large.
`422`	Data validation failed.

Example

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}`

Model details

Authentication : API key (X-API-Key) or web session (Authorization: Bearer)

Responses

Code	Description
`200`	Success
`401`	Authentication required, or invalid token.
`403`	This caller is not allowed to perform this action.
`404`	Unknown model.

Example

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

`PATCH /v1/models/{id}`

Rename a model

Authentication : API key (X-API-Key) or web session (Authorization: Bearer)

Request body

Name	Type		Description
`name`	string	optional

Responses

Code	Description
`200`	Success
`401`	Authentication required, or invalid token.
`403`	This caller is not allowed to perform this action.
`409`	Target and task are frozen once trained.

Example

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}`

Delete a model for good

Irreversible: the artefacts are purged from the engine and the pending outcomes go with them. To stop serving a model without losing it, archive it instead.

Authentication : API key (X-API-Key) or web session (Authorization: Bearer)

Responses

Code	Description
`204`	Deleted
`401`	Authentication required, or invalid token.
`403`	This caller is not allowed to perform this action.

Example

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

`POST /v1/models/{id}/archive`

Set a model aside

Nothing is destroyed: the trained artefacts are kept, the model simply stops serving and stops counting against the model quota. Restore it whenever you need it again. Predicting on an archived model returns 409 MODEL_ARCHIVED.

Authentication : API key (X-API-Key) or web session (Authorization: Bearer)

Responses

Code	Description
`204`	Archived
`401`	Authentication required, or invalid token.
`403`	This caller is not allowed to perform this action.
`404`	Unknown model.

Example

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

`POST /v1/models/{id}/outcomes`

Report what actually happened

Outcomes pile up, then join the context data of the model (POST /v1/models/{id}/refresh), and serve the predictions that follow. Each outcome is identified by the request_id of the original prediction (the features are looked up) or carries its full set of features. Send outcomes in batches: one call is one batch, and on a model with automatic updates (auto_update) a batch triggers an integration. Sending outcomes one by one would therefore trigger one training run per outcome.

Authentication : API key (X-API-Key) or web session (Authorization: Bearer)

TIP

Accepts Idempotency-Key: replaying the same call with the same key returns the already computed response, with no second charge.

Request body

Name	Type		Description
`outcomes`	object[]	required

Responses

Code	Description
`201`	Success
`401`	Authentication required, or invalid token.
`403`	This caller is not allowed to perform this action.
`404`	Unknown model.

Example

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`

Real-world performance, against the training metrics

Compares what was predicted to what happened (the outcomes you reported). observed stays null until an outcome can be matched to a prediction.

Authentication : API key (X-API-Key) or web session (Authorization: Bearer)

Parameters

Name	In	Type		Description
`days`	query	integer	optional

Responses

Code	Description
`200`	Success
`401`	Authentication required, or invalid token.
`403`	This caller is not allowed to perform this action.
`503`	PERFORMANCE_UNAVAILABLE: the log (BigQuery) could not be read.

Example

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

`POST /v1/models/{id}/refresh`

Fold pending outcomes into the context data

Produces a NEW version, which serves predictions right away; the previous one stays available, so rolling back is possible. No weights change: what grows is the set of examples the model looks at.

Authentication : API key (X-API-Key) or web session (Authorization: Bearer)

TIP

Accepts Idempotency-Key: replaying the same call with the same key returns the already computed response, with no second charge.

Responses

Code	Description
`201`	New version
`401`	Authentication required, or invalid token.
`403`	This caller is not allowed to perform this action.
`409`	No pending outcomes, or an update is already running.

Example

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

`POST /v1/models/{id}/restore`

Put an archived model back in service

Takes a place in the model quota again, so it can be refused when the plan is full. A model deleted for good cannot be restored (409 MODEL_DELETED). If the engine has moved on since, the model is restored but its version may no longer be servable: the next prediction says so (409 ENGINE_MISMATCH), and a refresh produces one on the current engine.

Authentication : API key (X-API-Key) or web session (Authorization: Bearer)

Responses

Code	Description
`200`	Success
`401`	Authentication required, or invalid token.
`402`	QUOTA_MODELS_EXCEEDED: the plan has no free slot left.
`403`	This caller is not allowed to perform this action.
`404`	Unknown model.
`409`	MODEL_DELETED: deleted for good, nothing to restore.

Example

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

`GET /v1/models/{id}/versions`

List versions

Authentication : API key (X-API-Key) or web session (Authorization: Bearer)

Responses

Code	Description
`200`	Success
`401`	Authentication required, or invalid token.
`403`	This caller is not allowed to perform this action.

Example

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

Models ​

POST /v1/datasets/validate ​

Request body ​

Responses ​

Example ​

GET /v1/engines ​

Responses ​

Example ​

GET /v1/models ​

Parameters ​

Responses ​

Example ​

POST /v1/models ​

Request body ​

Responses ​

Example ​

GET /v1/models/{id} ​

Responses ​

Example ​

PATCH /v1/models/{id} ​

Request body ​

Responses ​

Example ​

DELETE /v1/models/{id} ​

Responses ​

Example ​

POST /v1/models/{id}/archive ​

Responses ​

Example ​

POST /v1/models/{id}/outcomes ​

Request body ​

Responses ​

Example ​

GET /v1/models/{id}/performance ​

Parameters ​

Responses ​

Example ​

POST /v1/models/{id}/refresh ​

Responses ​

Example ​

POST /v1/models/{id}/restore ​

Responses ​

Example ​

GET /v1/models/{id}/versions ​

Responses ​

Example ​

Models

`POST /v1/datasets/validate`

Request body

Responses

Example

`GET /v1/engines`

Responses

Example

`GET /v1/models`

Parameters

Responses

Example

`POST /v1/models`

Request body

Responses

Example

`GET /v1/models/{id}`

Responses

Example

`PATCH /v1/models/{id}`

Request body

Responses

Example

`DELETE /v1/models/{id}`

Responses

Example

`POST /v1/models/{id}/archive`

Responses

Example

`POST /v1/models/{id}/outcomes`

Request body

Responses

Example

`GET /v1/models/{id}/performance`

Parameters

Responses

Example

`POST /v1/models/{id}/refresh`

Responses

Example

`POST /v1/models/{id}/restore`

Responses

Example

`GET /v1/models/{id}/versions`

Responses

Example