Models API

Endpoints for creating, listing, retrieving models, and managing model versions (upload/download).

List models

GET /api/v1/models

Returns a paginated list of models in the catalog, ordered by creation time (newest first).

Parameters

Parameter	Type	Default	Description
limit	integer	20	Max models to return (1-100)
offset	integer	0	Number of models to skip
framework	string	--	Filter by framework: pytorch, tensorflow, xgboost, sklearn
is_baseline	boolean	--	Filter by baseline flag

Request

cURL

curl "https://api.octomil.com/api/v1/models?framework=pytorch&limit=10" \
  -H "Authorization: Bearer $OCTOMIL_API_KEY"

Python

import requests

resp = requests.get(
    "https://api.octomil.com/api/v1/models",
    headers={"Authorization": f"Bearer {api_key}"},
    params={"framework": "pytorch", "limit": 10},
)
data = resp.json()
for model in data["models"]:
    print(f"{model['id']}: {model['description']}")

Response

{
  "models": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "round_id": null,
      "model_path": "s3://octomil-models/baseline/model_v1.pt",
      "model_size_bytes": 4521984,
      "model_hash": "sha256:e3b0c442...",
      "framework": "pytorch",
      "framework_version": "2.1.0",
      "accuracy": 0.82,
      "loss": 0.53,
      "is_baseline": true,
      "description": "MNIST digit classifier - 3-layer CNN",
      "created_at": "2025-07-01T11:00:00Z"
    }
  ],
  "total": 18,
  "limit": 10,
  "offset": 0
}

---

Retrieve a model

GET /api/v1/models/{model_id}

Retrieves a single model by ID, including its full metadata and version history.

Parameters

Parameter	Type	Description
model_id	string (uuid)	UUID of the model

Request

curl https://api.octomil.com/api/v1/models/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "Authorization: Bearer $OCTOMIL_API_KEY"

Response

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "framework": "pytorch",
  "framework_version": "2.1.0",
  "accuracy": 0.82,
  "loss": 0.53,
  "is_baseline": true,
  "description": "MNIST digit classifier - 3-layer CNN",
  "created_at": "2025-07-01T11:00:00Z",
  "versions": [
    {
      "version": 1,
      "format": "pytorch",
      "model_size_bytes": 4521984,
      "uploaded_at": "2025-07-01T11:00:00Z"
    },
    {
      "version": 2,
      "format": "onnx",
      "model_size_bytes": 4100096,
      "uploaded_at": "2025-07-01T13:00:00Z"
    }
  ]
}

---

Create a model

POST /api/v1/models

Creates a new model entry in the catalog. This registers model metadata -- actual weights are uploaded separately via the upload endpoint below.

Parameters

Parameter	Type	Required	Description
framework	string	No	pytorch, tensorflow, xgboost, or sklearn
framework_version	string	No	Version of the ML framework (e.g. 2.1.0)
description	string	No	Human-readable description (max 1000 chars)
is_baseline	boolean	No	Whether this is a baseline model. Default: false

Request

curl -X POST https://api.octomil.com/api/v1/models \
  -H "Authorization: Bearer $OCTOMIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "framework": "pytorch",
    "framework_version": "2.1.0",
    "description": "MNIST digit classifier - 3-layer CNN",
    "is_baseline": true
  }'

Response (201 Created)

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "framework": "pytorch",
  "framework_version": "2.1.0",
  "is_baseline": true,
  "description": "MNIST digit classifier - 3-layer CNN",
  "created_at": "2025-07-01T11:00:00Z"
}

---

Upload a version

POST /api/v1/models/{model_id}/versions/upload

Uploads model weights as a new version. The server stores the file in S3/MinIO and optionally converts it to ONNX format.

Parameters

Path: model_id (string, uuid) -- UUID of the model.

Body (multipart/form-data):

Field	Type	Required	Description
file	binary	Yes	Model weights file (.pt, .h5, .pkl, .onnx)
format	string	No	Source format: pytorch, tensorflow, onnx, sklearn, xgboost
description	string	No	Human-readable description of this version

Request

curl -X POST https://api.octomil.com/api/v1/models/b2c3d4e5-f6a7-8901-bcde-f12345678901/versions/upload \
  -H "Authorization: Bearer $OCTOMIL_API_KEY" \
  -F "file=@model.pt" \
  -F "format=pytorch" \
  -F "description=After round 18 aggregation"

Response (201 Created)

{
  "model_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "version": 3,
  "format": "pytorch",
  "model_path": "s3://octomil-models/b2c3d4e5/v3/model.pt",
  "model_size_bytes": 4521984,
  "model_hash": "sha256:a1b2c3d4...",
  "description": "After round 18 aggregation",
  "uploaded_at": "2025-07-01T13:30:00Z"
}

---

Download a version

GET /api/v1/models/{model_id}/versions/{version}/download

Downloads model weights for a specific version. Use the optional format query parameter to request a converted artifact (ONNX, TFLite, CoreML). Returns 404 if the requested format is not yet available.

Parameters

Path: model_id (uuid), version (integer).

Query: format (string, default: original) -- Desired format: pytorch, onnx, tflite, coreml.

Request

# Download as ONNX
curl -O "https://api.octomil.com/api/v1/models/b2c3d4e5-f6a7-8901-bcde-f12345678901/versions/3/download?format=onnx" \
  -H "Authorization: Bearer $OCTOMIL_API_KEY"

Response (200 OK)

Binary file download with these headers:

Header	Description
Content-Disposition	Suggested filename (e.g. attachment; filename="model_v3.onnx")
Content-Length	File size in bytes
X-Model-Hash	SHA-256 hash for integrity verification

---

Errors

All model endpoints return standard error responses:

Status	Error	Description
400	bad_request	Invalid or missing request fields
401	unauthorized	Missing or invalid API key
404	not_found	Resource does not exist
409	conflict	Resource already exists or state conflict
429	rate_limited	Too many requests; check Retry-After
500	internal_error	Unexpected server error