Versions & models
Base URL
https://api.example-sylvester-host
API versions vs. model versions
The API has two independent kinds of version:
| Concept | Where you see it | Example | Changes when… |
|---|---|---|---|
| API version | First path segment | /v2/... |
The request/response contract changes in a breaking way |
| Model | Path after /models/, and model.id in responses |
bc-v1 |
Sylvester releases a new detection model |
| Service version | model.version in v2 responses |
0.0.34 |
Sylvester deploys a new release of the service |
Reading a URL: /v2/models/bc-v1/predict means API v2, model bc-v1.
Choosing a model in v2
| Endpoint | Behaviour | Use when |
|---|---|---|
POST /v2/predict |
Uses the latest model. Today that is bc-v1. |
You want improvements automatically. |
POST /v2/models/{model_id}/predict |
Uses exactly the model you name. | You need consistent results across time (clinical studies, audits, A/B comparisons). |
When Sylvester releases a new model, /v2/predict switches to it. Pinned URLs keep using the model you named. Every v2 response reports the model that produced it in model.id.
Available models
model_id |
Description |
|---|---|
bc-v1 |
ResNet50-based classifier that estimates the probability a detected cat shows discomfort. |
Compatibility promise (v2)
- Non-breaking changes can happen at any time. Examples: new optional request fields, new response keys (for instance new attributes inside
cat), new errorcodevalues, new models. Your client must ignore response keys it doesn't recognise. - Breaking changes ship as a new API version (for example
/v3). Examples: removing or renaming fields, or changing a field's type or meaning.